From dc8b95a25714c61c760775866393ae640ca89a98 Mon Sep 17 00:00:00 2001
From: Rogee <rogee@ipao.vip>
Date: Mon, 9 Feb 2026 11:47:15 +0800
Subject: [PATCH] docs: add production go-live step-by-step guide

---
 docs/go_live_steps.md | 171 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 171 insertions(+)
 create mode 100644 docs/go_live_steps.md

diff --git a/docs/go_live_steps.md b/docs/go_live_steps.md
new file mode 100644
index 0000000..1ec6bac
--- /dev/null
+++ b/docs/go_live_steps.md
@@ -0,0 +1,171 @@
+# 生产上线步骤文档（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 代码门禁
+
+```bash
+# 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，先在发布流程中执行：
+
+```bash
+cd backend
+go run . migrate up
+```
+
+3. 启动服务并检查：
+
+```bash
+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 发布成功
+- [ ] 页面流验收通过
+- [ ] 证据归档完成
+- [ ] 观察期无异常