BullMQ 任务队列排错：重试、失败、优先级与卡死
作者：夸父
逐日 AI 的生成任务由 BullMQ（Redis）调度。本文排查队列的四个高频问题：任务不消费、重试风暴、失败堆积、优先级失效。
任务不消费：worker 或队列的定位
pm2 list 看 worker 进程 → 存活则查 Redis 连接（redis-cli ping）→ 连接正常则看队列深度（LLEN bull:队列名:wait）——深度在涨说明 worker 消费不动（worker 卡死或并发配置异常），深度为零说明任务没入队（API 层的问题）。三层定位，两分钟缩小范围。
重试风暴：429 的连锁反应
下游 API（生图/配音）限流时，任务的自动重试如果无退避策略，会形成"失败→立即重试→再 429"的风暴——放大限流并浪费预算。逐日 AI 内置指数退避（见批量调度）；自查队列配置时确认 attempts 与 backoff 参数存在且合理（attempts ≤3，backoff 指数型）。
失败堆积的处理
failed 集合的堆积是"历史问题档案"——处理节奏：每周清一次，清理前逐个看失败原因（可修复的修复后重提，不可修复的标记丢弃）。堆积的 failed 任务超过几百个时，多半意味着某类系统性故障发生过——回头看时间线，找到故障窗口，评估那个时段的任务是否需要补跑。
优先级失效：队列设计的自查
多业务线共用一个队列时，优先级常被"先到先得"稀释。BullMQ 的优先级是任务级属性（job.priority），但要确认 worker 的消费策略支持它。更简单的方案是分队列：高优先队列与普通队列分开，worker 数量按业务权重分配——逐日 AI 的队列架构支持按项目隔离，矩阵场景直接用项目维度隔离即可。
监控面板
BullMQ 有官方的监控 UI（bullmq board）——队列深度、失败率、消费速率一目了然。批量生产的团队建议部署一个，队列的可视化让"任务卡住"这类问题的定位从翻日志变成看面板。
常见问题
任务显示 completed 但结果没生成？
任务完成≠业务成功：BullMQ 的 completed 指 worker 正常执行完毕，业务失败（如 API 返回错误但被捕获）需要看任务内部的状态记录。逐日 AI 的切片状态独立于队列状态，以切片面板的状态为准。
怎么安全地清空积压的队列？
分情况：清等待中的任务（清 waiting 集合）、清失败任务（清 failed 集合）、全部重来（清整个队列）。清空操作不可逆，先确认 Redis 持久化已开（AOF），避免误清后无法追溯。