171 lines
3.7 KiB
Markdown
171 lines
3.7 KiB
Markdown
# 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 备份。
|
||
|