搭建 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+）。
| 主机名 | IP 地址 | 节点 ID (myid) | 端口说明 |
|---|---|---|---|
| zk-node1 | 192.168.1.101 | 1 | 2181(客户端), 2888( follower通信), 3888(选举) |
| zk-node2 | 192.168.1.102 | 2 | 同上 |
| zk-node3 | 192.168.1.103 | 3 | 同上 |
注意 ：请确保所有机器时间同步（使用 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.42. 创建数据目录和日志目录
在生产环境中，建议将数据和日志分开存放，且不要放在系统盘。
cd /opt/zookeeper/zookeeper-3.8.4
mkdir -p data
mkdir -p logs3. 配置 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 &
# 或者直接作为服务运行，若配置了 systemd6. 验证集群状态
在任意节点执行状态检查命令：
./zkServer.sh status预期输出：
- 其中一台显示
Mode: leader - 其余两台显示
Mode: follower
如果显示 Error contacting service. It is probably not running.，请检查：
- 防火墙是否拦截了 2181, 2888, 3888 端口。
zoo.cfg中的 IP 地址是否正确。myid文件内容是否与配置中的server.X对应。- 查看
logs目录下的.log和.out文件排查具体错误。
三、常用运维命令
| 命令 | 说明 |
|---|---|
./zkServer.sh start |
启动节点 |
./zkServer.sh stop |
停止节点 |
./zkServer.sh restart |
重启节点 |
./zkServer.sh status |
查看当前节点角色 (Leader/Follower) |
./zkCli.sh |
连接本地客户端进行测试 |
| `echo ruok | nc localhost 2181` |
四、常见问题与优化建议
- 脑裂问题：确保网络稳定。如果网络分区导致集群分裂，少数派节点将无法提供服务。
- 磁盘性能 ：ZooKeeper 对磁盘 I/O 延迟非常敏感（尤其是写操作，因为要写事务日志）。建议使用 SSD，并将
dataLogDir单独挂载到高性能磁盘。 - JVM 调优 ：编辑
bin/zkEnv.sh，调整JVMFLAGS。对于 3 节点小集群，默认设置通常足够；大规模集群需调整堆内存（不宜过大，避免 GC 停顿），通常 2GB-4GB 即可。 - 快照清理 ：ZooKeeper 会保留多个快照，可在
zoo.cfg中配置snapCount和purgeInterval(或使用PurgeTxnLog工具) 定期清理旧数据，防止磁盘爆满。
按照以上步骤，你就可以成功搭建一个稳定的 ZooKeeper 集群了。