ZooKeeper分布式集群搭建实战：从设计原理到高可用部署

做了这么多年大数据和分布式系统，ZooKeeper 是无论如何都绕不开的一个组件。但凡你接触过 Kafka、Hadoop、HBase、Dubbo、分布式锁、配置中心，底层基本都有 ZK 的身影。很多朋友照着教程在单机上跑通了 zookeeper 的伪集群，就以为自己会了，结果一到生产环境或者面试问起集群细节，当场露怯。这篇文章我打算把 ZooKeeper 分布式集群搭建这件事从设计原理到实操步骤完整过一遍，包括节点规划、配置项解释、启动验证、故障排查，最后再聊聊它和 Kafka、Hadoop 整合时候的注意点。不管你是刚入门准备搭一套测试环境，还是要在生产环境部署高可用集群，这篇都应该能帮到你。

先交代一下背景。我之前在团队里负责过好几套大数据基础组件的搭建和运维，从 Hadoop 集群、Kafka 集群到 Spark 集群，底层清一色都挂了 ZK。第一次搭的时候也踩了不少坑，比如配置项写错导致集群一直选举不出来 leader，比如 myid 和节点不匹配导致数据同步异常，比如把 dataDir 和 dataLogDir 放同一块磁盘结果 IO 被打爆。这些经验我都会在这篇里写清楚，让你少走弯路。

1. 为什么要搭 ZK 集群，单机到底差在哪

很多人最开始接触 ZooKeeper 都是在单机模式下解压个包，跑个zkServer.sh start，然后用命令行连上去 create 几个节点，觉得这玩意儿不就是个树形结构的存储吗？没毛病，单机模式确实是这么个功能，但如果你把单机 ZK 用到生产环境，后果基本就是灾难。

单机 ZK 最大的问题在于它是单点。一旦这台机器宕机或者网络出问题，所有依赖它的服务全部瘫痪。举几个实际场景，Kafka 的 controller 选举和 broker 元数据管理依赖 ZK，如果 ZK 挂了，整个 Kafka 集群不可用；HBase 的 HMaster 选举也依赖 ZK，ZK 挂了 HBase 基本就废了；业务系统里的分布式锁如果挂在单机 ZK 上，那 ZK 一挂，所有抢锁的请求全部阻塞或者报错，数据一致性直接没法保证。

所以生产环境的 ZK 必须是集群，而且是有高可用设计的集群。ZK 集群采取的是 leader-follower 模式，集群中会通过选举产生一个 leader，其他节点是 follower，所有的写请求都会转发给 leader 处理，leader 会将事务同步给大多数节点后才算提交成功。这个机制的基础就是 Zab 协议，也是 ZK 保证数据一致性的关键。

这里我多说一句为什么集群节点数必须是奇数，通常推荐 3 台、5 台、7 台。因为 ZK 有一个核心概念叫 quorum，也就是法定人数，公式是quorum = N/2 + 1，N 是集群总节点数。写请求只有在同步到 quorum 个节点后才会返回成功，选举 leader 也需要超过半数的节点参与才能选出结果。3 台机器的集群允许挂 1 台，5 台允许挂 2 台，7 台允许挂 3 台。你要是搭了 4 台，能容忍挂掉的也是 1 台，跟 3 台的效果一样，却多花钱多维护一个节点，纯属浪费。

再补充一个容易忽略的细节：ZK 集群中其实还有一种角色叫 observer，observer 不参与投票，只同步数据，用来扩展读性能。生产中某些大集群会引入 observer 节点，但常规场景下我们讨论的都是 leader + follower 模式。

2. 搭建前的环境规划和设计思路

动手之前先把环境和规划搞清楚，不然搭到一半发现服务器不够用或者端口冲突就尴尬了。我下面给的这套方案是我自己在测试环境和生产环境都用过的，按照这个规划基本不会出大问题。

2.1 服务器与版本选型

ZK 集群对服务器的要求不算苛刻，生产环境建议至少 2 核 4G 内存，磁盘 50G 以上预留，系统用 CentOS 7 或者 Ubuntu 18.04 及以上都可以。需要注意部署大数据生态组件时，服务器之间时间校准尽量用 NTP 保持同步，ZK 的事务处理对时间漂移容忍度不高，时间差过大会出现奇怪的问题。

