Zookeeper 指令集¶

zkCli.sh 与 zkServer.sh 速查。详见 ZooKeeper CLI 文档。

zkCli 命令¶

ZooKeeper 命令行客户端（zkCli.sh）。

先决条件
启动 CLI 并连接 ensemble：

# 连接本机默认端口 2181
bin/zkCli.sh
# 连接远程，会话超时 3 秒
bin/zkCli.sh -timeout 3000 -server remoteIP:2181
# 等待连接成功后再执行命令
bin/zkCli.sh -waitforconnection -timeout 3000 -server remoteIP:2181
# 使用客户端配置文件
bin/zkCli.sh -client-configuration /path/to/client.properties

addauth¶

为ACL添加授权用户。

[zkshell: 9] getAcl /acl_digest_test
    Insufficient permission : /acl_digest_test
[zkshell: 10] addauth digest user1:12345
[zkshell: 11] getAcl /acl_digest_test
    'digest,'user1:+owfoSBn/am19roBPzR1/MfCblE=
    : cdrwa
# 添加超级用户（需在服务端配置 DigestAuthenticationProvider.superDigest）
# 例如 zookeeper.DigestAuthenticationProvider.superDigest=zookeeper:qW/HnTfCSoQpB5G8LgkwT3IbiFc=
[zkshell: 12] addauth digest zookeeper:admin

close¶

关闭此客户端/会话。

[zkshell: 0] close
 2019-03-09 06:42:22,178 [myid:] - INFO  [main-EventThread:ClientCnxn$EventThread@528] - EventThread shut down for session: 0x10007ab7c550006
 2019-03-09 06:42:22,179 [myid:] - INFO  [main:ZooKeeper@1346] - Session: 0x10007ab7c550006 closed

config¶

显示仲裁成员的配置。

[zkshell: 17] config
 server.1=[2001:db8:1:0:0:242:ac11:2]:2888:3888:participant
 server.2=[2001:db8:1:0:0:242:ac11:2]:12888:13888:participant
 server.3=[2001:db8:1:0:0:242:ac11:2]:22888:23888:participant
 version=0

connect¶

连接ZooKeeper服务器。

[zkshell: 4] connect
 2019-03-09 06:43:33,179 [myid:localhost:2181] - INFO  [main-SendThread(localhost:2181):ClientCnxn$SendThread@986] - Socket connection established, initiating session, client: /127.0.0.1:35144, server: localhost/127.0.0.1:2181
 2019-03-09 06:43:33,189 [myid:localhost:2181] - INFO  [main-SendThread(localhost:2181):ClientCnxn$SendThread@1421] - Session establishment complete on server localhost/127.0.0.1:2181, sessionid = 0x10007ab7c550007, negotiated timeout = 30000
 connect "localhost:2181,localhost:2182,localhost:2183"

# 连接远程服务器
[zkshell: 5] connect remoteIP:2181

create¶

创建一个znode。

# 创建持久节点
[zkshell: 7] create /persistent_node
 Created /persistent_node

# 创建临时节点
[zkshell: 8] create -e /ephemeral_node mydata
 Created /ephemeral_node

# 创建持久顺序节点
[zkshell: 9] create -s /persistent_sequential_node mydata
 Created /persistent_sequential_node0000000176

# 创建临时顺序节点
[zkshell: 10] create -s -e /ephemeral_sequential_node mydata
 Created /ephemeral_sequential_node0000000174

# 创建带 ACL 的节点
[zkshell: 11] create /zk-node-create-schema mydata digest:user1:+owfoSBn/am19roBPzR1/MfCblE=:crwad
 Created /zk-node-create-schema
[zkshell: 12] addauth digest user1:12345
[zkshell: 13] getAcl /zk-node-create-schema
 'digest,'user1:+owfoSBn/am19roBPzR1/MfCblE=
 : cdrwa

# 容器节点：删除最后一个子节点后容器节点也会被删除
[zkshell: 14] create -c /container_node mydata
 Created /container_node
[zkshell: 15] create -c /container_node/child_1 mydata
 Created /container_node/child_1
[zkshell: 16] create -c /container_node/child_2 mydata
 Created /container_node/child_2
