从零搭建高可用Kafka集群：ZooKeeper部署与配置避坑指南

先说个我自己的真实经历。第一次在生产环境搭Kafka，我图省事，直接按单机模式套路部署——ZooKeeper和Kafka都跑在同一台机器上，配置几乎全是默认。结果业务量稍微上来一点，消费端就开始频繁报错，消息延迟从几十毫秒飙升到几秒钟。排查了半天才发现，ZooKeeper节点的连接数被打满，Kafka Broker和ZooKeeper之间心跳超时，整个集群的leader选举被反复触发，副本同步链路全被堵死了。后来痛定思痛，老老实实按生产标准搭了一套三节点Kafka+三节点ZooKeeper集群，把配置逐项梳理清楚，才算真正把Kafka集群玩明白。

这篇文章就是那次重构之后整理出来的完整过程。我会从0开始，带着大家完成一套高可用的Kafka集群搭建，ZooKeeper也是从0到1手动部署。内容包括集群架构设计、版本选型、环境准备、ZooKeeper集群搭建、Kafka Broker配置逐项拆解、集群验证、故障演练以及生产环境踩坑总结。适合刚接触Kafka、准备搭建自己集群的读者，也适合那些已经跑过单机版、想系统化理解Kafka集群工作机制的同学。

这篇的目标很简单：你按文章步骤操作完，能拿到一套可用的、扛得住常规故障的三节点Kafka集群，而且每个配置项你都明白为什么这么设，出了问题知道从哪里下手查。

1. 集群架构设计：为什么Kafka非得配ZooKeeper

1.1 ZooKeeper在Kafka里扮演的角色

很多人刚接触Kafka时第一个疑问就是：Kafka不是号称高吞吐、分布式的消息系统吗？怎么还要依赖ZooKeeper？

这里要先把角色理清楚。Kafka本身是一个分布式系统，Broker节点需要协调很多"集群级"的事情，比如：

• 每个Partition的Leader副本是谁、Follower副本在哪几台机器上；
• 某个Broker挂了，哪些Partition的Leader需要重新选举；
• 消费者组里的成员如何分配Partition，位移信息如何协调；
• 集群里有哪些Broker，元数据如何通知给所有客户端。

这些问题本质上是分布式一致性协调问题，Kafka在早期版本里并没有自己去实现一套共识机制，而是直接复用了ZooKeeper作为"分布式大脑"。ZooKeeper负责维护这些元数据，并通过自身的ZAB协议保证多节点之间数据一致。

提示：Kafka 3.x之后社区在推KRaft模式，逐步去ZooKeeper依赖。但截至我写这篇文章，生产环境里存量系统绝大多数还是ZooKeeper模式，而且KRaft本身也在持续演进。所以从ZooKeeper模式学起，对于理解Kafka的副本选举、消费者协调机制仍然是最直观的路径。

1.2 节点数量怎么定：三节点、五节点还是更多

ZooKeeper集群通常部署奇数个节点，原因在于ZAB协议需要"过半存活"才能选举出Leader并提供服务。三节点允许坏一台，五节点允许坏两台，七节点允许坏三台。从公式看，N个节点最多容忍(N-1)/2台故障。

Kafka本身在三节点规模下已经能满足绝大多数中小型业务的容灾需求：三台Broker，每个Topic设置3副本，任何一台宕机，剩下两台依然能选出一个新的Leader，数据不丢、服务不中断。如果只有两台Broker加2副本，坏一台就只剩一个副本，容灾能力其实和单副本差不多，风险很大。

我个人的建议是：测试环境用3台ZooKeeper+3台Kafka，或者干脆ZooKeeper和Kafka混合部署在三台机器上；生产环境如果资源充裕，ZooKeeper单独用3台，Kafka按流量横向扩展。节点数不一定要追求多，关键是每个节点的角色定位要清晰，别为了凑节点数而浪费资源。

1.3 部署拓扑：ZooKeeper与Kafka是否同机混部

这个问题在社区里争论比较多。同机混部的好处是省机器，坏处是故障域没有隔离——如果一台机器挂了，ZooKeeper和Kafka同时少一个节点。假如是三节点集群，一台宕机后ZooKeeper仍然能运行（三节点挂一个还有过半），但Kafka如果只有三个Broker且一个宕机，剩下两个Broker上的副本要承担全部流量，压力会明显上升。

