codex-app-server/cloud/HA-DESIGN.md

多机高可用方案

目标：单台主机挂了，任务队列、API、webhook、/pr 还能继续。 非目标：进行中的 turn 不迁移——中断后按现有语义由陈旧回收标 interrupted，再由人工或新建任务重跑（goal 任务本来就不支持 同任务 /retry，见 README）。零中断不在本方案范围内。

建议的可用性目标（建议值，实施前由用户定）：控制面 RTO < 10 分钟， 数据 RPO < 1 小时（由备份间隔决定，不是 0）。

一、现状：单点在哪里（2026-10-26 实测为准）

层	现状	多机影响
控制面	单进程 ThreadingHTTPServer（cloud/server.py create_server），只绑 127.0.0.1:8765，nginx（宝塔，api.diante.me）反代；systemd 重启只防进程死，不防主机死	主机挂 = API 全挂
数据库	Postgres 单容器 codex-postgres，卷 /var/lib/codex-postgres 在同一主机	主机挂 = 数据挂；磁盘坏 = 数据丢
备份	cloud/backup.py 的 pg_dump + deploy/restore-drill.sh 恢复演练都已存在，但没有定时任务，且 README 明确写着“真实环境 pg_dump 仍需验证一次”	有备份代码，无备份制度
队列认领	已多机安全：cloud/worker.py _claim 是 DB CAS（WHERE status='queued'，rowcount == 1 才算拿到）；陈旧回收 sweep_stale_tasks 也是 CAS 幂等，worker 每轮 + /admin/sweep 都可跑	多 worker 跨机抢任务今天就能用
worker 注册	workers 表（cloud/workers.py，worker_id/executor/capacity/last_seen）在 DB 里，可共享	好
worker 心跳	两条：DB 注册表心跳 + 文件心跳 worker-heartbeat.json；/health 的 worker_ok 读的是本机文件（_worker_heartbeat_status）	多 server 下 health 失真
限流	RateLimiter 是进程内存滑动窗口（cloud/server.py，按 key sha 或 IP 计），只对 API 路由生效	多 server 下预算 ×N
/pr	在 server 进程内跑，worktree 从 server 本机文件系统解析（host_worktrees_dir；Docker 任务的 tenants 目录同样在 server 本机）	server 与 worker 同主机是隐含前提，多机首先断在这里
worker 状态	host-state.json（host 任务登记）、autoscaler-state.json、codex-home 模板、test-repo、repos-dir、tenants/ 全部是本机路径	新主机要全套播种
镜像	codex-app-server:latest 只在工作主机本地有（代码本身不在镜像里，运行时只读挂载 /opt/codex-app-server:/app）	新主机要同步镜像 + 代码目录
出口	tinyproxy（8888）+ 白名单 + iptables，每主机一份	新主机要复制白名单与 iptables 规则
入口	nginx 单机；公网只经 api.diante.me 的 /oauth/ + /webhooks/ + /github-app/ 三组 location	nginx 挂 = 公网全挂
密钥	/etc/codex-app-server/env（0600）每机一份；GitHub App 的 webhook_secret 与 pem 在 Postgres github_app_config 表里（可共享）	新主机要分发 env 文件
监控	monitor.timer 每 5 分钟本机自查（systemctl、health、pg_isready、docker ps、磁盘），只写 journal；告警到 Muse 聊天的通道本身就是开放项（需 SSH key 常驻通道或 webhook URL）	多机要聚合视图 + 告警通道

结论：队列、注册表、webhook 去重（webhook_deliveries DB claim）、 OAuth state、App 配置都已经在 DB 里，server 本身除限流与文件心跳 外是准无状态的。真正的硬耦合只有三处：/pr 的 worktree 本地性、 Postgres 单机、nginx 单机。方案按这个顺序拆阶段，每个阶段可独立 回滚到单机。

二、推荐拓扑（分阶段）

阶段 0：先决条件（不动架构，先把保命的东西立起来）

1. 定时备份 + 恢复演练跑通：给 pg_dump（POST /admin/backup 或 cron）加每天一次定时任务，备份文件异地（另一台机器或对象 存储，只留本机等于没备）；deploy/restore-drill.sh 在备用库上 真跑一次，演练通过才算备份有效。RPO = 备份间隔，写进运维手册。
2. health 改读 DB：/health 的 worker_ok 从文件心跳改为 workers 表聚合（任一 worker last_seen 在 180 秒内即 ok）。 改动小，但多机 health 的前提。
3. 监控聚合：每机 monitor.sh 照常跑，结果汇总到一处（最简： 各机 journal + 一个汇总端点；不要为监控先引入新组件）。

阶段 1：worker 面多机（控制面仍单机，风险最低的一步）

加第二台 worker 主机：Docker worker + autoscaler，共享同一个 Postgres 队列。CAS 认领保证不重跑；一台 worker 主机挂了，另一台 继续认领（进行中的任务由 sweep 标 interrupted）。

但阶段 1 必须同时解决 /pr，否则 Docker 任务的 worktree 在 worker 主机上、server 在另一台主机上，/pr 直接 no_worktree：

• 方案 A（推荐）：/pr 跟着 worktree 走。tasks 表加 worktree_host 列，worker 认领时写自己的主机名；server 的 /pr 先查本机 worktree，没有则经 SSH/HTTP 转发到持有主机执行 （复用主机间已有的 SSH 通道与 codexsvc 身份），或至少返回 “worktree 在某主机”的明确错误而不是静默跳过。改动：tasks 迁移一列 + _claim 写主机名 + pr.py 转发分支 + 单测。
• 方案 B（不推荐首选）：tenants/ + host-worktrees/ 放共享存储 （NFS）。改动最小，但引入新单点、文件锁与跨机 git 竞态，性能 与一致性都不如 A，只在主机数很少且运维愿意管 NFS 时考虑。