[zkshell: 17] delete /container_node/child_1
[zkshell: 18] delete /container_node/child_2
[zkshell: 19] get /container_node
 org.apache.zookeeper.KeeperException$NoNodeException: KeeperErrorCode = NoNode for /container_node

# TTL 节点：需 zookeeper.extendedTypesEnabled=true
# 否则报错：KeeperErrorCode = Unimplemented
[zkshell: 20] create -t 3000 /ttl_node mydata
 Created /ttl_node
# 3 秒后节点过期
[zkshell: 21] get /ttl_node
 org.apache.zookeeper.KeeperException$NoNodeException: KeeperErrorCode = NoNode for /ttl_node

delete¶

删除具有特定路径的节点。

[zkshell: 2] delete /config/topics/test
[zkshell: 3] ls /config/topics/test
 Node does not exist: /config/topics/test

deleteall¶

删除特定路径下的所有节点。

zkshell: 1] ls /config
 [changes, clients, topics]
[zkshell: 2] deleteall /config
[zkshell: 3] ls /config
 Node does not exist: /config

delquota¶

删除路径下的配额(quota)。

[zkshell: 1] delquota /quota_test
[zkshell: 2] listquota /quota_test
 absolute path is /zookeeper/quota/quota_test/zookeeper_limits
 quota for /quota_test does not exist.
[zkshell: 3] delquota -n /c1
[zkshell: 4] delquota -N /c2
[zkshell: 5] delquota -b /c3
[zkshell: 6] delquota -B /c4

get¶

获取特定路径的数据。

[zkshell: 10] get /latest_producer_id_block
 {"version":1,"broker":0,"block_start":"0","block_end":"999"}

# -s 同时显示 stat
[zkshell: 11] get -s /latest_producer_id_block
 {"version":1,"broker":0,"block_start":"0","block_end":"999"}
 cZxid = 0x90000009a
 ctime = Sat Jul 28 08:14:09 UTC 2018
 mZxid = 0x9000000a2
 mtime = Sat Jul 28 08:14:12 UTC 2018
 pZxid = 0x90000009a
 cversion = 0
 dataVersion = 1
 aclVersion = 0
 ephemeralOwner = 0x0
 dataLength = 60
 numChildren = 0

# -w 监听数据变更（需开启 printwatches）
[zkshell: 12] get -w /latest_producer_id_block
 {"version":1,"broker":0,"block_start":"0","block_end":"999"}
[zkshell: 13] set /latest_producer_id_block mydata
 WATCHER::
 WatchedEvent state:SyncConnected type:NodeDataChanged path:/latest_producer_id_block

getAcl¶

获取一条路径的ACL权限。

[zkshell: 4] create /acl_test mydata ip:127.0.0.1:crwda
 Created /acl_test
[zkshell: 5] getAcl /acl_test
 'ip,'127.0.0.1
 : cdrwa
 [zkshell: 6] getAcl /testwatch
 'world,'anyone
 : cdrwa

getAllChildrenNumber¶

获取特定路径下的所有子节点数量。

[zkshell: 1] getAllChildrenNumber /
 73779
[zkshell: 2] getAllChildrenNumber /ZooKeeper
 2
[zkshell: 3] getAllChildrenNumber /ZooKeeper/quota
 0

getEphemerals¶

获取此会话创建的所有临时节点。

[zkshell: 1] create -e /test-get-ephemerals "ephemeral node"
 Created /test-get-ephemerals
[zkshell: 2] getEphemerals
 [/test-get-ephemerals]
[zkshell: 3] getEphemerals /
 [/test-get-ephemerals]
[zkshell: 4] create -e /test-get-ephemerals-1 "ephemeral node"
 Created /test-get-ephemerals-1
[zkshell: 5] getEphemerals /test-get-ephemerals
 test-get-ephemerals     test-get-ephemerals-1
[zkshell: 6] getEphemerals /test-get-ephemerals
 [/test-get-ephemerals-1, /test-get-ephemerals]
[zkshell: 7] getEphemerals /test-get-ephemerals-1
 [/test-get-ephemerals-1]

history¶

显示您最近执行的11个命令的历史记录。