如果资源紧张，同机混部完全可行，但要注意：

• 所有节点必须同时满足Kafka和ZooKeeper双重的资源需求；
• 避免在ZooKeeper所在节点再部署其他重负载服务；
• 混部时内存分配要有兜底，防止ZooKeeper OOM连带Kafka崩溃。

如果资源充足，更稳妥的做法是ZooKeeper用三台独立小规格机器（2C4G即可），Kafka用三台独立机器（按流量估算规格）。下面所有步骤我都按"三台机器，每台同时部署ZooKeeper和Kafka"的标准拓扑来写，这是最省资源、也最容易扩展的方案。

2. 环境准备：版本选型与机器资源规划

2.1 版本选型的两个关键教训

版本选型是搭建集群时最容易翻车的一步。我见过不少同学直接下载最新版，结果生态工具不兼容、配置语法变了，折腾一整天。选版本我只看两点：一是稳定性标签，二是生态兼容性。

以Kafka为例，2.8.0之前的版本是纯ZooKeeper架构，3.0~3.4之间是双模式过渡，3.5之后KRaft逐渐成熟。如果是新手或者生产环境求稳，我建议选Kafka 2.8.x或者3.3.x这种被大规模验证过的版本。本文的配置示例基于Kafka 3.3.2，配套ZooKeeper 3.8.1，这也是我当前在用的组合，实测稳定。

注意：不要用Kafka发布包里自带的zoo keeper脚本去搭多节点集群。那个是给单机快速测试用的，真正的集群配置还是要下载Apache ZooKeeper发行版，单独管理。

JDK方面，Kafka 2.8+官方要求JDK 8或JDK 11，ZooKeeper 3.8也支持JDK 8/11/17。我建议直接用JDK 8u202或JDK 11，避免过新的JDK版本带来的JVM垃圾回收行为差异。如果你系统里装了多个JDK，一定要确认JAVA_HOME指对了版本，这一步错了后面所有脚本都会莫名其妙报错。

2.2 JDK安装与系统参数调优

以CentOS 7.9或Ubuntu 20.04为例，先用yum或apt装好JDK，然后把下面这几行加到/etc/profile里：

bash复制export JAVA_HOME=/usr/local/jdk1.8.0_202
export PATH=$JAVA_HOME/bin:$PATH
export CLASSPATH=.:$JAVA_HOME/lib/dt.jar:$JAVA_HOME/lib/tools.jar

然后执行source /etc/profile，用java -version确认。JDK装好之后，有两项系统参数必须调，否则集群在流量上来后容易出问题：

• 文件描述符限制：Kafka和ZooKeeper都会打开大量socket和日志文件，默认1024肯定不够。在/etc/security/limits.conf里加上：

code复制* soft nofile 655350
* hard nofile 655350
* soft nproc  655350
* hard nproc  655350

• 最大虚拟内存映射数：有些系统默认max_map_count太小，会影响内存映射文件。执行：

bash复制sysctl -w vm.max_map_count=655360
echo 'vm.max_map_count=655360' >> /etc/sysctl.conf

这两项配置好之后建议重启机器或至少重新登录会话，确保生效。很多"Kafka一启动就报Too many open files"的坑，根源就在这里。

2.3 主机名、hosts与SSH免密配置

集群部署最忌讳用IP到处写死。我建议三台机器的主机名规划成：

code复制node1.example.com  192.168.10.11
node2.example.com  192.168.10.12
node3.example.com  192.168.10.13

修改hostname后，在每台机器的/etc/hosts里写入三行映射。这里有个重要细节：Kafka的advertised.listeners里如果配置的是主机名，那么所有客户端机器也必须能解析到这些主机名，否则客户端会一直报连接超时。跨机房部署时尤其要注意DNS解析问题。

SSH免密不是必须的，但如果接下来要批量分发配置、远程执行命令，免密能省下大量时间。生成密钥后，把公钥追加到三台机器的authorized_keys里，再用ssh node2.example.com这种形式验证。

2.4 防火墙与安全组策略

