133 lines
6.4 KiB
Markdown
133 lines
6.4 KiB
Markdown
# CMPP 平台生产部署手册
|
||
|
||
## 本次生产端口
|
||
|
||
- 运营端、客户端页面：`http://8.160.169.106:12026`
|
||
- API：仅本机 `127.0.0.1:3000`，由 Nginx `/api/` 反向代理。
|
||
- Redis：仅本机 `127.0.0.1:6379`。
|
||
- PostgreSQL：仅本机 `127.0.0.1:5432`。
|
||
- MinIO：仅本机 `127.0.0.1:9000/9001`，页面上传下载通过 API 转发。
|
||
- Gateway 控制服务：仅本机 `127.0.0.1:8090`。
|
||
- CMPP 入站端口：`17890`，由 Go Gateway 启动真实 CMPP 3.0 Server，接收企业应用下游 connect/login 和 submit。
|
||
|
||
## 首次部署
|
||
|
||
1. 本机提交并推送 `main`。
|
||
2. 使用 root 登录服务器，或先放置免密 SSH key。
|
||
3. 在服务器执行：
|
||
|
||
```bash
|
||
curl -fsSL http://175.27.255.91:3000/hectorzhao/lislgosms/raw/branch/main/tools/deploy/production-bootstrap.sh -o /root/production-bootstrap.sh
|
||
bash /root/production-bootstrap.sh
|
||
```
|
||
|
||
可覆盖的环境变量：
|
||
|
||
```bash
|
||
APP_DIR=/opt/cmpp-platform
|
||
REPO_URL=http://175.27.255.91:3000/hectorzhao/lislgosms.git
|
||
BRANCH=main
|
||
PUBLIC_HTTP_PORT=12026
|
||
API_PORT=3000
|
||
HTTP_API_MASTER_KEY=<至少32位随机值，用于AES-256-GCM加密HTTP访问凭据和Webhook密钥>
|
||
API_ENABLE_SEND_WORKER=true
|
||
API_SEND_WORKER_CONCURRENCY=50
|
||
ADMIN_SESSION_IDLE_TIMEOUT_MS=3600000
|
||
CLIENT_SESSION_IDLE_TIMEOUT_MS=7200000
|
||
SESSION_LOCK_RECOVERY_MS=14400000
|
||
SESSION_ABSOLUTE_TIMEOUT_MS=43200000
|
||
SESSION_RECENT_AUTH_MS=1800000
|
||
SESSION_COOKIE_SECURE=true
|
||
OPERATION_LOG_ARCHIVE_ENABLED=true
|
||
OPERATION_LOG_RETENTION_DAYS=180
|
||
OPERATION_LOG_ARCHIVE_BATCH_SIZE=1000
|
||
OPERATION_LOG_ARCHIVE_MAX_BATCHES=20
|
||
OPERATION_LOG_ARCHIVE_INTERVAL_MS=86400000
|
||
SMS_RECEIPT_TIMEOUT_SCAN_ENABLED=true
|
||
SMS_RECEIPT_TIMEOUT_HOURS=72
|
||
SMS_RECEIPT_TIMEOUT_SCAN_INTERVAL_MS=300000
|
||
REPORT_DAILY_REFRESH_ENABLED=true
|
||
REPORT_REFRESH_INTERVAL_MS=3600000
|
||
CMPP_DOWNSTREAM_ACK_TIMEOUT_SECONDS=30
|
||
GATEWAY_CMPP_ADDR=0.0.0.0:17890
|
||
GATEWAY_STARTUP_RECONNECT_DELAY_MS=1000
|
||
OBJECT_STORAGE_DRIVER=minio
|
||
OBJECT_STORAGE_LOCAL_ROOT=/var/lib/cmpp-platform/object-storage
|
||
PROD_ADMIN_EMAIL=admin@example.com
|
||
PROD_ADMIN_USERNAME=prod_admin
|
||
PROD_ADMIN_PASSWORD='change-me'
|
||
```
|
||
|
||
安全会话使用 HttpOnly Cookie，正式生产必须先为页面和 `/api` 配置 HTTPS，并保持 `SESSION_COOKIE_SECURE=true`。仅在用户明确授权的 HTTP 生产验证环境中，允许临时显式设置 `SESSION_COOKIE_SECURE=false` 维持验证可用性；该例外必须记录在发布验收中，不能替代正式环境 TLS。
|
||
|
||
系统操作日志默认在线保留 180 天。API 每日以最多 20 个、每批 1000 条的小事务将过期记录搬入 `OperationLogArchive`，并用 `archiveMonth=YYYY-MM` 标记归档月份；归档记录不会自动删除。调整保留期或批量参数前，应先评估数据库、备份窗口和审计要求。归档表达到千万级或清理窗口不能满足要求时，再实施按 `createdAt` 的月度 PostgreSQL 分区，不在当前数据规模下提前改造主表分区。
|
||
|
||
脚本会安装 Node.js、Go、PostgreSQL、Redis、MinIO、Nginx，创建 systemd 服务，执行 Prisma migrate，构建前端/API/Gateway，并创建平台管理员。Node.js、Go 和 MinIO 下载会按服务器架构自动选择 x64/amd64 或 arm64。
|
||
|
||
`API_ENABLE_SEND_WORKER=true` 是生产发送链路必填项。后续发布脚本会在构建和迁移前校验该开关以及正整数 `API_SEND_WORKER_CONCURRENCY`；缺失时直接终止发布，防止 API/Gateway 健康但 BullMQ 短信队列无人消费。
|
||
|
||
Gateway 的最终 TPS 防线依赖与 API 相同的 Redis。通道连接时会写入 `rate:gateway:channel:config:<channelId>` 权威上限，实际预约使用 `rate:gateway:channel:<channelId>`；这些 key 不应在正常发布时清理。多 Gateway 实例必须指向同一 Redis，才能共享单通道额度。超速的 `gateway.submit.commands` 消息会保持在 consumer group pending 中等待，不应通过手工 `XACK` 或删除 Stream 处理积压；先检查通道配置、Redis key、consumer group 和 Gateway 日志。
|
||
|
||
服务重启顺序必须是 Gateway 在前、API 在后。API 启动后等待 `GATEWAY_STARTUP_RECONNECT_DELAY_MS`（默认 1 秒），从 PostgreSQL 读取全部 active 通道并重新下发真实连接命令，同时恢复 Gateway 内存连接池和 Redis 权威 TPS key；禁止沿用数据库中重启前的 connected 状态冒充当前连接。
|
||
|
||
日报任务默认启用，并由 `REPORT_REFRESH_INTERVAL_MS` 每小时检查一次北京时间业务日是否变化；每个业务日只执行一次 T-4 至 T-1 重算。服务重启后也会自动补跑最近四个完整自然日，确保 72 小时回执更新反映到对账和利润报表。
|
||
|
||
如生产验证服务器临时无法稳定下载 MinIO，可显式传入 `OBJECT_STORAGE_DRIVER=local`，文件会通过真实 API 保存到服务器本地目录 `OBJECT_STORAGE_LOCAL_ROOT`，`cmpp-minio` 服务会跳过安装和启动。该模式只建议用于验证环境；正式生产建议恢复 `OBJECT_STORAGE_DRIVER=minio`。
|
||
|
||
## 后续发布
|
||
|
||
```bash
|
||
cd /opt/cmpp-platform
|
||
git fetch origin main
|
||
git reset --hard origin/main
|
||
bash tools/deploy/production-deploy.sh
|
||
```
|
||
|
||
## 账号和密钥
|
||
|
||
- 生产管理员账号写入 `/root/cmpp-platform-admin.txt`。
|
||
- 首次部署汇总凭据写入 `/root/cmpp-platform-credentials.txt`。
|
||
- 这两个文件权限为 `600`，不要提交到 Git。
|
||
- root 密码后续可修改；SSH 私钥放入 `/root/.ssh/authorized_keys` 后即可免密登录。
|
||
|
||
## 日志
|
||
|
||
```bash
|
||
journalctl -u cmpp-api -f
|
||
journalctl -u cmpp-gateway -f
|
||
journalctl -u cmpp-minio -f
|
||
tail -f /opt/cmpp-platform/logs/api/stderr.log
|
||
tail -f /opt/cmpp-platform/logs/gateway/stderr.log
|
||
```
|
||
|
||
## 健康检查
|
||
|
||
```bash
|
||
curl http://127.0.0.1:3000/api/health
|
||
curl http://127.0.0.1:8090/health
|
||
curl http://127.0.0.1:12026/
|
||
redis-cli -h 127.0.0.1 -p 6379 ping
|
||
pg_isready -d "$(grep '^DATABASE_URL=' /etc/cmpp-platform/cmpp-platform.env | cut -d= -f2-)"
|
||
grep -E '^(API_ENABLE_SEND_WORKER|API_SEND_WORKER_CONCURRENCY)=' /etc/cmpp-platform/cmpp-platform.env
|
||
redis-cli --scan --pattern 'rate:gateway:channel:*'
|
||
redis-cli XINFO GROUPS gateway.submit.commands
|
||
```
|
||
|
||
## 回滚
|
||
|
||
1. 数据库备份：
|
||
|
||
```bash
|
||
pg_dump "$(grep '^DATABASE_URL=' /etc/cmpp-platform/cmpp-platform.env | cut -d= -f2-)" > /opt/cmpp-platform/backups/cmpp-$(date +%F-%H%M%S).sql
|
||
```
|
||
|
||
2. 回滚代码：
|
||
|
||
```bash
|
||
cd /opt/cmpp-platform
|
||
git reset --hard <上一版提交>
|
||
bash tools/deploy/production-deploy.sh
|
||
```
|
||
|
||
3. 如迁移造成不可兼容故障，先停服务，再恢复数据库备份。
|