Redis Stream 消费组消息处理失败后怎么重新认领

Redis Stream 消费组里，消费者通过 XREADGROUP 读到消息后，如果业务处理还没完成就宕机，消息不会自动回到“未投递”区域，而是留在消费组的 Pending Entries List（PEL）中。正确的处理顺序是：先用 XPENDING 看清消息归属和空闲时间，再按消息数量选择 XCLAIM 或 XAUTOCLAIM 接管，业务成功后由新消费者执行 XACK。

少量已知消息用 XCLAIM，持续扫描超时 pending 用 XAUTOCLAIM；两者都不是“强制重试按钮”，接管前必须先设置合理的空闲阈值，并让业务处理具备幂等性。

先看 PEL：消息到底卡在哪个消费者手里

不要一看到消费端报错就直接从头读取 Stream。消费组维护的是“已投递但未确认”的状态：消息 ID、当前消费者、空闲时间和投递次数都可能影响接管判断。先执行摘要查询，确认组里是否真的有 pending：

# 查看订单组的 pending 总数、最早和最晚消息 ID
XPENDING orders-stream order-workers

# 按消费者查看各自持有的 pending 数量
XPENDING orders-stream order-workers - + 20 worker-a

如果摘要总数为 0，问题可能发生在生产者、消费组游标、业务代码或连接本身，不应直接调用认领命令。如果有 pending，再看消息的 idle 时间和消费者状态；短暂的网络抖动不等于消费者已经失效。

空闲阈值决定要不要接管

min-idle-time 是接管判断的核心。它表示消息至少空闲了多久，单位是毫秒。阈值太小，原消费者只是慢了一点就会被另一台机器抢走，造成重复处理；阈值太大，真正失效的消费者又会让消息长时间堆积。

这个阈值不是 Redis 替你做出的业务结论。它只保护“空闲足够久”的消息，不能证明原业务没有执行过，所以支付、库存、发货等场景必须再用订单号或事件 ID 做幂等。

已知 ID 用 XCLAIM，持续巡检用 XAUTOCLAIM

如果 XPENDING 已经给出少量明确的消息 ID，可以使用 XCLAIM：

# 只接管空闲超过 60 秒的两个消息，并把归属交给 recovery-worker
XCLAIM orders-stream order-workers recovery-worker 60000 1710000000000-0 1710000000001-0

命令成功后，消息归属转到新消费者，返回内容可以直接用于后续处理。多个消费者同时尝试接管同一条消息时，空闲时间会被重置，因此不能把返回结果之外的消息也当成已接管。

需要定时巡检一批 stale pending 时，XAUTOCLAIM 更合适：

# 从游标 0 开始扫描，接管空闲超过 60 秒的消息，每次最多取 20 条
XAUTOCLAIM orders-stream order-workers recovery-worker 60000 0 COUNT 20

XAUTOCLAIM 会返回下一游标和被接管的消息；巡检程序应保存下一游标，在后续周期继续扫描，直到回到 0-0。只取 ID 时可使用 JUSTID，再由消费者按自己的方式读取历史。若 Redis 版本不支持该命令，可以退回到 XPENDING 分页加 XCLAIM 的组合。

接管后怎样确认，才不会把失败吞掉

新消费者接管消息后，先按业务幂等键检查是否已经执行过，再处理订单、通知或写库动作。只有业务结果已经持久化，才执行：

# 业务成功后确认指定消息；返回 1 才表示这条 ID 被从 PEL 中确认
XACK orders-stream order-workers 1710000000000-0

XACK 只处理消费组的确认状态，不会替你撤销已经完成的外部副作用。业务失败时不要为了减少 pending 数而确认；可以保留它，增加重试计数，并把超过上限的消息转入人工或死信处理。生产巡检至少记录消息 ID、原消费者、新消费者、idle、重试次数和最后错误。

常见问题

重新调用 XREADGROUP 能自动拿回失败消息吗？

不能把它当作通用接管方案。新消息读取使用组游标；要读取某个消费者历史或接管其他消费者的 pending，应先检查 PEL，再使用认领命令。

为什么 XCLAIM 没有返回消息？

常见原因是消息已经被确认、其他消费者刚刚接管，或 idle 尚未达到 min-idle-time。重新查看 XPENDING，不要立刻把阈值降到零。

接管成功后还需要 XACK 吗？

需要。认领只是把待处理消息换了一个消费者，成功处理后仍要用 XACK 从该消费组的 PEL 中移除记录。