集群搭建过程中，防火墙配置是最容易被忽略的一环。我遇到过不少次"明明都配好了，客户端就是连不上"，最后发现是云安全组没放通端口。Kafka和ZooKeeper集群至少需要放通以下端口：

在CentOS上可以这样操作：

bash复制firewall-cmd --permanent --add-port=2181/tcp
firewall-cmd --permanent --add-port=2888/tcp
firewall-cmd --permanent --add-port=3888/tcp
firewall-cmd --permanent --add-port=9092/tcp
firewall-cmd --reload

如果是云主机，记得同步在安全组里配置。端口放通顺序别看轻了，我见过有人在本地裸机环境没问题，上云之后集群起不来，最后查了一圈就是安全组端口没放。

3. ZooKeeper集群搭建：从下载到myid的核心细节

3.1 目录规划与安装包准备

我习惯把软件统一装在/opt下，数据目录单独放到数据盘。以三台机器为例，每台机器执行：

bash复制mkdir -p /opt/zookeeper
mkdir -p /data/zookeeper/data
mkdir -p /data/zookeeper/logs

然后下载Apache ZooKeeper 3.8.1的二进制包，解压到/opt/zookeeper/。为了后续升级方便，我会再建一个软链：

bash复制tar -zxvf apache-zookeeper-3.8.1-bin.tar.gz -C /opt/zookeeper/
ln -s /opt/zookeeper/apache-zookeeper-3.8.1 /opt/zookeeper/current

注意ZooKeeper的bin包和src包的区别，一定要下-bin.tar.gz，src包还需要自行编译。这个细节踩过一次坑的人应该都懂。

3.2 zoo.cfg配置逐项拆解

ZooKeeper的配置文件在conf目录下，默认是zoo_sample.cfg，需要复制成zoo.cfg。我直接给出一份生产常用的配置：

code复制tickTime=2000
initLimit=10
syncLimit=5
dataDir=/data/zookeeper/data
dataLogDir=/data/zookeeper/logs
clientPort=2181
maxClientCnxns=200
server.1=node1.example.com:2888:3888
server.2=node2.example.com:2888:3888
server.3=node3.example.com:2888:3888
autopurge.snapRetainCount=5
autopurge.purgeInterval=24

逐项说下为什么这么设：

• tickTime=2000是ZooKeeper的最小时间单元，单位毫秒，心跳间隔是2个tick，也就是4秒；
• initLimit=10表示Follower启动时能和Leader完成数据同步的最大tick数，也就是20秒。网络环境差的机房可以适当调大，比如15；
• syncLimit=5表示Follower与Leader之间心跳响应的最大tick数，超过10秒没响应就会被认为死节点；
• clientPort=2181是客户端连接端口，Kafka的Broker就是通过这个端口连ZooKeeper的；
• maxClientCnxns=200是单台ZooKeeper允许的最大客户端连接数。如果Kafka集群很大，这个值要按Broker数乘以预期连接数去估算；
• server.X=host:2888:3888这一段是关键，X是节点编号，2888端口用于Follower与Leader之间的数据同步，3888端口用于Leader选举投票；
• autopurge配置是自动清理ZooKeeper的事务日志和快照，不清理的话，长时间运行后磁盘会被snapshot占满。

配置好zoo.cfg后，还有一件事容易漏：JVM堆内存。ZooKeeper默认堆内存偏小，大集群下频繁Full GC会很要命。可以在conf目录下新建一个java.env文件：

code复制export JVMFLAGS="-Xms2g -Xmx2g -XX:+UseG1GC -XX:MaxGCPauseMillis=200"

ZooKeeper本身管理的是元数据，2G堆对于日均几百万条消息的元数据量足够用了。堆内存不是越大越好，过大反而会造成GC暂停时间变长，这个度要把握好。

3.3 myid文件与启动顺序

ZooKeeper通过myid文件识别当前节点的身份，这个文件必须放在dataDir目录下，文件名就叫myid，内容是一个数字，与zoo.cfg里的server.X对应。

在三台机器上分别执行：

bash复制echo "1" > /data/zookeeper/data/myid   # node1
echo "2" > /data/zookeeper/data/myid   # node2
echo "3" > /data/zookeeper/data/myid   # node3

