跳到內容

執行 Connect 伺服器

Control Center Connect 會為尚未註冊自己應用程式的伺服器執行供應商登入(GitHub、 Google Calendar、Linear、Slack)。本指南說明如何執行你自己的 Connect,讓供應商 應用程式、它們的密鑰,以及獲准使用它們的伺服器清單,全都留在你手上。

Connect 看得到與看不到什麼,請見 Connect 參考。如果你 正在決定是否要執行一個,請先閱讀它。

  • 一個供 Connect 使用的公開 HTTPS 位址,例如 https://connect.example.com, 位於一個終止 TLS 的代理伺服器後方。純 http 只在回送位址上被接受
  • Docker,或一台你可以帶著額外環境變數重新啟動的 cc_server
  • 有權向你想服務的每個供應商註冊應用程式
  • 將使用它的伺服器,以及能隨時聯絡上的伺服器擁有者:每台伺服器都有一個安裝 ID, 要加入 Connect 的允許清單

現在就挑好網址並保留下來。CONNECT_PUBLIC_URL 是 Connect 所做一切的一部分:請求 簽章、封存的憑證、供應商重新導向網址,以及每台伺服器的安裝 ID,全都綁定到它。之後 變更它,就表示要重新註冊重新導向,而且每個人都得重新登入。

只註冊你想服務的供應商。變數不完整的供應商會被排除在 Connect 的設定之外,伺服器會 看到它無法使用。下方的 <base> 就是你的 CONNECT_PUBLIC_URL。

供應商 註冊 保留
GitHub App 回呼網址 <base>/oauth/github/callback。設定網址 <base>/oauth/github/setup,並開啟 Redirect on update。讓 Request user authorization (OAuth) during installation 保持關閉:開啟時,GitHub 會忽略設定網址。保持 Expire user authorization tokens 開啟 App id、slug、用戶端 id、用戶端密鑰、私密金鑰
Google 一個類型為 Web application 的 OAuth 用戶端,重新導向 URI 為 <base>/oauth/google/callback,並啟用 Google Calendar API 用戶端 id、用戶端密鑰
Linear 一個 OAuth 應用程式,回呼網址為 <base>/oauth/linear/callback 與 <base>/oauth/linear_app/callback 只需用戶端 id
Slack 重新導向網址 <base>/oauth/slack_oidc/callback 與 <base>/oauth/slack/callback。Event Subscriptions 位於 <base>/v1/hooks/slack/events(app_mention、message.*、assistant_thread_*、app_uninstalled、tokens_revoked)。斜線指令位於 <base>/v1/hooks/slack/commands。開啟權杖輪替 App id、用戶端 id、用戶端密鑰、簽章密鑰

為 GitHub App 授予下列儲存庫權限:Metadata 讀取、Contents 讀取與寫入、 Pull requests 讀取與寫入、Issues 讀取與寫入,以及 Checks、Actions 與 Commit statuses 讀取。為了團隊審查請求,請加上組織 Members 讀取。Webhook 可以保持關閉:伺服器會輪詢。

Connect 需要 GitHub App 的私鑰(App 設定中的產生私密金鑰)。它會為那些能找到涵蓋某儲存庫之安裝(若該儲存庫沒有,則為擁有者的安裝)的 App 請求簽章,並且只在提出請求的人自己的登入證明其對該儲存庫具有存取權之後,才簽發只適用於一個儲存庫的安裝權杖。

你的 Connect 上的每台伺服器都共用 App 的機器人。對其中任何一台,它都可以以機器人身分讀取、留言、加上標籤並做出反應。只有你在 CONNECT_GITHUB_REVIEW_BOT_INSTALLS 中列出的伺服器(以逗號分隔的安裝 ID)才被允許以機器人身分審查 pull request;其他每台伺服器都以審查者自己的權杖發佈審查。推送永遠不會以機器人身分進行。若要讓你自己的某台伺服器以機器人身分審查,請把它的安裝 ID 加進去並重新啟動。請把金鑰檔案當作機密保管,就像封存金鑰一樣。Linear 不需要密鑰:Connect 會把代碼交回伺服器,由伺服器自行完成交換。

Connect 只回應允許清單上的伺服器。在每台伺服器上,把它指向你的 Connect,然後讀取 它的安裝 ID:

  1. 前往 設定 → 伺服器 → 單一登入,開啟 Control Center Connect 卡片,選擇 使用自訂 Connect 伺服器
  2. 輸入你的網址並儲存。卡片會顯示伺服器的安裝 ID

