一个每天凌晨生成对账单的任务,最早是用 setInterval 写在服务进程里的,每隔二十四小时跑一次。上线一周后被财务投诉:周末的对账单少了两天。查日志发现服务在周六凌晨因为内存超限被重启,setInterval 的计时随之消失,重启后要再等二十四小时才会跑下一次。任务本身没有失败,它只是从来没被安排上。

第二个事故更危险。发券任务放在定时器里,服务扩到三个副本后,同一个时间点三个进程各自跑了一遍,用户收到了三张券。改成「谁抢到锁谁跑」之后又出现新问题:锁设置了三十秒过期,任务跑了四十秒,锁提前释放,第二个副本进来又跑了一遍。重复不是代码写错,而是调度模型没考虑多实例。

第三个问题出在事件循环。有人把一个导出 Excel 的任务直接写进队列的 process 函数,几十万行循环计算跑了二十秒。这一个任务把整个 Worker 进程的事件循环占住,其他任务全部排队,健康检查也超时。队列的 concurrency 开多大都没用,因为瓶颈不是并发数,而是那段同步计算。这篇讲清楚什么时候该用持久队列、BullMQ 的 Queue 和 Worker 各自负责什么、重试和并发怎么配、定时任务在多副本下怎么只跑一次,以及为什么「至少一次」意味着你必须写幂等。

进程内队列的三种失效方式

进程内队列是在当前 Node 进程里用一个数组或事件发射器保存待办任务。它实现简单,适合「请求返回后顺手做点不重要的事」,但有三种典型失效。第一,进程重启,内存里的任务全丢;第二,任务失败没有重试,也没有记录,谁都不知道少了什么;第三,多副本各自维护自己的队列,无法统一控制速率和顺序。

setInterval 和 setTimeout 还多一个问题:它们不保证准时。事件循环忙的时候,回调会被推迟;进程重启后,计时器不会从上次中断的地方继续。它们只适合「进程活着期间的周期性动作」,不适合「每天必须完成一次」的业务任务。

触发层: 定时器、HTTP 请求或手动脚本决定「什么时候要做」,它不应该承担「保证做到」的责任。
持久层: 任务写入 Redis 或数据库,带状态、重试次数和执行时间,进程重启后仍然存在。
执行层: Worker 从队列取任务,执行、成功确认或失败重试,多副本之间竞争同一个任务。

只要任务涉及钱、通知、对账、数据修复,就应该假设「进程随时会死」。把任务写进持久存储,重启后还能捡起来,这是队列存在的第一理由,不是「异步」两个字。

BullMQ 的 Queue 与 Worker

BullMQ 是建立在 Redis 上的任务队列。Queue 负责写入任务,Worker 负责取任务和执行,两者可以部署在不同进程甚至不同机器。任务在 Redis 里以 Hash 和 List 等结构保存,带状态、优先级、延迟和重试信息。Redis 在这里是任务存储,不是缓存,丢了就是任务丢了,所以生产要开持久化。

示例依赖只有 BullMQ;HTTP 层沿用 Express,Worker 单独启动。下面这份 package.json 同时放了入队服务和 Worker 的脚本:

{
  "name": "jobs-lab",
  "private": true,
  "type": "module",
  "scripts": {
    "start": "node src/server.js",
    "worker": "node src/worker.js"
  },
  "dependencies": {
    "express": "^5.3.0",
    "bullmq": "^6.7.1"
  }
}

npm install express@5 bullmq@6
npm run worker
一个任务从入队到完成
接口写入任务
Redis 保存待处理
Worker 取走并锁定
执行成功标记完成
失败按退避重试
超过次数进入失败集

一个最小的入队代码:

import { Queue } from 'bullmq';

const connection = { host: '127.0.0.1', port: 6379 };
const queue = new Queue('reports', { connection });

await queue.add(
  'daily-report',
  { tenant: 't1', date: '2026-11-06' },
  {
    jobId: 'report:t1:2026-11-06',
    attempts: 3,
    backoff: { type: 'exponential', delay: 1000 },
    removeOnComplete: { age: 3600, count: 100 },
    removeOnFail: { age: 86400 },
  }
);

HTTP 层只负责把请求转成任务,成功入队就返回 202,不等待报表生成:

app.post('/reports', async (req, res, next) => {
  try {
    const job = await queue.add('daily-report', req.body, {
      jobId: `report:${req.body.tenant}:${req.body.date}`,
      attempts: 3,
    });
    res.status(202).json({ jobId: job.id });
  } catch (err) {
    next(err);
  }
});

调用方式是普通的 JSON POST:

