Control Center Connect 参考
Control Center Connect 会为尚未注册自己应用的服务器执行提供商登录。服务器可以使用
Control Center 托管的 Connect、其组织自行运行的 Connect(运行 Connect 服务器),或者两者都不用。
这一选择位于 设置 → 服务器 → 单点登录 → Control Center Connect、
cc_server connect,或 CC_CONNECT_URL。工作区默认遵循该选择,除非管理员在 设置 → 工作区 → 集成 中为该工作区选择了其他选项(每个工作区的选择)。
在使用我自己的应用(或尚未有人选择之前)下,通道在服务器自己的应用配置完整时使用该应用,否则不可用。使用 Control Center Connect 或自定义 Connect 时,Connect 会服务它提供的每个通道:服务器自己的应用保留但不使用,无论是登录、服务器自动化还是服务器报告的状态。已选定自身选择的工作区则改按该选择运行每个通道。
| 通道 | 自有应用需要 | 通过 Connect |
|---|---|---|
github |
App id、私钥、客户端 id 与客户端密钥 | 人们登录共享的 GitHub App |
google |
客户端 id 与客户端密钥 | 人们连接 Google Calendar |
linear |
客户端 id | 人们登录 Linear |
linear_app |
客户端 id | 由工作区管理员连接 Linear 的应用执行者 |
slack |
工作区自己的 Slack 应用连接 | 由工作区管理员把 Slack 连接到共享的 Slack 应用 |
klipy |
KLIPY_APP_KEY |
GIF 搜索,由 Connect 代理 |
只配置了一部分的自有应用会使其通道进入错误状态,绝不会悄悄回退到 Connect。选择使用我自己的应用的工作区绝不会通过服务器的应用或任何 Connect 登录,对任何提供商都是如此。更改服务器的 Connect 选择不会让任何选择了自身选择的工作区退出登录。
Connect 能看到什么,永远看不到什么
标题为“Connect 能看到什么,永远看不到什么”的部分| Connect 能看到 | Connect 永远看不到 |
|---|---|
| 服务器的安装 ID 与请求签名 | 源代码、仓库内容、差异或 pull request 文本 |
| 登录期间,完成登录的那个提供商账户 | 工单、转录稿,或工作区数据库中的任何内容 |
| 某份凭据属于哪个工作区,以封存内的不透明 ID 形式呈现 | 服务器自己的应用密钥:它们永远不会离开服务器 |
| 仅适用于单个仓库的 GitHub 令牌是为哪个仓库签发的 | 静态存储的刷新令牌:它们只存在于服务器保存的封存之内 |
| 绑定到该服务器的 Slack 团队 | Linear 密钥:服务器会自行交换 Linear 的授权码 |
| 代理 Klipy 时的 GIF 搜索词 | 密码、配对密钥或模型提供商密钥 |
| Slack 事件引用(团队、频道、消息 id)与斜杠命令文本 | Slack 消息文本:Connect 在收到时即丢弃,服务器会自行从 Slack 读取消息 |
Connect 对进行中的登录、nonce 和缓存最多保留 10 分钟,对每小时的用量计数器最多保留两小时。以某个人身份签发的仅适用于单个仓库的 GitHub 令牌会一直保留着记录,并封存于请求它的那次登录之中,直到过期(最长 8 小时),因此 Connect 可以再次把它交出,并在断开连接时将其吊销。它唯一长期保存的记录是 Slack 绑定(每个 Slack 团队绑定到哪台服务器)以及已退役的安装 ID。错误只携带代码,绝不包含提供商的响应。日志只以带密钥的哈希记录安装 ID,GitHub 令牌则只以 GitHub 组织审计日志为它显示的 hashed_token 记录,因此组织所有者可以将二者对应起来。
| 模式 | 设置 | 行为 |
|---|---|---|
| 未配置 | 全新的服务器 | 没有任何通道使用 Connect。入门引导会请服务器所有者做出选择 |
hosted |
使用 Control Center 的应用 | https://connect.usectrl.dev,搭配一份离线签名的配置。服务器自己的应用不会被使用 |
custom |
使用自定义 Connect 服务器 | 位于 HTTPS 地址(仅回环地址可用 http)的 Connect,首次使用时即予以信任。服务器自己的应用不会被使用 |
off |
使用我自己的应用 | 没有任何通道使用 Connect。只有自有应用能让人们登录 |
服务器环境或 .env 中的 CC_CONNECT_URL 会锁定这一选择:hosted、off 或某个
Connect 地址。之后的设置会显示这一锁定,且无法更改它。
本构建版本没有内置任何托管配置密钥,因此托管模式会报告 hosted_unprovisioned,
且不提供任何通道。自有应用与自定义 Connect 都可以正常工作。
托管的 Connect 运行在单个容器中。其封存密钥和共享 GitHub App 的私钥是那里的环境变量,而不是 GitHub 对 App 私钥所建议的、仅用于签名或解密的密钥库中的密钥。这是当前配置中已知的一个缺口。
服务器最多每 10 分钟读取一次 Connect 的配置,每次调用最多等待 5 秒。当 Connect 无法 连接时,它会继续使用最后一份有效的配置,并由设置将其标记为过期。
每个工作区的选择
标题为“每个工作区的选择”的部分设置 → 工作区 → 集成 → Control Center Connect 会为某个工作区覆盖服务器的选择。每位成员都能看到它以及每次登录在哪里运行;只有工作区管理员可以更改。
| 选项 | 行为 |
|---|---|
| 与此服务器相同 | 默认值。工作区运行服务器所有者选定的任何配置;选项会写明该配置 |
| 使用 Control Center 的应用 | Control Center 托管的 Connect,无论服务器使用什么 |
| 使用我自己的应用 | 仅使用工作区自己的应用:其 GitHub App、Google 客户端、Linear 应用、Klipy 密钥与 Slack 应用。没有对应应用的提供商在此处关闭;只配置了一部分则是设置错误 |
| 使用自定义 Connect 服务器 | 工作区指定的 HTTPS 地址上的 Connect。私有网络或本地网络上的地址会被拒绝 |
- 除与此服务器相同外的任何选项,都会把每个人的 GitHub 与 Linear 登录保存在工作区自己的一个槽位中,因此它们绝不会与服务器范围的登录混在一起
- 切换时会先询问:工作区中的每个人都需要通过新应用重新登录 GitHub、Linear 和 Google Calendar
- 工作区自己的 Slack 应用连接在所有选项下都可用;将 Control Center 添加到 Slack 遵循所选选项
CC_CONNECT_URL也会阻止工作区拥有自己的 Connect:它们只能遵循服务器,或使用自己的应用- 工作区自己的自定义 Connect 只在该工作区内首次使用时受信任:那里的信任新应用绝不会改变服务器或其他工作区所信任的内容
安装身份
标题为“安装身份”的部分| 项目 | 说明 |
|---|---|
| 安装密钥 | 服务器机密文件中的一个 32 字节种子(connect_install_key),与设备配对密钥分开 |
| 每个 Connect 的密钥 | 由种子与该 Connect 的地址派生出的 Ed25519 密钥。每个发往 Connect 的请求都用它签名(RFC 9421) |
| 安装 ID | 由该公钥派生出的 26 个字符。显示在设置中,以及 cc_server connect status 的输出里 |
同一台服务器面对每个 Connect 地址都有不同的安装 ID。只有在密钥被轮换时,这个 ID 才会 改变。
封存的凭据
标题为“封存的凭据”的部分通过 Connect 的登录会返回一个凭据封存:一个只有创建它的 Connect 才能打开的加密 数据块。它绑定到提供商、Connect 地址、安装 ID、工作区、提供商账户、应用与密钥世代。
- 服务器保存这份封存以及与之对应的安装 ID。访问令牌只保留在内存中
- 需要刷新时,服务器会把封存送回,并获得新的访问令牌与新的封存
- 安装 ID 或 Connect 地址不再匹配的封存,会在下一次读取时被删除,那个人需要重新 登录。这会发生在密钥轮换、切换到另一个 Connect,或数据目录被还原到另一台服务器之后
- Connect 无法打开的封存会以
access_denied拒绝
GitHub 安装
标题为“GitHub 安装”的部分共享 GitHub App 的安装可以从每台服务器使用。Connect 不记录哪台服务器可以使用它。
- 设置 → 工作区 → 集成 中的安装 GitHub 应用会打开该应用在 GitHub 上的安装页面。 服务器会根据 Connect 配置中的应用名称生成链接
- 单个仓库的令牌需要应用已安装在仓库所有者账户上,并且登录的人有权访问该仓库。 这是该人自己的令牌,受其角色限制,绝不会更多
- 组织可以在 GitHub 上限制 Control Center:移除安装、缩小仓库范围或移除该成员
- 对于只有此人能进行的调用(例如列出他们的安装),Connect 会把此人自己的 App 用户令牌交给服务器,而不是仅限单个仓库的令牌。在某台服务器上登录,就意味着信任该服务器持有这份令牌
- 强制执行 GitHub IP 允许列表的组织无法使用托管 Connect,因为其地址并不固定。它应改为注册自己的 GitHub App,部署在自己的服务器上,或部署在它运行的 Connect 上
- 断开连接只撤销那一次登录:Connect 只使用一次其刷新令牌,并删除返回的内容,删除其用户令牌以及 Connect 为其签发的仅限单个仓库的令牌。保存在任何地方的该封存副本都会失效。此人在其他服务器和工作区上的登录会继续工作。若要完全从某个 GitHub 账户中移除 Control Center,请在 GitHub 的 Settings → Applications → Authorized GitHub Apps → Revoke 中将其吊销
共享的机器人
标题为“共享的机器人”的部分以应用机器人身份(as: app)签发的令牌,在 GitHub 上对同一 Connect 下的每台服务器都显示为同一个机器人:GitHub 无法区分这些服务器。
- 每台服务器都可以让机器人读取和评论:
read、review与comment(issue 和 pull request 上的评论、标签、负责人和反应) - 仅允许 Connect 运营方在
CONNECT_GITHUB_REVIEW_BOT_INSTALLS中列出的服务器,才可以以机器人身份审查 pull request(bot,该令牌会写入 pull request)。其他每台服务器都会收到needs_requester,并改由负责任的人自己的令牌发布审查,而 GitHub 会将其限制在该人身上:审查会以其名义出现。这涵盖 AI 审查发布、审查评论和请求审查者 - 推送、创建分支和打开 pull request(
write)从不以共享机器人身份签发,它们总是使用请求者自己的登录 - 在任何令牌上,批准 pull request 都绝不自动化
- 拥有自己 GitHub App 的服务器或工作区在所有这些事情上都保留机器人,包括审查
组织所有者和成员应当了解的事项
标题为“组织所有者和成员应当了解的事项”的部分- 有人登录的服务器持有其 App 用户令牌:每个令牌最长 8 小时,并一直续期直到他们断开连接。该令牌可以代表他们,在他们能访问的、共享 App 所安装的每个仓库上行事。Connect 可以彻底切断某台服务器(已退役或被拒绝的安装),但已交出的令牌在过期前仍然有效
- 在组织上安装共享 GitHub App,即是为每位成员登录的每台 Control Center 服务器授予同意,而不只是某一台服务器
- 如上所述,机器人是共享的:组织无法在 GitHub 上分辨出是哪台服务器以机器人身份行事
- 希望拥有自己边界的组织应注册自己的 GitHub App 并运行自己的 Connect(运行 Connect 服务器),或在自己的服务器上配置该应用
配置信任
标题为“配置信任”的部分| Connect | 服务器如何信任它的配置 |
|---|---|
| 托管 | 使用内置于构建版本的密钥验证 Ed25519 签名。拒绝低于它见过的最高世代号的配置(rollback) |
| 自定义 | 首次使用时固定 GitHub 应用 id 与客户端 id、Google 与 Linear 的客户端 id,以及 Slack 应用与客户端 id。任何变更都会暂停通过 Connect 的登录(pins_changed),直到服务器所有者点击信任新应用 |
服务器的 Connect 设置只限服务器所有者。
| 操作 | 作用 |
|---|---|
connect.status |
模式、地址、锁定、安装 ID、健康状态、配置世代号,以及每条通道的来源 |
connect.configure |
设置 hosted、custom(配合 url)或 off |
connect.test |
重新获取配置并报告健康状态 |
connect.confirmPins |
接受自定义 Connect 已更改的标识符 |
connect.rotateKey |
生成新的安装密钥和新的安装 ID(force 会在 Connect 无法退役旧的 ID 时替换它);参见轮换安装密钥 |
工作区自己的选择有独立的操作,每个操作都会指明工作区:
| 操作 | 谁 | 作用 |
|---|---|---|
workspaceConnect.status |
任何成员 | 选择、它解析为什么、健康状态以及每个提供商的来源。安装 ID 与待处理的固定项仅限管理员 |
workspaceConnect.set |
工作区管理员 | 设置 inherit、hosted、custom(配合 url)或 own |
workspaceConnect.test |
工作区管理员 | 重新获取该工作区的 Connect 配置并报告健康状态 |
workspaceConnect.confirmPins |
工作区管理员 | 接受该工作区自定义 Connect 已更改的标识符 |
登录本身使用 oauth.lanes、oauth.begin、oauth.status、oauth.complete、
oauth.connections 与 oauth.disconnect。登录者始终是已登录的调用者本人。
通过 Connect 登录
标题为“通过 Connect 登录”的部分- 服务器请求 Connect 开始该通道,并获得提供商的授权地址,在显示之前会先检查它。GitHub 始终会显示其账户选择器
- 用户在浏览器中批准。提供商返回 Connect
- Connect 会显示发起登录的服务器将能够以该用户身份做什么,以及持续多久。Connect 无法判断是谁在运行该服务器,因此页面只会在用户自己发起了登录时请其继续,如果是别人发给他们的链接则请其关闭页面。当浏览器所在的网络与发起登录的网络不同时,页面会说明这一点:对于托管服务器或其他设备来说这是正常的,但它也正是网络钓鱼的样子。取消会结束登录:提供商的代码永远不会被使用。每个页面只会应答一次:若应答不是来自 Connect 刚刚显示的那个页面,则会被拒绝
- 点击继续后,Connect 显示一组 8 个字符的代码,以及一个
control-center://oauth-done链接。任何拿到该代码的人都会获得刚刚批准的访问权限,因此它只应送往发起登录的地方 - 用户把代码输入应用,或点开链接。服务器凭该代码以及它自己对本次请求的证明认领这次登录
登录会在 10 分钟后过期。输错五次代码会使其结束。不是由此应用发起的链接会以
登录并非从这里发起拒绝。Connect 会限制一个网络地址能发起多少次登录,以及 GitHub 令牌按人与服务器、按人跨服务器、按地址以及对整个应用的签发频率。新登录有其自己的预算,因此它们绝不会拖慢其他人所需的续期。超过限制时,调用会以 rate_limited 被拒绝,服务器稍后会再试,且不会让任何人登出。超过该人限制的登录会在 GitHub 上被撤销并遭到拒绝。
轮换安装密钥
标题为“轮换安装密钥”的部分只有服务器所有者可以轮换密钥,方法是在 设置 → 服务器 → 单点登录 中的 Control Center Connect 卡片上点击轮换密钥。没有对应的命令。轮换会:
- 让每一条经由 Connect 的通道上的所有人登出。对于旧密钥曾被使用过的每台 Connect 服务器,服务器会撤销它从该处持有的 GitHub 与 Slack 登录(Google 登录没有可撤销的内容,会自行失效)
- 在每台这样的 Connect 服务器上退役旧的安装 ID。该请求以旧密钥签名,并以服务器从该 Connect 持有的一份凭据封存作为证明。此后 Connect 会拒绝所有使用旧密钥发出的请求,因此从本服务器获取的封存或旧密钥副本都将无用;绑定到旧 ID 的 Slack 工作区会被释放,以便它们可以重新连接。已经交出的令牌在过期前仍然有效(机器人令牌为一小时,个人令牌为八小时)。若服务器没有持有某台 Connect 的任何封存,则该 Connect 无可退役,会被跳过
- 然后为服务器分配新的安装密钥和新的安装 ID
- 若某台 Connect 服务器无法连接,或拒绝退役旧 ID,则会在切换密钥前停止,并显示 Connect 无法停用旧密钥。仍然轮换会无论如何切换密钥;此时旧安装 ID 在那台 Connect 上仍可使用,直到其令牌过期,对于 GitHub 最长为 8 小时
- 不影响通过服务器自有应用的登录
- 需要把新的安装 ID 加入自定义 Connect 的允许列表
状态代码
标题为“状态代码”的部分| 代码 | 含义 |
|---|---|
hosted_unprovisioned |
本构建版本没有托管配置密钥 |
signature |
托管配置未通过签名检查 |
rollback |
Connect 提供的配置比服务器已见过的更旧 |
unreachable |
服务器无法连接到 Connect |
install_blocked |
Connect 不允许这个安装 ID,或该 ID 已被退役 |
pins_changed |
自定义 Connect 公布了不同的应用标识符 |
protocol |
Connect 的响应格式是这台服务器无法理解的 |