Apache Storm 2.8.9 常用 CLI 命令与工具详解

目标：详解 Apache Storm 2.8.9 的常用命令行工具——storm 客户端全生命周期子命令（提交、查看、停用、扩缩容、杀拓扑、读配置）、UI REST API 调用、ZooKeeper 辅助工具。所有命令与回显均在 Ubuntu 22.04.5 + Storm 2.8.9 真实环境实测。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS
Apache Storm：2.8.9（安装目录 /opt/storm）
ZooKeeper：3.8.7（/opt/zookeeper）
Java：OpenJDK 17.0.20.1（Storm 2.8.9 必须运行于 Java 17+）
Python：3.10.12（storm 命令为 Python 包装脚本）
端口：Nimbus 6627、UI 8080、Logviewer 8081、ZooKeeper 2181
示例拓扑：官方 examples/storm-starter 的 WordCountTopology（构建产物 storm-starter-2.8.9.jar）

二、工具概览

工具	位置	用途
`storm`	`/opt/storm/bin/storm`	唯一 CLI 入口：拓扑生命周期、配置读取、守护进程启动
`curl`	系统自带	调用 Storm UI REST API
`jps`	JDK 自带	查看 Java 进程（Nimbus/Supervisor/UI/Logviewer/Worker）与 JVM 参数
`netstat`	`net-tools` 包	校验 6627/8080/8081/2181 端口监听
`zkServer.sh`	`/opt/zookeeper/bin/`	ZooKeeper 服务启停与状态
`zkCli.sh`	`/opt/zookeeper/bin/`	查看 Storm 在 ZooKeeper 中的元数据节点

💡 storm 子命令清单以安装版本为准，用任一错误子命令可让 argparse 回显完整列表（见 4.1）。

三、前置条件

已安装 Storm 2.8.9 且集群可用：ZooKeeper（2181）、Nimbus（6627）、UI（8080）、Logviewer（8081）均监听，jps -l 可见对应进程。
客户端机器需与 Nimbus 6627 端口互通（提交拓扑走 Thrift RPC）。
已安装 openjdk-17-jdk-headless（含 jps）、net-tools、curl、python3。

四、工具详解

4.1 storm 命令体系总览

storm 的完整子命令清单（实测：执行 storm help 因 help 非子命令，argparse 直接回显全部选择项）：

usage: storm [-h]
             {jar,localconfvalue,remoteconfvalue,local,kill,upload-credentials,blobstore,heartbeats,activate,set_log_level,list,deactivate,rebalance,get-errors,node-health-check,kill_workers,admin,shell,repl,nimbus,pacemaker,supervisor,ui,logviewer,drpc-client,drpc,dev-zookeeper,version,classpath,server_classpath,monitor}
             ...
storm: error: argument {jar,localconfvalue,remoteconfvalue,local,kill,upload-credentials,blobstore,heartbeats,activate,set_log_level,list,deactivate,rebalance,get-errors,node-health-check,kill_workers,admin,shell,repl,nimbus,pacemaker,supervisor,ui,logviewer,drpc-client,drpc,dev-zookeeper,version,classpath,server_classpath,monitor}: invalid choice: 'help' (choose from 'jar', 'localconfvalue', 'remoteconfvalue', 'local', 'kill', 'upload-credentials', 'blobstore', 'heartbeats', 'activate', 'set_log_level', 'list', 'deactivate', 'rebalance', 'get-errors', 'node-health-check', 'kill_workers', 'admin', 'shell', 'repl', 'nimbus', 'pacemaker', 'supervisor', 'ui', 'logviewer', 'drpc-client', 'drpc', 'dev-zookeeper', 'version', 'classpath', 'server_classpath', 'monitor')

高频子命令速查：

