ZooKeeper 命令行工具完全指南：从入门到精通


🌺The Begin🌺点点关注，收藏不迷路🌺

摘要：ZooKeeper提供了两套强大的命令行工具：用于服务运维的四字命令和用于数据操作的zkCli客户端。本文将详细介绍这两套工具的常用命令、使用场景和最佳实践，通过丰富的示例和流程图，帮助读者快速掌握ZooKeeper的命令行操作。

一、ZooKeeper命令行工具概览

ZooKeeper的命令行工具主要分为两大类，它们分别服务于不同的运维和管理场景：

ZooKeeper
命令行工具

四字命令
Four Letter Words

状态查询

stat

mntr

srvr

性能监控

ruok

cons

wchs

配置查看

conf

envi

客户端命令
zkCli.sh

节点操作

create

delete

set

查询操作

get

ls

stat

监听操作

get -w

ls -w

stat -w
工具类别 适用场景 主要用途 使用方式
四字命令 服务端运维 监控集群状态、性能指标、配置信息 echo cmd | nc ip port
zkCli.sh 数据管理 增删改查ZNode、设置Watcher、权限管理 ./zkCli.sh -server ip:port

二、四字命令：服务端运维利器

四字命令（Four Letter Words）是ZooKeeper提供的一组简洁的运维命令，每个命令由4个字母组成，用于快速获取服务端状态信息。

2.1 四字命令使用准备

在ZooKeeper 3.5+版本中，四字命令默认需要通过白名单配置启用：

# conf/zoo.cfg 配置
# 允许所有四字命令
4lw.commands.whitelist=*

# 或只允许特定命令
4lw.commands.whitelist=stat, ruok, conf, cons

2.2 常用四字命令详解

2.2.1 stat - 查看节点状态

作用：显示ZooKeeper节点的概要状态信息，包括角色、延迟统计、连接数等。

# 执行命令
echo stat | nc localhost 2181

# 输出示例
Zookeeper version: 3.8.1  # ZooKeeper版本
Latency min/avg/max: 0/1/23  # 延迟统计（毫秒）
Received: 12345  # 接收的包数
Sent: 12345  # 发送的包数
Connections: 10  # 当前连接数
Outstanding: 0  # 待处理请求数
Zxid: 0x1000  # 最新事务ID
Mode: leader  # 节点角色（leader/follower/observer）
Node count: 100  # ZNode总数
2.2.2 mntr - 获取监控指标

作用：输出结构化的监控指标，适合被监控系统（如Prometheus）采集。

# 执行命令
echo mntr | nc localhost 2181

# 输出示例
zk_version  3.8.1  # 版本信息
zk_avg_latency  1  # 平均延迟
zk_max_latency  23  # 最大延迟
zk_min_latency  0  # 最小延迟
zk_packets_received  12345  # 接收包数
zk_packets_sent  12345  # 发送包数
zk_num_alive_connections  10  # 活跃连接数
zk_outstanding_requests  0  # 待处理请求
zk_server_state  leader  # 服务器状态
zk_znode_count  100  # ZNode数量
zk_watch_count  5  # Watch数量
zk_ephemerals_count  20  # 临时节点数量
zk_approximate_data_size  10240  # 数据总大小（字节）
zk_open_file_descriptor_count  100  # 打开文件描述符数
zk_max_file_descriptor_count  1024  # 最大文件描述符数
2.2.3 ruok - 存活检测

作用：检测ZooKeeper服务器是否存活，返回"imok"表示正常。

# 执行命令
echo ruok | nc localhost 2181

# 正常返回
imok

# 脚本中使用
if echo ruok | nc localhost 2181 | grep -q imok; then
    echo "ZooKeeper is healthy"
else
    echo "ZooKeeper is down"
fi
2.2.4 conf - 查看配置信息

作用：显示服务器的当前配置参数。

# 执行命令
echo conf | nc localhost 2181

