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