在伺服器主機的終端機中,同樣的操作如下:

終端機視窗
cc_server connect enable --url https://connect.example.com
cc_server connect status

status 會印出安裝 ID。在完成步驟 5 之前,它會顯示 install_blocked,這是預期中的 情況。

安裝 ID 是依 Connect 位址衍生的,因此同一台伺服器面對每個 Connect 都有不同的 ID。 只有在其擁有者輪替金鑰時,它才會改變。

Connect 會用一把封存金鑰加密它交回的每一份憑證。產生一把,並將它保存為機密檔案:

終端機視窗
docker run --rm ghcr.io/samuelalev/cc-connect:latest \
cc-connect-config seal-key > seal_keys
chmod 600 seal_keys

遺失封存金鑰會讓所有人登出:沒有它,任何封存都無法開啟。

每次發行都會發布附帶建置來源證明的 ghcr.io/samuelalev/cc-connect。在正式環境中請 固定版本標籤。

終端機視窗
docker run -d --name cc-connect -p 8790:8790 \
-e CONNECT_PUBLIC_URL=https://connect.example.com \
-e CONNECT_ALLOWED_INSTALLS=<install id>,<install id> \
-e CONNECT_SEAL_KEYS_FILE=/run/secrets/seal_keys \
-v "$PWD/seal_keys:/run/secrets/seal_keys:ro" \
-e CONNECT_GITHUB_APP_ID=123456 \
-e CONNECT_GITHUB_APP_SLUG=acme-control-center \
-e CONNECT_GITHUB_CLIENT_ID=Iv23li0123456789abcd \
-e CONNECT_GITHUB_CLIENT_SECRET_FILE=/run/secrets/github \
-v "$PWD/github_secret:/run/secrets/github:ro" \
-e CONNECT_GITHUB_APP_PRIVATE_KEY_FILE=/run/secrets/github_key \
-v "$PWD/github_app_key.pem:/run/secrets/github_key:ro" \
-v cc-connect-data:/data \
ghcr.io/samuelalev/cc-connect:latest

把你的反向代理指向連接埠 8790,並把 CONNECT_TRUST_PROXY 設為 Connect 前方的代理數量,讓它的每位址限制能看到每位用戶端的位址。映像以非特權使用者執行,把狀態保存在 /data 磁碟區中,並內建健康檢查(cc-connect --healthcheck,它會探測 /healthz:只要程序有回應即可)。/readyz 還會檢查它的狀態與綁定儲存是否有回應,以及(若有使用 Redis)Redis 是否仍設定為 maxmemory-policy noeviction;請把編排器的就緒檢查指向那裡。

登入同意頁面會以表單 POST 回應,而 Connect 只接受來自其自身頁面的該 POST:Sec-Fetch-Site(若有送出)必須是 same-origin,Origin(若有送出)必須是 CONNECT_PUBLIC_URL 的來源;兩者皆無的 POST 會被拒絕。因此代理必須原樣轉送這兩個標頭,而 CONNECT_PUBLIC_URL 必須是人們的瀏覽器實際使用的位址。若在該頁面繼續時總是顯示「此連結已過期」,且日誌顯示 oauth.done_refused 且原因為 origin 或 no_origin,那麼這兩者之一就出錯了。

當設定是開放的、不安全的或只完成一半時,Connect 會拒絕啟動(結束代碼 78),並 印出是哪個變數有誤。缺少允許清單、不在回送位址上的 http 位址、格式錯誤的封存 金鑰,或同時設定了 NAME 與 NAME_FILE,都會讓它停下。

檢查點:在每台伺服器上,Connect 卡片顯示正常,而每種登入在哪裡進行會為你 註冊的每個供應商標示 Connect。cc_server connect status 會印出 Health: ok 與相同的通道。

伺服器可以自己代管 Connect,而不使用獨立的容器。掛載的服務與映像執行的是同一個。

  1. 把 CONNECT_* 變數放進伺服器的 .env 檔案,做法同步驟 5。 當 Connect 的任何機密(包括 CONNECT_SENTRY_DSN)被匯出在伺服器的環境中時,伺服器會拒絕啟動
  2. 加上 CC_SERVER_CONNECT_HOST=on
  3. 重新啟動伺服器。它的日誌會印出 embedded Connect at <url>