# 输出示例
clientPort=2181  # 客户端连接端口
dataDir=/var/lib/zookeeper  # 数据目录
dataLogDir=/var/log/zookeeper  # 日志目录
tickTime=2000  # 基本时间单位（毫秒）
maxClientCnxns=60  # 最大客户端连接数
minSessionTimeout=4000  # 最小会话超时
maxSessionTimeout=40000  # 最大会话超时
serverId=1  # 服务器ID
initLimit=10  # 初始化同步限制
syncLimit=5  # 心跳同步限制
electionAlg=3  # 选举算法
electionPort=3888  # 选举端口
quorumPort=2888  # 集群通信端口
peerType=0  # 节点类型（0:participant, 1:observer）
2.2.5 cons - 查看客户端连接

作用：列出所有连接到本节点的客户端详细信息。

# 执行命令
echo cons | nc localhost 2181

# 输出示例
 /192.168.1.100:52345[1](queued=0,recved=100,sent=100)
 /192.168.1.101:52346[0](queued=0,recved=50,sent=50)
 
 # 字段说明
 # IP:端口[会话ID](待处理,接收包,发送包)
2.2.6 wchs - 查看Watch信息

作用：显示服务器上Watch的汇总信息。

# 执行命令
echo wchs | nc localhost 2181

# 输出示例
4 connections watching 10 paths  # 4个连接在10个路径上设置了Watch
Total watches:15  # 总Watch数量
2.2.7 其他有用命令
命令 作用 输出示例
srvr 显示服务器详细信息 类似stat，但更详细
envi 显示环境变量 Java版本、主机名、系统信息等
dump 列出未完成的会话和临时节点 会话ID和临时节点路径
dirs 显示数据目录和日志目录使用情况 log dir size, snap dir size

2.3 四字命令实战脚本

#!/bin/bash
# zk_health_check.sh - ZooKeeper集群健康检查脚本

ZOOKEEPER_SERVERS=(
    "192.168.1.10:2181"
    "192.168.1.11:2181"
    "192.168.1.12:2181"
)

check_server() {
    local server=$1
    echo "===== 检查服务器: $server ====="
    
    # 存活检查
    local ruok=$(echo ruok | nc $server 2>/dev/null)
    if [ "$ruok" == "imok" ]; then
        echo "✅ 存活检查通过"
    else
        echo "❌ 存活检查失败"
        return 1
    fi
    
    # 角色检查
    local role=$(echo stat | nc $server 2>/dev/null | grep "Mode:" | awk '{print $2}')
    echo "📊 节点角色: $role"
    
    # 延迟检查
    local latency=$(echo mntr | nc $server 2>/dev/null | grep "zk_avg_latency" | awk '{print $2}')
    if [ -n "$latency" ] && [ $latency -lt 100 ]; then
        echo "✅ 延迟正常: ${latency}ms"
    else
        echo "⚠️ 延迟过高: ${latency}ms"
    fi
    
    # 节点数检查
    local znode_count=$(echo mntr | nc $server 2>/dev/null | grep "zk_znode_count" | awk '{print $2}')
    echo "📁 ZNode数量: $znode_count"
    
    # 连接数检查
    local connections=$(echo mntr | nc $server 2>/dev/null | grep "zk_num_alive_connections" | awk '{print $2}')
    echo "🔗 活跃连接数: $connections"
    
    echo ""
}

# 主循环
for server in "${ZOOKEEPER_SERVERS[@]}"; do
    check_server $server
done

# 统计Leader数量
leader_count=0
for server in "${ZOOKEEPER_SERVERS[@]}"; do
    role=$(echo stat | nc $server 2>/dev/null | grep "Mode:" | awk '{print $2}')
    if [ "$role" == "leader" ]; then
        ((leader_count++))
    fi
done

echo "===== 集群整体状态 ====="
if [ $leader_count -eq 1 ]; then
    echo "✅ 正常: 有且仅有1个Leader"
else
    echo "❌ 异常: 检测到 $leader_count 个Leader"
fi

三、zkCli.sh客户端命令

zkCli.sh是ZooKeeper自带的交互式命令行客户端，用于连接ZooKeeper服务端并对ZNode进行增删改查操作。

3.1 连接ZooKeeper集群

# 连接到单节点
./zkCli.sh -server localhost:2181

# 连接到集群（逗号分隔）
./zkCli.sh -server zk1:2181,zk2:2181,zk3:2181

# 指定会话超时时间（毫秒）
./zkCli.sh -server localhost:2181 -timeout 5000

# 连接成功后会进入交互式命令行
[zk: localhost:2181(CONNECTED) 0]

