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

部署细节

日常部署只需要仓库根目录的 compose.yaml,上手步骤见部署这套 bot 和管理员面板。本文说明镜像、从源码构建、版本发布与服务器部署、端口与环境变量、服务隔离和备份。

镜像

main 分支每次推送后,.github/workflows/images.yml 构建并发布下列 linux/amd64 镜像,标签为 latest 和 sha-<12 位提交>;Pull request 和合并队列只构建、不发布。发布版本时这些镜像再加上版本标签,见版本发布与服务器部署。

镜像 用途 Dockerfile Compose 服务
ghcr.io/agent-ci-infra/bot-control-plane 控制面:管理页、登录、GitHub 回调、Webhook 接收、任务调度;也用来生成密钥和运行入口网关 Dockerfile bot、key-init、webhook
ghcr.io/agent-ci-infra/bot-computer-manager 创建和运行各仓库的虚拟电脑,唯一挂载 Docker socket 的服务 manager/Dockerfile manager
ghcr.io/agent-ci-infra/bot-project-computer 每台虚拟电脑的系统镜像(批准镜像) images/project/Dockerfile project-image
ghcr.io/agent-ci-infra/bot-cloudflare-tunnel 可选的 Cloudflare Tunnel 连接器 tunnel/Dockerfile tunnel

控制面运行镜像和项目电脑镜像都预装 Debian 的 chromium(经 /usr/local/bin/bot-chromium 启动,BOT_BROWSER_EXECUTABLE 指向它),供任务浏览器在容器内直接启动,不必再 apt。包装脚本会把 Chromium 的 HOME 固定指到 BOT_BROWSER_HOME(默认 /tmp/bot-chromium-home),以便在只读根文件系统、没有家目录的控制面容器里写入 crashpad 数据。预装不等于开放任意外网:任务浏览器仍只访问该任务列出的源。助手电脑沿用项目电脑基础镜像,现有无网络边界不变,不能因此获得通用外网浏览。manager 与 tunnel 镜像不预装浏览器。合入本改动后也不会自动部署。

webhook(入口网关,服务名沿用旧名,Cloudflare 路由不用改)和 bot 用同一个镜像,但仍是单独的容器:只有它同时在 control 和 edge 两个网络,tunnel 只能经它连到 bot 的业务端口 bot:8791,连不到 manager。compose.yaml 默认使用 latest,在 .env 设置 BOT_IMAGE_TAG 可以把所有镜像固定到某个版本(如 v1.2.0)或 sha-<12 位提交>。manager 不拉取镜像,只检查 BOT_PROJECT_IMAGE 指向的本机镜像,所以它必须和 project-image 服务的镜像引用(含标签)完全一致;一次性的 project-image 服务负责让 Compose 把这个镜像拉到本机。

从源码构建

compose.build.yaml 只把镜像换成本地标签 department-bot*:local 并加上构建上下文,其余配置都来自 compose.yaml,所以两个文件一起使用:

docker compose -f compose.yaml -f compose.build.yaml up -d --build

需要验证未发布的改动、GHCR 包还没公开或者机器拉不到 GHCR 时用它。Compose 项目名取第一个文件所在的目录名,同一目录里在两种方式之间切换会沿用原来的卷;虚拟电脑在下次准备时换成新的批准镜像,工作卷和代次不变。以前在仓库根目录用 docker compose up --build -d 部署的实例,更新代码后如果只运行 docker compose up -d,会改为拉取已发布镜像;要继续从源码构建,就用上面的命令。

版本发布与服务器部署

在 main 的提交上打 v* 标签并推送(例如 git tag v1.2.0 origin/main && git push origin v1.2.0),.github/workflows/release.yml 依次:

  1. 确认该提交在 main 上,并等待 main 为它发布 sha-<12 位提交> 镜像;
  2. 不重新构建,给这四个镜像加上同名版本标签,所以版本运行的正是合并队列检查过的镜像;
  3. 创建 GitHub Release,列出镜像并附自动生成的变更说明;带后缀的标签(如 v1.2.0-rc.1)是预发布;
  4. 部署到 production 环境配置的服务器;还没配置服务器时跳过并在运行页提示。

要给某次推送到 main 的最新提交打标签:合并队列一次合入多个 PR 时只有最后一个提交发布镜像,main 的新推送也会取消旧提交还没完成的发布,这些提交打标签会失败。