版本选择方面，ZK 目前主流是 3.6.x 和 3.7.x 系列，3.8 和 3.9 也已经出现了。我个人的建议是生产环境优先选择 Apache ZooKeeper 3.6.3 及以上版本的稳定分支，比如 3.6.4、3.7.1，别追最新版本，稳定优先。CDH、HDP 这些发行版自带的 ZK 版本通常比较旧，如果你用的是纯 Apache 生态，用官方 release 包就行。下载的时候注意别下到 source 包，要下 bin.tar.gz 结尾的二进制包。

还有一个关键点是 JDK 环境。ZK 是用 Java 写的，运行依赖 JDK。ZK 3.5 以上版本要求 JDK 8 或 JDK 11，我用的是 JDK 8，最稳妥。安装 JDK 时记得配好JAVA_HOME环境变量，ZK 启动脚本会用到，不配置的话会直接报找不到 Java。

2.2 节点规划与端口说明

我这里以 3 节点集群为例，因为这是最低配也是大多数人能拿到的资源。三台服务器我习惯用 192.168.100.31、192.168.100.32、192.168.100.33，主机名分别设置成 zk01、zk02、zk03。

每台 ZK 节点对外要开放三个端口，这仨端口分别对应不同的用途，很多人配置的时候搞混过：

生产环境多台服务器之间如果有防火墙，除了 2181 要对你自己的业务网段开放，2888 和 3888 必须在 ZK 集群内部互相放通，否则集群建立不起来。我见过一个小伙伴搞了半天集群起不来，就是这三台机器之间的 3888 端口被防火墙拦了，日志里一直在刷 reconnection，排查到这个原因的时候恨不得拍自己脑门。

2.3 配置 ZooKeeper 的 zoo.cfg

配置文件在$ZK_HOME/conf/zoo.cfg，初始状态下目录里只有一个zoo_sample.cfg，你需要复制一份再改：

cp $ZK_HOME/conf/zoo_sample.cfg $ZK_HOME/conf/zoo.cfg

我常用的三节点最小配置如下，每个配置项的作用我下面逐条解释：

tickTime=2000 initLimit=10 syncLimit=5 dataDir=/data/zookeeper/data dataLogDir=/data/zookeeper/logs clientPort=2181 maxClientCnxns=60 autopurge.snapRetainCount=3 autopurge.purgeInterval=1 server.1=192.168.100.31:2888:3888 server.2=192.168.100.32:2888:3888 server.3=192.168.100.33:2888:3888

这些配置项里，tickTime是 ZK 的最小时间单位，单位是毫秒，默认 2000，也就是 2 秒。initLimit表示 follower 启动后与 leader 完成数据同步的最大时间，单位是 tickTime 的倍数，10 就是允许 20 秒。如果集群里节点多、数据量大，或者网络延迟高，这个值可以适当调大，不然 follower 启动时会一直起不来报错。syncLimit是 follower 与 leader 之间心跳检测的超时时间，同样是 tickTime 的倍数，5 就是 10 秒。如果你的网络环境不太好，这个值建议从 5 调到 8 或者 10。

dataDir和dataLogDir是我特别要注意提醒的。这两个路径可以指向同一块磁盘，但生产环境强烈建议分开。因为 ZK 的 dataLogDir 存放事务日志，写入非常频繁，而起快照的 dataDir 是定期生成文件。如果都放在同一块普通机械盘上，事务日志的大量小 IO 会拖垮系统。测试环境无所谓，生产环境有条件的话给 dataLogDir 配一块 SSD。

autopurge.snapRetainCount和autopurge.purgeInterval是控制快照和事务日志自动清理的。默认情况下 ZK 不会自动清理 dataDir 里的快照文件，时间长了磁盘会被撑爆，这也是一个经典的运维事故。autopurge.snapRetainCount=3表示保留最近 3 个快照，autopurge.purgeInterval=1表示每 1 小时执行一次清理。这两项一定要配好，别偷懒，不然以后磁盘满了有你受的。