3.2 核心命令详解

3.2.1 help - 查看帮助
[zk: localhost:2181(CONNECTED) 0] help
ZooKeeper -server host:port cmd args
  stat path [watch]
  set path data [version]
  ls path [watch]
  delquota [-n|-b] path
  ls2 path [watch]
  setAcl path acl
  setquota -n|-b val path
  history 
  redo cmdno
  printwatches on|off
  delete path [version]
  sync path
  listquota path
  rmr path
  get path [watch]
  create [-s] [-e] path data acl
  addauth scheme auth
  quit 
  getAcl path
  close 
  connect host:port
3.2.2 节点操作命令
命令 语法 功能说明 示例
create create [-s] [-e] path data 创建节点 create /my-node "hello"
delete delete path [version] 删除节点（节点必须为空） delete /my-node
deleteall deleteall path 递归删除节点及其子节点 deleteall /my-app
set set path data [version] 设置节点数据 set /my-node "world"

create命令详解：

# 创建持久节点（默认）
[zk: localhost:2181(CONNECTED) 1] create /config "db-config"
Created /config

# 创建临时节点（-e），会话结束自动删除
[zk: localhost:2181(CONNECTED) 2] create -e /temp "temporary"
Created /temp

# 创建顺序节点（-s），自动添加递增序号
[zk: localhost:2181(CONNECTED) 3] create -s /seq "sequential"
Created /seq0000000001
[zk: localhost:2181(CONNECTED) 4] create -s /seq "sequential"
Created /seq0000000002

# 创建临时顺序节点（结合-e和-s）
[zk: localhost:2181(CONNECTED) 5] create -e -s /ephemeral-seq "tmp-seq"
Created /ephemeral-seq0000000003

set命令的版本控制：

# 查看节点状态，获取当前版本
[zk: localhost:2181(CONNECTED) 6] stat /config
# 输出中包含版本号: dataVersion = 0

# 使用版本号更新（乐观锁）
[zk: localhost:2181(CONNECTED) 7] set /config "new-config" 0
# 更新成功

# 使用错误的版本号
[zk: localhost:2181(CONNECTED) 8] set /config "another-config" 0
# 失败：版本号不匹配
KeeperErrorCode = BadVersion for /config
3.2.3 查询操作命令
命令 语法 功能说明 示例
ls ls path 列出子节点 ls /
ls2 ls2 path 列出子节点并显示节点状态 ls2 /zookeeper
get get path 获取节点数据和状态 get /config
stat stat path 仅获取节点状态 stat /

ls命令示例：

# 查看根节点下的子节点
[zk: localhost:2181(CONNECTED) 9] ls /
[config, zookeeper, services]

# 查看指定路径
[zk: localhost:2181(CONNECTED) 10] ls /services
[api-gateway, user-service, order-service]

get命令输出详解：

[zk: localhost:2181(CONNECTED) 11] get /config
db-config  # 节点数据内容
cZxid = 0x100  # 创建时的事务ID
ctime = Thu Jan 01 08:00:00 CST 1970  # 创建时间
mZxid = 0x101  # 最后修改时的事务ID
mtime = Thu Jan 01 08:00:01 CST 1970  # 最后修改时间
pZxid = 0x100  # 子节点最后修改的事务ID
cversion = 0  # 子节点版本号
dataVersion = 1  # 数据版本号（修改次数）
aclVersion = 0  # ACL版本号
ephemeralOwner = 0x0  # 临时节点所有者（0表示持久节点）
dataLength = 9  # 数据长度
numChildren = 0  # 子节点数量
3.2.4 Watcher监听命令

Watcher是ZooKeeper的核心特性，可以实现事件通知机制。

命令 语法 功能说明
get -w get -w path 监听节点数据变化
stat -w stat -w path 监听节点状态变化
ls -w ls -w path 监听子节点列表变化

Watcher使用示例：

# 终端1：设置监听
[zk: localhost:2181(CONNECTED) 12] get -w /config
db-config  # 当前数据
...（状态信息）

# 终端2：修改数据触发监听
[zk: localhost:2181(CONNECTED) 13] set /config "new-value"

# 终端1：自动收到通知
WATCHER::
WatchedEvent state:SyncConnected type:NodeDataChanged path:/config

