跳转到内容

运行 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 时它是否仍运行着 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 以及相同的通道。

服务器可以自行托管 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 打开。