feat: add operations acceptance phase

2026-07-01 13:46:54 +08:00
parent 27bb2d798a
commit 924457a48e
11 changed files with 692 additions and 2 deletions
@@ -0,0 +1,170 @@
+# CMPP 平台第一版 Linux 上线部署与回滚方案
+
+## 部署组件
+
+- Frontend：React + TypeScript + Vite 静态资源。
+- API：NestJS + TypeScript。
+- Gateway：Go CMPP Gateway。
+- PostgreSQL：业务数据库。
+- Redis：BullMQ 队列、缓存、限速。
+- MinIO：文件对象存储。
+
+## 推荐目录
+
+```text
+/opt/cmpp-platform/
+  api/
+  gateway/
+  frontend/
+  infra/
+  logs/
+    api/
+    gateway/
+  backups/
+```
+
+## 环境变量
+
+```bash
+DATABASE_URL=postgresql://cmpp:password@postgres:5432/cmpp
+REDIS_URL=redis://redis:6379
+MINIO_ENDPOINT=minio
+MINIO_PORT=9000
+MINIO_ACCESS_KEY=cmpp
+MINIO_SECRET_KEY=change-me
+MINIO_BUCKET=cmpp-platform
+API_PORT=3000
+API_ENABLE_SEND_WORKER=true
+API_SEND_WORKER_CONCURRENCY=50
+GATEWAY_HTTP_ADDR=:8090
+```
+
+## Docker Compose 部署
+
+1. 准备 `.env`。
+2. 启动基础设施：
+
+```bash
+docker compose -f infra/docker-compose.yml up -d postgres redis minio
+```
+
+3. 安装依赖并生成 Prisma Client：
+
+```bash
+npm ci
+npm --prefix api ci
+npm run prisma:generate
+```
+
+4. 执行数据库迁移：
+
+```bash
+npm --prefix api run prisma:migrate:deploy
+```
+
+5. 构建服务：
+
+```bash
+npm run build
+npm --prefix api run build
+cd gateway && go build -o ../dist/cmpp-gateway ./cmd/gateway
+```
+
+6. 启动 API、Send Worker 和 Gateway。
+
+## systemd 部署
+
+API service 示例：
+
+```ini
+[Unit]
+Description=CMPP Platform API
+After=network.target postgresql.service redis.service
+
+[Service]
+WorkingDirectory=/opt/cmpp-platform/api
+EnvironmentFile=/opt/cmpp-platform/.env
+ExecStart=/usr/bin/node dist/main.js
+Restart=always
+RestartSec=5
+StandardOutput=append:/opt/cmpp-platform/logs/api/stdout.log
+StandardError=append:/opt/cmpp-platform/logs/api/stderr.log
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Gateway service 示例：
+
+```ini
+[Unit]
+Description=CMPP Gateway
+After=network.target redis.service
+
+[Service]
+WorkingDirectory=/opt/cmpp-platform
+EnvironmentFile=/opt/cmpp-platform/.env
+ExecStart=/opt/cmpp-platform/dist/cmpp-gateway
+Restart=always
+RestartSec=5
+StandardOutput=append:/opt/cmpp-platform/logs/gateway/stdout.log
+StandardError=append:/opt/cmpp-platform/logs/gateway/stderr.log
+
+[Install]
+WantedBy=multi-user.target
+```
+
+## 健康检查
+
+```bash
+curl http://127.0.0.1:3000/api/health
+curl http://127.0.0.1:8090/health
+redis-cli -u "$REDIS_URL" ping
+pg_isready -d "$DATABASE_URL"
+```
+
+## 日志目录
+
+- API：`/opt/cmpp-platform/logs/api/`
+- Gateway：`/opt/cmpp-platform/logs/gateway/`
+- PostgreSQL、Redis、MinIO：使用系统服务或容器日志。
+
+## 备份恢复
+
+数据库备份：
+
+```bash
+pg_dump "$DATABASE_URL" > /opt/cmpp-platform/backups/cmpp-$(date +%F-%H%M%S).sql
+```
+
+数据库恢复：
+
+```bash
+psql "$DATABASE_URL" < /opt/cmpp-platform/backups/cmpp-YYYY-MM-DD-HHMMSS.sql
+```
+
+MinIO 备份建议使用 `mc mirror` 将 bucket 同步到备份目录或对象存储。
+
+## 回滚方案
+
+1. 停止 API、Send Worker 和 Gateway。
+2. 切回上一版代码或镜像 tag。
+3. 如果已执行数据库迁移，优先使用兼容回滚：
+   - 保留新增列和新增表。
+   - 回滚应用代码到上一版。
+   - 禁止直接删除生产数据表。
+4. 如迁移导致不可兼容故障，使用上线前数据库备份恢复。
+5. 清理 Redis 中未消费的新版本队列 key，避免旧版本误消费不兼容消息。
+6. 启动上一版服务并执行健康检查。
+7. 抽查发送任务、短信记录、账务流水、回执记录。
+
+## 上线检查清单
+
+1. `npm run verify:phase8` 通过。
+2. Prisma migrate deploy 成功。
+3. API health、Gateway health、Redis ping、PostgreSQL ready 全部通过。
+4. 创建测试短信任务并确认手机号维度短信记录生成。
+5. Gateway submit result、receipt、uplink 事件接口可写入。
+6. 查询、统计、追踪、对账接口可访问。
+7. 已完成数据库和 MinIO 备份。
+