[M-AI-01-06] 统一 Docker 与生产 systemd 的 API/Worker 部署拓扑 #250

New Issue

wangdl · 2026-06-19T20:06:04+08:00

wangdl commented

2026-06-19 20:06:04 +08:00

背景

Docker 环境存在 API/Worker 双重注册，生产环境拓扑不明确。

目标

Docker: API 容器只启动 dist/main.js，Worker 容器只启动 dist/worker.main.js。
生产: 新增 zhixi-nest-worker.service systemd unit。

部署流程: build → 无 DB 变更 → 重启 Worker → 验证 heartbeat → 重启 API → 验证 health → smoke test。

非目标

不修改 Heavy Runtime 部署
不修改 Prisma
不迁移数据

风险等级：P1

依赖：M-AI-01-05

建议执行顺序：6（与 01-07 可并行）

验收标准

Docker 中 API Processor 数量为 0
Docker 中 Worker Processor 数量符合预期
API 重启不停止 Worker
Worker 重启不停止 API
回滚文档和 service 文件进入版本库

## 背景 Docker 环境存在 API/Worker 双重注册，生产环境拓扑不明确。 ## 目标 Docker: API 容器只启动 dist/main.js，Worker 容器只启动 dist/worker.main.js。生产: 新增 zhixi-nest-worker.service systemd unit。部署流程: build → 无 DB 变更 → 重启 Worker → 验证 heartbeat → 重启 API → 验证 health → smoke test。 ## 非目标 - 不修改 Heavy Runtime 部署 - 不修改 Prisma - 不迁移数据 ## 风险等级：P1 ## 依赖：M-AI-01-05 ## 建议执行顺序：6（与 01-07 可并行） ## 验收标准 - [ ] Docker 中 API Processor 数量为 0 - [ ] Docker 中 Worker Processor 数量符合预期 - [ ] API 重启不停止 Worker - [ ] Worker 重启不停止 API - [ ] 回滚文档和 service 文件进入版本库

wangdl added this to the M-AI-01 Worker 进程边界与部署收口 milestone 2026-06-19 20:06:04 +08:00

wangdl commented

2026-06-19 20:56:38 +08:00

开发完成评论

完成内容

Docker 拓扑已分离（历史遗留，确认无误）：
- Dockerfile CMD → node dist/main.js（API，无 Processor）
- Dockerfile.worker CMD → node dist/worker.main.js（Worker，仅 Processor）
- docker-compose.yml 含独立 api 和 worker service，无共享实例
新建 deploy/zhixi-nest-api.service：生产 systemd unit（TimeoutStopSec=30s）
新建 deploy/zhixi-nest-worker.service：生产 systemd unit（TimeoutStopSec=60s，MemoryMax=512M，After=api）
新建 deploy/deploy-flow.md：完整部署文档
- 部署拓扑图
- API/Worker 职责边界表
- Docker 部署命令
- systemd 部署命令
- 标准部署流程（Worker 先于 API 重启）
- 回滚方案（代码回滚 + Processor 恢复 + 数据回滚（N/A）+ 队列安全验证）
worker.main.ts 新增 30s 强制关闭超时：setTimeout(forceExit, 30_000) 兜底

修改文件

deploy/zhixi-nest-api.service（新建）
deploy/zhixi-nest-worker.service（新建）
deploy/deploy-flow.md（新建）
src/worker.main.ts（新增关闭超时）

代码证据

Dockerfile:34：CMD ["sh", "-c", "npx prisma migrate deploy && node dist/main.js"] — API only
Dockerfile.worker:29：CMD ["node", "dist/worker.main.js"] — Worker only
docker-compose.yml:63,128：独立 api 和 worker service
deploy/zhixi-nest-api.service:10：ExecStart=/usr/bin/node dist/main.js
deploy/zhixi-nest-worker.service:12：ExecStart=/usr/bin/node dist/worker.main.js
deploy/deploy-flow.md:20-25：API/Worker 职责边界表 — Docker 中 API Processor 数为 0
deploy/deploy-flow.md:48-56：标准部署流程 — Worker 先于 API 重启
deploy/deploy-flow.md:80-91：回滚方案 — 恢复 AppModule Processor 注册
src/worker.main.ts:92-94：setTimeout(forceExit, SHUTDOWN_TIMEOUT_MS) 强制超时