curl -i -X POST 127.0.0.1:3000/reports \
  -H "Content-Type: application/json" \
  -d '{"tenant":"t1","date":"2026-11-06"}'

本机 Redis 版本不满足 BullMQ 要求,这个接口未在本机实测。成功入队时应返回 202 和队列生成的 jobId;Redis 不可用时,错误中间件返回 500。不要把 jobId 写死成某个数字,它由队列分配,重启后可能变化。

Worker 端只关心「拿到数据后怎么做」,成功就返回结果,失败就抛错:

import { Worker } from 'bullmq';

const worker = new Worker(
  'reports',
  async (job) => {
    const { rows } = await buildReport(job.data);
    return { rows };
  },
  { connection, concurrency: 4 }
);

worker.on('failed', (job, err) => {
  console.error(JSON.stringify({ jobId: job.id, attempts: job.attemptsMade, error: err.message }));
});

本机实测时遇到一个前置问题:本机 Redis 版本是 3.0.504,BullMQ 6.7.1 在启动时直接拒绝连接,错误是 Error: Redis version needs to be greater or equal than 5.0.0 Current: 3.0.504。因此本文的入队、重试和重复任务代码均未在本机实测,需要在 Redis 5 以上的环境运行。这个错误本身也说明一件事:队列库对存储有版本要求,部署前先确认 INFO server 里的 redis_version。

不要把 BullMQ 的 Worker 和 HTTP 服务混在同一个进程里跑。发布重启时,HTTP 连接可以快速排空,但一个正在跑十分钟的任务不能跟着被杀。Worker 单独部署,给它更长的停机宽限期,才能把在途任务跑完。

attempts、backoff 与 concurrency

attempts: 3 表示最多执行三次,包含第一次,所以失败后还会重试两次。backoff 决定两次之间的等待:fixed 是固定间隔,exponential 按指数增长。指数退避适合外部服务短暂不可用的场景,避免所有任务在同一秒一起重试,把对方再次打挂。

concurrency 是一个 Worker 同时处理多少个任务。它不是线程数,所有任务仍然跑在同一个事件循环里。设成 10 意味着可以同时等待十个数据库查询或 HTTP 请求,适合 I/O 密集;如果任务里有大段同步计算,设成 100 也只会让它们排队,而且会拖慢所有其他任务。

重试要满足两个条件才有意义。第一,失败是可重试的,比如网络超时、对方 503;参数错误、权限错误重试一百次也不会成功,应该直接进入失败集并告警。第二,任务可重复执行而不产生副作用,或者有幂等保护。给一个已经扣款的订单再扣一次,不叫重试,叫重复扣款。

失败任务要有人看。removeOnFail 如果设得太短,失败记录很快被清掉,排查时什么都不剩;如果完全不清理,Redis 内存会被失败任务撑爆。折中的做法是保留七天或固定条数,再用监控看失败率。失败率突然上升通常不是队列的问题,而是下游数据库或第三方接口出了问题。

定时任务:repeatable 与 node-cron 的差别

node-cron 是进程内的 cron 表达式调度器,写法简单,适合单实例的小工具。它不持久化,进程重启后重新计时;它也不协调多副本,每个副本都会各自触发。用在多副本服务里,最常见的现象就是「每天凌晨的任务跑了好几遍」。

BullMQ 6 用 Job Scheduler 把调度信息存到 Redis,多个 Worker 通过队列竞争,同一个时间点只会有一个任务被取走。写法是:

await queue.upsertJobScheduler(
  'daily-report-2am',
  { pattern: '0 2 * * *', tz: 'Asia/Shanghai' },
  {
    name: 'daily-report',
    data: { tenant: 't1' },
    opts: { attempts: 3, backoff: { type: 'exponential', delay: 1000 } },
  }
);

区别不只是「持久化」。node-cron 的调度器在应用进程里,任务执行也在应用进程里;BullMQ 的调度在 Redis,执行在 Worker。前者部署简单,后者需要 Redis 和 Worker,但能做到重启不丢、多副本不重复、失败可重试、积压可观测。

node-cron 适合什么

单实例、任务轻、失败可以接受、不需要历史记录的场景。比如每天清理一次本地临时文件,或者开发环境定时打印状态。它的价值是零依赖、几行代码就能跑。

BullMQ 适合什么

多副本、任务涉及数据或资金、需要重试和审计、需要控制并发的场景。代价是多一个 Redis 依赖、多一套 Worker 部署和监控,还要处理幂等。

