企业官网建设流程全解析

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.8，ZooKeeper版本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节点分成2+2，两边都凑不齐超过半数的票，整个集群就会一直LOOKING，写操作全部不可用，这是最尴尬的场景，既没有完全宕机，但什么活也干不了。奇数节点在极端分区场景下至少能保证其中一侧满足半数条件。

另外，我还见过一些人问“为什么不用1节点或者2节点”。1节点是单点，挂了就全挂了，没意义。2节点更奇葩，两台机器默认配置下如果有一台挂了，剩下那台刚好达不到“超过半数”的要求，整个集群会拒绝写请求，可用性反而比单机还差——除非你开启了单机模式（standalone），但那就不是集群了。

2.2 Leader选举和ZAB协议，理解集群行为的钥匙

启动集群或者Leader节点宕机时，存活的Follower节点会重新发起选举。选举的核心指标是zxid（事务ID）和myid。每个写操作在ZooKeeper里都会被分配一个全局递增的zxid，zxid越大表示数据越新。选主时，节点会优先投票给zxid最大的节点，因为它的数据最完整；如果zxid相同，再看myid，myid大的优先成为Leader。

理解这一个机制，对排错非常有帮助。比如你第一次启动集群时，如果三台机器没有严格按照顺序启动，可能出现一种情况：先启动的机器成为Leader，后启动的机器进来之后发现Leader已经存在，就自动变成Follower，并且把Leader的数据同步到本地。这个过程叫“发现与同步”，由ZAB协议自动完成。

另一个常被忽视的点是：ZooKeeper集群节点不是“对等”的，Leader负责处理所有写请求，Follower只处理读请求并把写请求转发给Leader。所以你在搭建完集群后，用JConsole或jps观察进程，发现在某台机器上出现了Leader而另外两台是Follower，这是正常的。如果集群里出现了“双主”，那才是真正的问题，通常意味着网络分区或者防火墙配置有问题。

3. 集群搭建的核心步骤：从环境准备到三节点启动

前面原理讲得够多了，下面进入正题。我会按照实际操作的顺序，完整走一遍三节点集群的搭建，每一段都会解释配置项的含义，而不是让你无脑复制。

3.1 环境准备与主机规划

我这里的三台虚拟机信息如下：

每台机器至少分配2核CPU、2GB内存，磁盘留给ZooKeeper数据目录至少2GB空间。ZooKeeper本身对硬件要求不高，但如果你在同一批机器上还要跑Kafka或者Hadoop的NameNode，内存就得往上加。

首先需要确保三台机器之间网络互通。用ping测试一下，如果ping不通，先解决网络问题再继续。然后修改每台机器的主机名，分别设置为node1、node2、node3：

hostnamectl 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 -version

ZooKeeper安装包从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，三台机器上的核心配置如下：

tickTime=2000 initLimit=10 syncLimit=5 dataDir=/opt/zookeeper/data dataLogDir=/opt/zookeeper/logs clientPort=2181 server.1=node1:2888:3888 server.2=node2:2888:3888 server.3=node3: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.N=host:port1:port2。

• N是节点的唯一标识，对应每台机器上dataDir目录中的myid文件内容
• host是节点的主机名或IP地址
• port1（2888）是Leader与Follower之间通信的端口，用于数据同步和请求转发
• port2（3888）是选举端口，用于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 status

node3启动后，三台节点之间可以互相通信，这时会触发一次完整的选举流程。票数比较多的一方会胜出，成为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，说明当前节点是Leader；Mode: 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 高频率出现的启动失败问题

搭建过程中你可能会遇到各种问题，我把最常见的几种一次性给你列完整了，附上排查思路和解决方式。

还有一种比较隐蔽的问题：zoo.cfg中的dataDir目录没有写权限，导致ZooKeeper进程启动时无法创建快照文件，日志里报Permission denied。我在生产环境见过有人把dataDir配置到/root目录下，然后使用非root用户启动ZooKeeper，结果每次重启都会失败。解决方式很简单：确保dataDir目录的所有者和ZooKeeper启动用户一致。

5.2 生产环境集群搭建的几个额外建议

如果是用于生产环境，仅完成上面的基础配置还不够。我根据自己的实践经验，整理了几个生产环境必须考虑的增强项。

建议关闭ZooKeeper的自动清理功能，改为按需留存快照。ZooKeeper默认开启了自动清理（autopurge），配置如下：

autopurge.snapRetainCount=3 autopurge.purgeInterval=24

snapRetainCount=3表示保留最近3个快照，purgeInterval=24表示每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:MaxDirectMemorySize=1g"

Xms和Xmx设置成相同值可以避免JVM运行时动态扩容带来的性能损耗，这个技巧同样适用于其他Java服务。

还有一个容易被忽略的：ZooKeeper集群的部署必须确保各节点时间一致。ZooKeeper虽然不依赖严格的时间同步（不像某些分布式数据库那么苛刻），但节点间时间差异过大会导致会话超时判断异常，出现客户端频繁断开重连的诡异问题。生产环境建议统一配置NTP服务或者chrony，让所有节点时间偏差控制在几百毫秒以内。别小看这个细节，我见过有人排查了半个月的“客户端连接不稳定”问题，最后发现是其中一台机器时间快了整整5分钟。

最后提一下连接数限制。ZooKeeper默认最大客户端连接数是60，这个值对生产环境来说实在太低了。你搭Kafka集群的时候，每个broker都会建立一条连接，60这个上限很快就会被占满。在zoo.cfg中增加：

maxClientCnxns=2000

设置完重启所有节点生效。

5.3 关于数据目录迁移和滚动重启的建议

如果你刚搭完集群就发现数据目录磁盘空间不够，或者想把dataDir换到新的磁盘挂载点，不建议直接改配置然后重启一台机器。ZooKeeper集群支持滚动重启（rolling restart），操作顺序是：

1. 修改一台节点的zoo.cfg并停止该节点上的ZooKeeper服务
2. 将旧dataDir目录下的文件（包括myid和各版本快照）同步到新目录
3. 启动该节点，等待它重新加入集群并完成数据同步
4. 确认该节点状态正常（zkServer.sh status显示follower或leader）后，再操作下一台节点

逐台替换，不要同时停多台机器，否则可能触发不必要的选主流程。虽然选主本身会自动完成，但业务端在此期间可能会感知到抖动。滚动重启是最平滑的运维手段，这个经验同样适用于ZooKeeper的升级和迁移。

回到日常维护的层面，ZooKeeper集群本身并不复杂，真正需要用心的是数据目录的规划、JVM参数的合理设定、端口策略和监控告警的配合。搭好一个能跑的集群只要半小时，把集群调得好用、扛得住线上流量，才是更值得花时间的地方。如果你按这篇教程一步步操作下来，碰到的绝大多数问题都能在上面的排查表里找到答案。