# 重要：Watcher是一次性的，需要重新设置
[zk: localhost:2181(CONNECTED) 14] get -w /config  # 重新监听

三种Watcher的区别：

Watcher类型

数据监听
get -w

节点数据变更

状态监听
stat -w

节点删除

子节点监听
ls -w

节点创建

子节点列表变更
3.2.5 其他实用命令
命令 语法 功能说明 示例
history history 查看命令历史 history
redo redo cmdno 重新执行历史命令 redo 10
sync sync path 强制同步 sync /config
close close 关闭当前连接 close
connect connect host:port 连接到其他服务器 connect zk2:2181
quit quit 退出客户端 quit

3.3 ACL权限管理命令

ZooKeeper支持基于ACL的权限控制，相关命令如下：

命令 语法 功能说明 示例
getAcl getAcl path 获取节点ACL getAcl /secure-node
setAcl setAcl path acl 设置节点ACL setAcl /secret world:anyone:r
addauth addauth scheme auth 添加认证信息 addauth digest user:password

ACL设置示例：

# 创建带ACL的节点
[zk: localhost:2181(CONNECTED) 15] create /secret "confidential"
Created /secret

# 设置只有认证用户可读写
[zk: localhost:2181(CONNECTED) 16] addauth digest admin:admin123
[zk: localhost:2181(CONNECTED) 17] setAcl /secret auth:admin:admin123:cdrwa

# 查看ACL
[zk: localhost:2181(CONNECTED) 18] getAcl /secret
'digest,'admin:W5R8ZqN7nYqY9YqY
: cdrwa

四、实战应用场景

4.1 场景一：配置管理中心

# 1. 创建配置根节点
create /app-config "application config"

# 2. 创建各个配置项
create /app-config/database "{\"host\":\"localhost\",\"port\":3306}"
create /app-config/redis "{\"host\":\"redis-server\",\"port\":6379}"
create /app-config/threadpool "{\"core\":10,\"max\":50}"

# 3. 应用节点监听配置
get -w /app-config/database

# 4. 更新配置（触发所有监听应用更新）
set /app-config/database "{\"host\":\"new-db\",\"port\":3306}"

4.2 场景二：服务注册与发现

# 1. 创建服务根节点
create /services "service registry"

# 2. 服务提供者注册（使用临时节点）
create -e /services/api-gateway-1 "192.168.1.10:8080"
create -e /services/api-gateway-2 "192.168.1.11:8080"

# 3. 服务消费者发现服务
ls /services
[api-gateway-1, api-gateway-2]

# 4. 监听服务变化
ls -w /services

4.3 场景三：分布式锁实现

# 1. 创建锁根节点
create /locks "distributed locks"

# 2. 客户端尝试获取锁（创建临时顺序节点）
create -e -s /locks/lock- "client-1"

# 3. 查看所有等待锁的客户端
ls /locks
[lock-0000000001, lock-0000000002, lock-0000000003]

# 4. 判断是否获得锁（序号最小的获得锁）
get /locks/lock-0000000001

4.4 场景四：集群监控脚本

#!/bin/bash
# zk_operation.sh - ZooKeeper日常运维脚本

ZK_CLI="/opt/zookeeper/bin/zkCli.sh -server localhost:2181"
ZK_SERVER="localhost:2181"

# 创建应用命名空间
create_namespace() {
    echo "创建应用命名空间..."
    echo "create /myapp 'myapp namespace'" | $ZK_CLI 2>/dev/null
    echo "create /myapp/config 'config center'" | $ZK_CLI 2>/dev/null
    echo "create /myapp/services 'service registry'" | $ZK_CLI 2>/dev/null
    echo "create /myapp/locks 'distributed locks'" | $ZK_CLI 2>/dev/null
}

# 备份所有节点
backup_znodes() {
    local backup_file="zk_backup_$(date +%Y%m%d).txt"
    echo "备份所有ZNode到 $backup_file"
    
    # 递归获取所有节点
    dump_znodes "/" 0 > $backup_file
}