阶段 1 验收：停一台 worker 主机，新任务仍被另一台认领完成； /pr 在 worktree 所在主机与非所在主机上各跑一次，结果一致。

阶段 2：控制面多机（2 台 server + 负载均衡）

1. 两台 server 进程（同代码、同 env、同 DB 连接串），前面一台 nginx（upstream + 健康检查， /health 要求 ok 且 db_ok）。 webhook、OAuth、API 任一 server 都能处理：去重、state、App 配置全在 DB 里，天然幂等。
2. 限流二选一：改共享计数（Postgres 表存滑动窗口，量小够用； 量大再上 Redis）——推荐；或接受预算 ×N 并写进文档（不推荐， 等于限流失效一半）。
3. server 本机文件：server 进程不依赖 host-state.json（那是 worker 的），除限流与文件心跳（阶段 0/2 已处理）外无其它内存状态。 部署改为滚动：逐台传 tar、重启、health 通过再下一台，绝不同时 停两台。
4. 入口：nginx 本身仍是单点，见阶段 4。

阶段 2 验收：停一台 server，API、webhook、OAuth 回调、/pr （经阶段 1 转发）全部正常；限流在两台上的总和不超过设定值。

阶段 3：数据面（最难、最贵，放最后）

Postgres 单主是最后的单点。选项按成本排序：

1. 接受单 Postgres + 快速重建（推荐起步）：阶段 0 的定时备份 + 演练 + 一份重建手册（新容器 + 恢复备份 + 重启 server），RTO 约 30 分钟，RPO = 备份间隔。多数小团队到这里就够了。
2. 流复制 + 手动提升：一主一从，主机挂了手动提从为主、改连接 串、重启 server。RTO 约 10 分钟，有脑裂与数据滞后风险，演练 必须定期做。
3. Patroni 自动故障转移：RTO 最短，但要 etcd/consul、VIP、 fencing，运维复杂度上一个台阶；或直接用托管 Postgres（把 复杂度外包，按账单取舍）。

不要为“多机”先上 Patroni：阶段 1+2 解决的是最常见的进程/主机 故障，数据面按备份 + 演练先顶着，等阶段 2 稳定了再评估。

阶段 4：入口与出口（收尾）

• nginx 双机 + keepalived 浮动 IP（同机房），或 DNS 轮询 + 健康 检查（跨机房，生效慢）。宝塔重生成 vhost 会吃 location 的老 问题在多机下同样存在，备份恢复流程要同步到两台。
• tinyproxy 白名单与 iptables 规则做成配置同步（每机一份，改动 时同批下发，不要手工各改各的）。
• Docker 镜像进 registry（或每机同步构建产物），新主机入网不再 依赖某台机器的本地镜像。
• 新主机入网清单（每加一台必查）：env 文件、镜像、AppArmor profile（docker-codex、codex-host）、tinyproxy 白名单、 iptables、codex-home 模板、test-repo、repos-dir、tenants 根、 systemd units、monitor.timer、NTP（心跳与超时都依赖时钟）。

三、故障场景表（各阶段下的表现）

故障	今天（单机）	阶段 1 后	阶段 2 后	阶段 3 选项 1 后
server 进程死	systemd 重启，秒级	同左	另一台接管，无感	同左
worker 主机挂	任务卡住到 sweep（300 秒）标 interrupted	另一台继续认领	同左	同左
server 主机挂	全挂	API 全挂，worker 空转	LB 切走，继续	同左
Postgres 挂	全挂	全挂	全挂	备份重建（RTO 约 30 分钟）
nginx 挂	公网全挂	公网全挂	公网全挂	阶段 4 后切走
磁盘满	monitor 报 fail，人工清	同左（每机自查）	同左	同左
Docker daemon 挂	该机任务全停	另一台继续	同左	同左

四、不做的事与风险

• 不迁移进行中的 turn：主机挂时正在跑的 turn 一定中断， 由 sweep 标 interrupted；重跑走新建任务（goal 任务的限制不变）。 试图热迁移 turn 状态的代价远大于收益。
• 不共享 SQLite：多机只走 Postgres 后端；SQLite 只留给单测与 本地开发（现有的后端抽象已支持，部署时 CLOUD_DB_BACKEND 必须为 postgres，并在启动时校验，缺驱动明确失败不回落）。
• 脑裂：写路径永远只认一个 Postgres 主；CAS 认领与 sweep 的 WHERE status 守卫是最后一道防线，不要绕过它们做“强制认领”。
• 时钟：心跳、超时、sweep 全依赖时间戳，多机必须 NTP 同步， 否则会出现“活任务被误扫”或“死任务扫不掉”。
• 密钥分发：env 文件目前是手工放的；主机数上 3 台之前手工尚可， 再多就要 secrets 管理（Vault/托管密钥），不要把密钥写进仓库或 部署 tar（现行纪律不变）。

五、实施顺序与回滚

1. 阶段 0 → 验收：备份定时任务在跑、恢复演练通过、health 改 DB。
2. 阶段 1 → 验收：双 worker 主机 + /pr 转发；回滚：停第二台 worker 主机，worktree_host 列留着无害。
3. 阶段 2 → 验收：双 server + LB + 限流共享；回滚：LB 只留一台 upstream，另一台停服。
4. 阶段 3 → 按选项验收；回滚：切回单 Postgres + 备份。
5. 阶段 4 → 验收：nginx 切换演练；回滚：DNS/浮动 IP 指回原机。

每阶段结束都以一次“杀一台主机”的演练为准，不要以“服务都 active”为准——单机时代的 monitor 只能证明进程活着，证明不了 故障转移。