Apache Helix 常用 CLI 命令与工具详解

目标：系统梳理 Apache Helix 2.0.1 发行包 bin/ 目录下的启动与运维脚本、helix-admin.sh 的核心管理命令、任务管理命令，并给出真实回显。已在 Ubuntu 22.04 服务器（/opt/helix/helix-core-2.0.1）实测验证。

一、bin 脚本清单

安装根目录下的脚本：

ls -1 /opt/helix/helix-core-2.0.1/bin/

实测回显：

helix-admin.sh
quickstart-mirror-docs.sh
quickstart.sh
run-helix-controller.sh
start-helix-participant.sh
start-standalone-zookeeper.sh
task-admin.sh
yaml-cluster-setup.sh
zk-dumper.sh
zkgrep.sh

脚本	用途
`start-standalone-zookeeper.sh`	以独立模式启动单机 ZooKeeper（端口、数据目录）
`run-helix-controller.sh`	启动集群控制器（Controller）
`start-helix-participant.sh`	启动数据节点（Participant）
`helix-admin.sh`	集群/节点/资源/配置管理（最常用）
`task-admin.sh`	任务总线（Task）管理
`quickstart.sh`	一键拉起单机演示伪集群
`yaml-cluster-setup.sh`	基于 YAML 描述文件初始化集群
`zkgrep.sh`	在 ZooKeeper 中按路径检索存储的数据
`zk-dumper.sh`	导出 ZooKeeper 数据结构快照

二、通用约定

2.1 公共参数

几乎每个命令都需 --zkSvr <连接串>（ZooKeeper 连接，见《Apache Helix 配置参数详解》）。为简化书写，先设置环境变量：

export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64
export HELIX_HOME=/opt/helix/helix-core-2.0.1
export PATH=$HELIX_HOME/bin:$PATH

💡 后文省去 export，默认已通过 /etc/profile.d/helix.sh 加载。

2.2 查看帮助

helix-admin.sh

不带参数执行时会输出全部命令用法（子命令及参数说明），当遇到参数拼写错误时同样会打印用法。

三、集群管理命令

3.1 列出集群

helix-admin.sh --zkSvr localhost:2181 --listClusters

实测回显：

Existing clusters:
helix-cluster

3.2 创建集群

helix-admin.sh --zkSvr localhost:2181 --addCluster helix-cluster

实测回显关键行：

[INFO ] [main] [org.apache.helix.manager.zk.ZKHelixAdmin:1400] - Created cluster:helix-cluster

3.3 删除集群

helix-admin.sh --zkSvr localhost:2181 --dropCluster helix-cluster

⚠️ 对不存在的集群执行 drop 会给出提示但不报致命错，因此 2.0.1 上常用「先 drop 再 add」规避 addCluster 的结构竞态。

3.4 启用/暂停集群

helix-admin.sh --zkSvr localhost:2181 --enableCluster helix-cluster true
helix-admin.sh --zkSvr localhost:2181 --enableCluster helix-cluster false

四、节点（Instance）管理命令

4.1 注册数据节点

Participant 以 host_port 命名，先注册再启动进程：

helix-admin.sh --zkSvr localhost:2181 --addNode helix-cluster localhost_7001

4.2 列出节点

helix-admin.sh --zkSvr localhost:2181 --listInstances helix-cluster

实测回显：

Instances in cluster helix-cluster:
localhost_7001

4.3 删除节点

helix-admin.sh --zkSvr localhost:2181 --dropNode helix-cluster localhost_7001

4.4 启停节点

helix-admin.sh --zkSvr localhost:2181 --enableInstance helix-cluster localhost_7001 true
helix-admin.sh --zkSvr localhost:2181 --enableInstance helix-cluster localhost_7001 false

五、资源（Resource）管理命令

资源是 Helix 管理的基本单位（如 MyDB）。

5.1 添加资源

参数：--addResource <cluster> <resource> <partition数> <StateModel>：

helix-admin.sh --zkSvr localhost:2181 --addResource helix-cluster MyDB 6 MasterSlave

5.2 重平衡

参数：--rebalance <cluster> <resource> <副本数>：

helix-admin.sh --zkSvr localhost:2181 --rebalance helix-cluster MyDB 1

⚠️ 副本数超过节点承载会报 Number of instances must not be less than replicas + 1；rebalance 用 --rebalance helix-cluster MyDB 2（2 副本，需 2 个节点）。

5.3 查看资源信息（ExternalView）

helix-admin.sh --zkSvr localhost:2181 --getResourceInfo helix-cluster MyDB

实测回显：