2.4 创建 myid 文件

ZooKeeper 集群是靠 myid 来区分集群中每个节点的身份，myid 必须是一个正整数，并且要和zoo.cfg中server.N里的 N 一一对应。

比如说server.1=192.168.100.31:2888:3888这条配置，那么 IP 为 192.168.100.31 的那台机器，它的dataDir目录下就必须有一个文件叫myid，文件内容为数字 1。同理，192.168.100.32 的机器 myid 是 2，192.168.100.33 的机器 myid 是 3。

命令如下，在三台机器上分别执行：

# zk01 节点 echo "1" > /data/zookeeper/data/myid # zk02 节点 echo "2" > /data/zookeeper/data/myid # zk03 节点 echo "3" > /data/zookeeper/data/myid

这里千万注意，myid 文件是在每台机器上单独配置的，不是把三个数字都写上。有些新手会犯一个错误，在三台机器的 myid 文件里都写了 1、2、3，结果所有节点都以为自己是 1，集群直接乱套。还有个易错点是 myid 文件内容有特殊字符或者换行符，建议用echo "1"这种方式生成，不要用 Windows 记事本去编辑，否则可能有格式问题。

2.5 关闭本机防火墙或配置放通规则

这一步虽然是环境层面的，但特别关键。我这里分情况说，如果你的服务器是云主机，安全组规则里需要放通 2181、2888、3888 三个端口。如果是物理机或虚拟机，先看看防火墙状态：

systemctl status firewalld

如果启发式，可以直接关掉，或者放行这三个端口。我之前排障的时候经常看到 ZK 启动正常但选举不成功，最后发现就是 3888 端口没放行。

3. 一步一步搭建集群，全程实操记录

规划做完了，接下来就是动手环节。我把完整的搭建过程拆成几个步骤，每一步都附上命令和验证方法，你跟着操作基本一遍过。

3.1 安装 JDK 并配置环境变量

如果你的机器上还没有 JDK，这一步不能跳过。我用的是 JDK 8，这块直接给大家一个标准流程：

# 解压 JDK 到 /usr/local/java tar -zxvf jdk-8u202-linux-x64.tar.gz -C /usr/local/java # 配置环境变量 cat >> /etc/profile << 'EOF' export JAVA_HOME=/usr/local/java/jdk1.8.0_202 export PATH=$PATH:$JAVA_HOME/bin EOF source /etc/profile java -version

三台机器都要装，千万别只装一台。ZK 的启动脚本是通过JAVA_HOME找到 Java 的，如果这个变量没配置对，启动时候会报错JAVA_HOME is not set and java could not be found in PATH。

3.2 下载解压 ZooKeeper

三台机器都执行下面的操作：

# 下载 zookeeper 二进制包，版本按你自己需求选择 wget https://dlcdn.apache.org/zookeeper/zookeeper-3.7.2/apache-zookeeper-3.7.2-bin.tar.gz # 解压到 /opt 目录 tar -zxvf apache-zookeeper-3.7.2-bin.tar.gz -C /opt # 重命名一下，方便管理 mv /opt/apache-zookeeper-3.7.2-bin /opt/zookeeper

然后把ZK_HOME配到环境变量里：

cat >> /etc/profile << 'EOF' export ZOOKEEPER_HOME=/opt/zookeeper export PATH=$PATH:$ZOOKEEPER_HOME/bin EOF source /etc/profile

这里需要提醒一下，务必下载-bin.tar.gz结尾的文件。之前有人下载了apache-zookeeper-3.7.2.tar.gz，结果里面是一堆源码，没有 bin 目录和 jar 包，后面执行不了脚本。

3.3 修改 zoo.cfg 并创建相关目录

在三台机器上分别执行：

mkdir -p /data/zookeeper/data mkdir -p /data/zookeeper/logs

然后把zoo.cfg文件里三台机器的server.N都写上。这里注意一点：zoo.cfg的内容在三台机器上除了myid不同之外，其他内容应该一样，server.1、server.2、server.3这三条配置要在每台机器都写全。

3.4 启动集群与常见启动顺序