dump_znodes() {
    local path=$1
    local indent=$2
    
    # 获取节点数据
    data=$(echo "get $path" | $ZK_CLI 2>/dev/null | head -1)
    printf "%*s%s -> %s\n" $indent "" "$path" "$data"
    
    # 获取子节点
    children=$(echo "ls $path" | $ZK_CLI 2>/dev/null | tail -1 | tr -d '[]')
    for child in $children; do
        if [ "$child" != "" ] && [ "$child" != " " ]; then
            dump_znodes "$path/$child" $((indent + 2))
        fi
    done
}

# 清理临时节点
cleanup_temp_nodes() {
    echo "清理所有临时节点..."
    echo "ls /" | $ZK_CLI 2>/dev/null | tail -1 | tr -d '[]' | while read node; do
        if [[ $node == temp-* ]] || [[ $node == ephemeral-* ]]; then
            echo "delete /$node" | $ZK_CLI 2>/dev/null
            echo "已删除: /$node"
        fi
    done
}

# 菜单
case "$1" in
    init) create_namespace ;;
    backup) backup_znodes ;;
    cleanup) cleanup_temp_nodes ;;
    *) echo "用法: $0 {init|backup|cleanup}" ;;
esac

五、命令速查表

5.1 四字命令速查

命令 作用 常用场景 示例
stat 查看节点状态 检查角色、连接数 echo stat | nc localhost 2181
mntr 获取监控指标 性能监控、告警 echo mntr | nc localhost 2181
ruok 存活检测 健康检查 echo ruok | nc localhost 2181
conf 查看配置 确认参数设置 echo conf | nc localhost 2181
cons 查看连接 排查客户端连接 echo cons | nc localhost 2181
wchs Watch统计 监控Watch数量 echo wchs | nc localhost 2181
srvr 服务器详情 详细状态信息 echo srvr | nc localhost 2181
envi 环境变量 排查环境问题 echo envi | nc localhost 2181

5.2 zkCli命令速查

命令 作用 常用选项 示例
create 创建节点 -s顺序, -e临时 create -e -s /node "data"
delete 删除节点 [version] delete /node 1
deleteall 递归删除 - deleteall /app
set 更新数据 [version] set /node "new" 2
get 获取数据 -w监听 get -w /node
ls 列出子节点 -w监听 ls -w /
stat 查看状态 -w监听 stat -w /node
getAcl 获取权限 - getAcl /secure
setAcl 设置权限 - setAcl /node world:anyone:r
addauth 添加认证 - addauth digest user:pass
sync 强制同步 - sync /path
quit 退出客户端 - quit

六、总结

ZooKeeper的命令行工具是其生态系统中的重要组成部分：

6.1 四字命令核心价值

  • 运维监控：通过stat、mntr实时掌握集群健康状态
  • 故障排查：ruok快速检测存活，cons查看客户端连接
  • 配置管理：conf确认配置参数，envi排查环境问题

6.2 zkCli.sh核心价值

  • 数据管理：create、delete、set实现完整的ZNode生命周期管理
  • 查询分析：get、ls、stat支持灵活的节点查询
  • 事件监听：-w选项实现分布式协调的核心机制
  • 权限控制：getAcl、setAcl保障数据安全

6.3 最佳实践建议

  1. 日常巡检：编写脚本定期执行四字命令，监控集群状态
  2. 故障处理：结合stat、cons、wchs快速定位问题
  3. 数据管理：使用zkCli.sh的版本控制特性避免并发更新冲突
  4. 安全管控：合理使用ACL命令，实现精细化权限控制

掌握这些命令行工具，将大大提升ZooKeeper的运维效率和问题排查能力。无论是日常管理还是故障处理，这些命令都是开发者和运维人员的必备技能。

在这里插入图片描述


🌺The End🌺点点关注，收藏不迷路🌺
# zookeeper # debian # linux
Logo
https://edu.csdn.net/learn/39067/627173?utm_source=2019755004

汇聚全球AI编程工具，助力开发者即刻编程。

更多推荐

cover

一个 API 入口调用多个大模型：AiiOnly客户端 + CC Switch 打通 Codex AI编程流程

avatar AI编程社区
cover

VSCode Claude Code + MiMo 中转免登录完整配置教程（解决原生登录弹窗 + 模型报错）

avatar AI编程社区
cover

从零开始做一个属于自己的 Skill（保姆级教程）

avatar AI编程社区