做了这么多年大数据和分布式系统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 选举也依赖 ZKZK 挂了 HBase 基本就废了业务系统里的分布式锁如果挂在单机 ZK 上那 ZK 一挂所有抢锁的请求全部阻塞或者报错数据一致性直接没法保证。所以生产环境的 ZK 必须是集群而且是有高可用设计的集群。ZK 集群采取的是 leader-follower 模式集群中会通过选举产生一个 leader其他节点是 follower所有的写请求都会转发给 leader 处理leader 会将事务同步给大多数节点后才算提交成功。这个机制的基础就是 Zab 协议也是 ZK 保证数据一致性的关键。这里我多说一句为什么集群节点数必须是奇数通常推荐 3 台、5 台、7 台。因为 ZK 有一个核心概念叫 quorum也就是法定人数公式是quorum N/2 1N 是集群总节点数。写请求只有在同步到 quorum 个节点后才会返回成功选举 leader 也需要超过半数的节点参与才能选出结果。3 台机器的集群允许挂 1 台5 台允许挂 2 台7 台允许挂 3 台。你要是搭了 4 台能容忍挂掉的也是 1 台跟 3 台的效果一样却多花钱多维护一个节点纯属浪费。再补充一个容易忽略的细节ZK 集群中其实还有一种角色叫 observerobserver 不参与投票只同步数据用来扩展读性能。生产中某些大集群会引入 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 节点对外要开放三个端口这仨端口分别对应不同的用途很多人配置的时候搞混过端口类型默认端口用途clientPort2181客户端连接端口应用Kafka、业务服务通过这个端口连 ZK集群通信端口2888follower 与 leader 之间同步数据的端口选举通信端口3888leader 选举时节点间通信的端口生产环境多台服务器之间如果有防火墙除了 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我常用的三节点最小配置如下每个配置项的作用我下面逐条解释tickTime2000 initLimit10 syncLimit5 dataDir/data/zookeeper/data dataLogDir/data/zookeeper/logs clientPort2181 maxClientCnxns60 autopurge.snapRetainCount3 autopurge.purgeInterval1 server.1192.168.100.31:2888:3888 server.2192.168.100.32:2888:3888 server.3192.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.snapRetainCount3表示保留最近 3 个快照autopurge.purgeInterval1表示每 1 小时执行一次清理。这两项一定要配好别偷懒不然以后磁盘满了有你受的。2.4 创建 myid 文件ZooKeeper 集群是靠 myid 来区分集群中每个节点的身份myid 必须是一个正整数并且要和zoo.cfg中server.N里的 N 一一对应。比如说server.1192.168.100.31:2888:3888这条配置那么 IP 为 192.168.100.31 的那台机器它的dataDir目录下就必须有一个文件叫myid文件内容为数字 1。同理192.168.100.32 的机器 myid 是 2192.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 Jps3.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 端口发指令。我这里列几个最常用的命令作用示例输出说明ruok检查 ZooKeeper 是否健康如果返回 imok表示正常stat查看节点角色、连接数、延迟等信息会包含 Mode: leader/followersrvr查看节点服务端详细信息包含 zxid、mode、延迟等mntr查看监控指标用于接入监控系统输出一堆键值对适合 Prometheus 采集wchs查看 watch 信息会输出 watch 数量cons查看当前客户端连接详情能看到每个连接的 IP、端口、队列信息使用前确保 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 端口如果服务器上恰好有其他应用占用 8080ZK 启动时会报错。解决办法是在zoo.cfg里加上一行admin.enableServerfalse或者改成别的端口。4.3 优雅停机和维护操作日常维护中难免要重启节点ZooKeeper 提供优雅停止的命令/opt/zookeeper/bin/zkServer.sh stop优雅停止时这个节点会先尝试把当前 leader 身份交接掉尽量不影响外部服务。如果实在等不及也可以直接 kill 进程但若非必要不要这么暴力因为强行 kill 可能触发不必要的 leader 重选在极端情况下可能导致短时不可用。另外千万不要在集群运行的时候直接去修改zoo.cfg里的server.N配置然后单独重启一台机器。ZK 集群对节点列表的变化很敏感正确做法是滚动变更先停一台改完配置再启动确认这台正常之后再操作下一台。如果一次性把三台的配置全改了再逐个启动可能出现新旧配置冲突集群选举都起不来。5. 常见问题与排查技巧实录这部分是本篇的精华我把这几年来在 ZK 集群上踩过的坑和帮别人排查过的问题整理成一个速查表方便你直接对照。5.1 问题速查表现象可能原因排查方法 / 解决方案启动报IOException: Address already in use端口被占用常见的是 8080 被 Admin Server 占用netstat -tlnpstatus 显示Error contacting service. It is probably not running.进程未正常启动或者端口没监听查看日志确认具体错误jps看进程ss -lntp看端口三台机器都显示 standalone集群配置没生效多半是zoo.cfg没复制对或者 myid 文件内容不对逐台检查zoo.cfg中 server.N 是否都写了三行检查 myid日志中大量Cannot open channel to X at election address3888 选举端口不通检查防火墙和安全组telnet 测试端口连通性某个节点一直是 LOOKING进不了 leader/follower选举失败常见原因是网络分区或配置不一致检查zoo.cfg中 server.N 的 IP 是否可互访时间是否同步客户端连接报Session closed连接数满或 ZK 主动关闭空闲会话调整 maxClientCnxns客户端侧增加重试机制集群可用但写操作报connectionloss多数派节点不可用导致写请求无法提交检查各节点状态quorum 是否满足磁盘被快照文件占满没有开启自动清理或者清理周期太长配置 autopurge.snapRetainCount 和 autopurge.purgeInterval客户端连接超时延迟一直上升事务日志目录 IO 性能差把 dataLogDir 放到 SSD避免和 dataDir 混用5.2 一次真实的 leader 选举异常排查讲一个我实际遇到的案例。当时是一个测试环境三台机器突然全部变成 LOOKING 状态整个 Kafka 集群直接不可用。我先检查了网络和防火墙发现都没问题端口也能正常连通。再看日志发现三台机器都在选举但始终没有人当选 leader。后来我把三台机器上zoo.cfg全部拿出来对比发现其中一台的配置里server.3192.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.connect192.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 nameha.zookeeper.quorum/name value192.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 集群从“能跑”推进到“能扛事”这一步。如果你按上面的步骤搭完还有问题欢迎按问题现象对应到速查表逐项排查大部分情况都能找到答案。