zookeeper安装及常见的操作命令

Zookeeper安装及常见的操作命令

一、安装前准备

  • 推荐 Java：JDK 8/11/17，ZooKeeper 3.8+ 推荐 JDK 11+
  • 单机模式适合测试；生产建议至少 3 台组成集群
  • 集群节点数量建议为奇数：3、5、7
  • 默认端口：
    • 2181：客户端连接端口
    • 2888：Follower 与 Leader 通信端口
    • 3888：Leader 选举端口
    • 8080：AdminServer 端口，部分版本默认开启

1. 安装 Java

Ubuntu / Debian

1
2
sudo apt update
sudo apt install -y openjdk-11-jdk

CentOS / RHEL / Rocky Linux

1
sudo yum install -y java-11-openjdk java-11-openjdk-devel

检查 Java

1
java -version

示例输出：

1
openjdk version "11.0.x"

2. 创建运行用户

1
sudo useradd -r -m -s /sbin/nologin zookeeper

如果系统没有 /sbin/nologin，可使用：

1
sudo useradd -r -m -s /usr/sbin/nologin zookeeper

3. 下载 ZooKeeper

进入安装目录：

1
cd /opt

下载源码发布包对应的二进制包，例如 3.8.6：

1
sudo wget https://downloads.apache.org/zookeeper/zookeeper-3.8.6/apache-zookeeper-3.8.6-bin.tar.gz

如果机器不能访问 Apache 官方源，可以使用归档地址：

1
sudo wget https://archive.apache.org/dist/zookeeper/zookeeper-3.8.6/apache-zookeeper-3.8.6-bin.tar.gz

解压：

1
sudo tar -zxvf apache-zookeeper-3.8.6-bin.tar.gz

创建软链接：

1
sudo ln -s /opt/apache-zookeeper-3.8.6-bin /opt/zookeeper

授权：

1
2
sudo chown -R zookeeper:zookeeper /opt/apache-zookeeper-3.8.6-bin
sudo chown -h zookeeper:zookeeper /opt/zookeeper

4. 创建数据和日志目录

1
2
3
sudo mkdir -p /data/zookeeper/data
sudo mkdir -p /data/zookeeper/logs
sudo chown -R zookeeper:zookeeper /data/zookeeper

目录说明：

1
2
/data/zookeeper/data    # 快照数据目录
/data/zookeeper/logs    # 事务日志目录

单机模式安装

5. 配置单机 ZooKeeper

复制配置文件：

1
sudo cp /opt/zookeeper/conf/zoo_sample.cfg /opt/zookeeper/conf/zoo.cfg

编辑配置：

1
sudo vi /opt/zookeeper/conf/zoo.cfg

单机配置示例：

1
2
3
4
5
6
7
tickTime=2000
initLimit=10
syncLimit=5
dataDir=/data/zookeeper/data
dataLogDir=/data/zookeeper/logs
clientPort=2181
admin.serverPort=8080

参数说明：

1
2
3
4
5
6
tickTime=2000          # 基础时间单位，毫秒
initLimit=10           # Follower 初始化连接 Leader 的超时时间
syncLimit=5            # Follower 与 Leader 同步超时时间
dataDir=...            # 快照数据目录
dataLogDir=...         # 事务日志目录
clientPort=2181        # 客户端连接端口

6. 启动单机 ZooKeeper

前台启动，便于调试：

1
sudo -u zookeeper /opt/zookeeper/bin/zkServer.sh start-foreground

后台启动：

1
sudo -u zookeeper /opt/zookeeper/bin/zkServer.sh start

查看状态：

1
sudo -u zookeeper /opt/zookeeper/bin/zkServer.sh status

停止服务：

1
sudo -u zookeeper /opt/zookeeper/bin/zkServer.sh stop

重启服务：

1
sudo -u zookeeper /opt/zookeeper/bin/zkServer.sh restart

集群模式安装

假设有三台服务器：