测试情况

已运行命令：
- npx tsc --noEmit
- npx jest --no-coverage
结果：
- TypeScript 编译：通过（0 新增错误）
- 单元测试：283/283 全部通过，12 suites 全部通过

未完成 / 风险

生产 systemd unit 文件需运维部署时按实际路径调整 WorkingDirectory 和 EnvironmentFile
Docker 容器内 Processor 数量验证需运行时确认（docker compose up + Bull Board），集成测试在 M-AI-01-08 中覆盖

是否建议进入 Review

是

## 开发完成评论 ### 完成内容 - Docker 拓扑已分离（历史遗留，确认无误）： - `Dockerfile` CMD → `node dist/main.js`（API，无 Processor） - `Dockerfile.worker` CMD → `node dist/worker.main.js`（Worker，仅 Processor） - `docker-compose.yml` 含独立 `api` 和 `worker` service，无共享实例 - 新建 `deploy/zhixi-nest-api.service`：生产 systemd unit（TimeoutStopSec=30s） - 新建 `deploy/zhixi-nest-worker.service`：生产 systemd unit（TimeoutStopSec=60s，MemoryMax=512M，After=api） - 新建 `deploy/deploy-flow.md`：完整部署文档 - 部署拓扑图 - API/Worker 职责边界表 - Docker 部署命令 - systemd 部署命令 - 标准部署流程（Worker 先于 API 重启） - 回滚方案（代码回滚 + Processor 恢复 + 数据回滚（N/A）+ 队列安全验证） - `worker.main.ts` 新增 30s 强制关闭超时：`setTimeout(forceExit, 30_000)` 兜底 ### 修改文件 - `deploy/zhixi-nest-api.service`（新建） - `deploy/zhixi-nest-worker.service`（新建） - `deploy/deploy-flow.md`（新建） - `src/worker.main.ts`（新增关闭超时） ### 代码证据 - `Dockerfile:34`：`CMD ["sh", "-c", "npx prisma migrate deploy && node dist/main.js"]` — API only - `Dockerfile.worker:29`：`CMD ["node", "dist/worker.main.js"]` — Worker only - `docker-compose.yml:63,128`：独立 `api` 和 `worker` service - `deploy/zhixi-nest-api.service:10`：`ExecStart=/usr/bin/node dist/main.js` - `deploy/zhixi-nest-worker.service:12`：`ExecStart=/usr/bin/node dist/worker.main.js` - `deploy/deploy-flow.md:20-25`：API/Worker 职责边界表 — Docker 中 API Processor 数为 0 - `deploy/deploy-flow.md:48-56`：标准部署流程 — Worker 先于 API 重启 - `deploy/deploy-flow.md:80-91`：回滚方案 — 恢复 AppModule Processor 注册 - `src/worker.main.ts:92-94`：`setTimeout(forceExit, SHUTDOWN_TIMEOUT_MS)` 强制超时 ### 测试情况 - 已运行命令： - `npx tsc --noEmit` - `npx jest --no-coverage` - 结果： - TypeScript 编译：通过（0 新增错误） - 单元测试：283/283 全部通过，12 suites 全部通过 ### 未完成 / 风险 - 生产 systemd unit 文件需运维部署时按实际路径调整 `WorkingDirectory` 和 `EnvironmentFile` - Docker 容器内 Processor 数量验证需运行时确认（`docker compose up` + Bull Board），集成测试在 M-AI-01-08 中覆盖 ### 是否建议进入 Review - 是

wangdl closed this issue

2026-06-19 23:03:56 +08:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: wangdl/api-server#250