从单体拆分独立任务服务：数据库队列表驱动的异步任务架构实践

第一次看到这个项目代号的时候，不少同事都以为我买了张去马德拉群岛的机票，毕竟那地方在欧洲生活圈里就是“自然又治愈”的代名词。实际上，“Madeira”是我手头一个后端小项目的内部代号，用来做公司后台的对账、报表导出以及各种定时任务。当时的状况非常不舒服：老单体应用还能跑，但只要到月底，对账和批量重算开始跑，主进程的 CPU 和数据库连接数直接飙高，接口动不动就超时。为了不背上微服务的大包袱，我决定把这摊重活拆成一个独立进程，给它一个轻量 HTTP 接口、一张数据库队列表，容器一拉就能跑。到现在已经稳定运行了好几个月，中间踩的坑值得好好写出来。

这篇文章里，我会把 Madeira 的完整落地过程拆开：从模块设计、技术选型，到队列实现、容器部署，再到上线后遇到的几个真实问题。适合的读者包括小团队后端开发、想从单体系统里拆异步任务的架构同学，以及准备从零写任务服务的新手。中间的方案不一定最华丽，但都是经过实际环境验证过的，照着做起码不会翻车。

1. 项目到底要解决什么问题

1.1 取一个名字背后的意图

取名这事看着随意，实际能反映项目定位。马德拉酒是一种经过长时间陈化和氧化处理的强化葡萄酒，过去欧洲人航海远行时都靠它在船上长时间不变质，特点是“经得起折腾”。我当时拿到这个任务，核心诉求正好也是这样：从老系统里拆出一段代码，去处理那些不太紧急、但特别占资源的后台任务，要求它在生产环境里待得住、不会闹脾气。

拆出来之前，老系统里大概有四类事情在捣乱：每天晚上要同步一批上游经营数据，每个月月初要跑一遍集团对账，运营同学随时会在后台触发各种报表导出，还有一批定时清理任务。这些任务本身不复杂，但有共同点：时间不定、数据量大、失败不能无声无息。继续放在原来的应用里，和在线 API 抢资源，早晚出事。所以这个新服务的第一原则非常朴素：高流量接口和重任务之间必须做进程级隔离。这个原则决定了项目形态一定是一个独立服务，而不是在旧项目里加一个开关。

1.2 功能边界怎么划

独立进程不等于乱拆，功能边界一开始就要清楚。我最后只给 Madeira 定了五个职责：

• 接收并存储异步任务，任务状态可追踪；
• 从上游系统拉取对账文件和业务数据；
• 统一执行批量计算、写回业务库；
• 对外提供查询任务状态和小范围数据修正的接口；
• 输出结构化执行日志和基础监控指标。

为了不让它变成新的“大泥球”，服务内部模块也做了简短划分。直接用职责表说明当时的设计，看起来更直观：

这五个职责背后是一个很简单的道理：把一个不知道什么时候会跑的大任务，转成一套明确的状态机，让每个状态都有人负责。后面的实现基本都是围绕这套状态机来走的。

1.3 为什么不做微服务

可能有人觉得，既然都拆进程了，干脆做微服务，后面还能横向扩展。我的想法相反：项目里只有三十几个服务调用点，团队就三四个人，如果拆成微服务，光服务间认证、链路追踪、配置分发就能把进度拖慢一倍。微服务的第一准则永远是不做微服务。

一个更务实的做法，是在一个独立进程里保留清晰的模块边界。等哪天某个模块的流量和团队规模都长到需要单独部署时，再顺着边界把它抠出来。这种从“单体应用中可拆分的模块”过渡到“独立服务”的路线，收益一点都不比大刀阔斧的微服务差，还省掉了分布式环境下的大堆麻烦。

2. 技术选型与架构核心

2.1 为什么用 Node.js 而不是 Go

选型时我面前摆着两条路：用 Node.js + TypeScript，或者用 Go。从性能上限来讲，Go 在 CPU 密集任务和内存稳定性上一定有优势，但这个项目的真实情况是，团队过去几年一直在写 TypeScript，对异步任务的处理模式足够熟悉，业务逻辑从老系统搬过来时，几乎可以直接复用以前的类和工具方法。