启动顺序上有个细节：如果三台全是新节点，第一次启动时最好尽量同时启动，因为ZooKeeper要凑够过半节点才能选出Leader。单台先启动时会一直处于LOOKING状态，让你误以为启动失败，其实它在等兄弟节点。我习惯用脚本在三台机器上几乎同时执行：

bash复制/opt/zookeeper/current/bin/zkServer.sh start

启动后立刻看日志，日志一般输出在zookeeper.out或者通过log4j配置的目录。如果看到"Leader election"相关日志，说明节点正在参与选举，正常。

3.4 用四字命令与JMX验证ZK集群状态

ZooKeeper自带一套四字命令，用于快速检查运行状态。可以直接用nc发送：

bash复制echo ruok | nc node1.example.com 2181
echo stat | nc node1.example.com 2181

ruok返回imok表示节点存活；stat会输出当前节点的角色（leader/follower）以及连接数、节点数等信息。我还会执行：

bash复制echo srvr | nc node3.example.com 2181

看三台机器的角色是否一主两从。如果发现某个节点还是独立模式（standalone），说明集群没有配对成功，多半是myid写错、端口不通或者hosts解析有问题，按这个顺序排查很快。

注意：ZooKeeper某些版本默认可能禁用了四字命令，需要在zoo.cfg里加4lw.commands.whitelist=*才能启用，这一步容易被忽略。

4. Kafka集群搭建与Broker配置逐项拆解

4.1 解压安装与目录约定

ZooKeeper集群就绪之后，开始搭Kafka。首先下载Kafka 3.3.2的二进制包，解压到/opt/kafka/，同样建软链：

bash复制mkdir -p /opt/kafka
tar -zxvf kafka_2.13-3.3.2.tgz -C /opt/kafka/
ln -s /opt/kafka/kafka_2.13-3.3.2 /opt/kafka/current
mkdir -p /data/kafka/logs

这里有个注意点：Kafka发布包里的"2.13"是Scala的编译版本，不是Kafka版本号。选Kafka版本时先确认是否和你的客户端、生态工具兼容，不要看到2.13就当成Kafka 2.13，这个误解我见得太多了。

4.2 server.properties关键配置逐项拆解

Kafka的配置文件在config/server.properties，集群模式下需要逐项修改。我直接给出一份三节点集群的配置模板，然后解释每个关键项：

code复制broker.id=1
listeners=PLAINTEXT://0.0.0.0:9092
advertised.listeners=PLAINTEXT://node1.example.com:9092
log.dirs=/data/kafka/logs
zookeeper.connect=node1.example.com:2181,node2.example.com:2181,node3.example.com:2181
num.network.threads=8
num.io.threads=16
socket.send.buffer.bytes=102400
socket.receive.buffer.bytes=102400
socket.request.max.bytes=104857600
log.retention.hours=168
log.segment.bytes=1073741824
log.retention.check.interval.ms=300000
auto.create.topics.enable=false
delete.topic.enable=true
num.partitions=3
default.replication.factor=3
min.insync.replicas=2
unclean.leader.election.enable=false

逐项拆解：

• broker.id：每个Broker的唯一标识，不能重复。三台机器分别设1、2、3；
• listeners：Broker对外监听地址，0.0.0.0表示监听所有网卡；
• advertised.listeners：这个是最容易踩坑的配置。它告诉客户端"你该连我哪个地址"，必须填客户端能访问到的地址。如果你填了localhost，那远程的消费者永远连不上Broker；如果你填了内网IP，客户端跨网段访问也会失败；
• zookeeper.connect：写全三个ZooKeeper节点地址，用逗号分隔，这样某个ZK节点挂了，Kafka还能连到其他ZK；
• log.dirs：日志数据目录，建议放到独立数据盘上，不要和系统盘挤在一起；
• num.network.threads和num.io.threads：网络线程和IO线程数，默认值偏保守。8核机器分别设8和16是性价比比较高的组合；
• log.retention.hours=168：消息默认保留7天。如果业务方有特殊诉求，比如保留30天，需要单独按Topic配置retention.ms；
• auto.create.topics.enable=false：强烈建议关掉自动创建Topic。生产环境里手误向不存在的Topic写数据，自动创建会瞬间产生一堆无意义的分区副本，后面清理起来很痛苦；
• min.insync.replicas=2：配合acks=all使用，保证至少两个副本写入成功才返回确认，这是防止消息丢失的关键配置；
• unclean.leader.election.enable=false：关闭"非同步副本参与Leader选举"。保持false才能避免在数据丢失场景下选出一个数据不全的Leader，这个参数在生产环境一定要设为false。

