Redis Stream 消费组 pending 消息如何重新认领

Redis Stream 消费组里，消息被 XREADGROUP 投递后，如果消费者还没有执行 XACK，它就会进入 Pending Entries List（PEL）。这类消息不是“还没消费”，而是“已经交给某个消费者但尚未确认”。消费者异常退出时，处理方式是先用 XPENDING 看清空闲时间，再用 XAUTOCLAIM 把超过阈值的消息交给新消费者；业务处理成功后仍要执行 XACK。

官方地址：https://redis.io/

先确认 pending 消息是不是真的卡住

我排查 Stream 积压时，先看消费组摘要，再看 PEL 明细。XINFO GROUPS 里的 pending 表示已经投递但尚未确认的条数；它和还没有投递给任何消费者的消息不是一回事。

# 先看消费组的 pending、最后投递 ID 和 lag
XINFO GROUPS orders

# 查看指定消费组的 PEL 摘要：总数、最小 ID、最大 ID、消费者数量
XPENDING orders order-workers

# 展开前 20 条 pending，观察每条消息的拥有者和空闲时间
XPENDING orders order-workers - + 20

如果只是 pending 增长，但每条消息的 idle time 很短，通常说明消费者正在处理，不宜立刻抢走。真正需要恢复的是超过业务处理上限、且原消费者已经不再工作的消息。

用 XPENDING 筛出超过阈值的消息

Redis 支持在 XPENDING 中用 IDLE 过滤最小空闲时间。下面的命令只列出空闲超过 60000 毫秒的消息：

# 只找空闲超过 60 秒的 pending 消息，最多返回 20 条
XPENDING orders order-workers IDLE 60000 - + 20

# 只检查某个消费者名下的超时消息
XPENDING orders order-workers IDLE 60000 - + 20 worker-a

这里的 60000 不是 Redis 的固定规则，而是你的处理超时阈值。它至少要大于正常业务耗时的高分位，否则新消费者可能和旧消费者同时处理同一条消息。接管之后仍然要让业务具备幂等性，因为网络抖动或进程重启都可能造成重复处理。

用 XAUTOCLAIM 转移超时消息，再决定何时确认

知道具体 ID 时可以用 XCLAIM 定点接管；需要从 PEL 中持续找出超时消息时，XAUTOCLAIM 更顺手。它接收 Stream、消费组、新消费者、最小空闲时间和扫描起点，返回下一次扫描游标以及被接管的消息。

# 从 PEL 起点扫描，把空闲超过 60 秒的消息交给 worker-recovery
# COUNT 控制一批最多处理多少条，避免一次取走过多消息
XAUTOCLAIM orders order-workers worker-recovery 60000 0-0 COUNT 20

生产代码不要每次都固定使用 0-0 后立即结束。把返回的 next ID 作为下一轮起点，直到游标回到起点或本轮没有更多消息；如果需要长期巡检，可以下一次定时任务再从 0-0 开始。命令返回的消息内容交给新消费者处理，成功后再确认：

# 处理返回的每个消息；下面是假设业务处理函数已完成
# 只有外部副作用成功后才 XACK，失败就保留在 PEL 等待下一轮恢复
XACK orders order-workers 1692632662819-0

Redis 7.0 以后，如果消息已经从 Stream 中被删除，但仍残留在 PEL，认领结果可能只返回 ID 或把对应 PEL 条目清理掉。遇到这种情况不要把它当作完整业务消息重试，应记录 ID 并结合业务幂等记录判断是否需要补偿。

XAUTOCLAIM 和 XCLAIM 怎么选

我的经验是把恢复任务和正常消费分开：正常消费者负责新消息，恢复消费者只处理 idle time 超过阈值的 PEL。监控至少记录 pending 数、最长空闲时间、认领数量、处理失败数量和重复处理次数。这样才能区分“消费速度慢”和“某个消费者已经失联”。

常见问题

pending 数量变大就应该马上认领吗？

不应该。先看 idle time 和原消费者状态；正在处理但尚未确认的消息可能只是业务耗时较长。

XAUTOCLAIM 后还需要 XACK 吗？

需要。XAUTOCLAIM 只改变 PEL 中的消息归属并返回消息，业务成功后仍要由当前消费者执行 XACK。

为什么认领后仍可能重复执行？

接管和确认之间如果进程崩溃，下一轮仍可能再次得到这条消息。因此扣库存、发通知、写外部系统等副作用要用业务幂等键保护。