时区是定时任务的高发问题。0 2 * * * 在 tz: 'Asia/Shanghai' 下是北京时间凌晨两点,不写时区则按服务器时区解释。容器默认通常是 UTC,同一份配置在本地和线上会差八小时。统一显式写时区,数据库里的时间统一存 UTC,展示时再转换。

多副本:单实例调度、分布式锁与幂等

即使不用 BullMQ,多副本下也必须解决「谁来跑」。第一种做法是单实例调度:只让一个副本启用定时任务,其他副本通过环境变量关闭。它简单,但那个副本挂了任务就停,需要人工或编排系统保证它活着。第二种是分布式锁:每个副本都尝试抢锁,抢到的跑,没抢到的跳过。

const ok = await redis.set('lock:daily-report', instanceId, 'NX', 'PX', 30000);
if (!ok) return;
try {
  await runReport();
} finally {
  await releaseLockIfOwner('lock:daily-report', instanceId);
}

锁的过期时间必须覆盖任务最长执行时间,否则任务没跑完锁就释放,第二个副本会进来重复执行。但把过期时间设得很长,进程崩溃后锁又要等很久才释放。更稳的做法是给任务加「心跳续期」,并在业务写入时带一个单调递增的 fencing token,让数据库拒绝过期锁持有者的写入。这已经接近分布式系统的复杂地带,能用单实例调度或队列解决,就不要自己造锁。

无论用锁还是队列,最终都要落到幂等。因为网络分区、重试、进程崩溃都会导致「至少执行一次」,系统无法免费提供「恰好一次」。幂等的做法是在数据库里建一个唯一键,比如 job_key 或 idempotency_key,业务写入和这个键在同一个事务里提交。重复执行时唯一键冲突,捕获后当作成功返回,不再产生副作用。

insert into processed_jobs (job_key, finished_at)
values ($1, now())
on conflict (job_key) do nothing
returning job_key;

如果返回空行,说明这个任务已经处理过,直接结束。这个判断必须和业务写入在同一个事务里,否则「先查再写」的间隙仍然会有两个执行者同时通过。外部接口也一样,发券、支付、发短信都要带幂等键,不能假设对方会去重。

优雅停机与在途任务

发布时给进程发 SIGTERM,如果直接 process.exit(),正在执行的任务会被硬中断。BullMQ 的 Worker 在关闭时会等待当前任务完成,但需要你主动调用 close(),并且给外层留足时间。

async function shutdown() {
  await server.close();
  await worker.close();
  await queue.close();
}

process.on('SIGTERM', () => {
  const force = setTimeout(() => process.exit(1), 30000);
  shutdown().finally(() => {
    clearTimeout(force);
    process.exit(0);
  });
});

顺序是先停止接收新的 HTTP 请求,再关闭 Worker。Worker 关闭期间不再取新任务,但已取走的任务会继续跑。超过宽限期还没结束,只能强制退出,任务会在锁超时后被判定为 stalled,重新回到队列。所以任务本身要能承受「执行到一半被杀」,这也是幂等重要的原因。

容器编排里的 terminationGracePeriodSeconds 要大于应用的强制退出时间。如果编排只给十秒,应用却设了三十秒的排空,最后还是会硬杀。两个数字要对齐,并且把「是否还有在途任务」写进停机日志,发布后能确认每次都是干净退出。

事件循环与 worker_threads 的边界

Node 是单线程执行 JavaScript 的,所谓「并发」主要发生在等待 I/O 时。一个 Worker 的 concurrency 再高,遇到同步循环、超大 JSON 解析、图片处理、加密计算,都会把事件循环占住。表现是队列里其他任务不动、健康检查超时、Redis 心跳延迟,严重时看门狗判定任务 stalled。

处理 CPU 密集任务有三条路。第一,拆成更小的批次,每批之间用 setImmediate 让出事件循环;第二,用 worker_threads 把计算放到独立线程;第三,把这类任务拆成独立服务,用更适合的语言或工具处理。队列只负责调度,不负责让单线程变多线程。

import { parentPort } from 'node:worker_threads';

parentPort.on('message', (rows) => {
  const total = rows.reduce((sum, row) => sum + row.amount, 0);
  parentPort.postMessage({ total });
});

worker_threads 适合纯计算、数据已经在内存里的场景。它不能共享普通对象,消息传递有序列化成本,线程数也不是越多越好。如果任务主要是等数据库或 HTTP,用 Worker 的并发就够了,上线程池只会增加复杂度。

NestJS 的 Bull 集成

