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

> 本文保留第一版的部署示例，不是当前预生产的逐步执行清单。当前实例的磁盘分工、持久化目录、备份入口、服务依赖和实施状态，以[部署手册的“预生产磁盘与目录规划”](production-deployment.md#预生产磁盘与目录规划)为准。下列Compose与简化systemd示例不能直接覆盖预生产现有配置。

## 部署组件

- 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/
```

备份必须位于运行目录之外。当前预生产入口为 `/opt/cmpp-platform-backups`，实际指向数据盘的 `/data/cmpp-platform-backups`；不再使用 `/opt/cmpp-platform/backups`。2026-08-31晚间第二阶段已将PostgreSQL、Redis、MinIO迁入数据盘并用绑定挂载保留原访问路径；应用日志和监控数据未迁移。路径、启动保护与未实施项以部署手册为准。

## 环境变量

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

## 备份恢复

当前预生产数据库备份的环境加载、存储检查和固定入口见[部署手册的回滚章节](production-deployment.md#回滚)。已正确加载 `DATABASE_URL` 后，SQL格式备份示例为：

```bash
set -e
/usr/local/sbin/cmpp-backup-storage-check
pg_dump "${DATABASE_URL%%\?*}" > /opt/cmpp-platform-backups/cmpp-$(date +%F-%H%M%S).sql
```

数据库恢复必须另经授权并确认目标数据库、配套运行代码与停写方案。对于已验证的SQL格式备份，命令示例为（需替换为实际文件名）：

```bash
psql -v ON_ERROR_STOP=1 "${DATABASE_URL%%\?*}" < /opt/cmpp-platform-backups/cmpp-YYYY-MM-DD-HHMMSS.sql
```

custom格式的 `database.dump` 应使用 `pg_restore`，不能传给上面的SQL恢复命令。当前磁盘备份不等于异机灾备；MinIO另行建立对象备份时，须明确存储元数据/版本保留要求、目标位置和恢复验证，不能只凭同步命令成功就认定可恢复。

## 回滚方案

1. 先核对当前架构与在途业务，按已授权的停写方案协调API、Gateway及全部已启用Worker；第一版三进程列表不足以覆盖当前拆分架构。
2. 切回上一版代码或镜像 tag。
3. 如果已执行数据库迁移，优先使用兼容回滚：
   - 保留新增列和新增表。
   - 回滚应用代码到上一版。
   - 禁止直接删除生产数据表。
4. 如迁移导致不可兼容故障，使用上线前数据库备份恢复。
5. 保留Redis持久化、未消费队列、Streams、pending和幂等状态；禁止直接删除队列key或手工ACK/XDEL。协议不兼容时先确定配套恢复方案，不能通过丢弃消息实现回滚。
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 备份。