ZooKeeper 集群没有严格的启动顺序，但我的习惯是先启动 myid 为 1 和 2 的节点，再启动 myid 为 3 的节点。原因是前两个节点先起来后，它们之间可以进行 leader 选举，第三个节点加入时就能快速同步数据。

启动命令很简单：

# 每台机器上执行 /opt/zookeeper/bin/zkServer.sh start

启动完成后，用下面的命令查看状态：

/opt/zookeeper/bin/zkServer.sh status

正常情况下输出应该是这样的：

ZooKeeper JMX enabled by default Using config: /opt/zookeeper/bin/../conf/zoo.cfg Client port found: 2181. Client address: localhost. Mode: follower

或者：

Mode: leader

关于结果里的模式，我再详细说一下。3 节点集群里会有一个节点是 leader，另外两个节点是 follower。如果你执行 status 的时候看到全部都是 standalone 模式，这说明你启动的其实不是集群模式，大概率是配置文件没生效或者 myid 配置有问题。standalone 模式在 3 台机器上各自独立，没有任何关系，这必须要排查。

另外，检查进程一定要用jps，不要用ps -ef | grep java来替代，jps是 JDK 自带的工具，会输出当前节点上的 Java 进程名。启动成功之后，你应该能在进程列表里看到 QuorumPeerMain 这个进程。这才是 ZK 服务的主进程。

jps # 输出示例 2186 QuorumPeerMain 2245 Jps

3.5 使用客户端连接验证

在任意一台机器上，用 ZK 自带的客户端连接集群：

/opt/zookeeper/bin/zkCli.sh -server 192.168.100.31:2181,192.168.100.32:2181,192.168.100.33:2181

连接成功后会进入[zk: 192.168.100.31:2181(CONNECTED) 0]这样的交互界面。这代表你已经连上了集群，注意 CONNECTED 状态是正常，如果你看到 CONNECTING 或者超时，就说明网络或者系统状态有问题。

接下来可以随便创建和读取一个节点测试：

create /test_node "hello" get /test_node

能正常 get 出值，说明整个集群链路是通的。这时候你可以试试停掉当前连接的这台机器上的 ZK 服务，然后再次 get 这个节点，正常情况下服务依然可用，这就是集群高可用的最直接体现。

4. 启动验证与集群监控，四字命令要会用

集群起来只是第一步，后面怎么确认它一直健康，或者怎么快速定位问题，才是日常运维的核心。

4.1 四字命令与常用监控命令

ZooKeeper 提供了一批四字命令用于查看集群状态，使用方式是通过nc或者直接echo加回车向 2181 端口发指令。我这里列几个最常用的：

使用前确保 2181 端口可以访问，然后在服务器上执行：

echo ruok | nc 192.168.100.31 2181

如果输出imok，说明当前 ZK 进程正常。不过ruok只反映进程存活，不代表服务总体健康。我更推荐用mntr来监控，它输出的指标比较多：

echo mntr | nc 192.168.100.31 2181

输出示例：

zk_version 3.7.2 zk_avg_latency 1 zk_max_latency 85 zk_min_latency 0 zk_packets_received 5892 zk_packets_sent 5941 zk_num_alive_connections 6 zk_outstanding_requests 0 zk_server_state leader zk_znode_count 128

生产环境可以写一个定时脚本，每分钟抓一次mntr输出，把zk_server_state、zk_znode_count、zk_num_alive_connections、zk_outstanding_requests这几个指标送到监控平台。outstanding_requests这个指标如果持续上涨，代表请求堆积了，需要重点关注。

4.2 如何快速判断集群是否健康

我发现很多人只看每个节点的进程状态，其实这是不够的。判断一个 ZK 集群是否健康，至少要同时满足这几点：

第一，三台机器上zkServer.sh status都能看到明确的模式，一个 leader 两个 follower，没有独立的 standalone。第二，任意一个节点上面echo ruok | nc localhost 2181都返回 imok。第三，通过客户端可以在任意节点上读写数据，且数据能保持一致。第四，观察日志里没有大量的连接断开、重新连接的异常刷屏。

