merge: 集成V2.8 生产硬化与运维闭环
# Conflicts: # .gitignore # docs/deployment.md # docs/roadmap.md # package.json
This commit is contained in:
。
@@ -175,12 +175,13 @@ cp .env.production.example .env.production
|
||||
5. 执行 `docker compose --env-file .env.production -f docker-compose.prod.yml pull web server` 拉取本次 SHA 镜像。
|
||||
6. 启动数据库与 Redis，执行 `pnpm --filter server db:deploy`。
|
||||
7. 执行 `docker compose --env-file .env.production -f docker-compose.prod.yml up -d --remove-orphans` 重启服务。
|
||||
8. 通过 `/api/v1/health/version` 校验运行中的后端版本是否等于本次 commit SHA。
|
||||
8. 运行发布 smoke test：校验 `/api/v1/health/version`、前端首页、产品页、产品 API、V2.2 读路径和 AI 配置端点，并确认运行中的后端版本等于本次 commit SHA。
|
||||
|
||||
如果最后一步失败，Actions 会红掉，说明“代码已合并”不等于“线上容器已更新”。本地或服务器也可以手工运行：
|
||||
如果最后一步失败，Actions 会红掉，说明“代码已合并”不等于“线上容器已更新”或关键读路径不可用。本地或服务器也可以手工运行：
|
||||
|
||||
```bash
|
||||
pnpm deploy:check-runtime http://localhost/api/v1/health/version <expected-commit-sha>
|
||||
pnpm deploy:smoke -- --base-url http://localhost --expected-version <expected-commit-sha>
|
||||
```
|
||||
|
||||
## Nginx 路由
|
||||
@@ -193,6 +194,30 @@ pnpm deploy:check-runtime http://localhost/api/v1/health/version <expected-commi
|
||||
|
||||
生产 Compose 默认只监听 HTTP 80。HTTPS 建议优先交给云负载均衡、CDN 或宿主机外层证书管理工具；如果要让本 Compose 内的 Nginx 直接处理 HTTPS，可以在后续增加证书 volume 和 443 server block。
|
||||
|
||||
## 监控与告警基线
|
||||
|
||||
V2.8 提供可选 `monitoring` profile，不影响默认生产启动。启用前先在 `.env.production` 设置 `GRAFANA_ADMIN_PASSWORD`，不要使用示例密码对外暴露 Grafana。
|
||||
|
||||
```bash
|
||||
docker compose --env-file .env.production -f docker-compose.prod.yml --profile monitoring up -d
|
||||
```
|
||||
|
||||
默认入口：
|
||||
|
||||
- Prometheus: `http://localhost:9090`
|
||||
- Grafana: `http://localhost:3002`
|
||||
|
||||
配置目录在 `deploy/monitoring/`。基线覆盖：
|
||||
|
||||
- `FtbPostgresDown`：PostgreSQL 不可用。
|
||||
- `FtbDiskPressure`：宿主机根分区低于 15% 可用空间。
|
||||
- `FtbSlowApiLogBurst`：服务端慢 API 日志在 10 分钟内超过阈值。
|
||||
- `FtbSlowPrismaLogBurst`：慢 Prisma 查询日志在 10 分钟内超过阈值。
|
||||
- `FtbJobFailureLogBurst`：AppData 同步、AI 调用或后台任务失败日志出现。
|
||||
- `FtbXiaobaoSummaryStale`：`xiaobao_risk_summaries` 存在 dirty 或超过 6 小时未更新的摘要。
|
||||
|
||||
Prometheus 只加载本地规则，不提交真实通知密钥。接入 Slack、企业微信、邮件等通知时，把 Alertmanager receiver 放在未跟踪的服务器文件或环境变量中。
|
||||
|
||||
## 数据持久化
|
||||
|
||||
生产 Compose 使用三个命名 volume：
|
||||
@@ -235,6 +260,76 @@ pnpm consistency:v25 -- --url http://localhost/api/v1/consistency
|
||||
- `warn` 需要记录原因；历史数据没有审计事件属于预期 warning，不阻断 V2.5。
|
||||
- 后台页面 `/admin/consistency` 展示同一份报告，需要当前用户具备 `consistency:view`。
|
||||
|
||||
## 备份与恢复
|
||||
|
||||
备份分两类：PostgreSQL 业务数据和 `server_data` volume 中的运行时配置。真实备份文件默认写到 `backups/`，该目录已加入 `.gitignore`，不要把 dump 或 tar 包提交到仓库。
|
||||
|
||||
先演练命令，不写文件：
|
||||
|
||||
```bash
|
||||
pnpm backup:postgres -- --dry-run --env-file .env.production
|
||||
pnpm backup:server-data -- --dry-run --env-file .env.production
|
||||
```
|
||||
|
||||
执行正式备份：
|
||||
|
||||
```bash
|
||||
pnpm backup:postgres -- --env-file .env.production
|
||||
pnpm backup:server-data -- --env-file .env.production
|
||||
```
|
||||
|
||||
PostgreSQL 备份使用 `pg_dump --format=custom --no-owner --no-acl`，便于跨环境恢复。`server_data` 备份使用只读 volume mount 和 `tar -czf`，覆盖 AI Provider 配置等后端运行时文件。
|
||||
|
||||
恢复数据库必须显式确认覆盖。默认命令会拒绝执行，防止误删现有库：
|
||||
|
||||
```bash
|
||||
pnpm restore:postgres -- --env-file .env.production --input backups/postgres/ftb_pm-postgres-20260708T120000Z.dump
|
||||
```
|
||||
|
||||
确认要把目标数据库重建为 fresh DB 后，再运行：
|
||||
|
||||
```bash
|
||||
pnpm restore:postgres -- \
|
||||
--env-file .env.production \
|
||||
--input backups/postgres/ftb_pm-postgres-20260708T120000Z.dump \
|
||||
--confirm-overwrite
|
||||
```
|
||||
|
||||
恢复前建议先 dry-run 看清将执行的 `psql/dropdb/createdb/pg_restore` 步骤：
|
||||
|
||||
```bash
|
||||
pnpm restore:postgres -- \
|
||||
--dry-run \
|
||||
--confirm-overwrite \
|
||||
--env-file .env.production \
|
||||
--input backups/postgres/ftb_pm-postgres-20260708T120000Z.dump
|
||||
```
|
||||
|
||||
如果要恢复到临时库做校验，不覆盖当前生产库：
|
||||
|
||||
```bash
|
||||
pnpm restore:postgres -- \
|
||||
--env-file .env.production \
|
||||
--input backups/postgres/ftb_pm-postgres-20260708T120000Z.dump \
|
||||
--target-db ftb_pm_restore_check \
|
||||
--confirm-overwrite
|
||||
```
|
||||
|
||||
## 运维 Runbooks
|
||||
|
||||
生产发布、迁移和异常处置优先使用这些手册：
|
||||
|
||||
- `docs/runbooks/migration-rollback.md`：发布失败、迁移失败、数据恢复和镜像回滚。
|
||||
- `docs/runbooks/appdata-retirement.md`：AppData key 分阶段退场、双读核对、归档和回滚。
|
||||
- `docs/runbooks/xiaobao-background-jobs.md`：小宝摘要 stale 告警、手动刷新和未来后台任务规则。
|
||||
- `docs/production-readiness.md`：生产发布前后证据清单。
|
||||
|
||||
提交前运行 runbook 扫描：
|
||||
|
||||
```bash
|
||||
pnpm docs:check-runbooks
|
||||
```
|
||||
|
||||
## 升级流程
|
||||
|
||||
```bash
|
||||
@@ -248,7 +343,8 @@ docker compose --env-file .env.production -f docker-compose.prod.yml exec server
|
||||
升级前建议先备份数据库：
|
||||
|
||||
```bash
|
||||
docker compose --env-file .env.production -f docker-compose.prod.yml exec postgres pg_dump -U "$POSTGRES_USER" "$POSTGRES_DB" > ftb_pm_backup.sql
|
||||
pnpm backup:postgres -- --env-file .env.production
|
||||
pnpm backup:server-data -- --env-file .env.production
|
||||
```
|
||||
|
||||
## 常见排查
|
||||
|
||||
Reference in New Issue
Block a user