Redis XAUTOCLAIM批量接管失联消费者消息的实现方法

我在排查 Redis Stream 消费组积压时，最容易误判的是“消费者还在线”与“消息有人处理”是两件事。消息一旦被消费组投递，就会进入 Pending Entries List（PEL）；原消费者进程崩溃后，它不会自动回到可读队列。处理这类失联消息，适合让一个健康消费者使用 XAUTOCLAIM 按空闲时间批量接管。

核心做法是：从 0-0 开始扫描指定消费组的 PEL，只接管空闲时间超过阈值的消息；每次保存返回的下一游标，直到返回 0-0，再对接管到的消息执行业务处理和 XACK。接管不是确认，业务成功后仍要单独确认。

先把 PEL 和失联消费者分清楚

Stream 的消费组读取通常使用 XREADGROUP。当消费者以消息 ID > 读取新消息时，Redis 会把已投递但尚未确认的条目放入 PEL。消费者进程退出并不会替它执行 XACK，因此恢复逻辑应针对 PEL，而不是重新从 Stream 尾部盲目读取。

下面的初始化命令只用于构造实验数据：先写入几条消息，再创建消费组并让一个消费者读取但不确认。命令中的注释解释每个动作的目的，不代表真实运行截图。

# 写入测试消息，并让消费组从头开始接收
XADD orders * order_id 1001 status paid
XADD orders * order_id 1002 status paid
XGROUP CREATE orders order-workers 0-0 MKSTREAM
# 模拟 worker-a 已取走消息但暂未 XACK
XREADGROUP GROUP order-workers worker-a COUNT 2 STREAMS orders >
# 查看 PEL 中的消费者、空闲时间和投递次数
XPENDING orders order-workers - + 10

用 XAUTOCLAIM 批量接管超时消息

命令格式是 XAUTOCLAIM key group consumer min-idle-time start [COUNT count] [JUSTID]。例如让 worker-recovery 接管空闲超过 60 秒的消息：

# 从 PEL 开始扫描，最多尝试接管 25 条空闲消息
XAUTOCLAIM orders order-workers worker-recovery 60000 0-0 COUNT 25

返回结果的第一项是下一次扫描的起点，第二项是已经转移给新消费者的消息，第三项在 Redis 7.0 及更高版本用于报告 Stream 中已不存在、但从 PEL 清理掉的消息 ID。不要把第一项误当成“本次接管的最后一条消息”。

循环游标时，接管和确认要分两步

如果 PEL 很大，一次命令拿不完，就用返回的第一项作为下一次 start。返回 0-0 表示本轮已经扫描到末尾，但周期性恢复任务仍可以稍后再次从 0-0 开始，因为新的空闲消息可能已经达到阈值。

# 伪代码式 shell 示例：沿游标扫描，并保留每次返回的结果
cursor="0-0"
while true; do
  # COUNT 控制单次尝试量，避免恢复任务一次占满处理资源
  reply=$(redis-cli XAUTOCLAIM orders order-workers worker-recovery 60000 "$cursor" COUNT 25)
  printf '%s\n' "$reply"
  # 实际程序应解析 RESP 返回值，而不是用文本截取代替协议解析
  next_cursor="从 reply 第一项解析"
  if [ "$next_cursor" = "0-0" ]; then
    break
  fi
  cursor="$next_cursor"
done

拿到消息后先做业务幂等判断，再根据处理结果选择 XACK orders order-workers 消息ID。成功才确认；失败则保留在 PEL 中，交给下一轮接管。若只需要先拿 ID 再批量读取正文，可以使用 JUSTID，但它不会返回消息字段，也不会增加该消息的重试计数，适合做轻量扫描而不是替代完整处理。

COUNT、空闲阈值和重试监控怎么定

生产环境我会把恢复任务做成低频、可暂停的独立 worker，并为“接管数量、接管后失败数量、重试次数过高、失效 ID 数量”分别设指标。这样既能恢复真正失联的消息，也不会把短暂延迟误判为故障。

相关问题

XAUTOCLAIM 会自动确认消息吗？

不会。它只改变 PEL 中消息的归属；业务处理成功后仍要调用 XACK。

为什么 COUNT 设置为 25 却没有拿到 25 条？

Redis 会先扫描候选，再过滤掉空闲时间未达到阈值的条目，因此实际数量可以少于 COUNT。

返回 0-0 后还要继续调用吗？

当前扫描到末尾后可以结束本轮；下一次恢复周期仍从 0-0 开始，以覆盖后来达到空闲阈值的消息。

把 XAUTOCLAIM 看成“转移处理责任”的扫描命令，而不是“重放消息”的快捷按钮，恢复逻辑就会清晰很多：阈值负责降低误接管，游标负责覆盖 PEL，幂等和 XACK 负责最终一致性。