Apache Uniffle 0.10.0 常用 CLI 命令与工具详解
汇总 Apache Uniffle 0.10.0 命令行工具真实用法与回显：启停脚本、uniffle 统一 CLI、client-cli 应用查询、get-metrics.py 指标采集与 REST 接口实测。
Apache Uniffle 0.10.0 常用 CLI 命令与工具详解
一、工具总览
Uniffle 0.10.0 发行包 bin 目录（按 /opt/uniffle 部署）提供以下工具，全部脚本依赖 conf/rss-env.sh 中定义的 JAVA_HOME 与 HADOOP_HOME：
| 工具 | 用途 |
|---|---|
| bin/start-coordinator.sh | 后台启动 coordinator 进程 |
| bin/stop-coordinator.sh | 停止 coordinator 进程 |
| bin/restart-coordinator.sh | 重启 coordinator 进程 |
| bin/start-shuffle-server.sh | 后台启动 shuffle-server 进程 |
| bin/stop-shuffle-server.sh | 停止 shuffle-server 进程 |
| bin/restart-shuffle-server.sh | 重启 shuffle-server 进程 |
| bin/start-dashboard.sh | 后台启动 dashboard 进程（0.10.0 新增） |
| bin/stop-dashboard.sh | 停止 dashboard 进程 |
| bin/uniffle | 统一命令行入口，子命令：coordinator、shuffle-server、client-cli、admin-cli |
| bin/get-metrics.py | 从 coordinator 或 shuffle-server 的 HTTP 端口抓取指标（python2 脚本） |
| bin/uniffle-function.sh、bin/utils.sh | 被上述脚本引用的公共函数库，不单独执行 |
进程管理机制：启动脚本用 nohup 拉起 JVM，pid 写入 /opt/uniffle/coordinator.pid、/opt/uniffle/shuffle-server.pid、/opt/uniffle/dashboard.pid；进程存在性通过 jps 按主类名判断，端口占用通过 lsof 判断。
二、前置条件
- 已按安装指南完成部署（JDK 8、Hadoop classpath 依赖、conf 三文件）。
- conf/rss-env.sh 中 JAVA_HOME 与 HADOOP_HOME 已显式定义。这是硬性前提：rss-env.sh 顶部有 set -o nounset，HADOOP_HOME 未定义时 bin/uniffle 会在内部调用 $HADOOP_HOME/bin/hadoop 处直接报 HADOOP_HOME: unbound variable 退出。
- 本文示例中 coordinator 端口为 19991（HTTP 19990）、shuffle-server 端口为 19997（HTTP 19996），均为实测端口。
三、启动与停止脚本详解
3.1 启动 coordinator
cd /opt/uniffle/bin
./start-coordinator.sh
实测回显（classpath 输出较长，此处截断）：
Check process existence
classpath: /opt/uniffle/conf:/opt/hadoop/bin/../share/hadoop/common/...:/opt/uniffle/jars/coordinator/*:/opt/uniffle/jars/common/*
Write pid file to /opt/uniffle/coordinator.pid
Starting coordinator
脚本先检查进程是否已存在（避免重复启动），再打印完整 classpath（其中 /opt/hadoop/... 部分来自 HADOOP_HOME/bin/hadoop classpath），最后以 nohup 方式拉起 JVM 并写 pid 文件。
验证：
jps -l | grep CoordinatorServer
实测回显：
5819 org.apache.uniffle.coordinator.CoordinatorServer
3.2 启动 shuffle-server
cd /opt/uniffle/bin
./start-shuffle-server.sh
实测回显与 coordinator 类似，pid 文件为 /opt/uniffle/shuffle-server.pid。启动后等待心跳注册（默认 3 秒间隔），用 coordinator HTTP 接口确认：
curl -s http://127.0.0.1:19990/api/server/nodes/summary
实测回显：
{"code":0,"data":{"ACTIVE":1},"errMsg":"success"}
3.3 停止脚本
三个 stop 脚本行为一致：读取 pid 文件，逐次向进程发送 TERM 信号，最多尝试 10 次，进程消失即认为成功。
cd /opt/uniffle/bin
./stop-shuffle-server.sh
./stop-coordinator.sh
实测回显：
Killing shuffle-server. [pid: 6008], attempt: 1
shutdown succeeded
Killing coordinator. [pid: 5819], attempt: 1
shutdown succeeded
再用 jps -l 确认两个主类已消失。若进程不响应 TERM，attempt 计数会递增直至 10，之后脚本报 shutdown failed，需要人工 kill -9 $(cat /opt/uniffle/coordinator.pid)。
3.4 重启脚本
restart-coordinator.sh 与 restart-shuffle-server.sh 等价于先执行对应 stop 再执行对应 start，用于修改 .conf 配置后使参数生效。修改 coordinator.conf 后重启 coordinator，shuffle-server 会在心跳超时前自动重连注册（实测约 15 秒内恢复 ACTIVE:1）。
四、uniffle 统一命令行工具
4.1 子命令列表
cd /opt/uniffle/bin
./uniffle -h
实测回显：
Usage: uniffle [coordinator|shuffle-server|admin-cli|client-cli] [-c conf] ...
coordinator Start CoordinatorServer.
shuffle-server Start ShuffleServer.
admin-cli Admin CLI tool.
client-cli Debug client CLI tool.
coordinator 与 shuffle-server 两个子命令是 start 脚本的等价前台启动方式（不带 -d 参数时前台运行），一般仍推荐用 start 脚本后台启动。
4.2 client-cli 应用查询（实测可用）
client-cli 通过 coordinator 的 HTTP 接口查询应用信息。注意 -port 参数应传 HTTP 端口（19990）而不是 RPC 端口，传 19991 会抛 ClientProtocolException。
cd /opt/uniffle/bin
./uniffle client-cli -host 127.0.0.1 -port 19990 -app
实测回显（表格列出 coordinator 记录的历史应用）：
+----------------------------------------+------+
| appId | user |
+----------------------------------------+------+
| local-1791787414148_468443718-6 | root |
+----------------------------------------+------+
应用列表来自 coordinator 的 /api/app/appInfos 数据，应用过期时间由 rss.coordinator.app.expired 控制。
4.3 admin-cli
admin-cli 是集群管理入口（面向 coordinator 的管理操作，如动态配置下发与集群状态查询）。
cd /opt/uniffle/bin
./uniffle admin-cli -h
0.10.0 的 admin-cli 功能面较新，具体子命令以 ./uniffle admin-cli -h 的输出为准；其内部同样通过 coordinator HTTP 接口交互，host 与 port 参数语义与 client-cli 一致。
五、get-metrics.py 指标采集脚本
bin/get-metrics.py 是官方自带的指标抓取脚本，从目标进程的 HTTP 端口（/metrics）拉取指标文本，便于接入监控脚本。脚本头部 usage：
python get-metrics.py [serverListFile] [jettyPort] [metricName]
参数说明：
| 参数 | 说明 |
|---|---|
| serverListFile | 文本文件，每行一个 host:jettyPort 地址，指向要采集的进程列表 |
| jettyPort | 各进程的 HTTP 端口（coordinator 19990、shuffle-server 19996） |
| metricName | 可选，指定单个指标名，缺省输出全部指标 |
注意：该脚本为 python2 编写（import urllib2），在只有 python3 的服务器上直接运行会报 ImportError，需自行适配或使用 curl 直接访问 /metrics。实测环境（未安装 python）改用 curl 采集：
curl -s http://127.0.0.1:19990/metrics | tr ',' '\n' | grep active_server_num
实测回显（JSON 格式指标）：
{"name":"active_server_num","labelNames":[],"labelValues":[],"value":1.0}
shuffle-server 侧（19996）同样输出 /metrics，包含 shuffle_received_bytes_size、LocalFileFlushEventThreadPool 线程池指标等。
六、coordinator HTTP REST 接口
以下接口在 0.10.0 实测可用（HTTP 端口默认 19990），是与集群交互最直接的工具，全部返回统一结构 {"code":0,"data":...,"errMsg":"success"}：
| 接口 | 用途 | 实测 data 内容 |
|---|---|---|
| /api/coordinator/info | coordinator 自身信息 | serverIp、serverPort 19991、serverWebPort 19990、version 0.10.0、gitCommitId 2df9eebe |
| /api/server/nodes | 已注册 shuffle-server 列表 | 节点 id（如 172.17.0.13-19997-17000）、usedMemory、availableMemory、storage、tags、status |
| /api/server/nodes/summary | 节点状态汇总 | {"ACTIVE":1}；心跳超时节点显示 LOST |
| /api/app/total | 应用统计 | {"appTotality":1,"appCurrent":0} |
| /api/app/appInfos | 应用明细列表 | appId 与 user 等 |
| /api/server/status | server 维度状态 | 状态对象 |
示例：
curl -s http://127.0.0.1:19990/api/app/total
curl -s http://127.0.0.1:19990/api/server/nodes | head -c 260
实测回显：
{"code":0,"data":{"appTotality":1,"appCurrent":0},"errMsg":"success"}
{"code":0,"data":[{"usedMemory":0,"preAllocatedMemory":0,"availableMemory":268435456,...,"status":"ACTIVE","tags":["GRPC_NETTY"],"id":"172.17.0.13-19997-17000",...}],"errMsg":"success"}
注意：旧版本文档中的 /api/server/list 接口在 0.10.0 已不存在，统一使用 /api/server/nodes 系列。
七、注意事项
- 所有脚本的执行路径写死了相对 RSS_HOME 的目录解析，请在 /opt/uniffle/bin 目录内执行或使用绝对路径，不要拷贝脚本到其他目录运行。
- start 脚本的进程存在性检查基于 jps 按主类名判断：JDK 只装 JRE（无 jps）时检查逻辑失效，务必安装完整 JDK；端口检查基于 lsof，精简系统需补装。
- stop 脚本只对 pid 文件中记录的进程生效；pid 文件丢失时可用 jps -l 查主类对应 pid 后手工 kill，并清理 /opt/uniffle/*.pid 再重新启动。
- client-cli 与 admin-cli 的 -port 参数均指 coordinator 的 HTTP 端口（本文 19990），与 server.conf 的 rss.coordinator.quorum 中使用的 RPC 端口（19991）不同，混用是最常见报错来源（ClientProtocolException）。
- 重启 coordinator 后 shuffle-server 需要 1 个心跳周期重新注册，期间客户端 access 会看到节点数不足，切勿在重启后立即跑 Spark 作业，建议等待 /api/server/nodes/summary 恢复 ACTIVE 后再验证。
八、常见问题
Q1：执行 ./uniffle client-cli 报 HADOOP_HOME: unbound variable。 rss-env.sh 带 set -o nounset，且 bin/uniffle 无条件调用 $HADOOP_HOME/bin/hadoop classpath。在 conf/rss-env.sh 中显式加 HADOOP_HOME=/opt/hadoop（即使不用 HDFS 也需要 Hadoop 发行包在位）。
Q2：./uniffle client-cli -host 127.0.0.1 -port 19991 -app 报 ClientProtocolException。 端口传错。-port 应为 coordinator 的 HTTP 端口（rss.jetty.http.port，本文 19990），19991 是 RPC 端口。
Q3：start-coordinator.sh 输出 Starting coordinator 但 jps 看不到进程。 查看 /opt/uniffle/logs/coordinator.out 的异常堆栈。实测最常见的三个原因：缺 Hadoop classpath（NoClassDefFoundError: org/apache/hadoop/conf/Configuration）、堆默认 8g 超过物理内存、coordinator.conf 遗留 rss.coordinator.exclude.nodes.file.path file:///xxx 占位行。
Q4：stop 脚本输出 Killing ... attempt: 1 后没有 shutdown succeeded。 进程未正常响应 TERM。等待 10 次尝试后如仍失败，用 jps -l 找到 pid 手工 kill -9，删除 pid 文件后重新启动；此情况多见于 JVM 长时间 Full GC，应在 rss-env.sh 调整堆大小与 GC 参数。
Q5：重启 coordinator 后 REST 接口短暂返回节点数为空。 coordinator 内存中的节点列表由 shuffle-server 心跳重建，重启后需等待心跳重新注册（实测约 15 秒），可用 ./uniffle client-cli -host 127.0.0.1 -port 19990 -app 或 /api/server/nodes/summary 确认恢复。
九、参考链接
- Apache Uniffle 官方文档：https://uniffle.apache.org/docs
- 项目源码仓库（bin 脚本实现）：https://github.com/apache/uniffle
- 下载页（版本与发行物）：https://uniffle.apache.org/download