4fb652d273
Some checks failed
Deploy API Server / build-and-deploy (push) Failing after 39s
M-AI-01-01: ADR-001 统一 AI 架构决策记录 + 附录 A 依赖闭包审计 M-AI-01-02: Worker 执行依赖闭包审计（附录 A 文档） M-AI-01-03: 分离 AppModule/WorkerModule Processor 注册 M-AI-01-04: 统一 Queue Definition Registry + 环境变量覆盖 M-AI-01-05: 独立 Worker 启动与生命周期（instanceId/校验/优雅关闭） M-AI-01-06: Docker + systemd 部署拓扑（unit 文件 + 回滚文档） M-AI-01-07: Worker Heartbeat（Redis TTL 90s）+ Admin 在线状态 API M-AI-01-08: 集成验收脚本 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
139 lines
4.9 KiB
Markdown
139 lines
4.9 KiB
Markdown
# 部署流程与回滚方案
|
||
|
||
## 部署拓扑
|
||
|
||
```
|
||
┌──────────┐
|
||
│ 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 部署
|
||
|
||
```bash
|
||
# 构建
|
||
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 部署
|
||
|
||
```bash
|
||
# 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
|
||
|
||
## 回滚方案
|
||
|
||
### 代码回滚
|
||
|
||
```bash
|
||
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 无双重消费：
|
||
|
||
```bash
|
||
# 检查 Bull Board 或 Redis 中的 active/waiting 计数
|
||
redis-cli LLEN bull:ai-analysis:waiting
|
||
redis-cli LLEN bull:ai-analysis:active
|
||
```
|