quyun-v2/docs/go_live_steps.md

生产上线步骤文档（Go-Live SOP）

1. 目的与范围

本文用于指导 quyun_v2 的生产发布，覆盖：

• Backend（Go/Fiber）
• Frontend（portal / superadmin）
• 数据库迁移、健康检查、页面流验收、回滚触发

适用于常规功能发布与 P0/P1 缺陷修复发布。

---

2. 上线角色

• Release Owner：发布总控、Go/No-Go 决策
• Backend Owner：后端发布、migration、健康检查
• Frontend Owner：前端发布、页面流验证
• QA Owner：验收证据收集与签核

---

3. 上线前门禁（必须全部通过）

3.1 代码门禁

# backend
cd backend && 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

3.2 CI 门禁

• backend/.gitea/workflows/build.yml 全部 Job 通过：
  • FrontendChecks
  • BackendChecks
  • DockerImage

3.3 配置门禁

• backend/config.prod.toml 中敏感值必须来自部署 Secret 注入（非明文）
• release 模式 DB 必须 TLS（Database.SslMode=require/verify-*）

---

4. 上线执行步骤（按顺序）

Step 0：变更冻结与版本确认

1. 确认待发 commit / tag。
2. 冻结主干高风险变更（发布窗口内禁止插入新功能）。
3. 在发布群同步时间窗与负责人。

Step 1：备份（发布前）

按 docs/backup_restore_runbook.md 执行：

• PostgreSQL 备份（pg_dump）
• 对象存储备份（local tar / S3 mirror）
• 记录备份文件路径与时间戳

任一步失败，停止发布。

Step 2：部署后端

1. 发布 backend 新版本（镜像/二进制）。
2. 若包含 migration，先在发布流程中执行：

cd backend
go run . migrate up

3. 启动服务并检查：

curl -f -sS http://<backend-host>:<port>/healthz
curl -f -sS http://<backend-host>:<port>/readyz

要求：两者均返回 2xx。

Step 3：部署前端（portal/superadmin）

1. 发布 portal 产物。
2. 发布 superadmin 产物。
3. 如有 CDN，执行缓存刷新。

Step 4：功能验收（页面流）

至少覆盖：

• portal：首页加载、登录后核心业务页（如订单/内容）
• superadmin：登录页、关键列表页

要求：

• 页面可渲染，无致命报错
• 与后端联调正常
• 截图入证据目录：docs/release-evidence/<date>/

Step 5：发布确认（Go/No-Go）

Release Owner 汇总以下证据：

• 测试与构建结果
• healthz/readyz 结果
• 页面流验证结果
• 备份完成证明

满足后执行 Go；否则 No-Go 并触发回滚。

---

5. 发布后观察（至少 30 分钟）

重点监控：

• 错误率、超时率、5xx
• 接口成功率与 P95 延迟
• 关键业务转化（登录、下单、支付、审计查询）

若出现异常且 15 分钟内无法恢复，触发回滚。

---

6. 回滚触发与执行

触发条件（任一满足）：

• healthz/readyz 持续失败
• 关键业务流中断
• 错误率异常上升

执行参考：docs/rollback_runbook.md

回滚后必须再次验证：

• /healthz、/readyz
• portal/superadmin 关键页面
• 关键业务链路

---

7. 证据归档要求

发布完成后，更新：

• docs/release-evidence/<date>.md

最少包含：

1. 发布版本/commit
2. 门禁结果（测试、构建、CI）
3. 备份与恢复点
4. healthz/readyz 检查结果
5. 页面流验证截图路径
6. 最终结论（Go / No-Go）

---

8. 一键检查清单（简版）

• backend go test ./... pass
• portal lint/build pass
• superadmin lint/build pass
• CI workflow 全绿
• 发布前备份完成
• backend 发布成功
• healthz/readyz 正常
• frontend 发布成功
• 页面流验收通过
• 证据归档完成
• 观察期无异常