我更看重的是交付速度。这批后台任务更像 IO 密集和胶水代码，真正的算术复杂度并不高，Node.js 的单线程模型加上 Cluster 或者多 Worker，足够撑起目前几千到一万左右的日任务量。为了给未来留余地，我一开始就把纯业务逻辑写成了不依赖框架的函数库，即使后面某个热点部分要用 Go 重写，也不会碰伤主体流程。选型这件事，应该为团队服务，而不是为技术愿景服务。

2.2 队列为什么放在数据库表里

定时任务要么自己写调度，要么引一个消息队列。我最后选择最朴素的一招：在 PostgreSQL 里建一张任务表，用状态机管理任务。选用这个方案有一个很现实的理由：公司当时没有一套能稳定运维的 Redis 集群，用 Redis 做延迟队列虽然性能好，但一旦消息丢失或者集群抖动，排查成本非常高。数据库表方案虽然不炫，但对账这种场景最需要的是可靠和透明，查库就能知道每一条数据到底卡在哪。

任务表的核心字段大体是这样：

CREATE TABLE task_queue ( id BIGSERIAL PRIMARY KEY, type VARCHAR(50) NOT NULL, payload JSONB NOT NULL, status VARCHAR(20) NOT NULL DEFAULT 'pending', retry_count INT NOT NULL DEFAULT 0, max_retry INT NOT NULL DEFAULT 5, run_at TIMESTAMPTZ NOT NULL DEFAULT now(), locked_by VARCHAR(64), locked_at TIMESTAMPTZ, finished_at TIMESTAMPTZ, error_message TEXT, created_at TIMESTAMPTZ NOT NULL DEFAULT now(), updated_at TIMESTAMPTZ NOT NULL DEFAULT now() ); CREATE INDEX idx_task_queue_status_run_at ON task_queue (status, run_at);

每个任务都从显式状态流转到另一个状态：pending 表示待执行，processing 表示被某个 Worker 取走，success 和 error 是终态，部分失败任务会按规则重新回到 pending。字段里特意放了 run_at，这是给延迟任务准备的，比如报表导出可以先排到凌晨一点再真正执行。

可能有人问，用表做队列的话，轮询是不是很傻？确实如此，所以后面我把调度做成了“只取一次 + 短等待”的模式，而不是固定每秒全表扫一次。在并发量一千以内的场景，这个方案完全能跑，而且调试任务状态时非常爽，直接查库就能看到每个任务卡在哪一步。

2.3 服务内的模块边界

项目目录大致是这样：

src/ app.ts # 组装各模块，启动服务 config/ # 配置加载和环境变量解析 db/ # 数据库连接与迁移脚本 queue/ # 任务状态机、调度、并发控制 processor/ # 各种业务执行器 route/ # HTTP 路由 middleware/ # 日志、鉴权、错误处理中间件

这个结构看起来普通，但有一个关键约束：processor 不能 import queue 里的调度器，只能通过任务对象和返回值通信。这样后续增加新任务类型时，只需要在 processor 里加一个文件，注册表里加一行，不需要动调度核心，回归成本可以压到很低。

2.4 日志和链路打通

拆出独立服务之后，最容易被忽视的是日志。以前业务都在同一个进程里，用户出问题还能靠完整日志硬搜；拆出来以后，如果日志没有统一的 requestId、taskId，排查问题会让人一头雾水。

我花了不少力气把日志统一成 JSON 格式，并强制要求每次任务执行都带 taskId，每次 HTTP 请求都带 requestId。生产环境里直接把这些日志发到日志平台，按 taskId 聚合每次执行的生命周期。这里强烈建议，哪怕只写一个小服务，也一定别放过结构化日志，否则后期运维会非常痛苦。

3. 核心实现细节与代码拆解

3.1 环境配置不要写成硬编码

