ai-contract-platform/project-docs/V2-P1-04.9.1-kms-vault-slo-escalation-replay-handoff-runbook-2026-08-24.md

P1-04.9.1 实施与验收报告：KMS/Vault、SLO 升级、回放死信接管与错误手册

日期：2026-08-24
状态：实现、迁移、全量自动化与超级管理员 Chrome UAT 均完成。

1. 本阶段目标

1. 将企业日历 OAuth token、国内企业应用 secret、短期 token 与增量游标从单一本地主密钥扩展为可插拔 Vault Transit / 企业 KMS 托管。
2. 建立持久化恢复探针和不可变演练证据，确认“能加密”之外也“能恢复历史密文”。
3. 把日历 SLO 从只读仪表盘升级为打开、提醒、升级、恢复的通知生命周期。
4. 为回放死信增加负责人、人工重入、人工解决和不可变事件账本。
5. 将确定性错误分类发布为管理端可查的版本化运营手册。

2. 已实现范围

2.1 密钥托管

• 后端：local_fernet、vault_transit、kms_gateway。
• 新密文使用带后端版本的 envelope，错误后端不会静默尝试解密。
• Vault Transit 使用实际 encrypt/decrypt HTTP 契约；KMS 网关使用实际 HTTPS/Bearer 最小契约，可在网关侧适配阿里云、腾讯云或 HSM。
• 外部托管凭据只从文件读取，HTTP 不跟随重定向，生产强制 HTTPS。
• production 使用 local_fernet 时运行时检查返回 error。
• 旧 Fernet 密文通过独立、临时、只读 legacy recovery key file 双读，不允许与新密文后端混淆。

2.2 恢复演练

• 管理端展示脱敏托管状态、生产门禁、key reference 和旧密文恢复状态。
• round_trip 用于即时加解密验证；recovery_canary 会优先解密此前持久化的同一探针。
• 数据库不保存探针明文，只保存密文、期望摘要、恢复摘要、匹配结果、耗时和脱敏错误。
• 成功和失败都形成租户隔离的不可变证据。

2.3 SLO 告警升级

• 租户策略新增：告警开关、冷却分钟、升级等待分钟、恢复通知开关。
• Worker 生成 opened、reminded、escalated、resolved 事件。
• L1/L2 与首次观察时间一并保存；外部通知失败不影响 SLO 事件证据。
• 现有通知通道迁移时自动订阅 SLO 打开、升级、恢复和回放死信事件。

2.4 回放死信人工接管

• 回放任务新增负责人、接管原因、接管时间、人工重入累计、人工结论。
• 新增动作：take_over、requeue、resolve、cancel。
• 仅死信可接管、重入或人工解决；运行中任务禁止人工取消。
• 人工重入重置本轮 attempt count，但保留 manual_requeue_count、原失败运行和完整事件账本。
• 回放进入死信时自动发出站内及已订阅外部通知。

2.5 提供方错误手册

• 九类错误均定义默认重试性、首响/升级分钟、负责人角色和操作步骤。
• API 返回版本与 SHA-256 摘要，管理页展示同一目录，便于确认前后端手册一致。
• 本地详细手册：project-docs/playbook-calendar-provider-error-operations-runbook-2026-08-24.md。

3. 数据与接口

迁移：20260824_0062。

新增表：

• playbook_secret_recovery_drills
• playbook_calendar_slo_alert_events
• playbook_calendar_replay_events

新增接口：

• GET /governance/secret-custody/status
• GET|POST /governance/secret-custody/recovery-drills
• GET /governance/calendar-slo-alert-events
• GET /governance/calendar-provider-error-catalog
• GET /governance/calendar-replay-jobs/{job_id}/events
• POST /governance/calendar-replay-jobs/{job_id}/intervention

OpenAPI 当前为 117 paths / 174 schemas；最终验收会再次验证 YAML 可解析。

4. 明确边界

• 本地/UAT 没有伪造真实 Vault、阿里云 KMS 或腾讯云 KMS 账号；外部适配器通过隔离 MockTransport 验证请求、响应、密文 envelope 和 legacy 双读。
• 真正发布前仍需客户提供 Vault/KMS endpoint、key、文件凭据、CA 链和网络白名单，在隔离预发布环境执行恢复演练。
• KMS 网关负责云厂商认证、密钥轮换与 AAD 元数据；合同 API 不持有云厂商 AccessKey。

5. 验收证据

最终结果：

• 后端：355 collected，351 passed，4 skipped；无失败。新增用例覆盖 Vault Transit、KMS 网关、legacy 双读、production 门禁、持久化恢复探针、SLO 打开/升级/恢复、回放死信接管/重入。
• PostgreSQL：升级到 20260824_0062 (head)；全新 SQLite 从零升级到 head 也通过。
• 前端：typecheck 通过；45/45 测试通过；生产 build 通过，143 个页面/路由。
• OpenAPI：YAML 可解析，117 paths / 174 schemas，所有 schema $ref 均可解析。
• 服务：Contract API 8100 health=ok，Web 3000 HTTP 200，AI API 8101 保持运行；治理 Worker 重启且 stderr 无错误。
• 超级管理员 Chrome UAT：账号 uat.legal.20260823@example.test、工作区“Playbook 隔离 UAT”；P1-04.9.1、托管状态、恢复探针、SLO 升级、错误手册、回放人工接管均可见，治理数据加载错误为 false。

UAT 未点击“解密持久化恢复探针”，避免在用户租户写入额外演练证据；该写操作已由隔离 API 自动化覆盖。