部署经 SSH 把该版本的 compose.yaml 写到服务器目录,在同目录 .env 里写入 BOT_IMAGE_TAG=<版本>(其他设置保留),然后运行 docker compose pull,清理上次中断留下的替换容器,再运行 docker compose up -d --force-recreate,等 bot 的健康检查通过。服务器上这两条命令由 GNU coreutils 的 timeout 限时:pull 最多 15 分钟,重建最多 35 分钟(manager 可能用满 30 分钟的启动宽限),再加上 bot 最多 85 分钟的健康等待(含每轮两次 docker inspect 往返约 88 分钟),都算在部署步骤的 145 分钟里。到点先发 SIGTERM,30 秒宽限期后仍未退出就以 SIGKILL 结束,本次部署以非零状态失败(正常到点是 124,用到宽限期时是 137),与健康检查失败的报错分开;排除原因后重跑同一次运行即可收敛。compose.yaml 每次发布都会被覆盖,服务器自己的设置放在 .env 或 compose.override.yaml。

部署要能重跑。Compose 重建一个容器时,先以 <旧容器 id>_<项目>-<服务>-<序号> 创建替换容器,再删掉旧容器,最后把替换容器改回 <项目>-<服务>-<序号>。中途退出(例如 Docker 停不掉某个容器)会给同一个服务留下第二个容器:普通 up -d 会沿用它并保留临时名,--force-recreate 则会因为旧容器还占着名字而失败。所以部署在 up 之前,先删掉本项目服务中名字不是 <项目>-<服务>-<序号> 的容器(只查 docker compose ps 列出的服务容器,不碰 manager 创建的项目电脑;替换容器没有数据,数据都在卷里),再用 --force-recreate 按该版本的 compose.yaml 重建全部服务。发布本来就会换掉所有镜像标签,每个容器都会重建,所以正常部署的停机时间不会因此增加。部署中断或失败后,先看日志排除原因,然后在 Actions 里对该次 Release 运行选择 Re-run failed jobs,只重跑 deploy 任务即可恢复到该版本,不需要上服务器手工处理。任何一步失败时,日志末尾都有 docker compose ps -a 列出的每个容器及其状态;bot 容器停止,或 85 分钟内没有变为健康时,还会附上它最近 50 行日志;等待期间每分钟输出一次压缩进度(见启动时压缩数据库)。manager 启动时要逐个恢复已保存的项目,期间 up -d 等它健康后才启动 bot,这段等待算在 up -d 里。npm run test:deploy:docker 用真实 Docker Compose 验收这一步,见开发说明。

在仓库 Settings → Environments → production 中配置:

名称 类型 作用
DEPLOY_HOST 变量 服务器地址;不设置时只发布、不部署
DEPLOY_PORT 变量 SSH 端口,默认 22
DEPLOY_USER 变量 SSH 用户,需要能运行 docker compose,以及 GNU coreutils 的 timeout(要能解析 15m、35m 这类时长后缀,缺了会在 pull 前以 127 失败)
DEPLOY_PATH 变量 服务器上放 compose.yaml 的目录。目录名就是 Compose 项目名,接管已有部署时用它原来的目录,才会沿用原来的卷
DEPLOY_KNOWN_HOSTS 变量 服务器的 known_hosts 行,可用 ssh-keyscan -p <端口> <地址> 获取,核对指纹后填写;主机密钥不符时部署停止
DEPLOY_SSH_KEY Secret 部署用 SSH 私钥
DEPLOY_JUMP_HOST 变量 可选的 SSH 跳板机地址;不设置时直接连接目标服务器
DEPLOY_JUMP_PORT 变量 跳板机 SSH 端口,默认 22
DEPLOY_JUMP_USER 变量 跳板机 SSH 用户;设置跳板机地址时必填
DEPLOY_JUMP_KNOWN_HOSTS 变量 核对过指纹的跳板机 known_hosts 行;设置跳板机地址时必填

需要跳板机时,DEPLOY_HOST 和 DEPLOY_PORT 仍填写从跳板机能访问的目标服务器地址和 SSH 端口。工作流使用 ProxyJump 转发,跳板机必须允许到该目标的 TCP 转发。跳板机和目标服务器复用 DEPLOY_SSH_KEY,将其对应公钥分别加入两个 SSH 用户的授权列表即可;私钥只由 Actions runner 使用。两台机器的主机公钥记录会合并写入 known_hosts,并对两段连接都启用严格校验。跳板端口不是 22 时,其记录的主机字段应为 [<跳板地址>]:<跳板端口>。

可以在 Actions → Release → Run workflow 手动检查连接,或运行 gh workflow run release.yml --ref main。手动运行只验证 SSH 登录并显示远端用户,发布作业和部署步骤都跳过,不打标签、不创建 Release、不更新服务器文件或容器;目标服务器未配置时检查失败。以后推送 v* 标签仍按原流程发布、检查 SSH 连接并部署。

