docs(project): add production-ready documentation
Add a top-level README plus production configuration, API, and rollout documentation. Also align deployment and runbook docs with the current runtime semantics, ports, and daily pipeline entrypoints.
This commit is contained in:
phamnazage-jpg
204
docs/PRODUCTION_CHECKLIST.md
Normal file
204
docs/PRODUCTION_CHECKLIST.md
Normal file
@@ -0,0 +1,204 @@
|
||||
# 生产上线检查清单
|
||||
|
||||
本文档面向“准备把当前仓库作为生产服务上线”的场景，聚焦发布前检查、上线步骤、回滚和日常守护要求。
|
||||
|
||||
## 目标
|
||||
|
||||
上线后的最小可用能力应包括：
|
||||
|
||||
- 数据库可连接且已完成全部迁移
|
||||
- API Server 可稳定返回 `/health`、`/api/v1/models`、`/api/v1/reports/latest`
|
||||
- 正式日报可由调度脚本按天产出
|
||||
- 失败时可回退、可告警、可恢复
|
||||
|
||||
## 生产拓扑建议
|
||||
|
||||
建议采用以下最小拓扑：
|
||||
|
||||
1. PostgreSQL 16
|
||||
2. API Server：`cmd/server/main.go` 构建产物
|
||||
3. Nginx：托管 `frontend/dist` 并反向代理 `/api` 与 `/health`
|
||||
4. Cron 或 systemd timer：执行 `scripts/run_daily.sh`
|
||||
|
||||
如果使用容器部署，仓库内 `docker-compose.yml` 可作为单机参考，但正式环境仍建议：
|
||||
|
||||
- 单独管理数据库持久化与备份
|
||||
- 在网关层处理 TLS、限流和访问控制
|
||||
- 将密钥注入部署系统，而不是依赖仓库内 `.env`
|
||||
|
||||
## 发布前硬检查
|
||||
|
||||
### 基础设施
|
||||
|
||||
- PostgreSQL 已创建库并验证可连接
|
||||
- `DATABASE_URL` 在 API Server、调度脚本、备份脚本所在环境都可用
|
||||
- `reports/daily` 及其归档目录所在磁盘有足够空间
|
||||
- `/tmp` 不会被过早清理，避免影响每天的流水线日志追踪
|
||||
|
||||
### 数据与迁移
|
||||
|
||||
- 已执行 `bash scripts/apply_migration.sh`
|
||||
- `daily_report`、`report_runs`、`subscription_plan`、`region_pricing` 等关键表存在
|
||||
- 历史数据回填策略已确认，避免上线首日“空库”
|
||||
|
||||
### 应用与产物
|
||||
|
||||
- `go test ./...` 通过
|
||||
- `bash scripts/test.sh` 通过
|
||||
- `cd frontend && npm run test -- --run` 通过
|
||||
- `cd frontend && npm run build` 通过
|
||||
- `go build ./cmd/server` 通过
|
||||
|
||||
### 调度与日报
|
||||
|
||||
- 正式调度命令已确定：`bash scripts/run_daily.sh`
|
||||
- 手工复跑命令已确定：`bash scripts/run_real_pipeline.sh`
|
||||
- 历史补跑命令已确定：`bash scripts/rebuild_historical_report.sh YYYY-MM-DD`
|
||||
- `OPENROUTER_API_KEY` 已在正式调度环境可用
|
||||
- `FEISHU_WEBHOOK` 已配置或明确不上告警
|
||||
|
||||
### 安全与访问控制
|
||||
|
||||
- 密钥未提交入库
|
||||
- API 暴露路径已放在网关后，不直接裸露到公网
|
||||
- 已补充访问控制、TLS、限流与日志保留策略
|
||||
- `scripts/restore.sh` 属于高风险脚本，使用权限已收敛到少数运维成员
|
||||
|
||||
## 上线门禁命令
|
||||
|
||||
建议按下面顺序执行：
|
||||
|
||||
```bash
|
||||
bash scripts/verify_pre_phase6.sh
|
||||
bash scripts/verify_phase6.sh
|
||||
bash healthcheck.sh
|
||||
```
|
||||
|
||||
其中 `verify_phase6.sh` 会额外检查：
|
||||
|
||||
- 真实采集链路
|
||||
- API Server 构建与健康检查
|
||||
- `/api/v1/models` 响应时间 `< 500ms`
|
||||
- 最近 7 次采集成功率 `>= 95%`
|
||||
- 前端测试入口存在
|
||||
|
||||
## 上线步骤
|
||||
|
||||
### 1. 发布前备份
|
||||
|
||||
```bash
|
||||
bash scripts/backup.sh
|
||||
```
|
||||
|
||||
确认：
|
||||
|
||||
- 备份文件已生成在 `/tmp/llm_hub_backups`
|
||||
- 备份文件大小非零
|
||||
- 如接入 OSS，远端对象已上传成功
|
||||
|
||||
### 2. 执行迁移
|
||||
|
||||
```bash
|
||||
bash scripts/apply_migration.sh
|
||||
```
|
||||
|
||||
### 3. 构建与发布 API Server / 前端
|
||||
|
||||
```bash
|
||||
go build -o bin/server ./cmd/server
|
||||
cd frontend && npm run build
|
||||
```
|
||||
|
||||
### 4. 部署反向代理
|
||||
|
||||
确认 Nginx 已正确代理：
|
||||
|
||||
- `/` -> `frontend/dist`
|
||||
- `/api/` -> `app:8080/api/`
|
||||
- `/health` -> `app:8080/health`
|
||||
|
||||
### 5. 手工真实复跑一次
|
||||
|
||||
```bash
|
||||
bash scripts/run_real_pipeline.sh
|
||||
```
|
||||
|
||||
目的：
|
||||
|
||||
- 验证真实采集、补录、日报生成和写库全链路
|
||||
- 确认不会错误覆盖“最新正式日报”语义
|
||||
|
||||
### 6. 启用正式调度
|
||||
|
||||
```cron
|
||||
0 8 * * * cd /path/to/llm-intelligence && bash scripts/run_daily.sh >> /tmp/llm_hub_cron.log 2>&1
|
||||
```
|
||||
|
||||
### 7. 线上冒烟
|
||||
|
||||
```bash
|
||||
curl -fsS http://127.0.0.1:8080/health
|
||||
curl -fsS http://127.0.0.1:8080/api/v1/models
|
||||
curl -fsS http://127.0.0.1:8080/api/v1/reports/latest
|
||||
```
|
||||
|
||||
## 运行中监控基线
|
||||
|
||||
建议至少监控以下指标：
|
||||
|
||||
| 指标 | 目标 / 告警线 | 说明 |
|
||||
|------|---------------|------|
|
||||
| API 健康检查 | `200` | `/health` 必须稳定可达 |
|
||||
| `/api/v1/models` 响应时间 | `< 500ms` | Phase 6 验收门槛 |
|
||||
| 最近 7 次采集成功率 | `>= 95%` | Phase 6 验收门槛 |
|
||||
| 模型总数 | `< 300` 告警 | 来自现有 RUNBOOK 基线 |
|
||||
| 今日日报是否生成 | 每天 08:00 后应存在 | 检查 `daily_report` 与产物文件 |
|
||||
| 归档是否完整 | Markdown + HTML 均存在 | 检查 `reports/daily/YYYY/MM/` |
|
||||
|
||||
## 回滚方案
|
||||
|
||||
### 何时触发回滚
|
||||
|
||||
- API Server 启动失败或健康检查持续异常
|
||||
- 真实流水线连续失败且无法在发布窗口内修复
|
||||
- 正式日报生成语义错误，导致“最新正式日报”被污染
|
||||
- 迁移导致查询失败或关键表结构异常
|
||||
|
||||
### 回滚步骤
|
||||
|
||||
1. 停止正式调度，避免继续写入错误数据
|
||||
2. 回滚应用版本或镜像
|
||||
3. 如数据已损坏，使用备份恢复：
|
||||
|
||||
```bash
|
||||
bash scripts/restore.sh --force /path/to/backup.sql.gz
|
||||
```
|
||||
|
||||
4. 重新执行迁移到目标版本所需状态
|
||||
5. 启动服务后执行：
|
||||
|
||||
```bash
|
||||
bash healthcheck.sh
|
||||
curl -fsS http://127.0.0.1:8080/health
|
||||
curl -fsS http://127.0.0.1:8080/api/v1/reports/latest
|
||||
```
|
||||
|
||||
## 常见上线遗漏
|
||||
|
||||
- 只启动 API，没有配置正式日报调度
|
||||
- 只写入 `daily_report`，但落盘目录没有写权限
|
||||
- 手工复跑后误以为“正式日报已准备好”，但 `is_official_daily=false`
|
||||
- 把 API 直接暴露到公网，却没有鉴权或限流
|
||||
- 依赖 `.env.local`，但生产机器并不存在该文件
|
||||
- 没有先跑 `backup.sh` 就执行高风险恢复或迁移
|
||||
|
||||
## 建议的发布结论标准
|
||||
|
||||
满足以下条件后，才建议标记为“可生产上线”：
|
||||
|
||||
- `verify_pre_phase6.sh` 通过
|
||||
- `verify_phase6.sh` 通过
|
||||
- 手工真实复跑成功
|
||||
- API / 前端冒烟通过
|
||||
- 正式调度已配置并完成一次演练
|
||||
- 备份与恢复路径已演练至少一次
|
||||
Reference in New Issue
Block a user