Stream pending 消息怎么配置或排查

Redis Streams 里的 pending 不是另一种消息类型，而是消费组已经投递、但还没有被 XACK 确认的消息引用。它通常说明消费者处理变慢、进程中断，或代码忘记确认；不能把它简单当成 Stream 长度过大。排查时先看消费组，再决定确认、重试还是接管。

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

先看清 pending 到底代表什么

消费组用 XREADGROUP 读取消息时，Redis 会把消息 ID 记入 Pending Entries List（PEL）。在业务处理完成前，这条记录仍属于原 consumer；处理完成后由同一个 consumer 执行 XACK，它才会从该消费组的 pending 列表中移除。消息本身仍可能保留在 Stream 里，所以 XLEN 与 pending 数量不是同一个指标。

因此，所谓“配置 pending”通常不是改一个开关，而是把读取、处理、确认和故障恢复这条链路补完整。最小消费片段可以写成：

# 先按消费组读取新消息；0 表示每次最多取一条
XREADGROUP GROUP order-workers worker-a COUNT 1 BLOCK 2000 STREAMS orders >

# 业务处理成功后再确认；失败时不要提前执行这条命令
XACK orders order-workers 1710000000000-0

如果进程在两条命令之间退出，pending 增长是符合预期的；如果每条消息都处理成功却一直不下降，应优先检查确认是否发给了正确的 Stream、group 和消息 ID。

用 XPENDING 查看数量、ID 范围和消费者分布

先用摘要形式确认问题规模：

# 查看消费组 pending 总数、最早 ID、最晚 ID 和消费者分布
XPENDING orders order-workers+
# 查看某个 consumer 的前 20 条 pending 明细
XPENDING orders order-workers - + 20 worker-a

摘要里的总数只能回答“还有多少未确认引用”，还要结合最早/最晚 ID 和 consumer 分布判断是否集中在单个实例。明细查询得到消息 ID 后，再用 XRANGE orders 消息ID 消息ID 读取正文，避免把 ID 当作业务数据。

用消费组状态锁定故障边界

XPENDING 看的是 PEL，XINFO GROUPS 与 XINFO CONSUMERS 用来补充消费组和成员状态：

# 对照消费组的 pending、lag 和最后投递位置
XINFO GROUPS orders

# 查看每个 consumer 的 pending 数和空闲时间
XINFO CONSUMERS orders order-workers

如果某个 consumer 的 pending 很高、空闲时间也持续增长，通常要检查进程存活、网络连接和处理耗时；如果所有 consumer 都活跃但 pending 仍增长，则更像处理速度低于生产速度，不能直接接管所有消息。lag 与 pending 也要分开看：前者反映还没有投递到该组的消息，后者反映已经投递但未确认的消息。

只接管真正空闲的消息

Redis 6.2 及以上可以用 XAUTOCLAIM 扫描超过最小空闲时间的 pending，并把归属转给恢复 worker。下面的 60000 表示 60 秒，实际值应大于正常处理耗时和短暂抖动：

# 从 0-0 开始扫描，最多尝试接管 10 条空闲超过 60 秒的消息
XAUTOCLAIM orders order-workers recovery-worker 60000 0-0 COUNT 10

接管不是确认。恢复 worker 仍要重新执行业务处理，成功后再调用：

# 只有业务结果已经落库或下游成功后才确认
XACK orders order-workers 1710000000000-0

生产环境建议让处理逻辑具备幂等键，并记录原 consumer、接管时间、重试次数和最终结果。这样即使原 worker 只是网络抖动而不是彻底宕机，也能从日志判断是否发生重复处理。Redis 5.0 及以上也可以用 XCLAIM 指定消息 ID 做更精细的恢复；批量巡检则优先考虑 XAUTOCLAIM。

常见问题

pending 一直增加是不是 Stream 堵了？

不一定。pending 只说明已投递未确认；还要看生产速率、处理耗时、consumer 空闲时间和 group lag。

能不能直接执行 XDEL 清掉 pending？

不建议。删除 Stream 条目不等于完成业务处理，先确认结果或按恢复策略接管，再用 XACK 清理消费组引用。

XAUTOCLAIM 的空闲时间应该填多少？

以正常处理时长的高分位加网络抖动为基线，并留出故障检测余量；过小会制造重复消费，过大则恢复太慢。

排查顺序可以固定为：先用 XPENDING 定量，再用 XINFO 看成员和 lag，最后按业务阈值选择 XACK、XCLAIM 或 XAUTOCLAIM。关键不是把 pending 数字归零，而是确认每条消息的业务结果已经可追溯。