真实命令 · 少走弯路·已沉淀 95 篇排障/命令手册，25 份速查表，15 个配置工具进入排障台
LaoHand开发者排障手册
配置生成

mq Troubleshooting

Kafka 消费堆积排查方法

Kafka 消费组 lag 持续增大、消息堆积时，用 kafka-consumer-groups.sh --describe 查看 CURRENT-OFFSET、LOG-END-OFFSET、LAG 定位堆积分区，对比生产/消费速率判断瓶颈在消费端 GC/下游超时还是分区不均衡，再评估扩容消费者或增加分区。

通过 kafka-consumer-groups.sh --describe 查看 LAG 列定位堆积分区，结合消费速率与生产速率判断瓶颈在消费端还是生产端

适用环境Kafka / RabbitMQ / RocketMQ
风险等级低
最后验证2026-07-04
建议权限按服务权限要求执行

2026-07-04 更新·约 3 分钟阅读

Scenario

这篇文章解决什么问题

适用于“Kafka 消费堆积排查方法”对应的线上或本地排障场景。不要只根据最终报错下结论，应先把问题拆成入口、链路、目标服务和资源限制几层，再用命令逐层证实。通过 kafka-consumer-groups.sh --describe 查看 LAG 列定位堆积分区，结合消费速率与生产速率判断瓶颈在消费端还是生产端

Symptoms

典型现象

  • Kafka 消费组 lag 持续增大、消息堆积时，用 kafka-consumer-groups.sh --describe 查看 CURRENT-OFFSET、LOG-END-OFFSET、LAG 定位堆积分区，对比生产/消费速率判断瓶颈在消费端 GC/下游超时还是分区不均衡，再评估扩容消费者或增加分区。
  • 相关日志、命令或页面中反复出现 kafka、消费堆积、consumer-lag 等关键词。
  • 同一服务在不同机器、不同入口或不同时间段表现不一致，需要通过证据链缩小范围。

Before Debugging

排查前先确认

  • 先确认是生产者、Broker 还是消费者的问题，不要在三层之间盲改。
  • 保留消息 ID、offset 和故障时间点，方便和上下游日志对齐。
  • 区分消息丢失（没投递成功）和消息积压（投递了但没消费），两者根因完全不同。

Root Causes

常见根因分层

消费者处理速度跟不上生产速度

消费逻辑慢、单线程拉取、批量大小不合理，会让 lag 持续增长，表现为积压而不是丢失。

  • 看 lag 和消费 TPS
  • 确认并发消费者数
  • 排查消费逻辑是否有阻塞

分区或队列不均衡、rebalance 频繁

分区分配倾斜、消费者频繁上下线触发 rebalance，会让部分消费者空转、部分积压。

  • 看分区分布和消费进度
  • 确认 session timeout 和心跳
  • 排查消费者重启原因

连接数或 channel 爆满、内存水位触发

连接泄漏、channel 不复用、Broker 内存超 watermark 触发 flow control，会让生产者被限流甚至断连。

  • 统计连接和 channel 数
  • 看 Broker 内存水位
  • 确认是否触发 flow control

Diagnosis Path

分步诊断流程

1. 固定现场，避免追着变化状态跑

先记录故障时间、影响入口、完整错误和最近一次变更。Kafka 消费堆积排查方法 这类问题经常在重启、重试或缓存刷新后短暂消失，没有现场信息会很难复盘。

  • 截图或保存完整错误文本
  • 记录请求域名/IP/端口/namespace/服务名
  • 标出最近发布、配置、证书、镜像或依赖变更
1. 固定现场，避免追着变化状态跑
kafka-consumer-groups.sh --bootstrap-server localhost:9092 --describe --group my-group
kafka-topics.sh --bootstrap-server localhost:9092 --describe --topic my-topic

2. 在故障发生的同一位置复现

