lislgosms/docs/linux-deployment-and-rollback.md

CMPP 平台第一版 Linux 上线部署与回滚方案

部署组件

• Frontend：React + TypeScript + Vite 静态资源。
• API：NestJS + TypeScript。
• Gateway：Go CMPP Gateway。
• PostgreSQL：业务数据库。
• Redis：BullMQ 队列、缓存、限速。
• MinIO：文件对象存储。

推荐目录

/opt/cmpp-platform/
  api/
  gateway/
  frontend/
  infra/
  logs/
    api/
    gateway/
  backups/

环境变量

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. 启动基础设施：

docker compose -f infra/docker-compose.yml up -d postgres redis minio

3. 安装依赖并生成 Prisma Client：

npm ci
npm --prefix api ci
npm run prisma:generate

4. 执行数据库迁移：

npm --prefix api run prisma:migrate:deploy

5. 构建服务：

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 示例：

[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 示例：

[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

健康检查

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：使用系统服务或容器日志。

备份恢复

数据库备份：

pg_dump "$DATABASE_URL" > /opt/cmpp-platform/backups/cmpp-$(date +%F-%H%M%S).sql

数据库恢复：

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 备份。