Agenda作业进入locked状态永不执行问题咨询

Agenda 作业锁定后不执行问题排查方案 #

先明确Agenda锁定机制核心逻辑：为避免多进程环境下作业重复执行，作业到达触发时间时，Agenda会先将对应任务的lockedAt字段更新为当前时间标记为被当前进程持有，锁定完成后才会调用对应作业逻辑。出现lockedAt更新但作业不执行的问题，可按以下顺序排查：

1. 检查是否显式启动了Agenda调度进程 #

Agenda实例初始化仅完成数据库连接，不会自动启动作业调度逻辑，很多场景下会遗漏启动步骤。
修复方案：所有作业定义注册完成后，必须调用agenda.start()启动调度：

let agenda = new Agenda({ db: { address: config.getDbConnectionString() }});
// 必须先注册所有作业定义
agenda.define('你的定时作业名称', async (job) => {
  // 作业业务逻辑
})
// 最后启动调度进程
await agenda.start();

2. 排查PM2多进程部署的一致性问题 #

PM2开启多实例部署时，不同进程会同时抢占同库的作业锁，如果抢到锁的进程没有注册对应作业的定义，就会出现锁被占用但无执行逻辑的情况。
修复方案二选一：

• 单独启动1个PM2实例专门运行Agenda调度服务，与业务服务进程拆分部署
• 确保所有PM2启动的进程，都完整注册了全部Agenda作业定义

3. 检查作业定义名与定时绑定名是否一致 #

如果作业定义的名称、定时任务绑定的作业名称存在拼写差异，Agenda抢到锁后会找不到对应的执行函数，直接跳过作业执行。

内容的提问来源于stack exchange，提问作者Haresh Pithiya