1
2
3
zk01: 192.168.1.101
zk02: 192.168.1.102
zk03: 192.168.1.103

每台服务器都执行前面的 Java 安装、用户创建、目录创建、ZooKeeper 解压步骤。

7. 配置集群 zoo.cfg

三台服务器的 /opt/zookeeper/conf/zoo.cfg 内容基本一致：

1
2
3
4
5
6
7
8
9
10
11
12
tickTime=2000
initLimit=10
syncLimit=5
dataDir=/data/zookeeper/data
dataLogDir=/data/zookeeper/logs
clientPort=2181

server.1=192.168.1.101:2888:3888
server.2=192.168.1.102:2888:3888
server.3=192.168.1.103:2888:3888

admin.serverPort=8080

如果不需要 AdminServer，可以关闭：

1
admin.enableServer=false

8. 配置 myid

myid 必须与 zoo.cfg 中的 server.X 对应。

在 zk01 上执行

1
2
echo 1 | sudo tee /data/zookeeper/data/myid
sudo chown zookeeper:zookeeper /data/zookeeper/data/myid

在 zk02 上执行

1
2
echo 2 | sudo tee /data/zookeeper/data/myid
sudo chown zookeeper:zookeeper /data/zookeeper/data/myid

在 zk03 上执行

1
2
echo 3 | sudo tee /data/zookeeper/data/myid
sudo chown zookeeper:zookeeper /data/zookeeper/data/myid

检查：

1
cat /data/zookeeper/data/myid

9. 配置防火墙

firewalld

1
2
3
4
sudo firewall-cmd --add-port=2181/tcp --permanent
sudo firewall-cmd --add-port=2888/tcp --permanent
sudo firewall-cmd --add-port=3888/tcp --permanent
sudo firewall-cmd --reload

如果启用 AdminServer：

1
2
sudo firewall-cmd --add-port=8080/tcp --permanent
sudo firewall-cmd --reload

ufw

1
2
3
4
sudo ufw allow 2181/tcp
sudo ufw allow 2888/tcp
sudo ufw allow 3888/tcp
sudo ufw allow 8080/tcp

10. 启动集群

三台机器分别启动：

1
sudo -u zookeeper /opt/zookeeper/bin/zkServer.sh start

查看状态：

1
sudo -u zookeeper /opt/zookeeper/bin/zkServer.sh status

正常情况下，一台为：

1
Mode: leader

另外两台为：

1
Mode: follower

如果是观察者节点，会显示：

1
Mode: observer

使用 systemd 管理 ZooKeeper

11. 创建 systemd 服务文件

创建服务文件：

1
sudo vi /etc/systemd/system/zookeeper.service

内容如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
[Unit]
Description=Apache ZooKeeper
After=network.target

[Service]
Type=forking
User=zookeeper
Group=zookeeper
Environment=JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64
Environment=ZOO_LOG_DIR=/data/zookeeper/logs
ExecStart=/opt/zookeeper/bin/zkServer.sh start
ExecStop=/opt/zookeeper/bin/zkServer.sh stop
ExecReload=/opt/zookeeper/bin/zkServer.sh restart
Restart=on-failure
RestartSec=5
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target

注意：不同系统的 JAVA_HOME 可能不同。

查看 Java 路径：

1
readlink -f $(which java)

Ubuntu 常见路径：

1
/usr/lib/jvm/java-11-openjdk-amd64

CentOS/RHEL 常见路径：

1
/usr/lib/jvm/java-11-openjdk

12. 启动 systemd 服务

重新加载配置：

1
sudo systemctl daemon-reload

设置开机自启：

1
sudo systemctl enable zookeeper

启动服务：

1
sudo systemctl start zookeeper

查看状态：

1
sudo systemctl status zookeeper

停止服务：

1
sudo systemctl stop zookeeper

重启服务：

1
sudo systemctl restart zookeeper

查看日志：

1
sudo journalctl -u zookeeper -f

