1. 动手之前先把ZooKeeper集群的底层逻辑理清楚很多朋友一上来就照着教程敲命令node1、node2、node3三台机器装完启动一看状态全是follower或者leader就觉得“哦集群搭好了”。说实话这只能算“把服务跑起来了”离“真正理解并掌握ZooKeeper集群搭建”还有一段距离。我这篇不讲废话直接从底层逻辑讲到实操命令再讲到排错和避坑目标是让你搭完集群之后别人问你“为什么是奇数节点”“myid和zoo.cfg的server.x到底什么关系”“leader挂了这个集群还能不能干活”这类问题你都能接得住。ZooKeeper在分布式系统里扮演的角色说白了就是“协调者”。你在做Kafka、HBase、Dubbo、Flink这些上层组件的时候都会依赖ZooKeeper来做元数据管理、服务注册与发现、分布式锁、选主等事情。单机版ZooKeeper只适合开发调试一旦服务进程挂了所有依赖它的组件全部失控。因此生产环境必须上集群模式利用ZAB协议在多个节点之间做状态同步和故障恢复保证只要有超过半数的节点存活集群就能继续对外提供服务。这个“半数存活”的机制直接决定了集群节点数的选择逻辑也是你理解整个搭建流程的关键。这篇教程的实操环境是Linux系统我用三台CentOS 7.9虚拟机做演示JDK版本1.8ZooKeeper版本3.7.1。版本不用一模一样只要是3.4.x以上的主流版本配置逻辑完全通用但3.4.x已经是老古董了不建议新项目再用有些命令和默认端口行为跟3.6有明显差异。2. 核心机制拆解半数存活、Leader选举和节点身份2.1 为什么集群节点数必须是奇数先说结论ZooKeeper集群节点数推荐是3、5、7这样的奇数不推荐4、6这样的偶数。这个结论背后的逻辑包含两部分可用性和实现复杂度。“半数存活”规则意味着一个节点数为N的集群最多能容忍的故障节点数是(N-1)/2向下取整。3节点集群可以容忍1台宕机4节点集群可以容忍1台宕机5节点集群可以容忍2台宕机。从故障容忍度来看4和3一样6和5一样多出来的节点纯粹是浪费资源。这是“偶数不划算”的第一个原因。第二个原因跟选主过程有关。ZooKeeper集群里每个节点启动时会处于LOOKING状态通过投票选出Leader。如果遇到网络分区split-brain比如5节点集群被分成一边3台、一边2台3台那边能凑齐超过半数的票仍然可以选出Leader继续运行但如果偶数节点集群被分成两个相等的小组比如4节点分成22两边都凑不齐超过半数的票整个集群就会一直LOOKING写操作全部不可用这是最尴尬的场景既没有完全宕机但什么活也干不了。奇数节点在极端分区场景下至少能保证其中一侧满足半数条件。另外我还见过一些人问“为什么不用1节点或者2节点”。1节点是单点挂了就全挂了没意义。2节点更奇葩两台机器默认配置下如果有一台挂了剩下那台刚好达不到“超过半数”的要求整个集群会拒绝写请求可用性反而比单机还差——除非你开启了单机模式standalone但那就不是集群了。2.2 Leader选举和ZAB协议理解集群行为的钥匙启动集群或者Leader节点宕机时存活的Follower节点会重新发起选举。选举的核心指标是zxid事务ID和myid。每个写操作在ZooKeeper里都会被分配一个全局递增的zxidzxid越大表示数据越新。选主时节点会优先投票给zxid最大的节点因为它的数据最完整如果zxid相同再看myidmyid大的优先成为Leader。理解这一个机制对排错非常有帮助。比如你第一次启动集群时如果三台机器没有严格按照顺序启动可能出现一种情况先启动的机器成为Leader后启动的机器进来之后发现Leader已经存在就自动变成Follower并且把Leader的数据同步到本地。这个过程叫“发现与同步”由ZAB协议自动完成。另一个常被忽视的点是ZooKeeper集群节点不是“对等”的Leader负责处理所有写请求Follower只处理读请求并把写请求转发给Leader。所以你在搭建完集群后用JConsole或jps观察进程发现在某台机器上出现了Leader而另外两台是Follower这是正常的。如果集群里出现了“双主”那才是真正的问题通常意味着网络分区或者防火墙配置有问题。3. 集群搭建的核心步骤从环境准备到三节点启动前面原理讲得够多了下面进入正题。我会按照实际操作的顺序完整走一遍三节点集群的搭建每一段都会解释配置项的含义而不是让你无脑复制。3.1 环境准备与主机规划我这里的三台虚拟机信息如下节点IP地址角色规划操作系统node1192.168.100.11Leader/Follower候选CentOS 7.9node2192.168.100.12FollowerCentOS 7.9node3192.168.100.13FollowerCentOS 7.9每台机器至少分配2核CPU、2GB内存磁盘留给ZooKeeper数据目录至少2GB空间。ZooKeeper本身对硬件要求不高但如果你在同一批机器上还要跑Kafka或者Hadoop的NameNode内存就得往上加。首先需要确保三台机器之间网络互通。用ping测试一下如果ping不通先解决网络问题再继续。然后修改每台机器的主机名分别设置为node1、node2、node3hostnamectl set-hostname node1同时修改/etc/hosts文件在三台机器上都加上同样的映射关系。这一步非常关键因为ZooKeeper的配置和启动日志里会频繁用到主机名如果没有DNS解析节点之间无法互相识别cat /etc/hosts EOF 192.168.100.11 node1 192.168.100.12 node2 192.168.100.13 node3 EOF设置完用hostname和ping node2验证。如果你用的是云服务器记得在安全组/防火墙规则中放行ZooKeeper相关端口后面会细说端口。用VMware做实验的话把防火墙先关掉或者放行端口避免把时间浪费在排查网络问题上systemctl stop firewalld systemctl disable firewalld这里我不是推荐生产环境关防火墙生产环境应该按照最小权限原则配置防火墙只是说实验场景下为了快速验证集群功能先暂时关闭后面要记得重新开启。你的机器上已经跑了其他业务的话不要照抄这一步用防火墙放行特定端口更安全。3.2 JDK安装与ZooKeeper安装包准备ZooKeeper是Java程序所以环境里必须有JDK。推荐使用JDK 1.8这是ZooKeeper 3.7.x官方支持的版本范围。下载JDK的tar.gz包解压到/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 -versionZooKeeper安装包从Apache官网下载选择apache-zookeeper-3.7.1-bin.tar.gz这个文件。注意这里有个很容易踩的坑一定要下载带bin后缀的版本。Apache官网同时提供源码包和二进制包不带bin的源码包需要你自己用Maven编译会平白多折腾好几步而且编译过程中还有可能因网络问题下载依赖失败。我把话放这里新手一律选带bin的。下载完成后解压到/opt目录tar -zxvf apache-zookeeper-3.7.1-bin.tar.gz -C /opt/ mv /opt/apache-zookeeper-3.7.1-bin /opt/zookeeper然后把/opt/zookeeper目录的所有权分配给专门的应用用户。生产环境我强烈建议不要用root跑ZooKeeper而是单独建一个zookeeper用户降低安全风险useradd zookeeper chown -R zookeeper:zookeeper /opt/zookeeper这一步在实验环境不做问题不大但生产环境一定要做。用root启动的服务一旦被利用攻击者直接拿到的是最高权限这个风险不值得冒。3.3 三台机器上的zoo.cfg配置细节ZooKeeper的配置项全部集中在/opt/zookeeper/conf/zoo.cfg文件里。初次解压后目录下只有一个zoo_sample.cfg示例文件需要手动复制一份cp /opt/zookeeper/conf/zoo_sample.cfg /opt/zookeeper/conf/zoo.cfg用vim编辑zoo.cfg三台机器上的核心配置如下tickTime2000 initLimit10 syncLimit5 dataDir/opt/zookeeper/data dataLogDir/opt/zookeeper/logs clientPort2181 server.1node1:2888:3888 server.2node2:2888:3888 server.3node3:2888:3888我逐项解释一下这些参数的含义因为这直接关系到你对集群行为的理解。tickTime是ZooKeeper中最基本的时间单位单位毫秒默认3000我设置为2000。它定义了ZooKeeper各节点之间心跳检测的时间间隔基数。后续的initLimit和syncLimit都是以tickTime的倍数来计算的。initLimit是Follower在启动后与Leader进行同步初始化时最多能允许几个tickTime周期内完成。默认10代表10倍tickTime即20秒。如果网络环境比较差可以适当调大到20或30否则Follower启动时可能因为初始化超时而无法加入集群。这里有个实际例子我曾经在跨机房部署ZooKeeper时两个机房之间的网络延迟有30ms左右默认配置下节点启动后频繁超时日志里报“Timeout while waiting for another zooKeeper server”把initLimit从10调到30之后问题消失。syncLimit表示Follower与Leader之间进行数据同步时的超时时间同样是tickTime的倍数。默认5即10秒。如果某台Follower在10秒内无法与Leader完成数据同步它会被判定为连接超时从集群中移除。这个值在同一个局域网环境内一般不需要调整。dataDir是数据目录存放ZooKeeper的快照数据snapshot和myid文件。生产环境建议把这个目录放在单独的磁盘分区上不要和系统盘共用因为快照文件会随着数据量增长变得越来越大。dataLogDir是日志目录存放事务日志transaction log。从命名能看出事务日志和数据快照是分开存储的。生产环境强烈建议把dataLogDir放到独立的物理磁盘上这样事务日志写入的IO不会跟快照数据互相争抢可以明显降低写请求的延迟。很多初学的人会忽略这个配置项默认情况下事务日志和数据快照会写在同一个目录这在低并发时看不出区别一旦写请求量上来磁盘IO会变成瓶颈。clientPort是客户端连接端口默认2181。如果是多实例部署在同一台机器上机器上如果有其他服务占用了2181可以改成其他端口但客户端连接时也要同步修改。最关键的是末尾的server.1、server.2、server.3三行它们定义了集群由哪些节点组成格式为server.Nhost:port1:port2。N是节点的唯一标识对应每台机器上dataDir目录中的myid文件内容host是节点的主机名或IP地址port12888是Leader与Follower之间通信的端口用于数据同步和请求转发port23888是选举端口用于Leader选举时的通信很多人会在配置中把host写成IP地址这没有问题只要/etc/hosts能解析或者DNS能解析两种写法都可以。但需要注意所有机器上的server.x配置必须保持一致不允许出现A机器配的是IP、B机器配的是主机名的混用情况否则跨节点通信时可能出现地址无法对应。3.4 myid文件每个节点的“身份证”创建好dataDir目录后还需要在每个节点上创建一个名为myid的文件。这个文件的内容就是一个数字必须与zoo.cfg中对应节点的server.N编号一致。在node1上执行mkdir -p /opt/zookeeper/data mkdir -p /opt/zookeeper/logs echo 1 /opt/zookeeper/data/myid在node2上执行mkdir -p /opt/zookeeper/data mkdir -p /opt/zookeeper/logs echo 2 /opt/zookeeper/data/myid在node3上执行mkdir -p /opt/zookeeper/data mkdir -p /opt/zookeeper/logs echo 3 /opt/zookeeper/data/myid这里有三个关键细节需要特别提醒。第一myid文件必须与zoo.cfg中的server.x对应。如果node1上的myid内容写成了2而node2上的myid也写成了2整个集群会陷入混乱日志里全是找不动对应节点的错误。第二myid文件只有数字没有主机名、没有空格、没有换行以外的任何多余字符。我遇到过有人用Windows记事本编辑myid文件保存成带BOM头的UTF-8编码结果ZooKeeper读取myid时解析不出数字启动直接失败。解决办法是在Linux下用echo 1 myid这种方式创建这样最干净或者用echo -n 1 myid去掉末尾换行符。第三所有节点上的zoo.cfg中的server列表是完整的三行不需要在node1上只写server.1在node2上只写server.2。三台机器的zoo.cfg保持一致除了myid不同这样才是标准的集群配置方式。有些初学者会在node1上只留server.1那行结果节点之间无法互相发现这里特别强调一下。4. 启动集群和验证集群状态的完整过程4.1 首次启动的正确姿势集群首次启动启动顺序没有严格规定但按顺序逐台启动可以让你更清楚地观察每台节点加入集群的过程。实际生产环境里集群是允许各节点同时启动或者任意顺序启动的因为ZooKeeper的选举机制会自行协调。但第一次搭建时我建议这样操作先启动node1/opt/zookeeper/bin/zkServer.sh start启动完看一眼状态/opt/zookeeper/bin/zkServer.sh status此时node1的状态大概率是Mode: standalone或者Mode: leader实际上都不对。第一次启动时由于集群中只有node1一台机器启动其他两台还没起来node1会进入选举流程但无法凑齐多数票所以状态可能显示Mode: standalone单机模式或者一直处于LOOKING状态。这里有个版本差异在3.6以下版本中单台节点启动后会自动进入standalone模式日志会输出“Ignoring intermediate leading election”之类的信息在3.6及以上版本中你会看到状态变成Mode: standalone。接下来启动node2/opt/zookeeper/bin/zkServer.sh start /opt/zookeeper/bin/zkServer.sh status启动node2后node1和node2就能通过3888端口互相通信此时如果只有两台节点依然凑不齐超过半数的票3节点集群需要至少2票所以两台机器还是无法选出Leader。这个阶段集群依然不对外提供写服务。继续启动node3/opt/zookeeper/bin/zkServer.sh start /opt/zookeeper/bin/zkServer.sh statusnode3启动后三台节点之间可以互相通信这时会触发一次完整的选举流程。票数比较多的一方会胜出成为Leader另外两台自动成为Follower。此时三台机器的状态应该是一台显示Mode: leader另外两台显示Mode: follower。这里要注意一下第一次启动就出现Leader是正常的。但如果后续某台机器重启它进入集群后可能会继续当Follower不会抢Leader的位置因为已经存在的Leader会继续任职。4.2 使用四字命令检查集群健康状态ZooKeeper提供了一套四字命令Four Letter Words通过nc或telnet连接客户端端口即可获取集群状态信息。这是日常运维中最常用的排查手段。检查集群节点的角色echo stat | nc node1 2181输出会包含当前节点的角色Mode、连接数Clients、收发的数据包数量Received/Sent、节点总数Node count等信息。如果输出里看到Mode: leader说明当前节点是LeaderMode: follower则是从节点。查看集群成员信息echo cons | nc node1 2181在ZooKeeper 3.5及以上版本中还可以用mntr命令获取更丰富的监控指标echo mntr | nc node1 2181输出会列出zk_server_state、zk_num_alive_connections、zk_outstanding_requests等指标。这些指标对接Prometheus这类监控工具时非常有用建议生产环境接入。4.3 用zkCli.sh验证读写和故障转移配置和状态都正常最好再用客户端实测一轮读写确认集群对外提供的服务是真正常的。在三台机器任意一台执行/opt/zookeeper/bin/zkCli.sh -server node1:2181进入命令行交互界面后执行create /test_node hello_zookeeper get /test_node set /test_node updated_by_zk get /test_node ls /正常的结果是每次操作都有响应get能返回对应的值。这一步验证了ZooKeeper的数据读写在集群模式下工作正常。接下来验证故障转移。知道了Leader在node1上手动停止node1的ZooKeeper服务/opt/zookeeper/bin/zkServer.sh stop等待几秒然后查看node2和node3的状态/opt/zookeeper/bin/zkServer.sh status此时node2和node3会重新进行选举其中一台会变成Leader整个过程不需要人工干预。然后重新连接集群连接node2或node3读取之前创建的数据/opt/zookeeper/bin/zkCli.sh -server node2:2181 get /test_node能看到之前写入的数据说明数据同步正常没有丢数据。再把node1重新启动它会作为Follower加入集群并自动从Leader节点同步数据。到这里一个标准的ZooKeeper集群就完成搭建和功能验证了。5. ZooKeeper集群排错手册与进阶配置建议5.1 高频率出现的启动失败问题搭建过程中你可能会遇到各种问题我把最常见的几种一次性给你列完整了附上排查思路和解决方式。现象常见原因排查与解决启动报错找不到或无法加载主类下载的是源码包而不是bin包重新下载带bin后缀的压缩包我的id文件读取失败myid文件不存在或内容格式错误检查dataDir目录下是否有myid文件内容是否为纯数字节点间无法互相发现/etc/hosts未配置或防火墙阻断端口检查hosts映射、ping主机名、放行2888/3888端口集群状态一直显示standalone只启动了一台节点或2888/3888端口不通确认三台节点全部启动检查端口连通性选举完总是出现连接异常initLimit或syncLimit超时网络延迟高时适当调大这两个参数客户端连接失败clientPort端口被占用或未放行检查2181端口监听状态和防火墙规则还有一种比较隐蔽的问题zoo.cfg中的dataDir目录没有写权限导致ZooKeeper进程启动时无法创建快照文件日志里报Permission denied。我在生产环境见过有人把dataDir配置到/root目录下然后使用非root用户启动ZooKeeper结果每次重启都会失败。解决方式很简单确保dataDir目录的所有者和ZooKeeper启动用户一致。5.2 生产环境集群搭建的几个额外建议如果是用于生产环境仅完成上面的基础配置还不够。我根据自己的实践经验整理了几个生产环境必须考虑的增强项。建议关闭ZooKeeper的自动清理功能改为按需留存快照。ZooKeeper默认开启了自动清理autopurge配置如下autopurge.snapRetainCount3 autopurge.purgeInterval24snapRetainCount3表示保留最近3个快照purgeInterval24表示每24小时清理一次。如果你的集群数据量很大清理过程中磁盘IO会上升可能影响线上请求。稳妥的做法是把purgeInterval调大到48或72并且把清理任务放到业务低峰期。我自己在维护一个数据量较大的集群时甚至会把自动清理关掉换成crontab里定时执行zkCleanup.sh脚本效果更可控。其次是JVM参数调优。默认情况下ZooKeeper的堆内存设置为512MB或1GB生产环境如果节点上的znode数量很多或者写并发很高建议适当调大。在zkServer.sh脚本里找到ZOO_MAIN函数之前通常会有一段JVM参数设置可以在/opt/zookeeper/conf/zookeeper-env.sh里如果不存在则复制zookeeper-env.sh模板设置export ZOO_JVM_OPTS-Xms2g -Xmx2g -XX:MaxDirectMemorySize1gXms和Xmx设置成相同值可以避免JVM运行时动态扩容带来的性能损耗这个技巧同样适用于其他Java服务。还有一个容易被忽略的ZooKeeper集群的部署必须确保各节点时间一致。ZooKeeper虽然不依赖严格的时间同步不像某些分布式数据库那么苛刻但节点间时间差异过大会导致会话超时判断异常出现客户端频繁断开重连的诡异问题。生产环境建议统一配置NTP服务或者chrony让所有节点时间偏差控制在几百毫秒以内。别小看这个细节我见过有人排查了半个月的“客户端连接不稳定”问题最后发现是其中一台机器时间快了整整5分钟。最后提一下连接数限制。ZooKeeper默认最大客户端连接数是60这个值对生产环境来说实在太低了。你搭Kafka集群的时候每个broker都会建立一条连接60这个上限很快就会被占满。在zoo.cfg中增加maxClientCnxns2000设置完重启所有节点生效。5.3 关于数据目录迁移和滚动重启的建议如果你刚搭完集群就发现数据目录磁盘空间不够或者想把dataDir换到新的磁盘挂载点不建议直接改配置然后重启一台机器。ZooKeeper集群支持滚动重启rolling restart操作顺序是修改一台节点的zoo.cfg并停止该节点上的ZooKeeper服务将旧dataDir目录下的文件包括myid和各版本快照同步到新目录启动该节点等待它重新加入集群并完成数据同步确认该节点状态正常zkServer.sh status显示follower或leader后再操作下一台节点逐台替换不要同时停多台机器否则可能触发不必要的选主流程。虽然选主本身会自动完成但业务端在此期间可能会感知到抖动。滚动重启是最平滑的运维手段这个经验同样适用于ZooKeeper的升级和迁移。回到日常维护的层面ZooKeeper集群本身并不复杂真正需要用心的是数据目录的规划、JVM参数的合理设定、端口策略和监控告警的配合。搭好一个能跑的集群只要半小时把集群调得好用、扛得住线上流量才是更值得花时间的地方。如果你按这篇教程一步步操作下来碰到的绝大多数问题都能在上面的排查表里找到答案。
