跳至內容

執行 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 的設定中按 Generate a private key)。它會為尋找涵蓋某個程式庫之安裝的 App 請求簽章(若程式庫沒有,則為擁有者的安裝),並簽發只適用於單一程式庫的安裝權杖,且每次只在提問的人自己的登入證明其可存取該程式庫之後才進行。

每部使用你的 Connect 的伺服器都共用該 App 的機械人。它可以為其中任何一部讀取、評論、加上標籤並作出表情反應。以機械人身分審查 pull request,只允許 CONNECT_GITHUB_REVIEW_BOT_INSTALLS 中列出的伺服器(以逗號分隔的安裝 ID);其他每部伺服器都會以審查者自己的權杖發佈審查。推送絕不以機械人身分進行。若要讓你自己的伺服器以機械人身分審查,請把它的安裝 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 時檢查它是否仍運行 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 帳戶在一部伺服器上簽發的 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 開啟。