运行 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 的设置中选择生成私钥)。它为 App 的请求签名,用于查找覆盖某个仓库的安装(如果该仓库没有,则查找所有者的安装),并签发仅适用于单个仓库的安装令牌;而且只有在提出请求的人自己的登录证明其有权访问该仓库之后,才会这样做。
你的 Connect 上的每台服务器都共享该 App 的机器人。对于其中任何一台,它都可以以机器人身份读取、评论、加标签和做出回应。只有你在 CONNECT_GITHUB_REVIEW_BOT_INSTALLS 中列出的服务器(使用逗号分隔的安装 ID)才被允许以机器人身份审查 pull request;其他每台服务器都使用审查者自己的令牌发布审查。推送永远不会以机器人身份进行。若要让你自己的某台服务器以机器人身份审查,请把它的安装 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 只接受来自其自身页面的此类提交:若发送了 Sec-Fetch-Site,其值必须是 same-origin;若发送了 Origin,其值必须与 CONNECT_PUBLIC_URL 的来源相同;两者都没有的 POST 会被拒绝。因此代理必须原样传递这两个请求头,并且 CONNECT_PUBLIC_URL 必须是人们的浏览器实际使用的地址。如果在该页面上继续操作时总是显示“此链接已过期”,并且日志中出现原因为 origin 或 no_origin 的 oauth.done_refused,那么这两项中有一项设置有误。
当配置是开放的、不安全的或只完成了一半时,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 打开。