子命令	说明
`version`	打印 Storm 版本与实际 java 启动行
`jar`	提交拓扑（打包上传 jar 至 Nimbus）
`list`	列出运行中拓扑
`activate` / `deactivate`	启用 / 暂停拓扑数据处理
`rebalance`	在线调整 Worker/Executor 分配
`kill`	移除拓扑
`localconfvalue` / `remoteconfvalue`	读本地解析配置 / 远程读 Nimbus 配置
`classpath` / `server_classpath`	打印客户端 / 服务端 classpath
`nimbus` / `supervisor` / `ui` / `logviewer`	前台启动对应守护进程

每个 storm 子命令输出前会先打印一行 Running: java ...（实际执行的 java 命令），下文回显多省略该行，聚焦有效输出。

4.2 storm version

/opt/storm/bin/storm version

实测回显：

Running: java -client -Ddaemon.name= -Dstorm.options= -Dstorm.home=/opt/storm -Dstorm.log.dir=/opt/storm/logs -Djava.library.path=/usr/local/lib:/opt/local/lib:/usr/lib:/usr/lib64 -Dstorm.conf.file= -cp /opt/storm/*:/opt/storm/lib/*:/opt/storm/extlib/*:/opt/storm/extlib-daemon/*:/opt/storm/conf org.apache.storm.utils.VersionInfo
Storm 2.8.9
Branch v2.8.9
From source with checksum dd8ab586a06db2ced58135f6be47980

4.3 storm jar 提交拓扑

/opt/storm/bin/storm jar /opt/storm/examples/storm-starter/target/storm-starter-2.8.9.jar \
  org.apache.storm.starter.WordCountTopology wordcount

实测回显（节选）：

13:11:14.355 [main] INFO  o.a.s.u.NimbusClient - Found leader nimbus : 99d6ed5a8bdf:6627:0
13:11:14.420 [main] INFO  o.a.s.StormSubmitter - Uploading dependencies - jars...
13:11:14.445 [main] INFO  o.a.s.StormSubmitter - Uploading topology jar /opt/storm/examples/storm-starter/target/storm-starter-2.8.9.jar to assigned location: /data/storm/nimbus/inbox/stormjar-de8838c4-6b7f-4dd5-8a06-f81d13299feb.jar
13:11:15.355 [main] INFO  o.a.s.StormSubmitter - Successfully uploaded topology jar to assigned location: /data/storm/nimbus/inbox/stormjar-de8838c4-6b7f-4dd5-8a06-f81d13299feb.jar
13:11:15.355 [main] INFO  o.a.s.StormSubmitter - Submitting topology wordcount in distributed mode with conf {"storm.zookeeper.topology.auth.scheme":"digest","storm.zookeeper.topology.auth.payload":"-5386753987929280264:-4889585519887821651","topology.workers":3,"topology.debug":true}
13:11:16.126 [main] INFO  o.a.s.StormSubmitter - Finished submitting topology: wordcount

常用参数：-c key=value 覆盖拓扑级配置（可多次出现），如 -c topology.workers=2 -c topology.debug=true；jar 会同时上传到 Nimbus 的 inbox（对应 storm.local.dir）。

4.4 storm list 查看拓扑

/opt/storm/bin/storm list

实测回显（wordcount 运行中）：

Topology_name        Status     Num_tasks  Num_workers  Uptime_secs  Topology_Id          Owner
----------------------------------------------------------------------------------------
wordcount            ACTIVE     28         3            33           wordcount-1-1791810675 root

无拓扑时回显最后一行为 No topologies running.。状态取值：ACTIVE（运行）/ INACTIVE（已暂停）。

4.5 storm deactivate / activate 暂停与恢复

暂停拓扑（Spout 停止发射，Worker 进程保留）：

/opt/storm/bin/storm deactivate wordcount

实测回显：

13:18:48.951 [main] INFO  o.a.s.c.Deactivate - Deactivated topology: wordcount

storm list 立即反映状态：

Topology_name        Status     Num_tasks  Num_workers  Uptime_secs  Topology_Id          Owner
----------------------------------------------------------------------------------------
wordcount            INACTIVE   28         3            24           wordcount-1-1791811110 root

恢复：

/opt/storm/bin/storm activate wordcount

实测回显：

13:19:02.876 [main] INFO  o.a.s.c.Activate - Activated topology: wordcount

4.6 storm rebalance 在线扩缩容

运行中调整 Worker 数（-n 目标 Worker 数，-w 重平衡等待秒数，-e 可按组件调 Executor）：

/opt/storm/bin/storm rebalance wordcount -w 5 -n 2

实测回显：

13:19:10.474 [main] INFO  o.a.s.c.Rebalance - Topology wordcount is rebalancing

完成后 storm list 显示 Worker 3→2：

Topology_name        Status     Num_tasks  Num_workers  Uptime_secs  Topology_Id          Owner
----------------------------------------------------------------------------------------
wordcount            ACTIVE     28         2            63           wordcount-1-1791811110 root

UI 接口同步可见（python 解析后的关键字段）：

wordcount ACTIVE workers: 2 tasks: 28

4.7 storm kill 移除拓扑

/opt/storm/bin/storm kill wordcount -w 10

实测回显（节选）：

13:12:12.909 [main] INFO  o.a.s.c.KillTopology - Killed topology: wordcount

-w 10 表示先 deactivate 并等待 10 秒（让在途消息处理完）再彻底移除；不指定用拓扑的 topology.message.timeout.secs（默认 30 秒）。稍候 storm list 显示 No topologies running.。

4.8 storm localconfvalue / remoteconfvalue 读配置

/opt/storm/bin/storm localconfvalue ui.port
/opt/storm/bin/storm localconfvalue worker.heap.memory.mb
/opt/storm/bin/storm remoteconfvalue ui.port

实测回显：

ui.port: 8080
worker.heap.memory.mb: 768
ui.port: 8080

localconfvalue 按「内置默认 → 本地 conf/storm.yaml」解析；remoteconfvalue 走 Thrift 从主 Nimbus 读集群生效值，二者可用来核对客户端与 Nimbus 配置是否一致。

4.9 storm classpath 打印 classpath

/opt/storm/bin/storm classpath

实测回显（head 前 120 字符）：

/opt/storm/*:/opt/storm/lib-worker/*:/opt/storm/extlib/*:/opt/storm/extlib-daemon/*

自研客户端程序接入 Storm 依赖时可直接引用该路径。

4.10 守护进程启动子命令

storm nimbus / storm supervisor / storm ui / storm logviewer 均为前台运行（Ctrl+C 退出），配合 nohup 或 systemd 使用。systemd 单元示例（ExecStart 直接指向对应子命令）：

[Service]
Type=simple
User=root
ExecStart=/opt/storm/bin/storm nimbus
ExecStop=/bin/kill -TERM $MAINPID
Restart=on-failure
LimitNOFILE=100000

启动后验证（jps 与端口实测回显）：

# jps -l | grep -E "Nimbus|Supervisor|UIServer|Logviewer|QuorumPeerMain"
7845 org.apache.storm.daemon.supervisor.Supervisor
8341 org.apache.storm.daemon.logviewer.LogviewerServer
7836 org.apache.storm.daemon.nimbus.Nimbus
8335 org.apache.storm.daemon.ui.UIServer
5529 org.apache.zookeeper.server.quorum.QuorumPeerMain

# netstat -tlnp | grep -E "6627|8080|8081|2181"
tcp6       0      0 :::2181                 :::*                    LISTEN      5529/java
tcp6       0      0 :::8080                 :::*                    LISTEN      8335/java
tcp6       0      0 :::8081                 :::*                    LISTEN      8341/java
tcp6       0      0 :::6627                 :::*                    LISTEN      7836/java

JVM 堆生效值核对（配置了 *.childopts: -Xms256m -Xmx512m）：

# jps -v | grep -E "Nimbus|Supervisor|UIServer|LogviewerServer" | tr ' ' '\n' | grep -E "Nimbus|Supervisor|UIServer|LogviewerServer|Xms|Xmx"
Supervisor      -Xms256m        -Xmx512m
LogviewerServer -Xms256m        -Xmx512m
Nimbus  -Xms256m        -Xmx512m
UIServer        -Xms256m        -Xmx512m

4.11 UI REST API（curl）

Storm UI 内置 REST 服务（与网页同端口 8080），无需认证的运维查询常用端点：

端点	方法	说明
`/api/v1/cluster/summary`	GET	集群摘要（版本、slots、supervisor 数）
`/api/v1/nimbus/summary`	GET	Nimbus 列表与 Leader 状态
`/api/v1/supervisor/summary`	GET	Supervisor 列表
`/api/v1/topology/summary`	GET	拓扑列表
`/api/v1/topology/<id>`	GET	单拓扑详情（组件、吞吐）

实测回显：

# curl -s http://127.0.0.1:8080/api/v1/cluster/summary
{"stormVersion":"2.8.9","fragmentedCpu":0.0,"executorsTotal":0,"totalMem":4096.0,"availCpu":400.0,"slotsTotal":4,"stormVersionInfo":{"date":"2026-07-18T15:27Z","srcChecksum":"dd8ab586a06db2ced58135f6be47980","version":"2.8.9","branch":"v2.8.9","revision":"bfc02e4b78b708492c6fbbb39be96e5a96cb7da5"},"slotsUsed":0,"bugtracker-url":null,"topologies":0,"totalCpu":400.0,"cpuAssignedPercentUtil":"0.000","availMem":4096.0,"slotsFree":4,"memAssignedPercentUtil":"0.000","availGenerics":"","totalGenerics":"","central-log-url":null,"user":null,"fragmentedMem":0.0,"tasksTotal":0,"schedulerDisplayResource":false,"supervisors":1}

# curl -s http://127.0.0.1:8080/api/v1/nimbus/summary
{"nimbuses":[{"port":6627,"host":"99d6ed5a8bdf","nimbusUpTime":"2m 40s","nimbusLogLink":"http://99d6ed5a8bdf:8081/api/v1/daemonlog?file=nimbus.log","nimbusUpTimeSeconds":160,"version":"2.8.9","status":"Leader"}]}

⚠️ 路径是 /api/v1/topology/summary（topology 单数），访问 /api/v1/topology-summary 会 404（实测）。Logviewer 同样暴露 /api/v1/daemonlog?file=<日志名> 读取守护进程日志。

4.12 ZooKeeper 辅助工具

Storm 服务管理（zkServer.sh）：

/opt/zookeeper/bin/zkServer.sh status /opt/zookeeper/conf/zoo.cfg

实测回显：

ZooKeeper JMX enabled by default
Using config: /opt/zookeeper/conf/zoo.cfg
Client port found: 2181. Client address: localhost. Client SSL: false.
Mode: standalone

查看 Storm 写入 ZooKeeper 的元数据节点（zkCli.sh）：

echo "ls /storm" | /opt/zookeeper/bin/zkCli.sh -server 127.0.0.1:2181

实测回显（连接提示略，关键行）：

[zk: 127.0.0.1:2181(CONNECTED) 0] [assignments, backpressure, blobstore, blobstoremaxkeysequencenumber, errors, leader-lock, logconfigs, nimbuses, storm, storms, supervisors, workerbeats]

💡 /storm 下 assignments（拓扑分配）、supervisors（心跳）、errors（组件错误）是最常看的三个子树；排查「Nimbus 重启后拓扑丢失」类问题时先查这些节点。ZooKeeper 仅存元数据，业务数据不在其中。

五、注意事项

storm jar 提交是阻塞式上传，拓扑 jar 越大耗时越长；部署后 jar 保存在 Nimbus storm.local.dir/nimbus/inbox/，换 Nimbus 主节点时由 ZooKeeper 协调重新定位。
kill/deactivate/rebalance 的 -w 等待期由 Nimbus 计时，等待期内重复执行会报拓扑正在处理；耐心等状态变化即可。
Worker 进程名不固定（jps -l 显示为 worker 或 storm.daemon.worker.Worker 的变体，且按端口区分），排查用端口 netstat -tlnp | grep 6700 定位 PID。
storm 命令依赖 python3 与 Java 17+，任一缺失即启动失败（报错见 FAQ）。
日志体系：守护进程日志在 /opt/storm/logs/*.log，Worker 日志在 /opt/storm/logs/workers-artifacts/<拓扑ID>/<端口>/，也可用 Logviewer（8081）网页查看。

六、常见问题

6.1：`storm` 命令报 `/usr/bin/env: 'python3': No such file or directory`

解决：安装 python3（apt-get install -y python3）。bin/storm 是 Python 包装脚本，缺解释器时还会先打印 operand 语法错误样式的噪音回显，装上 python3 即消失。

6.2：`storm version` 报 `UnsupportedClassVersionError ... class file version 61.0`

定位：运行时 JVM 低于 Java 17（Storm 2.8.9 编译目标 17）。解决：安装 openjdk-17 并切换 update-alternatives --set java /usr/lib/jvm/java-17-openjdk-amd64/bin/java，java -version 确认后再用 storm 命令。

6.3：`storm list` 报 `Found leader nimbus` 后无下文或 Connection refused

定位：Nimbus 6627 未监听。jps -l 与 netstat -tlnp | grep 6627 排查进程与端口。解决：确认 ZooKeeper 可用后启动 Nimbus（systemd：systemctl start storm-nimbus）。

6.4：kill 拓扑后 `storm list` 仍显示拓扑

定位：处于 kill 等待期（-w 秒）属正常状态流转。解决：等待等待期结束；若长时间残留，查 nimbus.log 中该拓扑的错误事件。

6.5：UI 端点 `/api/v1/topology-summary` 返回 404

解决：正确路径为 /api/v1/topology/summary（topology 单数、斜杠分隔，实测 404 复现后已更正）。

七、参考链接

Storm 2.8.9 Command-line client 文档：https://storm.apache.org/releases/2.8.9/Command-line-client.html
Storm 2.8.9 REST API 文档：https://storm.apache.org/releases/2.8.9/STORM-UI-REST-API.html
Storm 2.8.9 Understanding-the-parallelism：https://storm.apache.org/releases/2.8.9/Understanding-the-parallelism-of-a-Storm-topology.html
Apache Storm 下载：https://archive.apache.org/dist/storm/

Apache Storm 2.8.9 常用 CLI 命令与工具详解

Apache Storm 2.8.9 常用 CLI 命令与工具详解

一、环境信息

二、工具概览

三、前置条件

四、工具详解

4.1 storm 命令体系总览

4.2 storm version

4.3 storm jar 提交拓扑

4.4 storm list 查看拓扑

4.5 storm deactivate / activate 暂停与恢复

4.6 storm rebalance 在线扩缩容

4.7 storm kill 移除拓扑

4.8 storm localconfvalue / remoteconfvalue 读配置

4.9 storm classpath 打印 classpath

4.10 守护进程启动子命令

4.11 UI REST API（curl）

4.12 ZooKeeper 辅助工具

五、注意事项

六、常见问题

6.1：storm 命令报 /usr/bin/env: 'python3': No such file or directory

6.2：storm version 报 UnsupportedClassVersionError ... class file version 61.0

6.3：storm list 报 Found leader nimbus 后无下文或 Connection refused

6.4：kill 拓扑后 storm list 仍显示拓扑

6.5：UI 端点 /api/v1/topology-summary 返回 404

七、参考链接

6.1：`storm` 命令报 `/usr/bin/env: 'python3': No such file or directory`

6.2：`storm version` 报 `UnsupportedClassVersionError ... class file version 61.0`

6.3：`storm list` 报 `Found leader nimbus` 后无下文或 Connection refused

6.4：kill 拓扑后 `storm list` 仍显示拓扑

6.5：UI 端点 `/api/v1/topology-summary` 返回 404