不管项目大小，环境变量统一管理都是基本素质。Madeira 的配置模块只做三件事：读取环境变量、做类型转换、给关键配置提供默认值。本地开发用 dotenv 加载 .env 文件，生产环境只用真实环境变量，避免敏感信息进仓库。

代码示例：

// src/config/index.ts import 'dotenv/config'; export const config = { env: process.env.NODE_ENV ?? 'development', port: parseInt(process.env.PORT ?? '3000', 10), pg: { host: process.env.PG_HOST ?? '127.0.0.1', port: parseInt(process.env.PG_PORT ?? '5432', 10), database: process.env.PG_DATABASE ?? 'madeira', user: process.env.PG_USER ?? 'madeira', password: process.env.PG_PASSWORD ?? '' }, queue: { pollIntervalMs: parseInt(process.env.POLL_INTERVAL_MS ?? '1000', 10), batchSize: parseInt(process.env.BATCH_SIZE ?? '10', 10), concurrency: parseInt(process.env.CONCURRENCY ?? '3', 10) } };

代码里故意没把数据库密码写成默认值。生产环境的密码走部署平台的 secret 注入，本地开发再通过 .env 补齐。一个小建议：所有端口解析都顺手做一次 parseInt，否则会因为“端口号是字符串”白踩不少坑。

3.2 用状态机驱动任务调度

调度部分核心是一个高约 50 行的 TaskQueue 类，职责是：从表里捞出到期待执行的任务、把状态从 pending 改成 processing、调用对应 processor、根据结果把状态改成 success 或 error。

简化后的核心方法大致是这样：

// src/queue/worker.ts async function processNextBatch(limit: number): Promise<number> { const now = new Date(); const rows = await db.query( `UPDATE task_queue SET status = 'processing', locked_by = $1, locked_at = now() WHERE id IN ( SELECT id FROM task_queue WHERE status = 'pending' AND run_at <= now() ORDER BY run_at ASC LIMIT $2 FOR UPDATE SKIP LOCKED ) RETURNING *`, [workerId, limit] ); if (rows.length === 0) return 0; for (const task of rows) { await executeTask(task).catch(async (err) => { await markFailed(task.id, err); }); } return rows.length; }

这段代码特别要注意的是FOR UPDATE SKIP LOCKED。多进程各自抢任务时，不写这行会导致两个 Worker 拿到同一个任务，重复执行对账逻辑。写上 SKIP LOCKED 后，正在被其他会话锁定的行会被跳过，这是用数据库做队列时最关键的技能之一。

每条任务能“防重跑”，还依赖 processor 的幂等性。我的做法是给每条业务数据定义一个 upstream_key，任务执行前后检查目标表里是否已存在相同 upstream_key，存在就直接跳过，确保重复执行也不会重复写账。这个对账场景尤其重要，宁可任务多跑两遍，数据不能多算一分钱。

3.3 路由层要做薄

很多项目把业务逻辑直接写在 controller 里，时间一长根本没法维护。在 Madeira 里，route 层只做参数校验、权限校验、调用 service、返回结果。参数校验用 JSON Schema，所有接口的入参、出参都有对应的 schema 文件，能挡掉不少低级错误。

// src/route/task.ts fastify.post('/tasks', { schema: createTaskSchema }, async (req, reply) => { const taskId = await createTask(req.body.type, req.body.payload, req.body.runAt); return { code: 0, data: { taskId } }; });

中间业务逻辑都放在 processor 里，接口层保持很薄。好处很明显：以后就算把 API 从 Fastify 换成别的框架，迁移成本也极低。这算是项目里最简单的设计决定之一，但收益一直持续到现在。

3.4 失败重试和指数退避

重试策略在任务队列里绝对不能乱来。如果每次失败都立刻重试，高峰期能把下游接口打挂。我采用指数退避：第 n 次重试的延迟是基础延迟 * 2^n，同时加一点随机抖动，降低同一时刻大批重试的峰值。