ZooKeeper 客户端操作

13. 连接 ZooKeeper

连接本机：

1
/opt/zookeeper/bin/zkCli.sh -server 127.0.0.1:2181

连接集群：

1
/opt/zookeeper/bin/zkCli.sh -server 192.168.1.101:2181,192.168.1.102:2181,192.168.1.103:2181

14. 常用 znode 命令

查看根目录：

1
ls /

创建节点：

1
create /app "hello"

查看节点数据：

1
get /app

修改节点数据：

1
set /app "new-value"

查看节点状态：

1
stat /app

删除空节点：

1
delete /app

递归删除节点：

1
deleteall /app

创建持久顺序节点：

1
create -s /queue/item "task1"

创建临时节点：

1
create -e /tmp-node "online"

创建临时顺序节点：

1
create -e -s /lock/node "client1"

查看命令帮助：

1
help

退出客户端：

1
quit

四字命令运维检查

ZooKeeper 支持四字命令，用于快速查看运行状态。部分版本需要先开启白名单。

15. 开启四字命令

编辑 zoo.cfg：

1
4lw.commands.whitelist=stat,ruok,mntr,conf,cons,srvr,wchs

如果测试环境想全部开放：

1
4lw.commands.whitelist=*

生产环境不建议开放 *。

重启：

1
sudo systemctl restart zookeeper

16. 常用四字命令

检查是否正常：

1
echo ruok | nc 127.0.0.1 2181

正常返回：

1
imok

查看服务状态：

1
echo stat | nc 127.0.0.1 2181

查看服务角色：

1
echo srvr | nc 127.0.0.1 2181

查看监控指标：

1
echo mntr | nc 127.0.0.1 2181

查看配置：

1
echo conf | nc 127.0.0.1 2181

查看客户端连接：

1
echo cons | nc 127.0.0.1 2181

查看 watch 数量：

1
echo wchs | nc 127.0.0.1 2181

日志与数据维护

17. 查看日志

如果使用脚本启动：

1
ls -lh /data/zookeeper/logs

查看主日志：

1
tail -f /data/zookeeper/logs/zookeeper-zookeeper-server-*.out

如果使用 systemd：

1
sudo journalctl -u zookeeper -f

18. 清理快照和事务日志

ZooKeeper 会生成快照和事务日志，长期运行需要清理。

手动清理，保留最近 10 个快照：

1
sudo -u zookeeper /opt/zookeeper/bin/zkCleanup.sh /data/zookeeper/data 10

更推荐配置自动清理，在 zoo.cfg 增加：

1
2
autopurge.snapRetainCount=10
autopurge.purgeInterval=24

含义：

1
2
autopurge.snapRetainCount=10   # 保留最近 10 个快照
autopurge.purgeInterval=24     # 每 24 小时清理一次

配置优化建议

19. 常用生产配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
tickTime=2000
initLimit=10
syncLimit=5

dataDir=/data/zookeeper/data
dataLogDir=/data/zookeeper/logs

clientPort=2181
maxClientCnxns=200

autopurge.snapRetainCount=10
autopurge.purgeInterval=24

4lw.commands.whitelist=stat,ruok,mntr,conf,srvr

admin.enableServer=false

集群配置：

1
2
3
server.1=192.168.1.101:2888:3888
server.2=192.168.1.102:2888:3888
server.3=192.168.1.103:2888:3888

20. JVM 参数配置

编辑：

1
sudo vi /opt/zookeeper/conf/java.env

示例：

1
export JVMFLAGS="-Xms1g -Xmx1g -XX:+UseG1GC -XX:MaxGCPauseMillis=200"

授权：

1
sudo chown zookeeper:zookeeper /opt/zookeeper/conf/java.env

建议：

1
2
3
4
-Xms 和 -Xmx 设置一致
小集群可用 1g
中等规模可用 2g~4g
不建议给 ZooKeeper 分配过大的堆

安装验证

21. 服务状态验证

查看进程：

