# 生产上线步骤文档（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 发布成功
- [ ] 页面流验收通过
- [ ] 证据归档完成
- [ ] 观察期无异常