文件
hyb-oa/.trellis/tasks/07-28-automatic-backup-runtime-identity-failure/design.md
T

2.2 KiB

自动备份运行身份失败修复设计

1. Root Cause

自动备份安装时把附件宿主目录冻结进 systemd unit。后续 server 容器重建使用了另一实际宿主目录,但 unit 未同步刷新。runner 在 runtime_identity 阶段比较 Docker 实际 mount source 与 unit 的 STORAGE_HOST_DIR,发现不一致后在 DB dump、附件归档和传输前失败关闭。

严格检查本身正确:两个目录均存在、非符号链接、realpath 和 inode 不同,因此不能通过路径规范化或放宽校验修复。

2. Safe Refresh

从 daily unit 读取现有环境合同,从唯一运行 server 容器解析实际附件 mount source,仅在内存中替换 STORAGE_HOST_DIR。验证所有路径、权限、build 对应关系后,调用仓库安装器 enable 原子重写三个 service/timer 文件并 daemon-reload;写入前保存三个 services/timers 的 root-only 临时副本用于失败回滚,成功验证后删除副本。

不在命令输出、task 或文档中记录实际路径、容器 ID、连接串或 webhook。

3. Validation Sequence

local 73-check contract
  -> production read-only recheck
  -> snapshot six unit files
  -> installer enable with actual storage mount
  -> six-dimension runtime identity check
  -> manual daily service start
  -> verify new success state + ARM finalize + recovery alert state
  -> verify timers and unrelated monitors
  -> remove temporary unit snapshot

4. Rollback

  • 安装器或 unit 验证失败:恢复六个 unit 快照、daemon-reload、恢复原 timer 状态;不运行备份。
  • unit 正确但补跑备份后续阶段失败:不恢复旧 STORAGE_HOST_DIR,因为旧值已证实错误;保留新配置、失败摘要和本地诊断,按具体 phase 另行修复。
  • 新批次只有在 ARM finalize 后才更新 success state 和触发本地保留策略,失败不会删除现有最后成功恢复点。

5. Prevention

把“部署后 active mount 与自动备份 unit 合同一致”写入部署/试运行规约和 checklist。涉及 data path 的部署不能只验证应用 /ready;若自动备份 units 已安装,必须在交付结束前核对或刷新冻结的 project/build/PGDATA/storage 身份。