quyun-v2/docs/plans/2026-02-09.md

Implementation Plan: 生产级部署能力 P0 补齐（两周）

Branch: [prod-p0-hardening] | Date: 2026-02-09 | Spec: 当前会话需求（生产部署能力评估后的整改计划） Input: 基于当前评估结果（12/24，50%）制定 P0 硬化计划，目标达到可审签上线门槛。

Summary

本阶段聚焦“可发布但未完全生产就绪”的关键缺口，按 P0 优先级补齐以下 5 项：

1. Secrets 治理：移除/替换仓库中生产明文敏感配置，完成密钥轮换与注入规范。
2. 生产数据库 TLS 强制：release 模式下禁止 sslmode=disable。
3. CI/CD 强门禁：强制 backend go test ./...、frontend lint(check-only)+build、最小 smoke 验证。
4. 备份恢复与回滚闭环：形成 runbook 并完成预发演练，沉淀可追溯证据。
5. /readyz 深度就绪检查：由“存活探针”升级为“依赖感知探针”。

阶段产出是可审签的 Go/No-Go 结论与证据链；未通过门禁则不得标记生产就绪。

Technical Context

Language/Version:

• Backend: Go（Fiber + GORM-Gen）
• Frontend: Vue 3 + Vite（portal/superadmin）

Primary Dependencies:

