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

mq Troubleshooting

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。

通过 kafka-topics.sh --describe 统计各 broker 的 leader 与副本数，再用 kafka-reassign-partitions 重新分配分区实现均衡

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

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

Scenario

这篇文章解决什么问题

适用于“Kafka 分区不均衡排查方法”对应的线上或本地排障场景。不要只根据最终报错下结论，应先把问题拆成入口、链路、目标服务和资源限制几层，再用命令逐层证实。通过 kafka-topics.sh --describe 统计各 broker 的 leader 与副本数，再用 kafka-reassign-partitions 重新分配分区实现均衡

Symptoms

典型现象

  • Kafka 分区 leader 集中在少数 broker 造成热点、消费者组频繁 rebalance 时，用 kafka-topics.sh --describe 统计各 broker leader 分布，再通过 kafka-reassign-partitions --generate/--execute/--verify 重新分配分区，rebalance 频繁则查 session.timeout.ms 与 max.poll.interval.ms。
  • 相关日志、命令或页面中反复出现 kafka、分区、rebalance 等关键词。
  • 同一服务在不同机器、不同入口或不同时间段表现不一致，需要通过证据链缩小范围。

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-topics.sh --bootstrap-server localhost:9092 --describe --topic my-topic
kafka-consumer-groups.sh --bootstrap-server localhost:9092 --describe --group my-group

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

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

  • 从报错服务所在机器执行测试
  • 必要时加 Host、SNI、namespace 或代理参数
  • 把成功路径和失败路径的输出并排比较
2. 在故障发生的同一位置复现
kafka-consumer-groups.sh --bootstrap-server localhost:9092 --describe --group my-group
kafka-reassign-partitions --bootstrap-server localhost:9092 --topics-to-move-json-file topics.json --broker-list 0,1,2 --generate
kafka-reassign-partitions --bootstrap-server localhost:9092 --reassignment-json-file plan.json --execute

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

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

  • 使用 kafka-topics.sh --describe 逐个 topic 统计每个 broker 上的 leader 数量与副本数量
  • 对比各 broker 的负载（CPU、磁盘 IO、网络），确认 leader 倾斜是否造成热点
  • 使用 kafka-consumer-groups.sh --describe 查看消费者组是否频繁触发 rebalance，记录 rebalance 原因
3. 读取服务端证据，而不是只看客户端提示
kafka-reassign-partitions --bootstrap-server localhost:9092 --topics-to-move-json-file topics.json --broker-list 0,1,2 --generate
kafka-reassign-partitions --bootstrap-server localhost:9092 --reassignment-json-file plan.json --execute

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

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

  • 使用 kafka-consumer-groups.sh --describe 查看消费者组是否频繁触发 rebalance，记录 rebalance 原因
  • 生成迁移方案：kafka-reassign-partitions --generate 生成候选分配 JSON，校验后再 --execute 执行
  • 执行后用 --verify 验证迁移完成，并复查 leader 分布与消费者 rebalance 频率是否恢复正常
4. 做最小修复并立即回归验证
kafka-reassign-partitions --bootstrap-server localhost:9092 --topics-to-move-json-file topics.json --broker-list 0,1,2 --generate
kafka-reassign-partitions --bootstrap-server localhost:9092 --reassignment-json-file plan.json --execute

Commands

排查命令与使用意图

命令 1

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

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

命令 2

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

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

命令 3

用于补充“Kafka 分区不均衡排查方法”的排查证据链。kafka-reassign-partitions 的输出需要结合上下文其他命令交叉验证，不要单独依赖某一条结果下结论。

命令 3
kafka-reassign-partitions --bootstrap-server localhost:9092 --topics-to-move-json-file topics.json --broker-list 0,1,2 --generate

命令 4

用于补充“Kafka 分区不均衡排查方法”的排查证据链。kafka-reassign-partitions 的输出需要结合上下文其他命令交叉验证，不要单独依赖某一条结果下结论。

命令 4
kafka-reassign-partitions --bootstrap-server localhost:9092 --reassignment-json-file plan.json --execute

Risk Notes

容易踩坑的地方

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

Verification

修复后怎么确认

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

Prevention

后续预防

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

常见问题

为什么新增 broker 后老 topic 的分区没有自动迁移过来？

Kafka 不会自动均衡已有分区，需要手动通过 kafka-reassign-partitions 触发迁移，或使用 Cruise Control 自动均衡

消费者组频繁 rebalance 但分区看起来均衡怎么办？

检查 session.timeout.ms、heartbeat.interval.ms、max.poll.interval.ms 配置，排查消费者处理过慢或 GC 停顿导致的误判离组

Long-tail SEO

你可能正在搜索这些报错

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

  • kafka 分区不均衡
  • kafka leader 倾斜
  • kafka rebalance 频繁
  • kafka 消费者组频繁重平衡
  • kafka 分区重新分配
  • kafka 热点 broker 排查

Related

相关排障 / 命令 / 工具

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

速查

消息队列常用命令速查表

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

mq命令

消息队列常用排障命令

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

mq排障

Kafka 消费堆积排查方法

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

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