Kafka 常见问题排查手册：连接超时、Maxwell 数据倾斜、ZooKeeper 缓慢（附排障流程图）

Kafka 常见问题排查手册：连接超时、Maxwell 数据倾斜、ZooKeeper 缓慢（附排障流程图）

Kafka 用得越久，遇到的问题越眼熟：连不上、写了但只进一个分区、zk 越来越慢。本文沉淀了三个高频问题的完整排查过程——真实报错日志 + 分析思路 + 解决方案，配一张通用排障决策流程图。都是生产环境踩过的坑，照着走一遍基本能覆盖日常 80% 的 Kafka 故障场景。

📚 相关系列：《Kafka 集群开启 SASL 认证实战（一）：内置 ZooKeeper 场景》《（二）外置 ZooKeeper 之 kafka 与 zk 间认证》《（三）外置 ZooKeeper 完整版》——认证配置类问题看这三篇，本文专注运行期故障排查。

问题一：客户端测试连接超时（TimeoutException: fetchMetadata）

现象

后台应用测试 Kafka 连接时报错，关键日志：

INFO o.a.k.c.s.authenticator.AbstractLogin:61  : Successfully logged in.
INFO o.a.k.common.utils.AppInfoParser:119      : Kafka version: 3.0.1
INFO [AdminClient clientId=adminclient-1] Metadata update failed

org.apache.kafka.common.errors.TimeoutException:
    Timed out waiting for a node assignment. Call: fetchMetadata

java.util.NoSuchElementException: Timeout waiting for idle object, borrowMaxWaitMillis=90000

日志经过精简——原始堆栈上百行，但有效信息就是这几行。

分析

三个观察点：

1. Successfully logged in：SASL 登录成功了，账号密码没问题，排除认证问题
2. 登录成功但 fetchMetadata 超时：TCP 层能建立连接，但 broker 返回元数据超时——典型的"半通"状态
3. 命令行直接对同一 broker 生产消费完全正常：网络链路和 broker 本身都健康

结论收敛到一点：应用所在机器与 broker 集群之间"能连上、聊不动"。

解决

检查应用机器的 hosts 配置，发现 /etc/hosts 里没有配置 Kafka 三节点的主机名映射——broker 返回的 metadata 里带的是主机名，应用机器解析不了这些主机名，后续的数据连接全部挂起直到超时。

补上映射后立刻恢复：

# 应用机器执行，补齐所有 broker 节点
echo "192.168.10.31  kafka01" >> /etc/hosts
echo "192.168.10.32  kafka02" >> /etc/hosts
echo "192.168.10.33  kafka03" >> /etc/hosts

Windows 服务器对应改 C:\Windows\System32\drivers\etc\hosts。

💡 这也解释了为什么命令行工具正常——我们手工验证时习惯用 IP 直连，绕开了主机名解析；而客户端库严格按 metadata 返回的地址回连，就会踩中这个坑。

问题二：Maxwell 写入 Kafka 数据严重倾斜

现象

用 Maxwell 解析 MySQL Binlog 同步到 Kafka，消费端发现数据倾斜：topic 有 3 个分区，其中一个分区的 offset 已经接近 200 万，另外两个还不到 200：

原因

Kafka 数据倾斜一般是生产者的分区选择策略导致：按 key 做 hash 后对分区数取模。查 Maxwell 文档可知，不配置分区参数时，Maxwell 默认拿"数据库名"作为 hash key，且默认哈希函数是 Java 的 hashCode。

而多数业务系统里，核心业务库的操作占了 binlog 的绝对大头——按库名 hash，等于把整个系统 90% 以上的写入全塞进了同一个分区，其他分区闲死。

解决

Maxwell 启动命令加两个参数：换更均匀的 murmur3 哈希 + 按主键做分区 key：

nohup /opt/maxwell-1.11.0/bin/maxwell \
  --user='maxwell' --password='******' --host='******' \
  --producer=kafka --kafka.bootstrap.servers=192.168.10.31:9092 \
  --kafka_partition_hash=murmur3 \
  --producer_partition_by=primary_key \
  >> /root/maxwell.log &

重启 Maxwell 后观察一段时间，各分区 offset 增量基本一致，倾斜消失。

⚠️ 注意取舍：按 primary_key 分区后，同一行的变更保证有序，但不同行之间的顺序不再有保障。下游如果依赖"表级全局有序"，这个方案不适用，需要评估业务语义。

问题三：Zookeeper 连接缓慢

kafka 的元数据操作变慢，先查 zk，三步走：

1. 检查 hosts 映射

老朋友了，和问题一同款：先确认 /etc/hosts 配了 zk 节点的主机名映射。

2. 检查 zk 内存设置

ps -ef | grep zoo | grep -i xmx

看不到 -Xmx 或值太小，就修改 /bin/zkEnv.sh 调整默认堆内存：

ZK_SERVER_HEAP="${ZK_SERVER_HEAP:-1000}"
export SERVER_JVMFLAGS="-Xmx${ZK_SERVER_HEAP}m $SERVER_JVMFLAGS"

改完重启 zk 生效。

3. 调整文件句柄数

zk 连接数多时容易撞到文件句柄上限，表现为连接缓慢、间歇性拒绝：

# 当前已打开句柄数
lsof -u es | wc -l
# 当前上限
ulimit -n

不够就把上限拉到 65536：

echo 'root    soft    nofile    65536' >> /etc/security/limits.conf
echo 'root    hard    nofile    65536' >> /etc/security/limits.conf

通用排障 Checklist

总结

三个问题共同点：报错信息都在指向"连接"，但根因各不相同——hosts 解析、分区策略、资源上限。排障时先分层定位（网络通不通 → 认证过不过 → 行为对不对），再对症下药，比对着报错瞎猜快得多。

你踩过最离谱的 Kafka 坑是什么？是 DNS 解析还是防火墙？评论区见。

排查过程来自生产环境实测；文中 IP、密码均为示例。