镜像自 HugoXK/LaunchPad@5cfa983 · upstream · 在 GitHub 上编辑 docs/admin.md ↗

部署这套 bot 和管理员面板

本文写给部署和管理这套 bot 的人。只想把 bot 装到自己仓库的用户看 README 即可。

一个控制面负责管理页面、接收 GitHub Webhook 和调度任务;每个启用的仓库各有一台长期运行的 Docker 容器(下文称“虚拟电脑”),bot 在里面读代码、跑命令。新开的 Issue 和 PR 会收到一条检视总结评论;打开自动开发后,明确要求改代码的 Issue 由 bot 实现、测试并开 PR。

项目页的「项目知识」以真实目录浏览共享项目文件,可创建空目录、预览 UTF-8 文本或 Markdown、编辑、重命名/移动、下载及查阅历史。历史按需展开,旧版本只读;确认恢复后创建新版本,已有历史保留。不能预览的二进制只提供原字节下载,不能在文本编辑器中覆盖。搜索限定文件名/路径,没有语义索引;旧角色/私有记录仍按原授权过滤,仓库来源文件只读,正文修改走 PR。保存使用 expected_revision,冲突时保留草稿并比较最新正文;草稿只在当前登录页面内存中保留,退出即清除。

每个仓库的稳定笔记卷读写挂在 /workspace/project-notes(任务使用 ../notes/),停机、重建、禁用和重置代次后保留;页面由 manager 直接访问同一份文件,无需启动项目电脑,删除项目时随环境删除笔记卷。相对路径拒绝穿越、绝对路径及符号链接;目录须先创建。.write-history/file-tree.json 在原卷锁内维护稳定文件 ID、旧 n: 别名和可恢复移动日志;版本 blob 与历史不随路径改名。旧文件及历史按首次访问迁入,旧 m: 记录保留原存储和来源。备份时须保存整个笔记卷,包括 .write-history,不能只复制当前正文。manager 与项目 runner 必须从同一版本源码构建并一起更新;manager 完成电脑镜像恢复前不会开放文件接口。目录历史启用后,回退旧版文件服务须恢复升级前的整卷备份,不能只切回旧镜像。

/api/repositories/:id/knowledge-files 支持按 directory 浏览、query 全目录文件路径搜索、deleted_only=1 查找已删除文件;创建兼容根目录 name 和相对 path。文件以稳定 ID 读取/保存,POST /:id/move 带目标 path 与 expected_revision;versions 与 restore 保留原版本语义。knowledge-directories 的 POST/DELETE 创建或删除空目录,不能删除根目录。所有操作沿用项目知识权限,读取完成后再次校验授权。

准备

启动

不需要克隆仓库,也不在本机构建:

mkdir department-bot && cd department-bot
curl -fsSLO https://raw.githubusercontent.com/agent-CI-Infra/bot/main/compose.yaml
docker compose up -d

然后在这台机器的浏览器打开 http://127.0.0.1:8791/。Bot 装在远程服务器上时,先 ssh -L 8791:127.0.0.1:8791 <服务器>,再在自己电脑上打开同一地址。配好公网 HTTPS 入口后,也可以直接从那个地址使用控制台。

镜像发布在 GHCR,匿名拉取要求这些包已公开;如果拉取报 denied 或 unauthorized,克隆本仓库后从源码构建。

