describe 看什么
kafka-topics.sh 的 --describe 逐个分区打印 Leader、副本列表、ISR 集合与主题级覆盖配置，是查看主题真实状态的主入口。前面加过滤参数，还能把范围收窄到「有副本掉队的」「不可用的」「刚好卡在最小同步副本边缘的」这几类分区。
为什么副本排查从它开始
客户端报超时、生产写入变慢、消费位移推进不动，原因可能都在副本层：某个 Broker 磁盘 IO 打满导致 Follower 跟不上，ISR 收缩，写入需要等待的副本减少但可用性下降。describe 的输出能在一屏内给出 Isr 与 Replicas 的差异，决定是继续查 Broker 还是转去查客户端。
基本信息
| 用途 | 查看分区、Leader、Replicas、ISR 与生效配置 |
|---|---|
| 过滤参数 | --under-replicated-partitions、--unavailable-partitions、--at-min-isr-partitions |
| 配置视图 | --topics-with-overrides 只看有覆盖配置的主题 |
| 输出规模 | 主题分区越多输出越长，先聚合再看 |
| 配套命令 | kafka-configs.sh --describe 查看动态配置明细 |
过滤参数怎么用
| 参数 | 筛出的分区 | 用途 |
|---|---|---|
| --under-replicated-partitions | ISR 数量少于副本数的分区 | 发现副本掉队，判断集群是否健康 |
| --unavailable-partitions | 没有 Leader 的分区 | 定位真正不可用的分区，属最高优先级 |
| --at-min-isr-partitions | ISR 数量刚好等于 min.insync.replicas | 再掉一个副本写入就会失败，属预警线 |
| --topics-with-overrides | 存在主题级配置覆盖的主题 | 核对是否有人手工改过保留时长等配置 |
典型使用场景
- 日常巡检：确认全集群没有 under-replicated 与 unavailable 分区
- 写入报错排查：检查是否因为 ISR 不足导致 acks=all 无法满足
- 扩容或 Broker 重启后：跟踪副本是否逐步追平、ISR 是否恢复完整
- 配置审计：列出被手工覆盖配置的主题，核对是否符合基线
- 上线前检查：确认新主题的分区数与副本分布符合预期
常用查询
常用查询
# 单主题全量详情：分区、Leader、副本与 ISR
kafka-topics.sh --bootstrap-server localhost:9092 --describe --topic orders
# Topic: orders Partition: 0 Leader: 2 Replicas: 2,3,1 Isr: 2,3,1
# 副本掉队的分区（集群级，不带 --topic）
kafka-topics.sh --bootstrap-server localhost:9092 --describe --under-replicated-partitions
# 完全没有 Leader 的分区，最需要立刻处理
kafka-topics.sh --bootstrap-server localhost:9092 --describe --unavailable-partitions
# 卡在最小同步副本线上的分区，属于写入可用性的预警
kafka-topics.sh --bootstrap-server localhost:9092 --describe --at-min-isr-partitions
# 统计掉队分区数量，便于巡检脚本判断
kafka-topics.sh --bootstrap-server localhost:9092 --describe --under-replicated-partitions | grep -c 'Partition:'Isr 列表短于 Replicas 说明有副本没跟上：先看该 Broker 的磁盘 IO、网络与 GC，再看是不是分区在同时做大量写入。多数情况下副本会自行追平，持续不恢复才需要干预。
输出的列顺序固定，但 Broker 编号在 Replicas 与 Isr 里排序不固定：写脚本判重时按集合比较，不要按位置比较，否则会误报。