INFO: ResourceId:MyDB
INFO: StateModelDefRef:MasterSlave, partition numbers: 6, RebalanceMode:FULL_AUTO
BUCKET_SIZE: 0, rebalance strategy: org.apache.helix.controller.rebalancer.DelayedAutoRebalancer
ExternalView:
    MyDB_0  MASTER localhost_7001
    MyDB_1  MASTER localhost_7001
    ...

5.4 查看分区信息

helix-admin.sh --zkSvr localhost:2181 --listPartitionInfo helix-cluster MyDB

5.5 删除资源

helix-admin.sh --zkSvr localhost:2181 --dropResource helix-cluster MyDB

5.6 查看状态模型

helix-admin.sh --zkSvr localhost:2181 --listStateModel helix-cluster

实测回显：

StateModels in cluster helix-cluster:
MasterSlave
LeaderStandby
OnlineOffline
OnlineOfflineWithBootstrap
SchedulerTaskQueue
STORAGE_DEFAULT_SM_SCHEMATA
Task

5.7 添加自定义状态模型

helix-admin.sh --zkSvr localhost:2181 --addStateModelDef helix-cluster MyModel MasterSlave

六、配置管理命令

6.1 查看集群配置

helix-admin.sh --zkSvr localhost:2181 --getConfig helix-cluster

6.2 设置集群配置

helix-admin.sh --zkSvr localhost:2181 --setConfig helix-cluster controller.paused=false

6.3 设置资源配置

helix-admin.sh --zkSvr localhost:2181 --setConfig helix-cluster/MyDB bucketSize=0

💡 配置键：集群级用 --getConfig <cluster>，资源级在集群后跟 /资源名。设置后运行期热生效。

七、任务管理命令（task-admin.sh）

当集群使用 Task/SchedulerTaskQueue 状态模型时，用任务管理命令：

task-admin.sh --zkSvr localhost:2181 --help

常用子命令（示意，--help 可查精确实参）：

子命令	作用
`createTaskQueue`	创建任务队列
`listTaskQueues`	列出任务队列
`getTaskStatus`	查看任务状态
`deleteTaskQueue`	删除任务队列

八、ZooKeeper 工具

8.1 zkgrep（按路径检索数据）

用法：zkgrep.sh --zkSvr <addr> /path

zkgrep.sh --zkSvr localhost:2181 /helix-cluster/INSTANCES

8.2 zk-dumper（导出快照）

导出当前集群全部结构到目录，用于离线排查 ZooKeeper 结构与数据：

zk-dumper.sh --helixcluster helix-cluster --outdir /opt/helix/logs/zkdump

💡 zk-dumper.sh 用于离线排查 ZooKeeper 结构与数据，产出 JSON/文本快照；参数细节详见 --help。

九、quickstart（一键演示）

quickstart.sh 可在单机自动拉起 ZooKeeper+Controller+Participant 伪集群，适合快速体验：

# 在解压目录下执行（依赖 JAVA_HOME/HELIX_HOME 已配置）
cd /opt/helix/helix-core-2.0.1
./bin/quickstart.sh

💡 快捷方式便于演示，正式环境建议按《Ubuntu 22.04 安装 Apache Helix 2.0.1 指南》分步手动搭建。

十、命令速查表

功能	命令
列集群	`helix-admin --zkSvr <zk> --listClusters`
建集群	`helix-admin --zkSvr <zk> --addCluster <cluster>`
删集群	`helix-admin --zkSvr <zk> --dropCluster <cluster>`
注册节点	`helix-admin --zkSvr <zk> --addNode <cluster> <host_port>`
列节点	`helix-admin --zkSvr <zk> --listInstances <cluster>`
启停节点	`helix-admin --zkSvr <zk> --enableInstance <cluster> <node> true/false`
加资源	`helix-admin --zkSvr <zk> --addResource <c> <r> <分区数> <SM>`
重平衡	`helix-admin --zkSvr <zk> --rebalance <c> <r> <副本数>`
资源信息	`helix-admin --zkSvr <zk> --getResourceInfo <c> <r>`
状态模型	`helix-admin --zkSvr <zk> --listStateModel <c>`
集群配置	`helix-admin --zkSvr <zk> --getConfig <c> / --setConfig <c> k=v`
资源配置	`helix-admin --zkSvr <zk> --setConfig <c>/<r> k=v`

💡 示例管理账号为 root / q1w2e3r4（体验环境演示用，生产请改为强口令）。

参考链接

Apache Helix 官方文档：https://helix.apache.org/
Helix 命令工具参考：https://helix.apache.org/
Helix 发行目录：https://downloads.apache.org/helix/