第一次配置

  1. 创建第一名管理员。 首页显示「创建第一名管理员」:填用户名和 12–256 位密码,点「初始化并登录」。初始化只成功一次,之后这里只有登录。
  2. 走完接入向导。 首次登录会自动打开「全局设置 → 接入向导」(仅系统超级管理员可用),按页内的七步走:
    1. 公网 HTTPS:选「自建 HTTPS 中转」,把一个专用域名整个反向代理到 http://<这台机器>:8791,填 https://<你的域名>,点「检查并使用」。或者选「Cloudflare Tunnel」,粘贴 tunnel token 点「保存 token」,在 Cloudflare 的 Published application 把 Service URL 设为 http://webhook:8791,回到向导点该路由的「检查并使用此域名」。这个域名是唯一的入口,控制台、登录和 Webhook 都走它,不需要第二个域名或端口;反向代理在另一台机器时,先在 .env 设置 BOT_BIND_ADDRESS=0.0.0.0。
    2. GitHub App:填「App 所属组织」和「App 名称」,点「准备 GitHub 确认页」→「前往 GitHub 确认创建」,在 GitHub 上确认后会回到向导。权限固定为 Contents、Issues、Pull requests、Commit statuses、Actions、Checks 写,Metadata、Members 读(Actions、Checks、Commit statuses 让检视和开发任务能用只读令牌查看 CI 状态,这三项的写权限留给控制面发布状态、检查结果和重跑 CI;之前创建的 App 要在 GitHub 上补加),订阅 issues、pull_request、issue_comment、pull_request_review、pull_request_review_comment、check_run、status 和 organization(已有 App 需由所有者在 Permissions & events 勾选 Issue comment、Pull request review、Pull request review comment 以触发评论和检视回复跟进,并勾选 Check run、Status 以向控制台推送 GitHub Actions 与提交检查状态;「检查权限和事件订阅」会列出缺少的事件);Webhook 地址 https://<你的域名>/hooks/github/<account_id>/<endpoint_id> 由向导写进 App,不用手填。已在「全局设置 → 机器人账号」登记过的 App 点「使用此 App」。
    3. GitHub 登录:创建独立的 OAuth App,按页面指引填写 Homepage URL 和 https://<你的域名>/auth/github/callback,复制这个 OAuth App 的 Client ID 并生成 Client secret,勾选启用并保存。仓库 GitHub App 与登录 OAuth App 分开配置;Secret 不回读,留空保留。本步骤可暂不启用,本地恢复账号继续可用。详见接入说明。
    4. 安装:点「在 GitHub 安装此 App」,选好仓库后回来点「重新检查安装」。
    5. 模型:在「添加模型」填接口 URL、API Key、模型名,点「保存并继续」。URL 下方会显示实际的对话地址和模型列表地址;bot 不会替你补上或去掉 /v1,地址不以 /v1 结尾时页面会提示。保存前可以点「获取模型列表」从上游选模型名,或点「测试模型」确认 URL、Key 和模型名可用。
    6. 规则:看一下内置规则,点「下一步」。
    7. 完成:点「同步已安装仓库」,在要用的仓库那一行点「启动并启用检视」。公网地址已验证、仓库 App 有效、至少一个安装范围已完整同步且有效、共享默认模型仍有 Key 时,才可点「完成向导」。暂时跳过安装不会标记为完成;可从「返回项目,稍后继续」离开并保留已保存配置。完成接入配置不等于项目已启用或任务正在运行。
  3. 确认跑通。 在已启用的仓库新开一个 Issue,bot 会在上面回复一条检视总结评论(之后再检视同一个 Issue 或 PR 时改写这条评论,不再新发);第一次要先启动该仓库的虚拟电脑,会慢一些。没等到时,到「任务看板」和「待处理」查看是否已经有对应任务。

日常使用

「待处理」只列出需要关注的任务,优先展示服务端记录的处理说明。任务详情中的模型、角色或环境配置故障提供对应的项目配置入口;由此进入配置页后,可用「返回待处理列表」回到原项目范围和分页。保存配置不代表任务已经恢复,返回后会重新读取任务记录。关闭任务详情也会刷新原列表,仍待处理时恢复到该任务的按钮,否则把焦点移到刷新入口;不会把自动排队计为人工待办。