第四点容易被忽略。有时候节点进程还在，但是由于网络抖动或者内存问题，它一直在后台反复重连，日志疯狂滚动。这种状态表面看没什么，但一旦 leader 出问题，这些节点根本无法参与选举，整个集群基本算是瘫痪了。建议时不时看一眼$ZOOKEEPER_HOME/bin/../logs/zookeeper.out里的日志，尤其是 ERROR 和 WARN 级别的内容。

另外，日志也是监控里重要的一环，ZooKeeper 默认日志输出在$ZOOKEEPER_HOME/bin/../logs/zookeeper.out，当然这个路径可以通过配置 log4j.properties 自定义。如果你发现日志里有Exception: Address already in use，说明端口被占用了，8080 端口被占用是 ZK 3.5 之后的常见坑，因为 ZK 自带的 Admin Server 默认会绑定 8080 端口，如果服务器上恰好有其他应用占用 8080，ZK 启动时会报错。解决办法是在zoo.cfg里加上一行：

admin.enableServer=false

或者改成别的端口。

4.3 优雅停机和维护操作

日常维护中难免要重启节点，ZooKeeper 提供优雅停止的命令：

/opt/zookeeper/bin/zkServer.sh stop

优雅停止时，这个节点会先尝试把当前 leader 身份交接掉，尽量不影响外部服务。如果实在等不及，也可以直接 kill 进程，但若非必要不要这么暴力，因为强行 kill 可能触发不必要的 leader 重选，在极端情况下可能导致短时不可用。

另外，千万不要在集群运行的时候直接去修改zoo.cfg里的server.N配置，然后单独重启一台机器。ZK 集群对节点列表的变化很敏感，正确做法是滚动变更：先停一台，改完配置再启动，确认这台正常之后，再操作下一台。如果一次性把三台的配置全改了再逐个启动，可能出现新旧配置冲突，集群选举都起不来。

5. 常见问题与排查技巧实录

这部分是本篇的精华，我把这几年来在 ZK 集群上踩过的坑和帮别人排查过的问题整理成一个速查表，方便你直接对照。

5.1 问题速查表

5.2 一次真实的 leader 选举异常排查

讲一个我实际遇到的案例。当时是一个测试环境，三台机器突然全部变成 LOOKING 状态，整个 Kafka 集群直接不可用。我先检查了网络和防火墙，发现都没问题，端口也能正常连通。再看日志，发现三台机器都在选举，但始终没有人当选 leader。

后来我把三台机器上zoo.cfg全部拿出来对比，发现其中一台的配置里server.3=192.168.100.33:2888:3888的端口写成了2888:2888，这就导致它作为服务器节点参与选举时，通信端口跟别人对不上。纠正之后重启，集群秒级选出 leader，服务恢复正常。

这个案例告诉我们，配置一定是集群中最大的无声杀手，且配置文件最好通过配置管理工具统一分发，不要手工逐个编辑。即便手工编辑，也需要用diff命令逐台比对。

5.3 时间同步问题值得花篇幅说

热词里正好有关于 “vsan 集群警报主机和 vc 之间的时间已同步” 的问题，其实 ZK 集群对时间同步也是相当敏感的。虽然 ZK 的事务是通过 zxid 来保证顺序的，但节点之间心跳检测、会话超时都依赖于相对稳定的时间。如果机器时间差超过几秒，很可能出现莫名其妙的 follower 频繁掉线，leader 反复切换。

所以生产环境建议所有 ZK 节点都用 NTP 或者 chrony 同步时间。测试环境如果没搭 NTP 服务器，至少确保每台机器和互联网时间源同步，别让集群内的时间偏差太大。我见过一个案例，某台虚拟机宿主机休眠恢复后时间慢了 5 分钟，结果那台 ZK follower 每次启动都会超时退出，折腾了很长时间才发现是时间问题。

6. 与 Kafka、Hadoop 等生态的整合要点

热词里出现了大量 ”kafka集群安装“、”hadoop和zookeeper整合实战“、”分布式锁“、”定时任务重复执行“ 这些内容，说明很多人搭 ZK 集群最终都是为了给上层组件服务，所以最后这部分我聊聊整合时候的实践经验。

6.1 Kafka 使用 ZK 的注意点