終端機視窗
CC_SERVER_CONNECT_HOST=on
CONNECT_ALLOWED_INSTALLS=<install id>
CONNECT_SEAL_KEYS=<output of cc-connect-config seal-key>
CONNECT_GITHUB_APP_ID=123456
CONNECT_GITHUB_APP_SLUG=acme-control-center
CONNECT_GITHUB_CLIENT_ID=Iv23li0123456789abcd
CONNECT_GITHUB_CLIENT_SECRET=<secret>
CONNECT_GITHUB_APP_PRIVATE_KEY_FILE=/etc/cc/github_app_key.pem

接著 Connect 會在 <server>/connect 提供服務:

  • CONNECT_PUBLIC_URL 預設為伺服器公開網址的來源加上 /connect。位於代理伺服器 後方時,請明確設定它。它的路徑必須正好是 /connect,而且除非是回送位址,否則 必須使用 HTTPS
  • 只有 CONNECT_* 變數會傳到掛載的服務,因此它永遠不會借用伺服器自己的供應商 應用程式
  • CONNECT_ALLOWED_INSTALLS 仍然是必要的,包括代管它的伺服器本身
  • 設定錯誤的掛載會讓伺服器無法開機,而不是提供一個開放的仲介
  • 示範伺服器永遠不會掛載它

請以 https://<server>/connect 註冊供應商的重新導向,然後如步驟 3 所述,把各伺服器 (包括代管的那一台)指向該網址。

每一項設定都是一個環境變數。任何密鑰都可以改從掛載的檔案取得:以 NAME_FILE 取代 NAME。Connect 最多每 30 秒重新讀取一次該檔案,並保留最後一個有效的值。標示 為雙值的密鑰在輪替期間也接受 NAME_PREVIOUS(或 NAME_PREVIOUS_FILE)。

