執行 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 的允許名單
步驟 1:選擇地址
標題為「步驟 1:選擇地址」的章節現在就決定好地址並保留下來。CONNECT_PUBLIC_URL 是 Connect 所做一切的一部分:請求簽章、封存的憑證、供應商重新導向網址,以及每部伺服器的安裝 ID,全都綁定到它。之後更改它,就表示要重新登記重新導向,而且每個人都得重新登入。
步驟 2:登記供應商應用程式
標題為「步驟 2:登記供應商應用程式」的章節只登記你想服務的供應商。變數不完整的供應商會被排除在 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、用戶端密鑰、私鑰 |
一個類型為 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 會把代碼交回伺服器,由伺服器自行完成交換。
步驟 3:收集安裝 ID
標題為「步驟 3:收集安裝 ID」的章節Connect 只回應允許名單上的伺服器。在每部伺服器上,把它指向你的 Connect,然後讀取它的安裝 ID:
- 前往 設定 → 伺服器 → 單一登入,開啟 Control Center Connect 卡片,選擇 使用自訂 Connect 伺服器
- 輸入你的網址並儲存。卡片會顯示伺服器的安裝 ID
在伺服器主機的終端機中,同樣的操作如下:
cc_server connect enable --url https://connect.example.comcc_server connect statusstatus 會印出安裝 ID。在完成步驟 5 之前,它會顯示 install_blocked,這是預期中的情況。
安裝 ID 是依 Connect 地址衍生的,因此同一部伺服器面對每個 Connect 都有不同的 ID。只有在其擁有者輪替金鑰時,它才會改變。
步驟 4:建立封存金鑰
標題為「步驟 4:建立封存金鑰」的章節Connect 會用一把封存金鑰加密它交回的每一份憑證。產生一把,並將它保存為機密檔案:
docker run --rm ghcr.io/samuelalev/cc-connect:latest \ cc-connect-config seal-key > seal_keyschmod 600 seal_keys遺失封存金鑰會讓所有人登出:沒有它,任何封存都無法開啟。
步驟 5:啟動容器
標題為「步驟 5:啟動容器」的章節每次發佈都會發佈附有建置來源證明的 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 與相同的通道。
在 cc_server 內掛載 Connect
標題為「在 cc_server 內掛載 Connect」的章節伺服器可以自行代管 Connect,而不使用獨立的容器。掛載的服務與映像運行的是同一個。
- 把
CONNECT_*變數放進伺服器的.env檔案,做法同步驟 5。若 Connect 的任何密鑰(包括CONNECT_SENTRY_DSN)被匯出到伺服器的環境中,伺服器會拒絕啟動 - 加上
CC_SERVER_CONNECT_HOST=on - 重新啟動伺服器。它的日誌會印出
embedded Connect at <url>
CC_SERVER_CONNECT_HOST=onCONNECT_ALLOWED_INSTALLS=<install id>CONNECT_SEAL_KEYS=<output of cc-connect-config seal-key>CONNECT_GITHUB_APP_ID=123456CONNECT_GITHUB_APP_SLUG=acme-control-centerCONNECT_GITHUB_CLIENT_ID=Iv23li0123456789abcdCONNECT_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 團隊的限制,則透過狀態存放區共用。
輪替供應商密鑰
標題為「輪替供應商密鑰」的章節不會有任何人被登出:
- 在供應商處建立新的密鑰,並保留舊的
- 把舊值移到
NAME_PREVIOUS,把新值放進NAME,並調高CONNECT_<LANE>_SECRET_GENERATION。掛載的檔案會在 30 秒內被讀取 - 等待各登入重新整理,然後在供應商處刪除舊密鑰,並移除
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;超過該數量時,輪替會被拒絕,並且日誌會以錯誤層級說明。
疑難排解
標題為「疑難排解」的章節伺服器表示 Connect 封鎖了它
標題為「伺服器表示 Connect 封鎖了它」的章節它的安裝 ID 不在 CONNECT_ALLOWED_INSTALLS 中,在 CONNECT_DENY_INSTALLS 中,或已被金鑰輪替退役。當其擁有者輪替金鑰時,這個 ID 會改變;請向對方索取新的 ID。
對某個供應商的每次登入都失敗
標題為「對某個供應商的每次登入都失敗」的章節它的某個變數可能缺漏,因此 Connect 把該通道排除在外。請檢查啟動日誌與上方的表格。GitHub 需要 App id、slug、用戶端 id、用戶端密鑰與私鑰這五項;Google 需要用戶端 id 與密鑰兩者。
登入因重新導向不符而失敗
標題為「登入因重新導向不符而失敗」的章節向供應商登記的重新導向與 CONNECT_PUBLIC_URL 不完全相符。請比對通訊協定、主機、連接埠,以及掛載式 Connect 的 /connect 路徑。
所有人都必須重新登入
標題為「所有人都必須重新登入」的章節封存金鑰已變更或遺失、某部伺服器輪替了它的金鑰,或某部伺服器的資料被還原到另一部機器上。封存的憑證只會為建立它的那個安裝與 Connect 開啟。