function nextRunAt(retryCount: number): Date { const baseDelayMs = 1000 * Math.pow(2, retryCount); const jitterMs = Math.floor(Math.random() * 500); return new Date(Date.now() + baseDelayMs + jitterMs); }

需要说明的是，重试次数和延迟不是越大越好。配合请求超时设置，我们把单任务最大重试次数控制在 5 次以内，超过后进入 error 终态直接告警，由人工介入。对账业务宁可任务在队列里躺一会儿，也不要用风暴式的方式反复冲击目标系统。

4. 部署实操与上线过程

4.1 开发环境的初始化细节

项目初始化时，我先把 TypeScript 和 tsx 配好，开发阶段用 tsx watch 直接跑源码，发布阶段再用 tsc 编译成 JavaScript。package.json 里的关键脚本：

{ "scripts": { "dev": "tsx watch src/app.ts", "build": "tsc -p tsconfig.json", "start": "node dist/app.js", "migrate": "node-pg-migrate up" } }

开发时直接npm run dev，源码改动会触发自动重启，效率比先编译再运行高很多。构建时所有编译产物放到 dist 目录，Docker 打包只复制 dist，不复制 src，镜像体积可以小不少。

4.2 Docker 镜像多阶段构建

服务最后跑在生产环境，镜像不能又大又乱。我用的多阶段构建方式：

FROM node:20-alpine AS build WORKDIR /app COPY package.json package-lock.json ./ RUN npm ci COPY tsconfig.json ./ COPY src ./src RUN npm run build FROM node:20-alpine WORKDIR /app ENV NODE_ENV=production COPY --from=build /app/package.json ./ COPY --from=build /app/dist ./dist RUN npm ci --omit=dev && npm cache clean --force USER node CMD ["node", "dist/app.js"]

这里有两个容易忽略的细节。首先，必须用npm ci而不是npm install，后者在 CI 环境里可能不会严格按 lockfile 安装，依赖漂移会让人崩溃。其次，镜像里要切到USER node，不要用 root 跑 Node，容器一旦被攻破，影响面会大很多。这个习惯在安全审查时也是重点检查项。

4.3 Compose 编排示例

日常联调时用 docker compose 拉起整套环境。为了不污染本地开发机，Postgres 不直接映射到宿主机端口，只在 compose 内部网络里提供服务。示例配置：

services: app: build: . env_file: .env depends_on: postgres: condition: service_healthy ports: - "3000:3000" postgres: image: postgres:16-alpine environment: POSTGRES_USER: madeira POSTGRES_PASSWORD: madeira POSTGRES_DB: madeira volumes: - pgdata:/var/lib/postgresql/data healthcheck: test: ["CMD-SHELL", "pg_isready -U madeira -d madeira"] interval: 5s timeout: 3s retries: 10 volumes: pgdata:

这里用condition: service_healthy而非depends_on: postgres，是因为应用必须在数据库真正就绪后再启动。有人问，为什么不自己在代码里做串行重试？用 healthcheck 更省事，底层机制由容器运行时自己兜底，应用侧代码可以保持干净。

4.4 上线前的检查清单

上线前我整理了一条很管用的清单，贴出来给大家参考：

• 环境变量是否在生产配置中完整注入，特别注意数据库密码和各类 secret；
• 数据库迁移脚本是否已经在测试环境完整跑过一遍；
• 队列表的索引是否创建，有没有联合索引或部分索引；
• 是否配置了优雅关闭，收到 SIGTERM 后能先把当前任务跑完再退出；
• 日志平台能否按 requestId 和 taskId 检索；
• 内存和 CPU 的告警阈值是否已经配置。

这份清单不需要覆盖所有内容，但上面六项，每一项我都对应过线上问题，尤其后两项，如果没提前配置，排查问题会非常受罪。

5. 上线后常见问题与排查记录

5.1 队列表插入变慢，接口被拖垮

上线第一周一切正常，到月底对账时，任务接口和业务接口同时变慢。查看数据库日志，发现大批查询在排序阶段消耗大量 CPU，不少查询走到 seq scan。最初建的复合索引idx_task_queue_status_run_at，一旦查询条件包含 type 和 run_at 的组合，索引就匹配不上。