變數 預設值 意義
CONNECT_PUBLIC_URL 必要 標準的公開網址。HTTPS,或僅限回送位址的 http。帶有路徑表示掛載。不可有查詢字串或片段
CONNECT_ALLOWED_INSTALLS 必要 以逗號分隔的安裝 ID。只有搭配 CONNECT_SIGNED_CONFIG_FILE 時才接受 *
CONNECT_DENY_INSTALLS 即使已被允許也會遭拒的安裝 ID
CONNECT_GITHUB_ALLOWED_OWNERS 數字形式的 GitHub 擁有者 ID。設定後,只會為這些擁有者所擁有的儲存庫簽發儲存庫權杖。它不限制誰能登入:獲准使用此 Connect 的人仍會取得他們自己的 App 使用者權杖。若只想為一個組織服務,請讓 App 只對它保持私有
CONNECT_GITHUB_REVIEW_BOT_INSTALLS 可讓 App 的機器人審查 pull request 的安裝 ID。預設為空;* 會被拒絕,且每個 ID 也都必須已被允許
CONNECT_HOST, CONNECT_PORT 0.0.0.0, 8790 繫結位址與連接埠
CONNECT_TRUST_PROXY 0 X-Forwarded-For 中受信任的代理跳數(0 到 8)。只用於依位址的限制、登入頁面的網路提示,以及記錄中的位址。位於代理之後時,0 會把每個用戶端都計為代理,而日誌會對此說明一次
變數 預設值 意義
CONNECT_GITHUB_APP_ID, CONNECT_GITHUB_APP_SLUG, CONNECT_GITHUB_CLIENT_ID GitHub App
CONNECT_GITHUB_CLIENT_SECRET 密鑰,雙值
CONNECT_GITHUB_APP_PRIVATE_KEY 密鑰。App 的私密金鑰(PEM)
CONNECT_GOOGLE_CLIENT_ID, CONNECT_GOOGLE_CLIENT_SECRET Google 用戶端。密鑰為雙值
CONNECT_LINEAR_CLIENT_ID Linear 應用程式。沒有密鑰
CONNECT_SLACK_APP_ID, CONNECT_SLACK_CLIENT_ID Slack 應用程式
CONNECT_SLACK_CLIENT_SECRET, CONNECT_SLACK_SIGNING_SECRET 密鑰,雙值
CONNECT_KLIPY_APP_KEY Klipy GIF 搜尋金鑰。密鑰,雙值
CONNECT_KLIPY_MODE proxy proxy 會把金鑰留在 Connect;key 會把它交給伺服器
CONNECT_<LANE>_SECRET_GENERATION 1 GitHub、Google 與 Slack:記錄在新封存中的世代
CONNECT_<LANE>_MIN_SEAL_GENERATION 1 GitHub、Google 與 Slack:較舊的封存必須重新登入
CONNECT_<LANE>_ACCEPTS_NEW true 每條通道:false 會停止新的登入,既有的登入則繼續重新整理
變數 預設值 意義
CONNECT_SEAL_BACKEND local local 或 gcp-kms
CONNECT_SEAL_KEYS 密鑰,local 必要。以逗號分隔的 kid:key 項目,最新的在前;較舊的項目仍可解密
CONNECT_KMS_KEY projects/…/locations/…/keyRings/…/cryptoKeys/…,gcp-kms 必要
CONNECT_STATE memory 單一執行個體用 memory,多個執行個體用 redis。已滿的記憶體儲存會拒絕新的登入與請求,而不是忘掉仍在使用中的項目
CONNECT_REDIS_URL 密鑰。redis:// 或 rediss://。Redis 須為 6.2 或更新版本並設定 maxmemory-policy noeviction,兩者都會在啟動時檢查
CONNECT_REDIS_CA_FILE rediss:// 使用的 CA 憑證組合
CONNECT_BINDINGS file Slack 團隊綁定存放的位置:file 或 firestore
CONNECT_DATA_DIR data(映像中為 /data) 存放 bindings.json。由一個 Connect 鎖定:同一目錄上的第二個 Connect 不會啟動
CONNECT_FIRESTORE_PROJECT, CONNECT_FIRESTORE_DATABASE (default) 資料庫 用於 CONNECT_BINDINGS=firestore。Firestore 沒有回應時,Connect 不會啟動
變數 預設值 意義
CONNECT_SIGNED_CONFIG_FILE 一份離線簽署的設定,原樣提供。由 Control Center 代管的 Connect 使用
CONNECT_CONFIG_PUBLIC_KEYS 簽署的設定必須通過驗證的金鑰
CONNECT_CONFIG_EPOCH 1 自行代管的 Connect 所產生之設定的世代號
CONNECT_LOG_HMAC_KEY 每個行程隨機產生 密鑰。設定它,可讓代替安裝 ID 的標記在重新啟動與不同執行個體之間保持穩定
CONNECT_SENTRY_DSN 密鑰。一個 https Sentry DSN,錯誤行會回報到該處:錯誤類型、堆疊框架、路由與請求 ID,絕不包含訊息、內文或標頭
CONNECT_SENTRY_ENVIRONMENT self-hosted Sentry 環境
CONNECT_VERSION, CONNECT_IMAGE_DIGEST 由 /v1/version 回報
CONNECT_RATE_INSTALL_PER_MINUTE 600 每個安裝的請求數
CONNECT_RATE_IP_PER_MINUTE 300 每個位址的請求數(IPv6 位址以 /64 計算)
CONNECT_RATE_GLOBAL_PER_SECOND 500 整個執行個體的請求數
CONNECT_RATE_SLACK_HOOK_IP_PER_MINUTE 600 每個位址的 Slack 事件與指令投遞,與其他請求分開計算
CONNECT_RATE_SLACK_HOOK_GLOBAL_PER_SECOND 100 整個執行個體的 Slack 事件與指令投遞
CONNECT_RATE_SLACK_TEAM_PER_MINUTE 600 每個團隊的 Slack 事件數
CONNECT_RATE_KLIPY_PER_MINUTE 120 每個安裝的 GIF 搜尋次數
CONNECT_RATE_KLIPY_IP_PER_MINUTE 240 每個位址的 GIF 搜尋次數,跨所有伺服器
CONNECT_RATE_LOGINS_IP_PER_10_MINUTES 60 每個位址開始的登入次數
CONNECT_RATE_GITHUB_TOKENS_ACCOUNT_PER_HOUR 30 每個 GitHub 帳戶在一台伺服器上簽發的權杖數(登入、重新整理、儲存庫權杖)
CONNECT_RATE_GITHUB_TOKENS_ACCOUNT_CEILING_PER_HOUR 4 × 上列值(120) 同一 GitHub 帳戶跨所有伺服器的相同限制
CONNECT_RATE_GITHUB_TOKENS_IP_PER_HOUR 600 每個位址簽發的 GitHub 權杖數
CONNECT_RATE_GITHUB_EXCHANGE_CEILING_PER_HOUR 500 整個應用程式新的 GitHub 登入數
CONNECT_RATE_GITHUB_APP_MINTS_INSTALL_PER_HOUR 120 每台伺服器的機器人權杖數
CONNECT_RATE_GITHUB_APP_MINTS_ACCOUNT_PER_HOUR 240 每個提出請求的 GitHub 帳戶的機器人權杖數,跨伺服器
CONNECT_RATE_GITHUB_APP_CEILING_PER_HOUR 3000 整個應用程式的機器人權杖數
CONNECT_RATE_GITHUB_TOKEN_CEILING_PER_HOUR 1500 整個應用程式的重新整理與儲存庫權杖。新的登入有上方所列的自身限制
CONNECT_GITHUB_TOKEN_CAP_WARN 10 一個 GitHub 帳戶可持有的有效儲存庫權杖數,超過後 Connect 會記錄警告
CONNECT_RATE_RETIRE_IP_PER_HOUR 10 每個位址退役的安裝 ID(IPv6 以 /48 計算)