Kafka 在 2.8 之前依赖 ZK 做 broker 注册、controller 选举和 topic 元数据管理。搭 Kafka 集群时，需要在config/server.properties里配置连接地址，例如：

zookeeper.connect=192.168.100.31:2181,192.168.100.32:2181,192.168.100.33:2181/kafka

注意这个/kafka是 ZK 上的一个 chroot 命名空间，意思就是 Kafka 所有元数据都写在 ZK 的 /kafka 节点下。这个设计能让你一套 ZK 集群同时给 Kafka、HBase、业务系统共用而互不干扰。这一点在生产环境非常好用，比如同一套 ZK 集群既给 Kafka 用，又给分布式锁用，只要把 chroot 路径分开就行。

Kafka 对 ZK 的连接数量要求比较高，如果 2181 端口上zk_num_alive_connections很高，注意调高maxClientCnxns，否则 Kafka 节点多了之后会触发连接数限制。

6.2 Hadoop HA 与 ZK 整合

Hadoop 的 NameNode 高可用部署方案里，ZK 承担了故障自动转移和 active NameNode 选举的角色。在hdfs-site.xml中需要配置：

<property> <name>ha.zookeeper.quorum</name> <value>192.168.100.31:2181,192.168.100.32:2181,192.168.100.33:2181</value> </property>

这种情况下，如果 ZK 集群出了故障，NameNode 自动故障转移也会失效，所以 Hadoop 集群的可用性直接依赖 ZK 集群的可用性。多个组件共用一套 ZK 时，一定要提前规划好容量和连接数，别把鸡蛋全放在一个篮子里还不管。

6.3 基于 ZK 的分布式锁实践

热词里有大量关于 redis 分布式锁、定时任务重复执行的问题，其实 ZooKeeper 同样可以实现分布式锁，而且基于 ZK 的锁在安全和公平性上表现更好。常见的方式是使用临时顺序节点，先创建/lock/lock_节点，通过节点序号判断自己是否最小，最小的获得了锁，然后其它客户端监听前一个节点，当前一个节点删除时重新尝试获取。

实现上可以直接用 Curator 框架，里面封装了分布式锁，不需要你手写这些底层逻辑：

InterProcessMutex lock = new InterProcessMutex(client, "/locks/order_create"); if (lock.acquire(10, TimeUnit.SECONDS)) { try { // 业务逻辑，保证只有一个实例在跑 doProcess(); } finally { lock.release(); } }

这种锁的好处在于，当持有锁的客户端连接断开时，ZK 会自动删除对应的临时节点，锁自然释放，不会出现 Redis 锁里的死锁和过期时间设置难题。这也是为什么很多云原生组件和中间件更倾向于用 ZK 做分布式协调的原因。

ZK 在这个场景下的核心价值是高可用协调，而不是存储大数据。把它理解成分布式系统的"神经中枢"就对了，数据能小则小，节点能短则短，别把无关的大对象往 ZK 里塞。

7. 运维经验总结，最后再分享几个细节

关于 ZK 的深入调优和源码分析能写的东西还有很多，但工程应用里，把本篇讲到的搭建和运维细节都做到位，已经足够支撑你维护一套生产可用的集群了。

有几个点我在实践中印象最深，最后再提一下：第一，配置文件一定不能靠手工在每台机器上敲，容易出错，用脚本分发或者 ansible 统一管理最稳妥。我后来帮团队搭新环境直接用脚本跑，三台机器一键初始化，再也没出过配置不一致的事故。第二，JVM 参数值得关注。默认堆内存有时偏小，如果 ZK 节点数上百万级，建议在zkServer.sh里把ZOO_JVM_OPTS中的堆设置调大一些，比如-Xmx2g -Xms2g，然后观察 Full GC 次数，尤其是在节点多、连接数大的环境下。第三，没事不要手动重启 ZK，更不要同时重启多台，真需要重启就用优雅停止，逐台操作，等一台稳定再处理下一台。

希望这篇能帮你把 ZK 集群从“能跑”推进到“能扛事”这一步。如果你按上面的步骤搭完还有问题，欢迎按问题现象对应到速查表逐项排查，大部分情况都能找到答案。