Redis XAUTOCLAIM 怎样转交空闲消费者的消息

我第一次把 Redis Stream 消费组接入后台任务时，最容易忽略的不是读取，而是“读到了却没有确认”的消息：原消费者退出后，消息还在 Pending Entries List（PEL）里，新的消费者不会因为它很久没人处理就自动拿到。这个场景可以用 XAUTOCLAIM 接管。

官方地址：https://redis.io/docs/latest/commands/xautoclaim/

本文只讨论 Redis Streams 消费组中的空闲消息转交。核心原则是：达到空闲阈值才接管，接管后由新消费者继续处理并用 XACK 收尾；0-0 只是当前扫描游标到达尾部，不代表以后永远没有新资格消息。

先看懂 XAUTOCLAIM 接管的对象

消费组用 XREADGROUP 交付消息时，尚未被 XACK 的条目会进入 PEL，并记录它当前归属的消费者、空闲时间和投递次数。原消费者可能崩溃、网络断开，或者处理逻辑卡住；这时新消费者应该接管“已经空闲足够久”的条目，而不是把所有未确认消息一股脑重放。

XAUTOCLAIM 可以理解为把查询 PEL 和改变消息归属组合成一次操作。它只考虑消息 ID 不小于 start 且空闲时间达到 min-idle-time 的条目；成功接管后，空闲计时会被重置，新消费者承担处理和确认责任。它仍然是至少一次投递语义，业务侧不能把“接管成功”误认为“只会处理一次”。

一条命令怎样表达接管条件

命令的基本形态如下。示例中的注释说明参数作用；这些是静态命令示例，不是本机运行结果。

# 从消费组的 PEL 起点，接管空闲至少 60 秒的消息
redis-cli XAUTOCLAIM orders orders-workers rescue-1 60000 0-0 COUNT 20

参数顺序依次是 Stream key、消费组、目标消费者、最小空闲毫秒数和起始 ID。COUNT 20 是本次尝试接管的上限，不保证一定返回 20 条，因为中间可能有消息尚未达到空闲阈值。起始 ID 常用 0-0，后续则应使用上一次返回的游标继续扫描。

如果只想先拿到待处理 ID，把消息重新读取交给另一套逻辑，可以加 JUSTID：

# 只返回被接管的消息 ID，并避免因返回正文而增加投递计数
redis-cli XAUTOCLAIM orders orders-workers rescue-1 60000 0-0 COUNT 20 JUSTID

不过 JUSTID 不是“免确认”开关。接管之后仍要根据 ID 完成业务处理和 XACK；如果只记录 ID 却不处理，PEL 仍会留下新的未确认责任。

用返回游标把接管循环跑完整

一次调用的返回通常包含三部分：下一次扫描用的游标、被接管的消息数组，以及 Redis 7.0 起可能出现的已从 PEL 清理的不存在条目。伪返回结构可以按下面的方式理解：

1) "1692632662819-0"   # 下一次 XAUTOCLAIM 的 start 游标
2) 1) 1) "1692632662819-0" # 消息 ID
      2) 1) "order_id"      # 消息字段
         2) "A-1001"

应用侧要保存返回的第一项，把它作为下一轮的 start。当 Redis 返回 0-0，说明这一轮已经扫描到 PEL 尾部；但经过一段时间，原本不够空闲的消息可能已经达到阈值，因此恢复任务时仍应从 0-0 重新开始，而不是永久停止。

接管得到完整消息时，处理成功后才确认。用命令表示就是：

# 业务处理成功后确认，避免把未完成的消息从 PEL 中提前移除
redis-cli XACK orders orders-workers 1692632662819-0

如果处理失败，不要为了让 PEL 变空而立即确认；应让重试、死信或人工处理策略接住它。接管动作本身会增加投递次数（使用 JUSTID 时例外），所以可以用投递次数识别持续失败的消息，避免它被无限接管。

四个容易把恢复逻辑写错的边界

• 空闲阈值不是处理超时。它描述消息自上次交付或接管以来的空闲时间，阈值过短会让仍在处理的消息被重复接管。
• COUNT 不是返回条数承诺。扫描中遇到未达阈值的条目时，实际接管数可能少于 COUNT。
• 0-0 不是任务完成标记。它只结束当前游标范围；定时恢复器需要周期性从头扫描。
• 接管不等于幂等。消息可能因为崩溃、超时或重复恢复再次投递，业务写入应使用消息 ID 或业务键做幂等约束。

相关问题

XAUTOCLAIM 和 XCLAIM 怎么选？

已知具体消息 ID、需要精确转交时可以用 XCLAIM；希望 Redis 从 PEL 中扫描满足空闲条件的消息时，XAUTOCLAIM 更适合恢复巡检。

接管后还需要 XACK 吗？

需要。接管只是改变消费组内的归属，业务处理完成后仍要由当前消费者调用 XACK，否则消息继续处于待确认状态。

因此，一个可靠的恢复循环应同时保存游标、控制空闲阈值、处理实际返回条数、保留失败消息，并把 XACK 放在业务成功之后。这样才能把“转交空闲消费者”变成有边界的故障恢复，而不是无条件重复消费。