很多误判来自测试位置不同：本机通不代表服务器通，容器内通不代表宿主机通，集群外通也不代表 Pod 内通。复现命令要尽量贴近真实流量路径。

  • 从报错服务所在机器执行测试
  • 必要时加 Host、SNI、namespace 或代理参数
  • 把成功路径和失败路径的输出并排比较
2. 在故障发生的同一位置复现
kafka-topics.sh --bootstrap-server localhost:9092 --describe --topic my-topic
kafka-log-dirs --bootstrap-server localhost:9092 --describe --topic-list my-topic
kafka-consumer-groups.sh --bootstrap-server localhost:9092 --describe --all-groups

3. 读取服务端证据，而不是只看客户端提示

客户端报错通常是结果摘要。真正能区分根因的是服务端日志、内核日志、事件、进程状态或数据库状态。

  • 使用 kafka-consumer-groups.sh --describe 查看 GROUP、TOPIC、PARTITION、CURRENT-OFFSET、LOG-END-OFFSET、LAG 列
  • 筛选 LAG 持续增大且非零的分区，记录分区编号与对应消费者实例
  • 使用 kafka-topics.sh --describe 确认分区数与 leader 分布，排除分区不均衡导致的堆积
3. 读取服务端证据，而不是只看客户端提示
kafka-log-dirs --bootstrap-server localhost:9092 --describe --topic-list my-topic
kafka-consumer-groups.sh --bootstrap-server localhost:9092 --describe --all-groups

4. 做最小修复并立即回归验证

每次只改一个变量，修复后用同一条复现命令回测，并观察日志是否停止增长。这样可以避免多个临时改动互相掩盖。

  • 使用 kafka-topics.sh --describe 确认分区数与 leader 分布，排除分区不均衡导致的堆积
  • 检查消费者端日志与监控指标，确认消费速率、GC、线程阻塞、下游依赖超时等瓶颈
  • 根据瓶颈采取扩容消费者实例、增加分区、优化消费逻辑或临时跳过堆积消息等措施
4. 做最小修复并立即回归验证
kafka-log-dirs --bootstrap-server localhost:9092 --describe --topic-list my-topic
kafka-consumer-groups.sh --bootstrap-server localhost:9092 --describe --all-groups

Commands

排查命令与使用意图

命令 1

用于补充“Kafka 消费堆积排查方法”的排查证据链。kafka-consumer-groups.sh 的输出需要结合上下文其他命令交叉验证，不要单独依赖某一条结果下结论。

命令 1
kafka-consumer-groups.sh --bootstrap-server localhost:9092 --describe --group my-group

命令 2

用于补充“Kafka 消费堆积排查方法”的排查证据链。kafka-topics.sh 的输出需要结合上下文其他命令交叉验证，不要单独依赖某一条结果下结论。

命令 2
kafka-topics.sh --bootstrap-server localhost:9092 --describe --topic my-topic

命令 3

用于补充“Kafka 消费堆积排查方法”的排查证据链。kafka-log-dirs 的输出需要结合上下文其他命令交叉验证，不要单独依赖某一条结果下结论。

命令 3
kafka-log-dirs --bootstrap-server localhost:9092 --describe --topic-list my-topic

命令 4

用于补充“Kafka 消费堆积排查方法”的排查证据链。kafka-consumer-groups.sh 的输出需要结合上下文其他命令交叉验证，不要单独依赖某一条结果下结论。

命令 4
kafka-consumer-groups.sh --bootstrap-server localhost:9092 --describe --all-groups

Risk Notes

容易踩坑的地方

  • 不要直接清空队列丢弃消息来“解决”积压，会导致业务数据丢失，应先确认积压原因。
  • 不要盲目重启 Broker，未持久化的消息和未确认的投递会丢失，重启前应确认同步状态。
  • 不要在生产环境随意调整分区数，分区扩展后不能缩减，且会影响现有消息的顺序。

Verification

