api-server/deploy/deploy-flow.md

部署流程与回滚方案

部署拓扑

                    ┌──────────┐
                    │  NGINX   │  :80/:443
                    └────┬─────┘
                         │
              ┌──────────┴──────────┐
              │                     │
        ┌─────▼─────┐         ┌─────▼─────┐
        │ zhixi-api │         │zhixi-worker│
        │  :3000    │         │ (no port)  │
        │ main.js   │         │worker.main │
        └─────┬─────┘         └─────┬─────┘
              │                     │
              │    ┌──────────┐     │
              └────┤  Redis   ├─────┘
                   │ (BullMQ) │
                   └────┬─────┘
                        │
                   ┌────▼────┐
                   │  MySQL  │
                   └─────────┘

  zhixi-heavy-runtime  (独立服务, 本批不修改)

API 与 Worker 职责边界

职责	API	Worker
HTTP Controller	✅	—
Queue Producer (add)	✅	—
BullMQ @Processor	—	✅
Prisma migration	✅ (启动时)	—
监听端口	:3000	无
systemd unit	zhixi-nest-api	zhixi-nest-worker
Docker CMD	node dist/src/main.js	node dist/worker.main.js

Docker 部署

# 构建
docker compose build api worker

# 启动（含 MySQL/Redis 依赖）
docker compose up -d

# 验证
docker compose exec api wget -qO- http://localhost:3000/health      # API health
docker compose logs worker | grep "Worker version"                   # Worker startup
# Heartbeat 验证见 M-AI-01-07

Docker 环境中 API 进程 Processor 数量为 0（AppModule 不含任何 @Processor() 注册，仅 WorkerModule 注册全部 5 个 Processor）。

生产 systemd 部署

# 1. 复制 unit 文件
sudo cp deploy/zhixi-nest-api.service /etc/systemd/system/
sudo cp deploy/zhixi-nest-worker.service /etc/systemd/system/
sudo systemctl daemon-reload

# 2. 启用自启动
sudo systemctl enable zhixi-nest-api zhixi-nest-worker

# 3. 启动
sudo systemctl start zhixi-nest-api
sudo systemctl start zhixi-nest-worker

# 4. 验证
sudo systemctl status zhixi-nest-api zhixi-nest-worker
curl -s http://localhost:3000/health
sudo journalctl -u zhixi-nest-worker -n 20 | grep "Worker version"

标准部署流程

无 DB 变更时（回滚同样适用）：

1. npm run build                              # 构建
2. sudo systemctl restart zhixi-nest-worker   # 先重启 Worker
3. sleep 5 && journalctl -u zhixi-nest-worker # 验证 Worker heartbeat
4. sudo systemctl restart zhixi-nest-api      # 再重启 API
5. curl http://localhost:3000/health          # 验证 API health
6. smoke test                                  # 业务验证

原则：Worker 先于 API 重启。API 重启期间 Worker 继续消费队列。Worker 重启期间 API 继续响应请求（jobs 变为 waiting）。

独立重启验证

• API 重启不停止 Worker：systemctl restart zhixi-nest-api 后 systemctl status zhixi-nest-worker 仍为 active
• Worker 重启不停止 API：systemctl restart zhixi-nest-worker 后 curl localhost:3000/health 返回 200

回滚方案

代码回滚

git revert <commit>           # 回滚代码
npm run build                 # 重新构建
sudo systemctl restart zhixi-nest-worker
sudo systemctl restart zhixi-nest-api

Processor 恢复（回滚 M-AI-01-03）

如果拆分导致问题，恢复全部 5 个 Processor 到拆分前位置即可回退为 API 进程内消费模式：

1. 在 app.module.ts providers 中恢复 AiAnalysisWorker、DocumentImportWorker、NotificationWorker
2. 在 admin-audit-log.module.ts providers 中恢复 AuditLogProcessor 及 BullModule.registerQueue({ name: QUEUE_AUDIT_LOG })
3. 在 files.module.ts providers 中恢复 FileCleanupProcessor 及 BullModule.registerQueue({ name: QUEUE_FILE_CLEANUP })
4. 从 worker.module.ts providers 移除 AuditLogProcessor、FileCleanupProcessor
5. 停止 zhixi-nest-worker service：sudo systemctl stop zhixi-nest-worker
6. 重启 API：sudo systemctl restart zhixi-nest-api

此时全部 5 个 Processor 回到拆分前位置，API 进程同时担任 Producer 和 Consumer。

推荐使用 git revert 作为主回滚方案，可一步覆盖上述所有文件。

数据回滚

本批不涉及 Prisma Schema 变更，无需数据回滚。

队列安全

回滚前后验证 BullMQ 无双重消费：

# 检查 Bull Board 或 Redis 中的 active/waiting 计数
redis-cli LLEN bull:ai-analysis:waiting
redis-cli LLEN bull:ai-analysis:active