hyb-oa/.trellis/tasks/08-01-production-secret-recovery-env-externalization/implement.md

生产密钥恢复与环境文件外置：实施计划

0. 边界

• 本任务按 Phase 1、Phase 2 分开批准、提交和验收；Phase 1 批准不授权生产访问或迁移。
• 不读取、打印、哈希或提交生产 Secret；只处理键名、类别、布尔状态和计数。
• FIELD_ENCRYPTION_KEY 版本化/keyring/重加密登记为后续任务，不在本轮顺手实现。

1. Phase 1：恢复卡与分类合同

• 从 .env.example 自动提取当前键集合，逐项归入 5 个固定类别；对 FIELD_ENCRYPTION_KEY、数据库口令、JWT/pepper、外部平台凭据做人工复核。
• 新增无值的 JSON 分类合同，并扩展 validate-env-contract.js：全集相等、恰好一次、类别固定、键名格式正确、内容不含疑似赋值/Secret 正文。
• 更新 deploy/trialrun/runbook.md 顶部恢复卡，写清 5 类影响、责任人与恢复后验证；数据库为隔离停机重置，不写成明文找回。
• 更新 .trellis/spec/hyb-oa/deployment-trialrun.md，固化环境恢复分类、双人托管、preserve_original 最高风险和 keyring 延期边界。
• 增加聚焦单元测试：正常 164-key 合同、漏键、重复键、多余键、未知类别、非法键名/疑似值、FIELD_ENCRYPTION_KEY 与 POSTGRES_PASSWORD 错误分类。
• 运行环境合同、聚焦测试、server 全量测试、JS 语法、task/governance/process/docs/sensitive/diff 门禁。
• Phase 1 单独提交；证据明确“未访问或修改生产”，不把文档完成冒充密钥已封存。

5. Phase 1 验证证据（2026-08-01）

• 环境合同：PASS，.env.example 164 个键，恢复分类 164 个键，恰好覆盖一次。
• Prisma 与语法：prisma validate、validator/test node --check 均 PASS。
• 服务端全量：173 个测试文件、1144 个测试 PASS；其中恢复分类聚焦用例 8/8 PASS，既有部署安全用例 7/7 PASS。
• 治理门禁：task validate、Trellis governance、process contract、sensitive-content scan、git diff --check 均 PASS；docs registry audit 为 0 error、1 个既有汇总 warning（22 个未登记 docs 文件）。
• 人工复核：五类语义、双人托管、PostgreSQL 隔离停机重置与 FIELD_ENCRYPTION_KEY 原值保留边界一致；清单仅含键名和类别。
• 操作边界：本阶段未连接、读取或修改生产；未创建密码库条目，未迁移 env，未修改 Compose/systemd，未重启服务，也未删除任何生产文件。

2. Phase 2：代码与脚本准备（仍不自动迁移）

• Compose 四个 service 使用显式 ${REMOTE_ENV_FILE}；部署、备份、WARCH3、巡检和 QA 脚本移除同步树内生产默认。
• deploy.sh、preflight 和环境合同拒绝 env 与同步树重叠，校验 root owner、0600、普通非 symlink 文件；保留 rsync exclude 仅作纵深防御。
• 更新 runbook、checklist、管理员手册和 OPS7 中所有生产路径示例；本地示例明确使用非生产测试 env。
• 扩展合成回归，覆盖旧路径拒绝、新路径通过、Compose v1/v2 config、4 个 unit 参数一致、rsync 前失败和旧副本否定检查。
• 运行 Docker Compose config、部署合同、备份合同、全量测试与 Trellis 门禁；单独提交但不连接生产。

3. Phase 2：生产迁移（另行明确批准）

• 只读冻结活动 project、构建、当前 env、PGDATA/storage、4 个 service/timer；确认系统管理员与公司负责人均可取用 preserve_original 封存项，只记录完成状态。
• root 原子复制到同步树外目标，校验键集合、owner/mode/非 symlink；不输出值或文件内容。
• 重装 4 个 units，运行 Compose config、新 init 配置预检并切换 server；未获批准不启用 worker/minio profile。
• 验证 migration status、/ready、external/runtime smoke、普通登录、企微入口、automatic backup daily/watchdog、4 个 timer 和构建身份。
• 验收全部通过后按精确旧路径删除旧副本；再次证明旧路径不存在，活动容器和 units 只引用新路径。
• 任一验证失败时，在旧副本删除前回滚 unit/Compose 引用；记录失败尝试，不美化为一次成功。

4. 后续独立任务

• 建立 FIELD_ENCRYPTION_KEY 版本化与安全轮换任务：带 key id 的新密文格式、keyring、惰性/批量重加密、全字段覆盖、审计与旧键删除门禁。
• 约 18 个孤儿 E2E 继续作为独立测试治理任务，不与密钥恢复混做。