修复后怎么确认

  • 原始故障现象已经消失，且使用同一入口重新测试 Kafka 消费堆积 能稳定成功。
  • 服务端日志不再出现同类错误，监控中的错误率、重启次数、连接数或延迟回到正常区间。
  • 如果做过临时绕过，已经记录恢复计划，例如还原宽松策略、补监控、补限制或提交正式配置。

Prevention

后续预防

  • 监控 lag、连接数和磁盘使用，而不是只看 Broker 是否存活，及时发现潜在问题。
  • 消费者做幂等处理，避免重复消费导致数据错乱，特别是在重试和 rebalance 场景下。
  • 设置合理的消息 TTL 和死信队列，防止异常消息无限堆积影响正常消息处理。
  • 对关键消息链路做端到端监控，从生产到消费全链路追踪，快速定位问题节点。

常见问题

LAG 一直为 0 但业务仍感觉延迟怎么办？

检查消费者是否提交了 offset 但未完成业务处理，或存在重复消费；通过业务埋点与日志确认实际处理时延

消费者扩容后 LAG 没有下降反而 rebalance 频繁怎么办？

确认消费者实例数不超过分区数，并检查 session.timeout.ms 与 max.poll.interval.ms 配置，避免因处理慢触发 rebalance

Long-tail SEO

你可能正在搜索这些报错

下面这些错误原文、场景词和中英文搜索词，都是排查同类问题时常见的入口。

  • kafka 消费堆积
  • kafka consumer lag 过大
  • kafka 消息积压怎么排查
  • kafka 消费者跟不上生产
  • kafka lag 持续增长
  • kafka 消费组 offset 查询

Related

相关排障 / 命令 / 工具

按分类和标签关联的排障流程、命令模板和配置工具，方便顺着同一个问题继续往下查。

命令

消息队列常用排障命令

Kafka、RabbitMQ、RocketMQ 消息队列排障命令速查，Kafka 用 kafka-consumer-groups.sh --describe 看 LAG 分区，RabbitMQ 用 rabbitmqctl list_queues/list_connections 看队列和连接，RocketMQ 用 mqadmin queryMsgById/consumerStatus 追踪消息与死信。

mq速查

消息队列常用命令速查表

Kafka、RabbitMQ 和 RocketMQ 三大消息队列一页速查：kafka-consumer-groups 查 lag 与 rebalance、rabbitmqctl list_queues/connections 排查积压泄漏、mqadmin consumerProgress 与 queryMsgById，以及磁盘水位与日志排查命令。

mq排障

Kafka 分区不均衡排查方法

Kafka 分区 leader 集中在少数 broker 造成热点、消费者组频繁 rebalance 时，用 kafka-topics.sh --describe 统计各 broker leader 分布，再通过 kafka-reassign-partitions --generate/--execute/--verify 重新分配分区，rebalance 频繁则查 session.timeout.ms 与 max.poll.interval.ms。

mq排障

RabbitMQ 连接数爆满排查方法

RabbitMQ 新连接被拒绝、报 no available sockets 或 file_descriptors 耗尽时，用 rabbitmqctl list_connections 统计各来源 IP 的连接与 channel 数，找出未复用连接池、未关闭 channel 的泄漏客户端，rabbitmqctl status 查 sockets/erlang processes 上限。

mq排障

RabbitMQ 队列阻塞排查方法

RabbitMQ 队列 messages_ready 持续增长、消费者不消费或镜像队列同步卡住时，用 rabbitmqctl list_queues 看队列状态和消费者数，list_consumers 检查 ack_required 长时间无 ack 的阻塞消费者，list_queues slave_pids 判断镜像同步进度。

mq排障

RocketMQ 消息丢失排查方法

RocketMQ 消息发送成功但消费端收不到、疑似丢失时，用 mqadmin queryMsgById 追踪消息落盘与消费轨迹，consumerStatus 查消费组 offset，检查死信队列 %DLQ%<group> 是否堆积，并确认 Broker 是否开启同步刷盘和主从同步复制。

mq