• Backend: backend/providers/http/*, backend/providers/postgres/*, backend/app/commands/*
• Frontend: frontend/portal/package.json, frontend/superadmin/package.json
• CI: backend/.gitea/workflows/build.yml

Storage:

• PostgreSQL
• Redis（若 readiness 纳入依赖探测）

Testing:

• Backend: cd backend && env GOCACHE=$PWD/.gocache GOTMPDIR=$PWD/.gotmp go test ./...
• Frontend:
  • npm -C frontend/portal run lint
  • npm -C frontend/portal run build
  • npm -C frontend/superadmin run lint
  • npm -C frontend/superadmin run build
• Frontend 页面流（受影响路径）:
  • superadmin 登录与关键列表页加载
  • portal 登录与关键业务页加载

Target Platform:

• Linux server / containerized deployment

Project Type:

• Web application（frontend + backend）

Performance Goals:

• readiness 依赖检查在健康场景下响应 p95 <= 200ms（不含外部网络抖动）
• CI 主门禁总时长可控（目标 <= 20 分钟，按流水线并行优化）

Constraints:

• 不手改生成文件（routes.gen.go, docs.go, swagger.*）
• 控制器保持薄层（bind -> services -> return）
• 不使用 as any / @ts-ignore / @ts-expect-error
• Bugfix 最小化，不做无关重构

Scale/Scope:

• 覆盖 backend 发布安全基线、CI 门禁、前端构建策略、发布/回滚操作基线

Constitution Check

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

• ✅ 满足仓库“先计划后实施”要求：本计划作为当前活动计划。
• ✅ 覆盖测试与前端页面流验收要求（frontend-involved 必须含页面流 + backend go test ./...）。
• ✅ 变更范围集中于 P0 风险，不引入无关架构调整。
• ✅ 包含任务拆解、依赖、验收标准、风险与证据路径。

Project Structure

Documentation (this phase)

docs/
├── plan.md                               # 当前活动计划（本文件）
├── release-evidence/<date>.md            # 执行证据（测试/演练/门禁结果）
└── plans/<date>.md                       # 阶段通过后归档

Source Code (repository root)

backend/
├── .gitea/workflows/build.yml
├── providers/
│   ├── http/engine.go
│   └── postgres/config.go
├── app/commands/
│   └── http/http.go
└── config*.toml

frontend/
├── portal/package.json
└── superadmin/package.json

Structure Decision: 在现有目录中做增量硬化；不新增子工程，不改动无关模块。

Plan Phases

Phase 1 — Secrets 基线治理（D1-D2）

• 盘点仓库中敏感配置（DB/JWT/Storage/第三方凭据）
• 输出替换与轮换清单（包含责任人与窗口）
• 将生产敏感配置改为安全注入策略（模板化占位）

Phase 2 — 后端安全与可用性护栏（D3-D4）

• release 模式强制 DB TLS
• /readyz 增加依赖探测（DB，按实际接入补 Redis/Storage）
• 补充依赖异常路径测试

Phase 3 — CI/CD 门禁与前端可复现性（D5-D6）

• CI 增加强制 test/lint/build/smoke 门禁
• 前端 lint 分离为 check-only 与 fix-only 模式
• 失败即阻断发布流程

Phase 4 — 恢复能力与回滚演练（D7-D8）

• 备份/恢复 runbook
• 回滚 runbook（应用版本与数据变更策略）
• 在预发环境进行演练并记录证据

Phase 5 — 总体验证与发布评审（D9-D10）

• 运行全量门禁
• 完成页面流验证
• 形成 Go/No-Go 决策与归档动作

Tasks

• T1 建立敏感信息台账（位置、等级、替代方案、责任人）。
• T2 制定并执行密钥轮换计划（含失效旧密钥）。
• T3 清理仓库中的生产明文敏感配置，改为模板/注入方式。
• T4 在 backend 增加 release 模式 DB TLS 强制校验。
• T5 升级 /readyz 为依赖感知检查（至少 DB）。
• T6 增加 readiness 相关测试（依赖正常/异常两类）。
• T7 改造 CI：加入 backend go test ./... 强门禁。
• T8 改造 CI：加入 portal/superadmin lint(check-only)+build 门禁。
• T9 增加最小 smoke（API + 页面流）门禁。
• T10 前端脚本拆分：lint(check-only) 与 lint:fix(本地修复)。
• T11 编写 backup/restore runbook。
• T12 编写 rollback runbook（含触发条件与回退步骤）。
• T13 在预发完成一次备份恢复演练并留存证据。
• T14 在预发完成一次回滚演练并留存证据。
• T15 执行 backend 全量测试并记录结果。
• T16 执行双前端 lint/build 并记录结果。
• T17 执行受影响前端页面流验证并记录结果。
• T18 汇总发布门禁清单并形成 Go/No-Go 结论。
• T19 Go 时归档 docs/plan.md -> docs/plans/<date>.md，并清空活动 docs/plan.md。

Dependencies

• T1 -> T2 -> T3（先盘点，再轮换，再清理）
• T4 + T5 -> T6（代码完成后补测试）
• T7 + T8 + T9 依赖 T4/T5/T10（门禁规则与代码策略一致）
• T11 + T12 -> T13/T14（先文档后演练）
• T6 + T7 + T8 + T9 + T13 + T14 -> T15/T16/T17 -> T18
• T18(Go) -> T19

Acceptance Criteria

1. 仓库中不再存在生产明文敏感配置；密钥轮换已完成且有记录。
2. release 模式下若 DB 配置非 TLS，服务必须拒绝启动并给出明确错误。
3. /readyz 能真实反映依赖健康状态（异常返回非 2xx）。
4. CI 对 backend test、frontend lint/build、smoke 具备不可绕过门禁。
5. backup/restore 与 rollback 均完成至少一次预发演练并有证据。
6. 前端受影响页面流验证通过；backend go test ./... 通过。
7. 发布结论明确（Go/Conditional Go/No-Go），并可追溯到证据文件。

Risks

• 风险1：密钥轮换影响现网可用性

  • 缓解：采用双窗口/灰度切换，先验证再失效旧密钥。

• 风险2：readiness 判定过严导致误摘流量

  • 缓解：设置超时、重试和降级策略，先在预发压测验证。

• 风险3：CI 门禁增加导致发布节奏变慢

  • 缓解：门禁并行化、缓存依赖、区分必选与补充检查。

• 风险4：演练环境与生产不一致导致“伪通过”

  • 缓解：预发配置尽量贴近生产，并记录偏差项。

Complexity Tracking

Violation	Why Needed	Simpler Alternative Rejected Because
N/A	N/A	N/A