[zkshell: 7] history
 0 - close
 1 - close
 2 - ls /
 3 - ls /
 4 - connect
 5 - ls /
 6 - ll
 7 - history

listquota¶

列出一条路径的配额(quota)。

[zkshell: 1] listquota /c1
             absolute path is /zookeeper/quota/c1/zookeeper_limits
             Output quota for /c1 count=-1,bytes=-1=;byteHardLimit=-1;countHardLimit=2
             Output stat for /c1 count=4,bytes=0

ls¶

列出一条路径的子节点。

[zkshell: 36] ls /quota_test
 [child_1, child_2, child_3]

# -s 同时显示 stat
[zkshell: 37] ls -s /quota_test
 [child_1, child_2, child_3]
 cZxid = 0x110000002d
 ctime = Thu Mar 07 11:19:07 UTC 2019
 mZxid = 0x110000002d
 mtime = Thu Mar 07 11:19:07 UTC 2019
 pZxid = 0x1100000033
 cversion = 3
 dataVersion = 0
 aclVersion = 0
 ephemeralOwner = 0x0
 dataLength = 0
 numChildren = 3

# -R 递归列出子节点
[zkshell: 38] ls -R /quota_test
 /quota_test
 /quota_test/child_1
 /quota_test/child_2
 /quota_test/child_3

# -w 监听子节点变更（需开启 printwatches）
[zkshell: 39] ls -w /brokers
 [ids, seqid, topics]
[zkshell: 40] delete /brokers/ids
 WATCHER::
 WatchedEvent state:SyncConnected type:NodeChildrenChanged path:/brokers

printwatches¶

开关：是否打印 watch 事件。

[zkshell: 0] printwatches
 printwatches is on
[zkshell: 1] printwatches off
[zkshell: 2] printwatches
 printwatches is off
[zkshell: 3] printwatches on
[zkshell: 4] printwatches
 printwatches is on

quit¶

退出CLI窗口。

[zkshell: 1] quit

# WATCHER::
# WatchedEvent state:Closed type:None path:null
# 2025-06-30 23:12:37,793 [myid:] - INFO  [main:o.a.z.ZooKeeper@1232] - Session: 0x100688b50580000 closed
# 2025-06-30 23:12:37,793 [myid:] - INFO  [main-EventThread:o.a.z.ClientCnxn$EventThread@568] - EventThread shut down for session: 0x100688b50580000
# 2025-06-30 23:12:37,797 [myid:] - INFO  [main:o.a.z.u.ServiceUtils@45] - Exiting JVM with code 0

reconfig¶

运行时动态调整 ensemble 成员。使用前请阅读 Dynamic Reconfiguration 文档，尤其 Security 章节。

先决条件：

zoo.cfg 中设置 reconfigEnabled=true
配置超级用户或 skipACL，否则报 Insufficient permission（例如 addauth digest zookeeper:admin）

# 将 follower 2 改为 observer 并改端口；添加 observer 5；移除 observer 4
[zkshell: 1] reconfig --add 2=localhost:2781:2786:observer;12182 --add 5=localhost:2781:2786:observer;2185 -remove 4
 Committed new configuration:
 server.1=localhost:2780:2785:participant;0.0.0.0:2181
 server.2=localhost:2781:2786:observer;0.0.0.0:12182
 server.3=localhost:2782:2787:participant;0.0.0.0:2183
 server.5=localhost:2784:2789:observer;0.0.0.0:2185
 version=1c00000002

# -members 指定完整成员列表
[zkshell: 2] reconfig -members server.1=localhost:2780:2785:participant;0.0.0.0:2181,server.2=localhost:2781:2786:observer;0.0.0.0:12182,server.3=localhost:2782:2787:participant;0.0.0.0:12183
 Committed new configuration:
 server.1=localhost:2780:2785:participant;0.0.0.0:2181
 server.2=localhost:2781:2786:observer;0.0.0.0:12182
 server.3=localhost:2782:2787:participant;0.0.0.0:12183
 version=f9fe0000000c