不再需要任何人处理的任务会自动移出「待处理」(#713),改为 bot 自行停止的 cancelled(与 #655 相同),原因码写明是哪种情况:同一 Issue 或 PR 上已有更新的同类任务接手(obsolete_superseded;更新的那个也是 bot 自行停止的不算);Issue 或 PR 已关闭或合入,包括后续任务来源的那个(obsolete_closed,以 webhook 和任务输入记下的对象状态为准,没见过关闭的视为仍开着);以及超过 BOT_OBSOLETE_FAILURE_DAYS(默认 7 天)的平台类或临时失败、之后任务没有任何变化(obsolete_expired,只针对 failed)。后台每 15 分钟按创建时间从旧到新清扫一小批,同一工作的新任务开始时也立即清扫它之前的任务。手动暂停的任务、对象仍开着且未被取代的求助、权限等待和待确认的发布,以及引擎会自行重试的等待(重试等待、配置、环境、PR head)一律不动。被移出的任务保留历史、结果和原来的失败:时间线记下移出原因、原状态和原失败码,看板卡片回到最近一个不是 bot 自行停止的任务所在列,待处理列表和项目总览的计数同时变化;仍需要时可在任务详情点「重试」,按原状态重新开始。

在任务看板或项目总览打开“新建任务”;手机也可从底部“更多”进入。选择项目并填写原始需求、目标、工作范围、验收条件和交付类型。页面先读取服务端执行上下文;提交沿用当前身份和项目角色配置,代码 PR 仍需原有写入授权、验证及独立 QA。服务端回执分别显示已创建和失败;只有获得真实任务编号才提供详情入口。网络中断时保留本页草稿并核对同一次提交,不能改写需求后盲目重建。草稿仅保存在当前网页内存,退出登录或网页重新载入后不保留;结果未知时先在管理审计中核对。

项目「机器配置」将 manager 实时核验与保存的状态记录分开展示。连接失败、记录缺失、管理服务恢复中和状态异常分别显示对应提示,不能据旧的“就绪”判断当前可用;核验时间不代表心跳。资源指标缺失显示未知,真实零值仍显示零;超过 30 秒的采样或读取失败时保留的上次采样会明确标记。运行与排队数量可进入同一项目活动页核对。刷新只更新状态,保留表单草稿、已展开日志和焦点;授权失效会清除原电脑内容与配置。

配置按资源上限、软件与初始化、网络与环境变量分组,各字段分别标明全局默认或项目控制台来源;仓库里的 .bot/computer.yaml 不再读取(#935)。资源的配置目标与电脑报告分开展示,全局默认等待重建时不据目标值宣称运行中容器已应用。保存影响区列出本组未保存的字段及重建、后台进程结束和工作卷保留的影响;项目任务并发单独保存,与角色限额分开,也不会重建电脑。已保存的机器配置读取失败时,各字段显示来源未知并禁止保存;点击「重新读取电脑配置」重新读取。机器页不等待、也不读取默认分支(#935)。读取失败会在入口旁显示原因,仍可重试。

项目的「基本设置」按概况、分支、标签(检视标签和开发标签)、监听与触发入口和公开可见性分组;仓库还留着已导入的 .bot/ 文件时,概况里提示可以删除,能力上限和事件来源统一在项目「监听与触发」页编辑;启用、禁用与删除集中在危险区。分支和「监听与触发」页功能策略的未保存输入只在当前浏览器页面内存中保留,切换页面再返回或使用「刷新项目设置」不会丢弃草稿;重新载入整个网页后不保留。保存失败保留输入,可显式放弃本组草稿。项目列表和基本设置中的公开看板开关共用范围确认,列明目标项目;开启和关闭分别确认,取消不保存,失败保留原状态并显示原因。私有仓开启时也会说明无需登录的公开范围,且不随项目禁用自动关闭。

「成员」按当前项目展示实际授权来源、范围、状态和时效:「来自 GitHub(继承)」(仓库 Admin、组织 owner)、「来自 GitHub:Write/Maintain 协作者」「来自 GitHub:Triage/Read 协作者」、「来自组织授权(继承)」、「项目管理员 <名字> 授予」和「本项目手动分配」。读取需要本项目配置权限。项目管理员在页面底部「授权成员」里按 GitHub 用户名授出只读、成员或项目管理员,只能授出自己在本项目拥有的权限,也能逐条撤销本项目里不超出自己权限的委派;由项目管理员授予的权限只在授予人仍有这些权限时有效,否则显示为暂停(规则见项目内委派)。整个组织的授权和平台角色仍只由超级管理员授予;旧式项目管理员分配仍仅由平台管理员(用户页显示为「管理员」)编辑,移除项目分配不会撤销组织继承或独立委派。

项目「模型」页和「全局设置 → 模型」按供应商(同一范围、同一请求地址)分组显示模型。列表只在供应商标题旁提供「编辑供应商」,「新增供应商」使用同一套表单:连接信息在上,选择或手动添加模型在下。获取模型列表只在该表单提供,不再逐条模型重复展示;可以选择多个模型,保存时一并添加,也能填写列表外的模型名。

编辑供应商时,修改 URL 会更新组内全部模型;填写新 Key 会统一更换,留空保留各模型现有 Key。「撤销供应商 Key」是编辑表单内的独立操作,确认后撤销这组模型的 Key,不保存尚未提交的 URL 或待添加模型。Key 加密保存且不回显。已有数据即使同一地址下使用了不同 Key,也不会因为留空保存而丢失;只有明确填写新 Key 时才统一替换。供应商操作在一个事务中完成,其他页面修改过模型或组内模型有变化时拒绝过期保存,提示重新打开编辑。模型 ID、项目选择和计费单价保持不变。

模型行提供测试、修改模型名、计费单价、能力与目录和删除。「能力与目录」显示匹配条目与快照时间,可自动匹配、手动选择或取消匹配,并按字段覆盖上下文窗口、最大输出和推理能力;能力留空继承目录,没有匹配时使用默认值。目录每 6 小时刷新,超级管理员可立即刷新;失败保留旧快照并显示失败状态。目录价格以 USD 计价,不与 CNY 混算。共享供应商仍只有超级管理员能修改,项目管理员只能编辑自己负责项目的专属供应商。新增供应商至少添加一个模型,不保存空的供应商记录。

供应商列表

供应商统一编辑表单(390px)

在项目「模型」中,本项目专属模型行的「删除」会先读取并列出项目默认/工作类型引用、当前已保存角色的显式引用(包括停用角色),以及接入默认模型的影响;历史角色版本和运行快照不计入当前引用。完整引用读取失败时不能确认删除。确认后只删除本系统的模型配置并销毁封存的 API Key,不会删除 GitHub 上的任何东西。项目管理员可删本项目专属模型;部署共享模型只能在「全局设置 → 模型」中由超级管理员删除,删除后所有项目都不能再选它。项目默认选择会改回「不使用模型」,任务专属选择保留为不可用,相关任务进入「配置待补」。项目角色的显式引用保留为不可用,之后执行等待补充配置,不换用其他模型;平台服务角色改为未配置模型。已经运行的任务不会被取消,已有请求和成本记录保留,仍按当时记下的模型名和单价展示。删除失败会留在确认框中,可重试或取消;删掉的若是接入向导的默认模型,这个默认随之清空。

修改 CI

bot 不再生成门禁文件。要改 CI 时,项目管理员在「新建任务」写明要改什么,交付类型选「可检视的代码 PR」并勾选「允许修改 .github/workflows/(CI 改动)」;bot 按仓库自己的情况修改 workflow,测试和独立 QA 通过后开 PR,人检视合并后才生效。只有这样确认的任务推送时才申请 Workflows 权限,github_write 不能写 .github/workflows/。详见接入说明。

排查失败

docker compose -p bot logs --since 1h manager   # 虚拟电脑:Docker 失败、恢复失败、意外异常
docker compose -p bot logs --since 1h bot       # 控制面:对账、任务运行故障、外部转发

任务记录里的消息先经过脱敏;日志只写错误码、Docker 的说明、异常消息和出错位置,不写请求内容和凭据。

升级与数据

在 compose.yaml 所在目录运行:

docker compose pull
docker compose up -d

数据在五个部署卷里:bot-data(控制面数据库)、bot-keys(加密凭据的主密钥)、internal-keys(bot 与 manager 的内部认证)、manager-data(虚拟电脑账本及各项目笔记卷的文件)和 assistant-homes(群聊助手、管理助手电脑的持久 HOME);tunnel-keys 只放 Cloudflare Tunnel token。丢了主密钥,已保存的 App 私钥和模型 Key 都解不开。docker compose down 会保留卷;日常升级不要加 -v(--volumes),它会删掉这些卷。备份见备份与恢复。

以前在仓库根目录用 docker compose up --build -d 从源码部署的实例,更新代码后再运行 docker compose up -d 会改为拉取 GHCR 镜像(同一目录,数据卷不变);要继续从源码构建,改用 docker compose -f compose.yaml -f compose.build.yaml up -d --build。

常用设置

在 compose.yaml 同目录的 .env 里写变量,然后重新 docker compose up -d:

全部变量见端口与环境变量。

文档

知识文件移动恢复出现 note_move_uncertain 时,本项目知识区会保持拒绝读写,不应手工清空 pending。停写、整卷备份与恢复步骤见知识文件恢复。