0 Fork 0

Files

T

openqjandhost de81b1643f docs: Postgres fast-rebuild runbook (HA stage 3, option 1) (#53 )

Co-authored-by: host <host@test.local>

2026-10-27 00:22:31 +08:00

5.4 KiB

Raw Permalink Blame History

Postgres 快速重建手册（HA 阶段 3，选项 1：单 Postgres + 快速重建）

前提（2026-10-26 实测值，改配置后同步改这里）：

容器 codex-postgres：镜像 postgres:16，--restart unless-stopped，只绑 127.0.0.1:5432，卷 /var/lib/codex-postgres 挂到 /var/lib/postgresql/data，库 codex_control，用户 codexsvc。
备份：每天 03:00 CST 由 codex-pg-backup.timer 跑 pg_dump，在 /var/lib/codex-app-server/backups/，轮转 7 份，目录 700、文件 600（含生产全量，含 GitHub App 配置，绝不要放宽权限、绝不要进仓库）。
连接参数只在 /etc/codex-app-server/env（0600 root）里，密码只经环境变量传，不进命令行、不进日志。
RTO：场景 A 约 5 分钟，场景 B 约 30 分钟；RPO = 24 小时（备份间隔，备份后到故障前的数据会丢，写进事故通报里）。

通用顺序（三个场景都一样）：先停两台 server（避免恢复中途有写请求进来），再动数据库，恢复完先 pg_isready、再起 server、再看 health 与 monitor。不要在 server 还跑着的时候往生产库里恢复备份。

systemctl stop codex-cloud-server codex-cloud-server-2
# ... 按场景恢复 ...
systemctl start codex-cloud-server codex-cloud-server-2
curl -s http://127.0.0.1:8765/health   # 要求 db_ok=true
curl -s http://127.0.0.1:8766/health   # 同上
sh /opt/codex-app-server/deploy/monitor.sh  # 要求 overall pass

恢复后 running 任务的处理：恢复出来的 running 行心跳一定过期，会被 worker 的陈旧回收（300 秒）标 interrupted；不要手动改状态，让 sweep 走，之后新建任务重跑（goal 任务本来就不支持同任务 /retry）。

场景 A：容器丢了，卷还在

docker ps -a | grep codex-postgres  # 确认容器没了、卷还在
ls /var/lib/codex-postgres          # 卷里应有 PGDATA 内容
docker run -d --name codex-postgres --restart unless-stopped \
  -p 127.0.0.1:5432:5432 \
  -v /var/lib/codex-postgres:/var/lib/postgresql/data \
  -e POSTGRES_DB=codex_control -e POSTGRES_USER=codexsvc \
  postgres:16
# 注意：卷已存在时 POSTGRES_PASSWORD 不再生效（只在初始化空卷时
# 用），所以这里不用传密码；旧卷的口令就是 env 里的那个。
pg_isready -h 127.0.0.1 -p 5432

场景 B：卷丢了（磁盘坏、误删），用备份重建

# 1. 先确认旧卷确实不可恢复（不要在还能抢救的卷上直接重建）。
# 旧目录还在但已损坏时先 mv 走（保留取证），不要直接 rm。
ls /var/lib/codex-postgres || echo "卷已丢"
# 2. 新卷 + 新容器。密码必须等于 env 里 CLOUD_DB_PASSWORD 的值，
# 否则 server 连不上（新卷初始化时口令就按这个值建）。
set -a; . /etc/codex-app-server/env; set +a
mkdir -p /var/lib/codex-postgres
docker run -d --name codex-postgres --restart unless-stopped \
  -p 127.0.0.1:5432:5432 \
  -v /var/lib/codex-postgres:/var/lib/postgresql/data \
  -e POSTGRES_DB=codex_control -e POSTGRES_USER=codexsvc \
  -e POSTGRES_PASSWORD="$CLOUD_DB_PASSWORD" \
  postgres:16
# 3. 恢复最新备份（备份是 pg_dump 明文 SQL，不含 CREATE DATABASE；
# 库已由容器的 POSTGRES_DB 建好，导入只建表与数据）。
# 新卷是空库，正常应干净导入；有报错先看日志尾部再定。
LATEST=$(ls -t /var/lib/codex-app-server/backups/cloud-backup-*.sql | head -1)
echo "restoring $LATEST"
PGPASSWORD="$CLOUD_DB_PASSWORD" psql -h 127.0.0.1 -U codexsvc \
  -d codex_control -f "$LATEST" > /tmp/pg-restore.log 2>&1 \
  || tail -20 /tmp/pg-restore.log
# 4. 校验：表在、行数非零（与事故前最后一次 monitor/演练记录对照）。
PGPASSWORD="$CLOUD_DB_PASSWORD" psql -h 127.0.0.1 -U codexsvc \
  -d codex_control -At -c \
  "SELECT (SELECT count(*) FROM tasks), \
          (SELECT count(*) FROM projects), \
          (SELECT count(*) FROM users), \
          (SELECT count(*) FROM audit_log);"

场景 C：整机丢了

按 deploy/new-host-checklist.md（HA 阶段 4）先把新机入网（env、代码、units、镜像、代理白名单），再走场景 B。注意新机的 /etc/codex-app-server/env 必须与旧机一致（尤其是 CLOUD_DB_PASSWORD，否则场景 B 的新卷口令对不上）。

安全红线

演练永远恢复到测试库（deploy/restore-drill.sh 已把“目标库名绝不等于生产库名”写进脚本逻辑）；只有真实重建（场景 B/C）才以 codex_control 为目标，且必须先确认旧卷已丢。
备份文件含 GitHub App 的 webhook_secret 与 pem：恢复、拷贝、传输时一律按密钥处理，不进仓库、不进聊天、不打印内容。
重建完先不要急着接流量：health 的 db_ok 与 monitor 的 overall pass 都通过，再用自己的 API key 调一次 GET /projects 能返回，才算通。

演练节奏

每季度：sh /opt/codex-app-server/deploy/restore-drill.sh （新鲜备份 -> 测试库 -> 四表行数比对 -> 删测试库），PASS 才算备份有效；不要只看“备份文件存在”。
每半年：场景 A 演练一次（docker restart codex-postgres 后 health 与 monitor 恢复），验证容器重建路径没过期。
演练结果记进运维记录；手册里的实测值（镜像、端口、卷路径、备份间隔）变了就同步改手册，不要让手册过期。

5.4 KiB Raw Permalink Blame History Unescape Escape