GHCR 包还没公开时,先在服务器上用有 read:packages 权限的令牌运行一次 docker login ghcr.io。

端口与环境变量

控制面只有一个业务监听:容器端口 8791。管理页面和管理 API、GitHub 用户登录(/auth/github/*)、App 注册回调和安装 Setup 回调(/onboarding/github/*)、GitHub Webhook(/hooks/github/<account_id>/<endpoint_id>)、飞书事件、外部执行端兑换令牌(/external/*)、公开看板(/dashboard/、/boards/)、向导地址检查(/.well-known/bot-webhook-probe)和 /healthz 都在这个端口上按路径分派,各自的校验不因合并而改变:管理 API 要求登录、权限、CSRF 令牌和合法 Origin;OAuth 回调校验 state、PKCE 和浏览器 cookie;Webhook 只按原始请求体验签,不需要浏览器会话。manager、虚拟电脑和 tunnel 指标接口不在这个端口上,也不对宿主或公网发布。

Compose 只发布这一个端口,宿主端口默认 8791,默认只绑定宿主回环地址 127.0.0.1:这个端口同时提供控制台和首次初始化,不应以明文 HTTP 直接暴露到局域网或公网。对外统一使用一个 HTTPS origin(例如 https://bot.example.com),由同机的 HTTPS 反向代理或 Cloudflare Tunnel 把整个域名转发到这个端口,不按路径拆分。反向代理在另一台机器时,设置 BOT_BIND_ADDRESS=0.0.0.0(或某个网卡地址),并用防火墙只对代理开放该端口。HTTPS 反向代理应转发原始 Host;生产环境可设置 BOT_COOKIE_SECURE=true。管理 API 不开放跨域访问。

写请求接受这些 Origin:BOT_PUBLIC_ORIGIN(未设置时为按请求 Host 和 BOT_COOKIE_SECURE 推导的地址)、向导验证的公网地址、升级前登录配置保存的控制台地址,以及 Host 为 127.0.0.1 或 localhost 的本机请求。入口地址尚未接通或填错时,仍可在这台机器上打开 http://127.0.0.1:8791 登录修复;DNS 重绑定无法伪造回环 Host,所以这条例外不会放行其他网站。

下列变量从启动 Compose 的 shell 环境或 Compose 文件同目录的 .env 读取,都不包含上游凭据:

变量 默认值 作用
BOT_IMAGE_TAG latest 所有镜像的标签:版本(如 v1.2.0)或 sha-<12 位提交>;也传给控制面进程,「全局设置」显示它作为当前运行版本。叠加 compose.build.yaml 时不选择镜像,控制面收到空值,页面显示源码运行
BOT_PORT 8791 唯一业务端口的宿主端口
BOT_BIND_ADDRESS 127.0.0.1 业务端口的宿主绑定地址;只有反向代理在另一台机器时才改为 0.0.0.0 或具体网卡地址
BOT_PUBLIC_ORIGIN 空 部署的统一入口 origin,例如 https://bot.example.com,不含路径;只允许 HTTPS,本机测试可用 http://localhost 或 http://127.0.0.1(可带端口),格式不符时控制面拒绝启动。它始终是写请求的合法 Origin;向导尚未验证公网地址时,也用于 GitHub 登录回调和消息链接。向导验证过的地址优先用于生成这些 URL
BOT_COOKIE_SECURE false 设为 true 时强制 Secure Cookie;经 HTTPS 的统一入口或部署地址登录时也会自动使用 Secure,本机回环 HTTP 登录的 Cookie 不受影响
BOT_WEBHOOK_PORT、BOT_ADMIN_PORT、BOT_ADMIN_ORIGIN — 旧变量,处理方式见从双端口升级
BOT_COMMAND_TIMEOUT_MAX_SECONDS 600 模型命令显式超时的统一上限(秒,1–2147363);超过时按上限执行并返回 timeout_notice,省略参数保留各入口默认值,见执行运行时
BOT_PROJECT_EGRESS true 设为 false 时虚拟电脑没有外网出口
BOT_GITHUB_API_URL https://api.github.com GitHub API 地址
BOT_GITHUB_OAUTH_CLIENT_ID 空 独立 OAuth App 的 Client ID 部署默认值;也可在全局设置的接入向导配置
BOT_GITHUB_OAUTH_CLIENT_SECRET_FILE /run/secrets/github-oauth-client-secret(Compose) 使用环境变量启用 OAuth 时读取的只读 Client secret 文件;向导配置不需要此文件
BOT_MENTION_NAMES bot,agent-ci-infra-bot 评论中提到时一定再检视一次的 @名字,逗号分隔、忽略大小写;设置后替换默认值,off 关闭提到触发。不提到名字的评论是否触发,由项目「检视」里的更新开关决定
BOT_OBSOLETE_FAILURE_DAYS 7 平台类或临时原因的失败(限流、GitHub 或模型不可用、上下文或响应超限、运行异常等)在这么多天里没有新动静后自动移出「待处理」,见日常使用
BOT_NOTES_RECLAIM_ATTEMPTS、BOT_NOTES_RECLAIM_DELAY_MS 6、60000 已提交删除留下的笔记卷的重试次数与首次重试间隔(毫秒,逐次翻倍,上限 1 小时);次数用尽记 repository.notes_volume_abandoned 审计并计入 /readyz 的 abandoned。两项都必须是正整数,否则控制面拒绝启动
BOT_NOTES_ORPHAN_THRESHOLD、BOT_NOTES_ORPHAN_MAX_AGE_MS、BOT_NOTES_ORPHAN_WARN_AGE_MS 10、604800000、86400000 /readyz 的孤儿笔记卷阈值:数量超过阈值或最老一份超过最大年龄时返回 503;警告年龄只报告不判失败。毫秒值必须 ≥ 1000,非法值使控制面拒绝启动
BOT_FORWARD_PRIVATE_HOSTS 空 外部执行端允许转发到的内网主机名,逗号分隔,见外部执行端
BOT_TRUSTED_PROXIES 空 密码登录限流信任的代理 IP 或 CIDR,逗号分隔;默认不信任转发头,只按连接来源计数。只填写受控代理的地址或专用代理网络,配置方式见下文
BOT_AGENT_TOOLS_DIR /opt/agent-tools 控制面进程读取与安装受信任 Agent CLI(Claude Code、Codex)二进制的目录;Compose 中固定挂在具名卷 agent-tools,本机源码直接运行时可指定本地目录

反向代理后的密码登录限流

反向代理后的用户会共享代理的连接地址。支持此配置的 Bot 版本可通过 BOT_TRUSTED_PROXIES 按真实客户端区分密码登录的失败计数:在 Compose 同目录的 .env 中填写逗号分隔的代理 IP 或 CIDR,Compose 将它传入 bot 容器。只有直接连接 Bot 的对端可信时,才读取 X-Forwarded-For(缺少时回退到 Forwarded),从右向左跳过已配置的可信代理,取第一个非可信地址。未配置、直接对端不可信或没有可用来源地址时,仍按连接地址计数。

地址以 Bot 实际看到的对端为准:Cloudflare Tunnel → webhook → bot 拓扑中,直接对端是 webhook 容器;同机代理经过 Docker 端口映射时,也不一定呈现为 127.0.0.1。先核对实际连接来源和 Docker 网络。代理地址固定时使用精确 IP;需要 CIDR 时只信任受控代理所在的最小专用网段,并限制谁能接入该网络。不要默认信任全部内网,也不要使用 0.0.0.0/0 或 ::/0。

可信入口必须覆写客户端自行提供的来源头,或在已有链末尾追加它实际核实的连接来源,并清理不可信的冲突头;X-Forwarded-For 优先于 Forwarded。多级代理应保留可核验的完整链,并只把实际受控的中间代理加入信任列表。本仓库的 webhook 网关原样转发请求头,不会生成或验证真实客户端地址,所以必须先确认 Cloudflare 或自建 HTTPS 入口满足这些要求,再启用信任。仅设置环境变量不能为缺失的转发头补出客户端地址。

修改 .env 后重新创建 Bot 容器(docker compose up -d bot),单独重启已有容器不会应用新的环境变量。可用 docker compose exec bot node -p "process.env.BOT_TRUSTED_PROXIES" 核对容器实际收到的配置。验收时同时检查:同一可信代理后的客户端 A 触发失败限流后,客户端 B 仍可正常登录;不可信来源仅更换转发头不能绕过限流。

服务、卷与隔离

Compose 包含长运行的 bot、manager、webhook、tunnel,以及一次性的 key-init 与 project-image。key-init 首次启动时生成主密钥和内部认证。project-image 仅确保批准的项目镜像已在本机 Docker 中(compose.yaml 拉取,加上 compose.build.yaml 时构建),不是某个仓库的长期环境。tunnel 在向导保存 Cloudflare Tunnel token 之前不连接任何账号;它只在独立的 edge 网络,经 webhook 入口网关固定转发到 bot:8791,不能直接连接 bot 或 manager。manager 按仓库创建动态项目容器,按群或私信的归属创建短时的助手电脑容器(无网络,空闲到期即删除),它们都不属于 Compose 静态服务,不对宿主或公网发布端口;manager 启动时删除上次留下的助手电脑。

bot-data 保存控制面 SQLite、仓库 Git 镜像(/data/git-cache,只是缓存,删掉后任务会重新从 GitHub 拉取;控制面进程的 BOT_GIT_CACHE_DIR 可改位置)以及任务浏览器截图证据(browser-evidence/,与轨迹正文共用保留窗口),bot-keys 保存加密主密钥,仅 bot 可读;internal-keys 保存 bot 与 manager 的内部认证,manager 不挂载上游凭据或控制面数据库。manager-data 保存环境和操作账本。assistant-homes 保存群聊助手和管理助手电脑的持久 HOME(每个群或每个人一个目录,按代次分子目录):bot 以与这些电脑相同的用户(10001)读写挂载,manager 只读挂载,用来找到卷名,并为每台助手电脑只挂入一个归属当前代次的子目录(Docker 卷 subpath,需要 Engine API 1.45 及以上)。agent-tools 保存受信任的 Agent CLI(Claude Code 及其绑定 Node 运行时、Codex 静态二进制)多版本目录与来源 manifest.json(#705):bot 以用户 10001 读写挂载在 /opt/agent-tools,仅经哈希校验后的超级管理员安装接口写入;manager 只读挂载在 /opt/agent-tools 以核验该卷的 Compose/平台标签,并将其只读挂入每台项目电脑和按运行隔离的 RunEnvironments 容器的 /opt/agent-tools,任务进程无权修改。tunnel-keys 只放 Cloudflare Tunnel token 文件。每个环境代次拥有独立具名工作卷和内部网络,标签同时绑定部署、仓库 ID、代次和资源类型。部署 ID 从独立内部认证材料派生,不同部署不会共用资源名。

只有 manager 挂载 Docker socket;它以 UID 0、GID 10001 访问 socket 和只读内部认证卷,丢弃所有 capabilities、禁止提权、根文件系统只读。Docker socket 本身仍赋予 manager 管理宿主 Docker 的能力,因此不对宿主发布 manager 端口,也不向项目网络提供该接口。它只接受登记项目的固定生命周期和 runner 请求,不能指定任意镜像、挂载、容器 ID 或 Docker API。bot 和项目容器没有 socket,项目容器也不挂载任何认证卷。bot/manager 使用独立控制网络,每个项目使用自己的 bridge 网络,项目之间互不可达。项目容器默认可以访问外网,用于安装依赖和访问测试地址;设置 BOT_PROJECT_EGRESS=false 可改回无出口的内部网络。外网出口意味着仓库代码也能访问宿主在 0.0.0.0 上发布的端口,以及公网入口本身;业务端口默认只绑定回环地址,项目容器经宿主地址访问不到它。设置 BOT_BIND_ADDRESS=0.0.0.0 后,项目容器和局域网一样能连到控制台和 Webhook(仍需登录或签名)。GitHub 和模型凭据仍不进入项目容器。

控制面在单线程上处理请求、定时任务和所有任务;一段同步工作(很重的查询、很大的 JSON)没返回之前,其他事情都得等,等到的请求可能已经超时。bot 日志里的 [stall] event loop blocked ~N s; requests finished while blocked: …; requests in flight: … 表示线程被占了约 N 秒。占住线程的同步处理在定时器恢复前就已结束,所以通常列在「finished while blocked」里;「in flight」是排在它后面等待的请求(都只有方法和路径,不含查询参数)。两项都是 none 时,占用来自后台工作(引擎、定时任务)。[slow] <方法> <路径> <毫秒> ms 是用时 5 秒以上的请求;[slow-sql] <毫秒> ms <get|all|run|begin|commit|transaction> <SQL 指纹> 是单次执行或提交达到 100 ms 的同步 SQLite 操作(只保留语句结构,不含绑定参数和字面量值);[slow-migration] <表> <read|verify|apply> <毫秒> ms (<行数> rows) 是后台正文迁移单片同步步骤达到 200 ms 的记录。排查控制台打不开或任务因超时失败时,先看这几类日志。

任务工作区清理

每个任务在项目电脑上有自己的目录 /workspace/tasks/<工作区 ID>,里面是任务上下文和 agent 状态。仓库检出(#769)是共享的 git worktree,放在 /workspace/worktrees/<worktree ID>,任务目录里的 repo 是指向它的链接,测试装的依赖和构建产物在 worktree 里;观察者角色和独立 QA 的检出也是 worktree:各用一个自己的任务目录,链接到停在候选提交上、为读而建的 worktree;Git 缓存不可用时的文件拷贝、从文件拷贝复制出来的评估者检出和隔离运行环境仍是任务目录里自己的 repo。控制面在 task_workspaces 表里记录每个任务目录和 worktree 被哪些任务用过:任务自己的目录、评估者和其他角色检出固定候选用的目录(kind 为 checkout)、重试恢复或集成用到的旧工作区,以及任务用过的 worktree(kind 为 worktree,每个用到它的任务各一行)。重试和重置会把 tasks.workspace_id 清空,旧目录仍能按这份记录找到所属任务。

worktree 的登记在 worktrees 表:所在电脑代次、HEAD 和 HEAD 的 tree、为读还是写而建、能否交出(ready、refused、removed)。每次任务拿到一个 worktree 记一行 worktree_bindings(任务、任务目录、读或写、拿到时的提交),同时写任务历史 workspace_bound(含 decided_by:system、agent 或主控角色),这就是“这次运行用了哪个 worktree、哪个提交、谁选的”的记录。

准备阶段只把提交传到电脑上的对象库,不建 worktree:worktree_plans 记下任务目录要用的提交和读写方式(planned),任务上下文的 workspace 字段写明还没有绑定。任务的主控(Manager)可以在委派之前先替任务选(list_workspaces、use_workspace、create_workspace,见下),被委派的角色就在它选的 worktree 里工作,自己不能再选;任务固定下来的角色配置没有让主控安排这类任务时(角色团队没打开,或这类入口没交给主控,例如按旧配置运行的历史任务),由执行任务的 agent 自己选。主控读 read_version_context 不会占用 worktree:任务还没绑定时,结果里没有 workspace_head_ref,而是 workspace 写明计划的提交。没人选时,任务第一次读仓库文件或运行命令时,由系统按下面的规则选,不需要多一个回合。runner 的文件工具和命令找不到 repo 时经邮箱请控制面绑定后重做一次;Claude Code、Codex 角色用 CLI 自己的文件工具直接读写检出,所以在 CLI 启动前就按同一规则绑定;任务上下文(../context/)、项目笔记和 agent 会话不需要 worktree,所以从不读仓库文件、也不运行命令的任务只用自己的任务目录,不建 worktree。Git 缓存不可用时的文件拷贝、需求任务和集成照旧在准备阶段建好。系统的选择:

任务自己选时,系统仍保证:

控制面启动 5 分钟后清理一次,之后每小时一次,逐台处理运行中的项目电脑:先经 runner 列出任务目录(只返回目录名和最近活动时间),再按下表决定,然后经 runner 每次删除最多 10 个目录,两次之间停 1 秒,让同一电脑上的任务调用先走;之后用同样的方式和同一张表处理 /workspace/worktrees(worktrees_list、worktrees_remove)。一个目录或 worktree 被多个任务用过时,以最晚才能删的那个任务为准,所以 worktree 只在所有用过它的任务都不再需要、且过了保留天数后才删除。删除任务目录只删掉其中的链接,worktree 留下。

用到目录的任务 规则
未结束:运行中、排队、准备中、发布中、等待(retry_wait、waiting_*)、暂停、等待人处理(needs_*)等 不删
是某个未结束的后续任务的来源任务(后续任务要从它恢复成果) 不删
开发任务打开的 PR 或它修订的 PR 仍打开 不删,不论多久
上面的 PR 已合并或关闭;检视的 PR 已合并或关闭 看到合并或关闭后的下一轮删除
成功、取消、被取代 任务最后更新(目录之后还有活动则按活动时间)超过 1 天后删除
失败 超过 7 天后删除
没有记录指向的目录(升级前留下的、会话和服务角色用过的) 目录最近活动超过 1 天后删除

上表的 1 天和 7 天是默认值,可以在全局设置「存储」的「按天数清理」里改(workspace_finished_days、workspace_failed_days,没有记录指向的目录跟随前者,见按天数清理)。

PR 的合并或关闭以 pull_request closed 事件或检视读到的 PR 状态为准(review_objects)。最近 30 分钟内有活动、或本进程最近 30 分钟用过的目录这一轮不删;正在删除的 worktree 不会被交给新任务,交出时找不到目录就记为 removed、任务新建。每次交出都会更新 worktree 目录的修改时间,runner 删除前再看一次活动时间,列出之后有写入或被交出的目录留下。删除或发现已不存在的 worktree 在 worktrees 里记为 removed,它的占用一并释放。升级后第一次清理前,控制面为当时未结束的任务补记它们的工作区、恢复和集成来源及后续任务的来源任务工作区。

runner 只接受 48 位十六进制的目录名,只删除 /workspace/tasks 或 /workspace/worktrees 下真实存在的目录,不跟随符号链接,这两个目录本身被换成链接时拒绝执行;删除后清理电脑 Git 对象库里的 worktree 登记。删除的目录在 task_workspaces 里记下 released_at、原因和释放的字节数,这些记录保留 30 天。/workspace 根目录下 agent 留下的其他文件和 /workspace/home 缓存不在清理范围内。

SQLite WAL 大小

控制面(control.sqlite)和 manager(manager.sqlite)的连接都设置 PRAGMA journal_size_limit=536870912。WAL 文件会保持它到过的最大尺寸;设置后,checkpoint 把 WAL 内容全部写回数据库、下一次写入从头使用 WAL 时,SQLite 把文件截到 512 MiB。升级后已经很大的 WAL 在第一次这样的 checkpoint 后变小,启动时不读取或重写大表。

启动时压缩数据库

两个数据库建立时都是 auto_vacuum=NONE:清理或迁移空出的页只留在文件里给新数据复用,文件不会变小(#436 把正文搬进轨迹文件后,生产的 control.sqlite 128 GB 里约 101 GB、manager.sqlite 108 GB 里约 99 GB 是空闲页)。把空闲页还给磁盘只能重写整个文件,期间要独占数据库,所以由每个服务在启动时、开始服务之前做一次(manager/compaction.mjs,控制面共用同一份代码):manager 在开始监听、报告就绪之前压缩 manager.sqlite,控制面在开始监听之前压缩 control.sqlite。这是「启动时不重写大表」的一次性例外。

发版前:压缩期间服务不可用,时长大致与实际数据量成正比。在一台 14 核、31 GB 内存的开发机上,一份 8.9 GiB、其中 3.1 GiB 实际数据的合成库(宽行加索引,删去三分之二)复制加完整性检查用了 11 秒,但文件刚写过、全在页缓存里。生产的库不在缓存里,实际数据还分散在大文件中,按数据盘 100–300 MB/s 的读写估算:control.sqlite(约 27 GB 实际数据)约 10–30 分钟,manager.sqlite(约 10 GB)约 5–10 分钟,以日志里的进度为准。 manager 先压缩,bot 等 manager 健康后才启动,所以总停机是两者之和;manager 健康检查的 start_period 为 30 分钟,部署步骤最多等 bot 85 分钟并输出压缩进度。数据盘要先留出两边实际数据之和再加余量的空间,否则这次启动跳过压缩、照常运行。

备份与恢复

备份前停止 bot 和 manager,并备份部署卷(assistant-homes 只有助手的持久 HOME,可按需要单独备份或不备份;agent-tools 只放已安装的 Agent CLI 二进制,可按需要备份或恢复后经 /api/agent-tools/install 重新安装)及项目具名卷;数据库停止写入后再复制,恢复时使用同一套内部认证和管理账本。bot-data 卷里除了 control.sqlite,还有数据库引用的轨迹文件 trajectories/,以及任务浏览器的截图目录 browser-evidence/,备份时要来自同一次停写。丢失主密钥会无法解密凭据,丢失内部认证会改变部署 ID,不能用新的空账本直接接管旧容器。docker compose down 保留卷;--volumes 会删除部署认证和账本,日常升级不要使用。动态项目资源需要通过环境接口管理,Compose down 不会直接删除它们。

GitHub 用户登录

推荐由系统超级管理员进入「全局设置 → 接入向导 → GitHub 登录」,创建独立 OAuth App,登记 Bot Homepage URL 和登录 Callback URL,填写该 OAuth App 的 Client ID 和 Client secret,再启用保存。不要复用仓库 GitHub App 的凭据;仓库连接、执行和权限核验仍由仓库 App 负责。配置立即生效,SecretBox 加密存入数据库,不修改部署文件,Secret 不回显。向导配置优先于环境默认值,明确停用后重启也不会重新启用。升级前的仓库 App 登录继续运行到管理员保存新 OAuth 凭据;迁移后原 GitHub 会话需重新登录,按数字 GitHub ID 保留账号绑定。

登录不再单独填写控制台地址。用户授权 Callback URL 固定为 <统一入口>/auth/github/callback,统一入口依次取向导验证的公网地址和 BOT_PUBLIC_ORIGIN;两者都没有时,取保存登录配置时的控制台地址,只适合本机回环测试。同一入口下还有安装 Setup URL <统一入口>/onboarding/github/setup、只在向导创建 App 时使用一次的注册回调 /onboarding/github/callback(回到发起创建时的控制台地址,不写进 App 设置),以及 Webhook URL <统一入口>/hooks/github/<account_id>/<endpoint_id>。登录回调对应 OAuth App,其他地址对应仓库 GitHub App 的字段,不能互相替代。公网地址变化后,登录回调立即跟随新地址;GitHub 不提供修改 Callback URL 和 Setup URL 的接口,管理员需分别在 OAuth App 更新登录回调、在仓库 App 更新 Setup URL,Webhook URL 由「机器人账号」的「重新检查」写入。

未保存向导配置时,也可使用部署默认值:设置 BOT_GITHUB_OAUTH_CLIENT_ID、BOT_PUBLIC_ORIGIN,并以只读文件挂载 Client secret 到 BOT_GITHUB_OAUTH_CLIENT_SECRET_FILE;本地测试可用 loopback HTTP。生产环境设置 BOT_COOKIE_SECURE=true。secret 不写进镜像、仓库或浏览器配置,Compose 基础配置不会在未启用 OAuth 时要求该文件。

选择部署默认值时,例如用私有 Compose 覆盖文件给 bot 服务增加 volumes: ["./secrets/github-oauth-client-secret:/run/secrets/github-oauth-client-secret:ro"],文件按运行 UID 10001 设置最小读取权限。OAuth App 的 Client ID 与仓库 App ID、仓库 App Client ID 不同,不能互换。登录请求空 scope,令牌仅用于公开身份核实;组织 owner 识别通过仓库 App 的 Members 只读权限完成,不申请成员写权限。无法证明当前权限时显示待验证。

先完成原有本地超级管理员初始化,再允许用户 GitHub 登录;升级后本地恢复账号不变。备份仍须同时保护数据库与原 master key,新增用户 token 也由 SecretBox 加密。迁移报告、未知归属处理、权限来源和撤销说明见 GitHub 登录与统一授权。

从双端口升级

以前的版本有两个业务监听:Webhook 8791 和管理页 8792。现在控制面只监听 8791,8792 不再存在,管理页、登录、GitHub 回调和 Webhook 共用一个公网 HTTPS 入口。升级不改数据库和卷,账号、App 凭据、安装、用户授权和业务数据都保留,不需要重建 App 或重置用户。

  1. 改 .env:
    • BOT_WEBHOOK_PORT 改名为 BOT_PORT。旧名在 v0.3.0 之前仍作为 BOT_PORT 未设置时的回退;两者都设置时以 BOT_PORT 为准。
    • 删除 BOT_ADMIN_PORT,它不再发布任何端口。
    • BOT_ADMIN_ORIGIN 改名为 BOT_PUBLIC_ORIGIN,值改为统一入口(不再是独立管理域名,也不再指向 8792)。旧名在 v0.3.0 之前仍会读取,并在日志里提示改名;两者同时设置且不同时控制面拒绝启动,日志写明原因。
    • 以前依赖 Webhook 端口绑定 0.0.0.0、反向代理在另一台机器的部署,设置 BOT_BIND_ADDRESS=0.0.0.0 并用防火墙限制来源。同机反向代理和 Cloudflare Tunnel 不需要这一项。
  2. 改入口:自建反向代理把统一域名整个转发到 http://<这台机器>:8791。原来指向 8792 的独立管理域名可以删除,也可以同样改为转发到 8791:它仍能登录和写入,但 GitHub 回调和生成的链接都用统一入口。Cloudflare Tunnel 的 Published application 继续用 http://webhook:8791,删除指向管理端口的路由。本机书签和 SSH 端口转发从 8792 改为 8791。
  3. 运行 docker compose pull 和 docker compose up -d(源码构建时叠加 compose.build.yaml)。
  4. 在「全局设置 → 公网接入」确认统一入口已验证。新的检查只核对 HTTPS 和本实例的一次性凭证,不再因为入口提供管理页面而失败。
  5. 在独立 OAuth App 设置里:Authorization callback URL 改为 <统一入口>/auth/github/callback;仓库 GitHub App 的 Setup URL 改为 <统一入口>/onboarding/github/setup,点「Save changes」。Webhook URL 不在统一入口下时,到「机器人账号」点当前 App 的「重新检查」。确认没人再用旧地址后,再删除旧的 Callback URL。
  6. 打开「接入向导 → GitHub 登录」。为独立控制台地址保存过的配置会同时列出旧、新 Callback URL;完成第 5 步后点一次「保存登录配置」,提示消失。只在本机测试、没有公网入口、以 http://127.0.0.1:8792 保存过登录配置的部署,从 http://127.0.0.1:8791 打开这一步保存一次,并把 OAuth App 的 Authorization callback URL 改成页面显示的新地址。

迁移期间,升级前登录配置里保存的控制台地址仍是合法写 Origin,入口或证书尚未就绪时,可在原地址或本机 http://127.0.0.1:8791 登录修复。会话 Cookie 按域名保存,入口域名变化后用户要在新地址重新登录一次;GitHub 身份、授权和用户 token 不受影响。