跳转到内容

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 永远看不到
服务器的安装 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 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。登录者始终是已登录的调用者本人。

  1. 服务器请求 Connect 开始该通道,并获得提供商的授权地址,在显示之前会先检查它。GitHub 始终会显示其账户选择器
  2. 用户在浏览器中批准。提供商返回 Connect
  3. Connect 会显示发起登录的服务器将能够以该用户身份做什么,以及持续多久。Connect 无法判断是谁在运行该服务器,因此页面只会在用户自己发起了登录时请其继续,如果是别人发给他们的链接则请其关闭页面。当浏览器所在的网络与发起登录的网络不同时,页面会说明这一点:对于托管服务器或其他设备来说这是正常的,但它也正是网络钓鱼的样子。取消会结束登录:提供商的代码永远不会被使用。每个页面只会应答一次:若应答不是来自 Connect 刚刚显示的那个页面,则会被拒绝
  4. 点击继续后,Connect 显示一组 8 个字符的代码,以及一个 control-center://oauth-done 链接。任何拿到该代码的人都会获得刚刚批准的访问权限,因此它只应送往发起登录的地方
  5. 用户把代码输入应用,或点开链接。服务器凭该代码以及它自己对本次请求的证明认领这次登录

登录会在 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 的响应格式是这台服务器无法理解的