4.3 三台机器的差异化配置与启动

broker.id和advertised.listeners在每个节点上必须不一样。所以server.properties不能简单整份复制，建议在node2、node3上分别修改这两行，然后再启动：

bash复制/opt/kafka/current/bin/kafka-server-start.sh -daemon /opt/kafka/current/config/server.properties

启动后马上看日志，路径在log.dirs配置的目录，默认会生成server.log。如果出现"INFO [KafkaServer id=1] started"，就说明Broker启动成功。如果一直卡在"Connecting to zookeeper"，多半是zookeeper.connect填错、2181端口被防火墙拦了，或者ZooKeeper集群本身没形成过半健康状态。

这里我额外提醒一件事：Kafka启动脚本里默认的JVM堆内存是1G，生产环境一般不够。可以在bin/kafka-server-start.sh里修改KAFKA_HEAP_OPTS，比如设成-Xmx4g -Xms4g。堆内存大小取决于Topic数量、Partition总量和消息缓存需求，4G是常见起步值。

4.4 开启JMX端口，为可视化监控做准备

Kafka集群跑起来只是第一步，后面肯定要接监控。我习惯每台Broker都暴露JMX端口，方便接入Prometheus加Kafka Exporter，或者用JConsole等工具直接看。设置方式是在启动前导出环境变量：

bash复制export JMX_PORT=9999
export KAFKA_JMX_OPTS="-Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.ssl=false -Dcom.sun.management.jmxremote.port=9999"

把这两行加到/opt/kafka/current/bin/kafka-server-start.sh的开头，或者单独写进环境变量文件。之后再启动Broker，就能通过JMX端口采集到未消费消息数、请求处理耗时、网络线程池状态等核心指标。如果不想用命令行操作Kafka，也可以接Kafka UI或者Offset Explorer这类可视化工具，配合JMX端口就能把集群状态看得明明白白。

5. 集群验证、Topic操作与故障演练

5.1 创建Topic并确认副本分布

Kafka集群跑通后，第一步是创建一个三副本的Topic，验证ZooKeeper和Broker之间的元数据协调是否正常：

bash复制/opt/kafka/current/bin/kafka-topics.sh --create --topic test-topic --partitions 3 --replication-factor 3 --bootstrap-server node1.example.com:9092

注意新版本Kafka推荐用--bootstrap-server代替旧的--zookeeper参数。创建成功后，用describe命令看分区和副本分布：

bash复制/opt/kafka/current/bin/kafka-topics.sh --describe --topic test-topic --bootstrap-server node1.example.com:9092

输出里会显示每个分区的Leader、Replicas、Isr。如果你的Topic显示3个分区，每个分区有3个副本，并且ISR列表都是满的，说明集群副本同步是健康的。如果ISR里少了副本，多半是某个Broker负载过高、网络抖动或者磁盘写满导致副本落后，需要结合Broker日志进一步排查。

5.2 生产消费验证

Topic创建好之后，用Kafka自带的console脚本做一次端到端验证。开一个终端启动消费者：

bash复制/opt/kafka/current/bin/kafka-console-consumer.sh --topic test-topic --from-beginning --bootstrap-server node1.example.com:9092

再开一个终端启动生产者，随便输入几条消息：

bash复制/opt/kafka/current/bin/kafka-console-producer.sh --topic test-topic --bootstrap-server node1.example.com:9092
>hello kafka cluster
>message from node1

消费者终端能实时看到消息，就说明整个链路通了。这一步验证完，再顺手测试一下消息延迟：生产端输入一条消息，消费者端打印接收时间，正常同机房内延迟应该在毫秒级。如果延迟持续偏高，优先检查网络、磁盘IO和GC。

5.3 故障演练：杀掉一个Broker看集群表现