NestJS 11 通过 @nestjs/bullmq 把 BullMQ 包成模块。用 BullModule.forRoot 配 Redis 连接,BullModule.registerQueue 注册队列,再用 @Processor('reports') 装饰一个类,继承 WorkerHost 并实现 process 方法。任务注入、配置和生命周期由 DI 容器管理。

和 Express 里的写法相比,差别主要在组织方式:Express 里 Queue 和 Worker 是普通模块,自己管理连接和关闭;NestJS 里它们是可注入的 Provider,能在 onModuleDestroy 里统一关闭。底层仍然是同一个 BullMQ,重试、幂等、事件循环的规则完全一样。不要把 NestJS 的装饰器当成「自动可靠」,任务失败照样要重试,重复执行照样要幂等。

现象、真实原因与第一步

现象真实原因第一步查什么
队列积压持续增长Worker 没启动、并发太低,或下游变慢看 waiting 与 active 数量,确认 Worker 进程和消费速率
同一个任务执行多次多副本各自调度,或重试没有幂等保护查调度器数量和 jobId,确认业务是否有唯一键
发布后任务消失任务只在进程内存里,没有持久化确认任务是否写入 Redis,重启前是否有未处理数组
任务被判定 stalled执行时间超过 lockDuration,或事件循环被阻塞看任务耗时和同步代码,调整锁时长或拆分任务
定时任务不触发时区写错、cron 表达式不合法,或 Worker 没运行打印调度器配置和下次执行时间,确认 tz
Redis 内存持续上涨完成和失败任务没有清理策略看键数量与内存,设置 removeOnComplete 和 removeOnFail
健康检查超时但 CPU 很高Worker 里跑了同步重计算,占住事件循环用性能分析找同步热点,拆批或移到 worker_threads
停机后重复发券任务执行到一半被杀,锁过期后重新投递检查幂等键是否和业务写入同事务,宽限期是否足够

边界与代价

队列提供的是「至少一次」语义,不是「恰好一次」。任何声称恰好一次的方案,最后都靠幂等键或业务约束实现。接受这一点,代码里就会自然长出唯一键、状态机和补偿逻辑;不接受,就会在事故里反复修「为什么又发了一次」。

引入 Redis 和 Worker 是有运维成本的。多一个存储要监控内存、持久化和连接数;多一类进程要部署、扩缩容和排空;多一套失败任务要有人看。任务量很小、失败可以接受时,node-cron 或系统级 cron 更划算。不要为了「架构先进」把三个定时任务抬成一套队列系统。

BullMQ 的并发控制也不是无限的。Redis 连接数、Worker 数量、下游数据库容量都会成为瓶颈。把 concurrency 调高只是让更多任务同时打数据库,数据库撑不住时,积压会从队列转移到连接池。容量要按下游能承受的速率来定,而不是按队列想跑多快。

最后是时间语义。定时任务按 cron 表达式触发,遇到夏令时、服务器时区变更、时钟漂移,都可能提前或延后。对账、结算这类任务要记录「业务日期」和「实际执行时间」,允许补跑和重跑,不要把「凌晨两点」当成绝对保证。

当天能自己验证的练习

  1. 执行 redis-cli INFO server 查看 redis_version;如果低于 5.0,先起一个 Redis 7 容器,再用 node -e 连接并打印 PING,确认版本满足 BullMQ 要求。
  2. 写一个 attempts: 3、固定退避一秒的任务,让 Worker 前两次抛错、第三次成功,观察 job.attemptsMade 和最终状态;确认失败任务没有凭空消失。
  3. 同时启动两个 Worker 消费同一个队列,各加十个任务,观察两个进程的日志分布,确认同一个 jobId 不会被两边同时执行。
  4. 用 node-cron 起两个进程跑同一个 * * * * * 表达式,记录两边都打印的时间点;再换成 BullMQ 的 Job Scheduler,观察只有一个任务被执行。
  5. 在 Worker 的处理函数里写一个十秒的同步 while 循环,同时请求健康检查,观察请求被阻塞;再把计算移到 worker_threads,对比健康检查的响应时间。

小结

三句话:涉及钱和数据完整的任务要写进持久队列,进程内定时器不保证「做到」;多副本下调度要么单实例、要么用队列或锁,并且必须配幂等;concurrency 只提高 I/O 并发,CPU 密集任务要拆批或移到线程。

下一篇讲上线。队列、数据库、HTTP 服务都准备好之后,最后一关是部署:配置校验、结构化日志、健康检查、优雅退出和容器信号。很多线上事故不是业务代码错,而是进程被 OOM 杀掉、发布时连接没排空、健康检查只返回一个 ok。下一篇会从退出码 137 和发布时的 502 开始,把上线前的检查清单串起来。