搭建 ZooKeeper 集群是构建高可用分布式系统（如 Kafka、Hadoop HHA、Dubbo 等）的关键步骤。ZooKeeper 集群通常采用奇数节点部署（如 3 台、5 台），以容忍(n-1)/2台机器故障。

以下是基于最新稳定版本（如 3.8.x 或 3.9.x）的3 节点集群搭建详细指南。

一、环境规划

假设我们有 3 台 Linux 服务器（CentOS/Ubuntu均可），已安装好 JDK（JDK 8 或 JDK 11+）。

注意：请确保所有机器时间同步（使用ntpdate或chrony），防火墙已关闭或放行了相关端口。

二、搭建步骤（每台机器均需执行，除 myid 不同外）

1. 下载与解压

前往 Apache 官网下载最新稳定版（例如apache-zookeeper-3.8.4-bin.tar.gz）。

# 创建目录 sudo mkdir -p /opt/zookeeper cd /opt/zookeeper # 下载 (以 3.8.4 为例，请替换为最新版本链接) wget https://dlcdn.apache.org/zookeeper/zookeeper-3.8.4/apache-zookeeper-3.8.4-bin.tar.gz # 解压 tar -zxvf apache-zookeeper-3.8.4-bin.tar.gz mv apache-zookeeper-3.8.4-bin zookeeper-3.8.4

2. 创建数据目录和日志目录

在生产环境中，建议将数据和日志分开存放，且不要放在系统盘。

cd /opt/zookeeper/zookeeper-3.8.4 mkdir -p data mkdir -p logs

3. 配置zoo.cfg

进入conf目录，复制示例配置文件并修改。

cd conf cp zoo_sample.cfg zoo.cfg vim zoo.cfg

修改后的zoo.cfg内容示例：

# 客户端连接端口 clientPort=2181 # 数据目录 (对应上面创建的 data 目录) dataDir=/opt/zookeeper/zookeeper-3.8.4/data # 日志目录 (可选，不配则默认在 dataDir) dataLogDir=/opt/zookeeper/zookeeper-3.8.4/logs # 心跳检测时间 (毫秒) tickTime=2000 # 初始化连接超时时间 (tickTime 的倍数) initLimit=10 # 同步超时时间 (tickTime 的倍数) syncLimit=5 # --- 集群配置核心部分 --- # 格式: server.A=B:C:D # A: 节点 ID (对应 myid 文件中的数字) # B: 节点 IP # C: Follower 与 Leader 交换信息的端口 (2888) # D: 选举 Leader 的端口 (3888) server.1=192.168.1.101:2888:3888 server.2=192.168.1.102:2888:3888 server.3=192.168.1.103:2888:3888 # (可选) 4lw commands whitelist，允许使用 ruok 等监控命令 4lw.commands.whitelist=*

提示：将此配置好的zoo.cfg文件分发到其他两台节点的相同目录下。

4. 创建节点标识文件 (myid)

这是区分不同节点的关键步骤。每台机器的该文件内容必须不同。

在dataDir指定的目录下（即/opt/zookeeper/zookeeper-3.8.4/data）创建名为myid的文件：

• 在 node1 (192.168.1.101) 上执行：

echo "1" > /opt/zookeeper/zookeeper-3.8.4/data/myid

• 在 node2 (192.168.1.102) 上执行：

echo "2" > /opt/zookeeper/zookeeper-3.8.4/data/myid

• 在 node3 (192.168.1.103) 上执行：

echo "3" > /opt/zookeeper/zookeeper-3.8.4/data/myid

5. 启动集群

在所有节点上依次执行启动命令（顺序不限，但建议同时或快速连续启动以加速选举）。

cd /opt/zookeeper/zookeeper-3.8.4/bin ./zkServer.sh start

或者使用后台运行模式（推荐生产环境）：

./zkServer.sh start-foreground & # 或者直接作为服务运行，若配置了 systemd

6. 验证集群状态

在任意节点执行状态检查命令：

./zkServer.sh status

预期输出：

• 其中一台显示Mode: leader
• 其余两台显示Mode: follower

如果显示Error contacting service. It is probably not running.，请检查：

1. 防火墙是否拦截了 2181, 2888, 3888 端口。
2. zoo.cfg中的 IP 地址是否正确。
3. myid文件内容是否与配置中的server.X对应。
4. 查看logs目录下的.log和.out文件排查具体错误。

三、常用运维命令

四、常见问题与优化建议

1. 脑裂问题：确保网络稳定。如果网络分区导致集群分裂，少数派节点将无法提供服务。
2. 磁盘性能：ZooKeeper 对磁盘 I/O 延迟非常敏感（尤其是写操作，因为要写事务日志）。建议使用 SSD，并将dataLogDir单独挂载到高性能磁盘。
3. JVM 调优：编辑bin/zkEnv.sh，调整JVMFLAGS。对于 3 节点小集群，默认设置通常足够；大规模集群需调整堆内存（不宜过大，避免 GC 停顿），通常 2GB-4GB 即可。
4. 快照清理：ZooKeeper 会保留多个快照，可在zoo.cfg中配置snapCount和purgeInterval(或使用PurgeTxnLog工具) 定期清理旧数据，防止磁盘爆满。

按照以上步骤，你就可以成功搭建一个稳定的 ZooKeeper 集群了。