[micln]

做了什么（issue #227 / R-102）

1. docs/deployment/backup-restore.md（新增）：开头硬前提「迁移不可逆，回滚唯一手段是 restore」+ SECURITY_KEY 一致性引用 production.md §7；三组可复制命令——pg_dump -Fc 备份（compose 容器内 / 外部 PG 两条路 + 一键脚本）、pg_restore --clean --if-exists 恢复、命名卷 docker run … alpine tar czf 兜底等价命令（附跨大版本数据目录的警示）；升级 runbook 与迁移顺序红线（dry-run 看报告 → -apply 写库 → 再放量新版本）+ 失败回滚两步。
2. scripts/backup.sh（新增）：产出 di-backup-<版本>-<时间戳>.dump 并打印 sha256；自动探测 compose 容器 data-insights-postgres 走 docker exec pg_dump，否则用本机 pg_dump + DATABASE_URL（环境变量或仓库根 .env，与后端同优先级、不覆盖已有 env）。
3. scripts/upgrade.sh（新增）：备份 → 迁移前置检查（红线作为显式步骤；交互确认，非交互需 --yes）→ TAG=<new> docker compose up -d → 轮询 ready 60s（判据是 HTTP 200，不是容器状态——迁移失败时进程根本不监听端口）→ 失败打印两条回滚命令（旧 TAG 起容器 + pg_restore 指向本次备份）。支持 --dry-run（只备份 + 打印迁移步骤 + 真实调用一次 ready 判据）与 --yes。
4. 文档收口：production.md §7 改为指向 runbook 并同步迁移顺序红线；docker.md Compose 升级段引用 runbook；docs/AGENTS.md 索引与 README.md 文档导航补条目。

关键设计：对 R-100（未合 PR #242）的探测回退

issue 依赖 R-100 的 /health/detail（版本串）与 /health/ready（判据来源），两者尚未合入 master。脚本做成探测回退，R-100 合入后零改动自动用上完整判据：

• 版本：GET /health/detail 的 version → 回退 app 容器镜像 tag → 回退 unknown；
• ready：/health/ready 非 404 则以它为准 → 回退 /health（master 现状：只证进程活着）。
• 已知边界：master 的 /health 不探库，所以 R-100 合入前，ready 判据对「postgres 停但进程活着」不敏感；这正是 R-100 的 ready 要补的能力。

怎么验证的

• bash -n + shellcheck（0.11.0）两脚本 0 error；
• compose 环境实跑 upgrade.sh --dry-run：产出 113 条目的 pg_dump -Fc 备份 + sha256，pg_restore -l 校验 dump 可读，ready 判据被真实调用，rc=0；
• 故障注入 A（验收原文）：docker stop data-insights-postgres 后重跑 → 备份步骤快速失败，报错指明「容器不在且 DATABASE_URL 未设置」；
• 故障注入 B：注入坏 DATABASE_URL 重建 app（模拟「迁移失败进程不监听端口」）→ 60s 内 ready 判失败（严格按秒轮询到 60）→ 打印旧 TAG 起容器 + pg_restore 两条回滚命令，rc=1。
• 本单元只改文档与 shell 脚本，未动前后端代码，故验证以 compose 实跑与脚本行为为准（未跑 go test / pnpm build:check，代码零改动）。

顺手发现（不在本 PR 修，建议另立 issue）

1. master 的 docker-compose.allinone.yml 对全新部署当前是坏的：postgres:18-alpine 新入口（Change PGDATA in 18+ to /var/lib/postgresql/MAJOR/docker docker-library/postgres#1259）要求数据卷挂载在 /var/lib/postgresql（大版本子目录布局），现挂 /var/lib/postgresql/data 会让 postgres 容器启动即退出（Error: in 18+ … unused mount/volume）。验证时用 /tmp 覆盖文件（!override 改挂载点）绕过；修 compose 涉及存量部署的数据布局迁移，超出本 issue 范围。
2. bash 3.2（macOS 自带）下 $VAR 后紧跟全角标点会把多字节字符并进变量名，set -u 下误报 unbound variable——两个脚本已全量排查并加花括号（${VAR}（ 形式），review 时请留意不要改回去。