# 从文件加载配置，且当前配置版本须为 2100000010
[zkshell: 3] reconfig -file /data/software/zookeeper/zookeeper-test/conf/myNewConfig.txt -v 2100000010
 Committed new configuration:
 server.1=localhost:2780:2785:participant;0.0.0.0:2181
 server.2=localhost:2781:2786:observer;0.0.0.0:12182
 server.3=localhost:2782:2787:participant;0.0.0.0:2183
 server.5=localhost:2784:2789:observer;0.0.0.0:2185
 version=220000000c

redo¶

使用历史记录中的索引重新执行命令(cmd)。

[zkshell: 4] history
 0 - ls /
 1 - get /consumers
 2 - get /hbase
 3 - ls  /hbase
 4 - history
[zkshell: 5] redo 3
 [backup-masters, draining, flush-table-proc, hbaseid, master-maintenance, meta-region-server, namespace, online-snapshot, replication, rs, running, splitWAL, switch, table, table-lock]

removewatches¶

删除节点下的监视。

[zkshell: 1] get -w /brokers
 null
[zkshell: 2] removewatches /brokers
 WATCHER::
 WatchedEvent state:SyncConnected type:DataWatchRemoved path:/brokers

set¶

设置/更新路径上的数据。

[zkshell: 50] set /brokers myNewData

# -s 同时显示 stat of this node.
[zkshell: 51] set -s /quota_test mydata_for_quota_test
 cZxid = 0x110000002d
 ctime = Thu Mar 07 11:19:07 UTC 2019
 mZxid = 0x1100000038
 mtime = Thu Mar 07 11:42:41 UTC 2019
 pZxid = 0x1100000033
 cversion = 3
 dataVersion = 2
 aclVersion = 0
 ephemeralOwner = 0x0
 dataLength = 21
 numChildren = 3

# -v 乐观锁更新，版本号来自 stat 的 dataVersion
[zkshell: 52] set -v 0 /brokers myNewData
[zkshell: 53] set -v 0 /brokers myNewData
 version No is not valid : /brokers

setAcl¶

为一个节点设置Acl权限。

[zkshell: 28] addauth digest user1:12345
[zkshell: 30] setAcl /acl_auth_test auth:user1:12345:crwad
[zkshell: 31] getAcl /acl_auth_test
 'digest,'user1:+owfoSBn/am19roBPzR1/MfCblE=
 : cdrwa

# -R 递归设置 ACL
[zkshell: 32] ls /acl_auth_test
 [child_1, child_2]
[zkshell: 33] getAcl /acl_auth_test/child_2
 'world,'anyone
 : cdrwa
[zkshell: 34] setAcl -R /acl_auth_test auth:user1:12345:crwad
[zkshell: 35] getAcl /acl_auth_test/child_2
 'digest,'user1:+owfoSBn/am19roBPzR1/MfCblE=
 : cdrwa

# -v 按 aclVersion 条件更新 ACL
[zkshell: 36] stat /acl_auth_test
 cZxid = 0xf9fc0000001c
 ctime = Tue Mar 26 16:50:58 CST 2019
 mZxid = 0xf9fc0000001c
 mtime = Tue Mar 26 16:50:58 CST 2019
 pZxid = 0xf9fc0000001f
 cversion = 2
 dataVersion = 0
 aclVersion = 3
 ephemeralOwner = 0x0
 dataLength = 0
 numChildren = 2
[zkshell: 37] setAcl -v 3 /acl_auth_test auth:user1:12345:crwad

setquota¶

在一条路径中设置配额。

# -n 限制子节点数量（软配额，超限仅告警）
[zkshell: 18] setquota -n 2 /quota_test
[zkshell: 19] create /quota_test/child_1
 Created /quota_test/child_1
[zkshell: 20] create /quota_test/child_2
 Created /quota_test/child_2
[zkshell: 21] create /quota_test/child_3
 Created /quota_test/child_3
# 软配额：仅记录 WARN，不硬拒绝
 2019-03-07 11:22:36,680 [myid:1] - WARN  [SyncThread:0:DataTree@374] - Quota exceeded: /quota_test count=3 limit=2
 2019-03-07 11:22:41,861 [myid:1] - WARN  [SyncThread:0:DataTree@374] - Quota exceeded: /quota_test count=4 limit=2