超過限制的呼叫會被回應 rate_limited。伺服器會稍後重試,而且絕不會因此讓任何人登出。

對大多數組織而言,一個使用 CONNECT_STATE=memory 的執行個體就足夠了。位於同一個位址後方的多個執行個體需要 CONNECT_STATE=redis 與 CONNECT_BINDINGS=firestore,這樣在某個執行個體上開始的登入才能在另一個上完成,而且每個執行個體都會看到相同的 Slack 綁定與已退役的安裝 ID。共用的 CONNECT_DATA_DIR 行不通:先啟動的 Connect 會將它鎖定。每個安裝、每個位址與整個執行個體的請求限制都是各執行個體獨立計算的;登入、GitHub 權杖、機器人權杖、每個位址的 GIF 搜尋、退役與 Slack 團隊的限制則透過狀態儲存共享。

不會有任何人被登出:

  1. 在供應商處建立新的密鑰,並保留舊的
  2. 把舊值移到 NAME_PREVIOUS,把新值放進 NAME,並調高 CONNECT_<LANE>_SECRET_GENERATION。掛載的檔案會在 30 秒內被讀取
  3. 等待各登入重新整理,然後在供應商處刪除舊密鑰,並移除 NAME_PREVIOUS

若要輪替封存金鑰,請把一個新的 cc-connect-config seal-key 項目放在 CONNECT_SEAL_KEYS 的最前面,並保留舊項目,直到它的封存都已重新整理為止。

伺服器會記住你的 Connect 在它們第一次使用時公告的應用程式 ID 與用戶端 ID。如果你 更換了某個應用程式,每台伺服器的 Connect 卡片都會顯示 Connect 的應用程式已變更, 而透過 Connect 的登入會暫停,直到其擁有者按下信任新應用程式。在切換之前請先通知 各伺服器擁有者,讓他們知道這個提示來自你。

把它的安裝 ID 加進 CONNECT_DENY_INSTALLS 並重新啟動。其擁有者會看到「Connect 已封鎖此伺服器的安裝 ID。請聯絡你的 Connect 伺服器營運者。」,而它上面所有透過 Connect 的登入都會停止。

伺服器在其擁有者輪替金鑰時,也會退役它自己舊的安裝 ID。它以 Connect 為它建立的一個憑證封存來證明該 ID 是它自己的,因此只有曾經為某人登入過的伺服器才能退役一個 ID。Connect 會永久保留已退役的 ID,因此舊金鑰以及為它建立的每個封存都會停止運作,並釋放綁定在舊 ID 上的 Slack 工作區。已發出的權杖會自行過期:人員的權杖在 8 小時內過期,機器人的權杖則在 1 小時內過期。Connect 最多保留 100,000 個已退役的 ID;超過時,輪替會被拒絕,且日誌會以錯誤等級說明此事。

它的安裝 ID 不在 CONNECT_ALLOWED_INSTALLS 中、在 CONNECT_DENY_INSTALLS 中,或已因金鑰輪替而退役。 當其擁有者輪替金鑰時,這個 ID 會改變;請向對方索取新的 ID。

它的某個變數可能缺漏,因此 Connect 把該通道排除在外。請檢查啟動日誌與上方的表格。GitHub 需要 App id、slug、用戶端 id、用戶端密鑰與私鑰這五項;Google 需要用戶端 id 與密鑰兩者。

向供應商註冊的重新導向與 CONNECT_PUBLIC_URL 不完全相符。請比對通訊協定、主機、 連接埠,以及掛載式 Connect 的 /connect 路徑。

封存金鑰已變更或遺失、某台伺服器輪替了它的金鑰,或某台伺服器的資料被還原到另一台 機器上。封存的憑證只會為建立它的那個安裝與 Connect 開啟。