Redis Stream 消费组如何处理 Pending 列表里的超时消息

Redis Stream 消费组里出现 Pending，不等于 Stream 里还有一批从未读过的消息。它表示消息已经投递给某个消费者，但还没有被 XACK 确认；消费者崩溃、处理超时或网络中断，都可能让消息长期留在这里。处理这类消息的常用组合是：先用 XPENDING 看空闲时间和归属，再用 XAUTOCLAIM 让健康消费者接管超过阈值的消息，业务成功后才确认。

真正需要接管的不是“所有 Pending”，而是空闲时间超过业务超时、且原消费者已经没有可靠处理迹象的那部分消息。接管后仍可能重复投递，副作用必须依靠业务幂等兜底。

先看懂 Pending：它记录的是谁尚未确认

以订单流 orders 和消费组 order-workers 为例，worker-a 通过 XREADGROUP 读到一条消息后，这条消息就进入该组的 Pending Entries List，简称 PEL。只要没有确认，它就仍然占着消费组的未完成记录，即使 Stream 本身还在继续追加新消息。

先看摘要可以知道总量、最小和最大消息 ID，以及涉及的消费者：

# 先看消费组里有多少条未确认消息，以及它们的 ID 范围
redis-cli XPENDING orders order-workers

# 需要定位具体归属时，再按消费者和 ID 范围查看明细
redis-cli XPENDING orders order-workers - + 10 worker-a

明细里的 idle time 是这条消息自上次投递或重新认领以来的空闲毫秒数。它不是业务处理耗时，也不能单独证明原消费者已经退出；如果原消费者只是慢，过早接管就可能形成并行重复处理。

用 XPENDING 做接管前检查

接管前至少要回答三个问题：消息已经闲置多久，原消费者是否仍有心跳，业务允许多长时间后重试。比如订单扣库存可能允许 60 秒后重试，但这不意味着所有超过 60 秒的消息都能无条件重做。外部支付、发货、通知等副作用都要先用订单号或消息 ID 做幂等判断。

如果只是想读取某个 Pending 消息的内容，应该根据返回的消息 ID 使用 XRANGE，或让客户端用对应的读取命令获取字段；XPENDING 本身主要是状态查询。

用 XAUTOCLAIM 认领真正超时的消息

XAUTOCLAIM 适合做周期性的恢复 worker。它接收 Stream、消费组、新消费者名、最小空闲时间和起始游标；只有 idle time 达到阈值的 Pending 消息才会被转移。下面把 60 秒写成 60000 毫秒，每轮最多扫描 20 条：

# 只接管空闲超过 60 秒的消息，0-0 是第一次扫描的游标
redis-cli XAUTOCLAIM orders order-workers worker-b 60000 0-0 COUNT 20

# 业务处理成功后再确认消息，失败时不要提前 XACK
redis-cli XACK orders order-workers 1694000000000-0

返回结果包含下一次扫描游标和被认领的消息。生产代码应保存这个游标，在下一轮继续扫描；扫描回到起点后再重新开始。COUNT 只限制一轮的工作量，不是一次性清空 PEL 的承诺。若只需要 ID，可使用 JUSTID，再由应用按 ID 获取内容，但这样会把读取消息字段的责任留给应用。

认领之后如何避免重复消费

认领只是改变消息在消费组里的归属，不会替业务撤销已经发生的副作用。因此恢复 worker 的处理顺序应当是：读取返回的消息字段，检查幂等键，执行或跳过业务动作，成功后执行 XACK，失败则记录原因并让下一轮继续尝试。

幂等键可以使用订单号、业务流水号或“Stream 名 + 消息 ID”。如果业务无法做到严格幂等，至少把“已接管次数”和最后错误写入可观测日志，并限制同一消息的重试频率，避免慢消费者和恢复 worker 同时放大流量。

与手工指定 ID 的 XCLAIM 相比，XAUTOCLAIM 更适合按游标发现超时消息；与继续执行 XREADGROUP 相比，恢复逻辑关注的是旧的 Pending，而不是新到达的消息。两条通道可以共存，但应为正常消费和恢复消费分别设置并发、告警和退出条件。

常见问题

Pending 数量很大，能不能直接全部 XACK？

不建议。直接确认会丢掉尚未完成的业务，应该先按 idle time、消费者状态和 delivery count 分批接管。

min-idle-time 越小越好吗？

不是。阈值太小会把正常慢处理误判为失联，阈值太大又会延迟恢复，应以业务最长处理时间和可接受重试延迟为依据。

XAUTOCLAIM 后消息会不会再次被原消费者处理？

会有这种可能。所有权转移不能取消已经在执行的代码，所以原消费者和恢复 worker 都必须使用同一套幂等判断。

Redis 官方命令参考中的 XAUTOCLAIM、XPENDING 和 XREADGROUP 可作为参数和返回结构的更新入口。