备份、恢复与恢复演练

Halro 的数据目录是一个一致性单元。数据库、Ledger、Audit、Usage 与本地 Provider 对象必须一起备份和恢复，不能只复制 halro.db，也不能组合不同时间点的文件。

三份恢复材料必须分开

一次可恢复备份至少依赖：

加密的 .hmbk 归档；
独立的 32 字节 Backup Key；
归档创建时使用的 File-mode Master Key，或对应 Key Slot/KMS descriptor 与目标恢复身份。

Halro 备份不会包含 Master Key、Backup Key、TLS 私钥、Metrics Token、云身份 Token 或 Recovery 凭据。归档、Backup Key 和 Master Key 不应存放在同一个卷、Bucket、快照或故障域。

失败诊断捕获也不进入归档；不过恢复时保留的旧 previous_data_dir 可能仍含未过期诊断内容，应按原隐私保留策略保护和清理。

创建并校验备份

创建备份、恢复和会访问数据目录的维护命令需要独占数据目录：先停止 Halro，并确认服务已经释放锁；不要删除锁文件来绕过失败。backup verify 只读取归档和 Backup Key，不访问数据目录，可以在实例运行时独立执行；它仍不能代替隔离恢复演练。

创建专用 Backup Key：

umask 077
openssl rand 32 > /secure-secrets/halro-backup.key
test "$(wc -c < /secure-secrets/halro-backup.key | tr -d ' ')" -eq 32

创建归档时，输出必须是数据目录外尚不存在的绝对路径：

halro backup create \
  --config /etc/halro/config.yaml \
  --output /secure-backups/halro-2026-09-05.hmbk \
  --key-file /secure-secrets/halro-backup.key

halro backup verify \
  --file /secure-backups/halro-2026-09-05.hmbk \
  --key-file /secure-secrets/halro-backup.key

保存校验返回的非敏感 manifest、Backup ID、二进制版本、创建时间、Master Key 代次或 Key Slot descriptor 标识，以及归档上传结果。backup verify 只证明归档认证、manifest 和文件校验一致，不能证明目标环境仍能取得正确 Master Key 或 KMS 权限。

隔离恢复演练

恢复演练必须在隔离环境中使用与备份兼容的 Halro 版本。为演练准备独立配置，使监听地址保持回环，并让 storage.data_dir 指向演练卷中的子目录；File 模式使用该备份所记录的原 Master Key。不要把生产数据目录直接当演练目标。

先校验归档并复制返回的准确 Backup ID，再执行：

halro backup verify \
  --file /secure-backups/halro-2026-09-05.hmbk \
  --key-file /secure-secrets/halro-backup.key

halro backup restore \
  --config /etc/halro/staging-config.yaml \
  --file /secure-backups/halro-2026-09-05.hmbk \
  --key-file /secure-secrets/halro-backup.key \
  --confirm-backup-id bkp_REPLACE_WITH_VERIFIED_ID

--confirm-backup-id 是破坏性操作的精确确认，不能猜测或复用另一份归档的 ID。恢复成功后，旧目标目录会以 previous_data_dir 返回并保留，完成验证和回滚保留期前不要删除。

恢复后先保持外部流量关闭，并执行：

halro doctor --config /etc/halro/staging-config.yaml
halro audit verify --config /etc/halro/staging-config.yaml
halro ledger verify --config /etc/halro/staging-config.yaml
halro usage verify --config /etc/halro/staging-config.yaml

随后启动恰好一个实例，验收 /health/live、/health/ready、Admin 登录与 MFA、Metrics、Provider 连接测试、普通请求、流式请求和 Usage 结算。恢复结果列出的已启用 Gateway Key 必须与事故和撤销记录逐项对照；旧备份可能恢复后来已经停用的 Key。

如果恢复后 Deployment 进入价格隔离，不要直接开放流量。在 Admin Console 重新核对当前 Provider 条款和价格来源，再经重新认证执行恢复确认，或建立正确的新 Price Version。

Key Slot 的 Recovery 恢复

只有经过审批的恢复场景才使用 Recovery Slot，并准确填写配置中的 Slot ID：

halro backup restore \
  --config /etc/halro/staging-config.yaml \
  --file /secure-backups/halro-2026-09-05.hmbk \
  --key-file /secure-secrets/halro-backup.key \
  --confirm-backup-id bkp_REPLACE_WITH_VERIFIED_ID \
  --use-recovery-slot \
  --confirm-recovery-slot slot_aws_recovery

Recovery 身份只用于离线验证和恢复，不能成为 Runtime 的长期身份。恢复后应先修复并独立验证新的 Primary，再撤销临时 Recovery/Lifecycle 授权。Key Slot 当前成熟度和完整步骤见 Master Key 与 Key Slot 生命周期。

生产恢复门禁

只有以下条件同时成立，才能把一次演练记为“可恢复”：

使用目标环境真实的密钥托管和权限边界，而非只运行 backup verify；
doctor、Audit、Ledger 与 Usage 验证全部通过；
Admin、MFA、Provider、正常/流式调用和费用结算通过；
恢复出的 Gateway Key 与价格状态完成复核；
记录 Backup ID、版本、时间、操作者、结果和非敏感证据；
原数据、原镜像和 previous_data_dir 保留到批准的回滚窗口结束。