# -b 限制节点数据字节数（软配额）
[zkshell: 22] setquota -b 5 /brokers
[zkshell: 23] set /brokers "I_love_zookeeper"
# 软配额：仅记录 WARN，不硬拒绝
 WARN  [CommitProcWorkThread-7:DataTree@379] - Quota exceeded: /brokers bytes=4206 limit=5

# -N 子节点数量硬配额
[zkshell: 3] create /c1
Created /c1
[zkshell: 4] setquota -N 2 /c1
[zkshell: 5] listquota /c1
absolute path is /zookeeper/quota/c1/zookeeper_limits
Output quota for /c1 count=-1,bytes=-1=;byteHardLimit=-1;countHardLimit=2
Output stat for /c1 count=2,bytes=0
[zkshell: 6] create /c1/ch-3
Count Quota has exceeded : /c1/ch-3

# -B 字节数硬配额
[zkshell: 3] create /c2
[zkshell: 4] setquota -B 4 /c2
[zkshell: 5] set /c2 "foo"
[zkshell: 6] set /c2 "foo-bar"
Bytes Quota has exceeded : /c2
[zkshell: 7] get /c2
foo

stat¶

显示一个节点的统计/元数据。用于查看 /zookeeper 节点的状态信息。这个命令可以帮助我们了解该节点的创建时间、最后一次修改时间、版本信息以及子节点数量等重要元数据。

选项：

[-w] 可选，注册数据 watch

# stat [-w] path

# 创建此节点时的事务 zxid（zxid 是 ZooKeeper 分配给每个事务的唯一 ID）。
cZxid = 0x0
# 此节点的创建时间戳。
ctime = Thu Jan 01 08:00:00 CST 1970
# 最后一次修改此节点时的事务 zxid。
mZxid = 0x0
# 此节点最后一次修改的时间戳。
mtime = Thu Jan 01 08:00:00 CST 1970
# 此节点子节点最后一次变更（添加或删除）时的 zxid。注意，这不包括子节点数据的变化。
pZxid = 0x0
# 此节点子节点更改的次数。
cversion = -2
# 此节点数据被修改的次数。从 0 开始，每次更新增加 1。
dataVersion = 0
# 此节点访问控制列表（ACL）的版本号。每次 ACL 变更时增加。
aclVersion = 0
# 如果节点是临时节点，则为拥有该节点的会话 ID。值为 0x0 表示这是一个持久节点。
ephemeralOwner = 0x0
# 存储在此 znode 中的数据长度。此处为 0，表示没有存储任何数据。
dataLength = 0
# 此 znode 下的子节点数量。
numChildren = 2

sync¶

在领导者和追随者之间同步一个节点的数据（异步同步）。

[zk: localhost:2181(CONNECTED) 23] sync /
Sync is OK

version¶

显示ZooKeeper客户端/CLI的版本。

[zk: localhost:2181(CONNECTED) 19] version
ZooKeeper CLI version: 3.8.3-6ad6d364c7c0bcf0de452d54ebefa3058098ab56, built on 2023-10-05 10:34 UTC

whoami¶

提供添加到当前会话中的所有身份验证信息。

[zk: localhost:2181(CONNECTED) 20] whoami

# Auth scheme: User
# ip: 127.0.0.1

[zk: localhost:2181(CONNECTED) 21] addauth digest user1:12345
[zk: localhost:2181(CONNECTED) 22] whoami
# Auth scheme: User
# ip: 127.0.0.1
# digest: user1

zkServer 命令¶

服务端生命周期脚本（bin/zkServer.sh）：

bin/zkServer.sh start              # 后台启动
bin/zkServer.sh start-foreground   # 前台启动（容器/调试）
bin/zkServer.sh stop
bin/zkServer.sh restart
bin/zkServer.sh status             # 模式 standalone/leader/follower + 延迟
bin/zkServer.sh print-cmdline      # 打印 Java 启动命令

示例：

bin/zkServer.sh start
bin/zkServer.sh status

# follower 示例输出片段：
# Mode: follower
# Node count: 12345
# Latency min/avg/max: 0/1/2

Note

生产环境在 start/restart 后执行 status，确认各节点为 leader 或 follower（ensemble 中不应意外长期 standalone）。各节点 zoo.cfg 与 myid 须一致。