集群搭建完，不做故障演练等于没搭。我强烈建议在测试环境模拟一次Broker宕机，看看集群到底能不能自愈。三节点集群里，直接kill掉node1上的Kafka进程：

bash复制kill -9 $(pgrep -f kafka.Kafka)

然后在node2上执行：

bash复制/opt/kafka/current/bin/kafka-topics.sh --describe --topic test-topic --bootstrap-server node2.example.com:9092

正常情况下你会发现，原来node1上的Leader分区被重新选举到了node2或node3，ISR列表里少了node1，但其余副本仍然同步。只要消息生产消费还在继续，就说明集群发生了正常的故障转移。

提示：kill -9在线上要慎用。更好的做法是kill（默认SIGTERM），让Broker优雅停机，先把Leader角色移交给其他节点再退出。这个差异在规模大的集群里尤其明显，优雅停机可以把不可用时间压缩到秒级以内。

5.4 离线安装场景的补充说明

如果你的环境是内网隔离的，没法访问外网下载安装包，就需要走离线安装。核心思路是先在能联网的机器上下载好JDK、ZooKeeper、Kafka的二进制包，用scp或内部镜像源分发到所有节点，然后按同样的步骤解压、配置、启动。唯一要注意的是离线环境下的依赖工具，比如nc、telnet等排查工具要提前装好，不然真出问题时手里连个排查工具都没有。Kafka集群离线安装其实不复杂，关键是提前把安装包和依赖梳理清楚。

6. 生产环境避坑指南与压测建议

6.1 那些"配置落盘"之外的脏活累活

把集群搭起来只是开始，真正考验人的是后面一系列看不见的细节。我按踩坑频率从高到低列几个典型问题：

• 时钟不同步：Kafka是分布式系统，对时间戳敏感。三台机器时间偏差过大会导致日志错乱、监控数据失真。建议部署NTP或chrony同步，偏差控制在几十毫秒内；
• 磁盘选择：Kafka重度依赖磁盘顺序写，机械盘和SSD的吞吐差距是数量级的。生产环境至少要给Kafka配SSD，并且用独立数据盘，不要和系统盘共用；
• 数据盘写满：这是生产事故高发区。Kafka不会因为数据盘写满自动清数据，只会一直报错并拒绝服务。建议配置磁盘使用率告警，预留20%以上余量；
• 文件描述符和网络连接数：很多"莫名其妙"的异常，查到最后都是这两个系统参数没调。上面第2.2节提过的limits配置，建议所有集群节点统一执行。

6.2 常见故障及排查链路

我再整理一个高频故障排查表，方便你遇到问题时对照着查。以下每一条都是我在真实环境中反复遇到过的，背后都有具体场景，不是凭空列出来的。

6.3 生产者和消费者端的连接配置

搭建完集群后，业务侧的配置同样关键，否则集群能力再好也白搭。生产端我建议至少设置：

code复制acks=all
retries=3
enable.idempotence=true
max.in.flight.requests.per.connection=5

消费端建议设置：

code复制enable.auto.commit=false
auto.offset.reset=earliest

enable.idempotence配合acks=all，可以做到消息不丢不重；消费端关掉自动提交，改为业务处理成功后再手动提交位移，这是数据一致性的底线。很多人集群搭得没问题，但业务上还是丢消息，一查八成是消费端自动提交位移、业务还没处理完就提交了。

6.4 压测与容量评估的粗浅经验

最后聊一下压测。搭建完集群，不要急着上线，先用Kafka自带的性能测试工具跑一轮：

bash复制/opt/kafka/current/bin/kafka-producer-perf-test.sh \
  --topic perf-topic \
  --num-records 1000000 \
  --record-size 1024 \
  --throughput 20000 \
  --producer-props bootstrap.servers=node1.example.com:9092 acks=all

/opt/kafka/current/bin/kafka-consumer-perf-test.sh \
  --bootstrap-server node1.example.com:9092 \
  --topic perf-topic \
  --messages 1000000

压测跑完，能拿到单Broker的吞吐上限，然后根据业务预估的QPS和单条消息大小，反推出需要几个分区、几台Broker。这里有个经验值：分区数不是越多越好，过多的分区会带来