Kafka 故障排查手册¶

文档概览¶

• 本篇为 ops 速查骨架；Broker 配置项见 Kafka 配置手册
• last_reviewed: 2026-07-07

1. 客户端 Metadata / 连接失败¶

概要¶

应用报 Connection to node -1 could not be established 或 Metadata 中 Broker 地址不可达。

关键词¶

advertised.listeners / LISTENERS / NAT / 容器网络

排查步骤¶

1. 确认客户端使用的 bootstrap 地址可达。
2. 在 Broker 上检查 advertised.listeners 是否为客户端/VPC 可解析、可路由的地址。
3. telnet / nc 验证 Metadata 返回的 每个 Broker host:port。
4. 检查安全协议（PLAINTEXT/SSL/SASL）与 listener.security.protocol.map 一致。

参考¶

• Kafka 配置手册 — advertised.listeners

2. 消费 lag 持续升高¶

概要¶

kafka-consumer-groups.sh --describe 显示 LAG 增大且不回落。

关键词¶

consumer lag / max.poll.interval.ms / rebalance

排查步骤¶

1. 确认消费者进程存活、无频繁 rebalance（日志中 Revoke/Assign 风暴）。
2. 对比分区数与消费者实例数并行度。
3. 检查处理逻辑是否阻塞 poll 线程；评估 max.poll.interval.ms 与 max.poll.records。
4. 排查 Broker 端磁盘、网络、ISR 收缩导致 fetch 变慢。

3. Under-Replicated Partitions（URP）¶

概要¶

Topic 分区副本未全部同步，存在数据丢失窗口风险。

关键词¶

UnderReplicatedPartitions / ISR / 磁盘 / 网络

排查步骤¶

1. kafka-topics.sh --describe 查看 URP 分区与离线副本。
2. 检查副本 Broker 磁盘、GC、网络；查看 Broker 日志 IOException。
3. 确认 replica.lag.time.max.ms 与硬件/跨机房 RTT 匹配。
4. 修复离线副本后观察 ISR 恢复；必要时触发分区重分配。

4. 磁盘占满 / 保留策略异常¶

概要¶

Broker 磁盘使用率告警，或 retention 未按预期回收。

排查步骤¶

1. kafka-log-dirs.sh --describe 定位大 Topic/分区。
2. 核对 log.retention.hours / log.retention.bytes（Broker 默认 vs Topic 覆盖）。
3. 检查压缩 Topic 的 cleanup.policy=compact 是否符合预期。
4. 紧急扩容：提高 retention 阈值、增加磁盘、或临时删除测试 Topic（需变更流程）。