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