hyb-oa/.trellis/tasks/07-27-automatic-offhost-backup/design.md

每日自动异机备份设计

总体边界

本任务不建设备份平台。生产主机负责生成和推送一个不可变成对批次，ARM 用受限 SSH 接收身份把传输区与归档区隔离；systemd 负责每日执行、缺失监测和季度提醒。

production 02:30
  resolve active Compose identity
  -> flock
  -> backup-all.sh (DB + storage + manifest)
  -> local verify
  -> rsync to ARM inbox/<run-id>.partial
  -> restricted finalize <run-id> <manifest-sha>
       -> ARM verify exact files/manifest/hash
       -> atomic move to archive/<run-id>
       -> daily + weekly retention
  -> write safe success state
  -> prune local daily copies

production 07:10 watchdog
  -> last off-host success <= 24h ? pass : alert

quarterly reminder
  -> one redacted WeCom reminder per calendar quarter
  -> human runs ARM shadow restore separately

生产备份编排

• 新增一个宿主 wrapper，所有正式输入由安装器写入 systemd：仓库根、Compose project/file/env、活动 PGDATA/附件目录、完整/短构建 SHA、备份根、状态根、SSH alias/key/known-hosts 和告警开关。
• wrapper 通过 Compose label 解析唯一 server/db 容器，并把实际 DB/附件 mount、server build SHA 与安装时冻结值逐项比较。任一漂移在调用 backup-all.sh 前停止。
• DB 名称/用户和密码只从活动容器环境在内存中取得，传给现有 Docker 备份路径；不得 source 漂移的旧部署 env，不得输出取值。
• 每个自动批次使用 auto-<UTC timestamp>，源端根和状态根均为显式安全绝对路径、权限 0700。flock 拒绝同一任务重入。
• 只有 ARM finalize 成功后才写 last-success.json 并清理源端旧日批次。失败保留本次完整源批次供重试，不产生异机成功状态。

ARM 受限接收边界

• ARM 一次性安装 rsync，创建密码锁定的专用账号、独立 inbox/archive/weekly 目录和一把专用公钥。该公钥的 authorized_keys 强制执行仓库提供的 receiver，并禁用 PTY、端口转发、agent 转发和 X11 转发。
• receiver 只接受两类 SSH_ORIGINAL_COMMAND：rsync server 接收模式，或 hyb-backup-finalize <run-id> <manifest-sha256>。其他命令全部拒绝。
• rsync 通过 rrsync -wo 只能进入 inbox；archive 和 weekly 位于 rrsync 根之外。即使生产端密钥泄露，也不能用 rsync 读取或删除已归档批次。
• finalize 只接受 auto- 安全批次号和完整 manifest SHA。它要求 inbox 中恰有三个普通文件、无链接，manifest 的 runId/status/schema、相对文件名、大小和 SHA-256 全部匹配；已存在 archive 目标时拒绝覆盖。
• 校验通过后在同一文件系统内原子移动到 archive。每个自然日最多接受一个正式自动批次进入保留计算，避免失陷源端通过短时间伪造大量批次提前挤掉历史。
• archive 保留最近 7 个日批次；每个 ISO 周首次成功批次用只读硬链接快照形成周检查点，保留最近 4 周。清理不得删除最后一个 archive 或当前 finalize 批次。
• 旧手工/审计批次不进入自动前缀和自动轮转范围。

传输与主机身份

• 生产 root 使用一把仅用于本接收器的私钥，权限 0600；SSH config 使用专用 alias，known_hosts 由人工核对的固定主机指纹生成，timer 固定 StrictHostKeyChecking=yes，不得使用 accept-new。
• rsync 只发送完整源批次到同名 .partial inbox。网络中断可续传同一 partial；远端 archive 同名存在时 finalize 失败，不覆盖。
• 仓库、任务和报告只记录 alias 类别、布尔值和批次数量，不记录地址、账号、密钥、公钥原文或完整运行目录。

告警与静默失败检测

• wrapper 无论成功或失败都生成字段白名单 summary；失败 trap 尝试通过活动 server 容器调用现有企微运维告警 CLI，并使用备份专属 state file，避免与 WARCH3 降噪状态互相覆盖。
• 现有告警 CLI 小范围泛化为接受 stdin summary、保留 summary issueId，并为备份失败/过期提供正确建议；发送仍受既有 WARCH3_OPS_ALERT_SEND=1 双门控制。
• 独立 watchdog timer 在每日巡检前读取宿主 last-success.json。文件缺失、格式错误、构建/项目不匹配或成功时间超过 24 小时均产生失败 summary 并尝试告警。
• 若 Docker、整机网络或企微本身同时不可用，主机无法自证并外发，这是自托管告警的物理边界；watchdog 能覆盖 timer 未运行和短暂失败，但不替代外部主机存活监控。
• 季度提醒以年份+季度作为 finding key，确保每季度一次且同季度不重复；只提醒人工影子恢复，不执行恢复。

安装与回滚

1. 本地先实现合成测试、受限 receiver、告警适配和两个安装器，不接触生产/ARM。
2. 获批后先在 ARM 安装 rsync、受限账号/receiver/公钥和目标目录；使用无业务数据的合成批次验证拒绝 shell、拒绝 archive 覆盖和 finalize。
3. 再在生产安装专用私钥/known_hosts、每日备份 service/timer、stale watchdog 和季度提醒；首次安装先保持 timer disabled。
4. 手工启动一次获批自动备份，核对源/ARM 哈希、状态和无敏感输出；再 enable timers。
5. 用不包含业务正文的可控失败验证企微告警后恢复链路，最终确认下次执行时间。

回滚只 disable/stop 新 timer、移除 unit 和专用密钥授权；保留已生成的完整备份、状态报告和 ARM archive，不删除历史数据。旧手工 backup-all.sh 入口保持兼容。

取舍

• 选择生产推送而非 ARM 拉取，是为了让一次任务同时掌握生成、传输、目标校验和即时告警结果。
• 不给生产普通 ARM shell，而用 inbox + 强制 receiver + archive 隔离，抵消推送方案最主要的跨机删除风险。
• 使用 rsync 而不是新备份服务；当前压缩批次规模较小，收益主要是断点续传和成熟 SSH 传输，不追求块级去重。
• 不自动恢复。季度人工影子恢复才是可恢复性证据，日 timer 只负责生成恢复点。