优化方案是增加一个部分索引，只处理 pending 状态的任务：

CREATE INDEX idx_task_queue_pending ON task_queue (run_at) WHERE status = 'pending';

加了部分索引之后，扫描量大减，月底跑批期间接口响应时间从几秒下降到几百毫秒。用数据库做队列，索引设计就是生命线，建议上线前就拿预估的数据量压一遍。

5.2 容器时区错乱造成定时任务不准

上线第二天，运营反馈定时导出任务提前了。定位半天发现容器默认时区是 UTC，老系统里跑得好好的延迟导出逻辑，在容器里一开始就差出八小时。解决方式很简单：compose 里注入TZ=Asia/Shanghai环境变量，如果涉及老数据，还要保证数据库连接串里的 timezone 参数一致。

更稳妥一点的做法是，任务调度不依赖服务器本地时间，统一使用 run_at 里存的带时区时间戳。调度器只和数据库当前时间比较，查询时间时显式指定 timezone。这样宿主机时区怎么变，任务执行时间都不会乱。

5.3 进程内存只涨不降

跑了一周后，发现 Worker 进程 RSS 从 150MB 慢慢爬到 400MB，这个信号不正常。先用node --inspect连上 Chrome DevTools，做了几次堆快照，发现大量解析后的 JSON 停留在内存里。后来定位到某类报表任务会一次性把几十 MB 的源文件读进内存，处理后再释放，但异常导致队列积压时，多个文件同时堆积，内存自然就上去了。

修复办法是把大文件解析改成流式读取，按行处理，内存占用立刻降到可控范围。对 Node.js 服务而言，内存问题多半不是 V8 的毛病，而是应用层把大量内容装进内存，做代码审查时一定要盯大对象。

5.4 重试风暴差点打挂下游

T+1 对账任务通常是凌晨批量执行，某次上游系统故障，返回超时非常多，任务失败后大量重试在同一时刻集中发出，下游接口直接出现雪崩迹象。事后把重试机制改成指数退避加随机抖动，同时在第一层引入熔断：如果某个任务类型在五分钟内错误率超过 40%，立刻停止自动重试，转为只告警不执行。

这是线上事故给的最大教训：任务队列不仅要管调度，还要保护下游。再强壮的服务端，也经不起一堆 Worker 同时重试同一个下游接口。合适的做法是让重试逻辑主动“认怂”，把压力分散到更长的时间窗口里。

5.5 常见问题速查表

这张表里的问题，我都真真切切遇到过至少一次，排查时先对照它，可以省掉好几个小时的盲目翻日志。

6. 再做一版的话，我会改哪些事

最后分享一个这个项目真正收尾后我才想明白的事。如果现在让我重写 Madeira，第一件事不是选框架，而是先把任务类型和状态转移规则用测试固定下来。遗憾的是，发布前虽然给导出任务写了测试，但状态机的覆盖仍然不足，后来加功能时每一步都要小心翼翼，生怕破坏已经跑通的状态流。

第二个会改的是队列字段的冗余设计。我会直接建一张 task_log 表，记录每次状态变更、耗时、错误堆栈，而不是只留最后一个 error_message。当时为了省事没有加，等到想排查“任务为什么在 processing 状态卡了十分钟”时才后悔，数据早就被覆盖了。

第三个建议是给所有外部依赖调用都加上可观测性指标，不只是成功或失败，还要知道 P99 响应时间。这样才能在任务量上涨时提前判断瓶颈是数据库、网络还是下游系统。这三个改动，每个看起来都不大，但对后期维护的安心程度提升会非常明显。

作为这个项目的实际操盘者，我越来越觉得，一个稳定到让你“感觉不到它存在”的服务，靠的往往不是高深技术，而是早早就把日志、索引、重试策略这些看似不起眼的环节做扎实。如果你也在做类似的拆服务项目，不妨把这些经验直接带进去，能省掉好几周的返工时间。