1
ps -ef | grep zookeeper

查看端口：

1
ss -lntp | grep 2181

查看角色：

1
sudo -u zookeeper /opt/zookeeper/bin/zkServer.sh status

健康检查：

1
echo ruok | nc 127.0.0.1 2181

查看监控指标：

1
echo mntr | nc 127.0.0.1 2181

常见故障排查

22. 启动失败

查看 systemd 日志：

1
sudo journalctl -u zookeeper -xe

查看 ZooKeeper 日志：

1
tail -n 200 /data/zookeeper/logs/*.out

常见原因：

1
2
3
4
5
Java 未安装或 JAVA_HOME 错误
dataDir 没有权限
zoo.cfg 配置错误
myid 缺失或与 server.X 不匹配
端口 2181/2888/3888 被占用

23. 检查端口占用

1
ss -lntp | grep -E '2181|2888|3888|8080'

或：

1
netstat -lntp | grep -E '2181|2888|3888|8080'

24. 检查 myid

1
cat /data/zookeeper/data/myid

确认它与配置一致：

1
2
3
server.1=192.168.1.101:2888:3888
server.2=192.168.1.102:2888:3888
server.3=192.168.1.103:2888:3888

25. 检查集群连通性

在每台机器上测试其他节点端口：

1
2
3
4
5
6
7
8
9
nc -vz 192.168.1.101 2181
nc -vz 192.168.1.101 2888
nc -vz 192.168.1.101 3888
nc -vz 192.168.1.102 2181
nc -vz 192.168.1.102 2888
nc -vz 192.168.1.102 3888
nc -vz 192.168.1.103 2181
nc -vz 192.168.1.103 2888
nc -vz 192.168.1.103 3888

常用运维命令汇总

服务管理

1
2
3
4
5
6
sudo systemctl start zookeeper
sudo systemctl stop zookeeper
sudo systemctl restart zookeeper
sudo systemctl status zookeeper
sudo systemctl enable zookeeper
sudo systemctl disable zookeeper

脚本管理

1
2
3
4
sudo -u zookeeper /opt/zookeeper/bin/zkServer.sh start
sudo -u zookeeper /opt/zookeeper/bin/zkServer.sh stop
sudo -u zookeeper /opt/zookeeper/bin/zkServer.sh restart
sudo -u zookeeper /opt/zookeeper/bin/zkServer.sh status

客户端连接

1
2
/opt/zookeeper/bin/zkCli.sh -server 127.0.0.1:2181
/opt/zookeeper/bin/zkCli.sh -server 192.168.1.101:2181,192.168.1.102:2181,192.168.1.103:2181

健康检查

1
2
3
4
echo ruok | nc 127.0.0.1 2181
echo stat | nc 127.0.0.1 2181
echo srvr | nc 127.0.0.1 2181
echo mntr | nc 127.0.0.1 2181

日志查看

1
2
sudo journalctl -u zookeeper -f
tail -f /data/zookeeper/logs/*.out

端口检查

1
ss -lntp | grep -E '2181|2888|3888|8080'

推荐安装流程总结

生产环境建议按这个顺序执行：

1
2
3
4
5
6
7
8
9
10
1. 安装 JDK
2. 创建 zookeeper 用户
3. 下载并解压 ZooKeeper
4. 创建 dataDir 和 dataLogDir
5. 配置 zoo.cfg
6. 集群模式配置 myid
7. 开放 2181、2888、3888 端口
8. 配置 systemd
9. 启动 ZooKeeper
10. 使用 zkServer.sh status 和四字命令验证

最关键的三个配置是：

1
2
3
dataDir=/data/zookeeper/data
dataLogDir=/data/zookeeper/logs
server.X=IP:2888:3888
linux
#linux
zookeeper安装及常见的操作命令
https://blog.t-ao.cn/2026/07/21/zookeeper安装及常见的操作命令/
作者
TAO
发布于
2026年7月21日
许可协议