Apache Kyuubi 1.12.0 常用 CLI 命令与工具详解
Apache Kyuubi 1.12.0 常用 CLI 命令与工具详解（bin/kyuubi 服务管理、kyuubi-beeline 连接查询、kyuubi-admin 节点管理、kyuubi-ctl 批处理全流程、日志与进程排查、FAQ，全部命令实测）。
Apache Kyuubi 1.12.0 常用 CLI 命令与工具详解
目标：整理 Apache Kyuubi 1.12.0 的命令行工具集——
bin/kyuubi（服务管理）、kyuubi-beeline（SQL 客户端）、kyuubi-admin（节点管理）、kyuubi-ctl（批处理与运维），以及日志与进程排查路径。本文所有命令输入与回显均在 Ubuntu 22.04 实机环境（Kyuubi 1.12.0 + Spark 3.5.8 引擎）实测通过。
一、环境信息
- Apache Kyuubi：1.12.0（安装于
/opt/kyuubi-1.12.0，软链接/opt/kyuubi，构建信息 Scala 2.12 / Spark 3.5.8 / Hadoop 3.4.3 / Hive 3.1.3） - Java：OpenJDK 17.0.20.1（
JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64）；Spark 引擎：3.5.8（local 模式） - 服务端口：10009（Thrift Binary JDBC）、10099（REST API）、10019（Prometheus 指标）、2181（内嵌 ZooKeeper）
- 服务主机名：kyuubi-u22（回显中的主机名与引擎 URL 以实际环境为准）
- 实测演示账号：root / q1w2e3r4（默认认证方式 NONE，密码不校验）
二、工具概览
Kyuubi 发行版 bin/ 目录自带的工具（ls /opt/kyuubi/bin 实测）：
beeline beeline-old docker-image-tool.sh kyuubi kyuubi-admin kyuubi-beeline kyuubi-ctl kyuubi-logo kyuubi-zk-cli load-kyuubi-env.sh stop-application.sh
| 工具 | 用途 | 使用频率 |
|---|---|---|
bin/kyuubi | Kyuubi Server 服务管理（start/stop/restart/status/run/kill） | 日常必用 |
bin/kyuubi-beeline | SQL 客户端（JDBC 连接、执行查询；旧脚本 bin/beeline 已标记废弃并自动转发） | 日常必用 |
bin/kyuubi-admin | 管理工具：查看/删除 Server 与引擎节点、刷新配置（走 REST API） | 运维常用 |
bin/kyuubi-ctl | 批处理作业提交/查询/取消/日志，服务与引擎节点管理 | 运维常用 |
bin/kyuubi-zk-cli | ZooKeeper 客户端包装，检查服务发现节点（对接外部 ZK 时使用） | 排查用 |
bin/stop-application.sh | 按 YARN applicationId 强制终止应用（需 yarn 命令） | 排查用 |
bin/load-kyuubi-env.sh | 加载 kyuubi-env.sh 与 JVM 参数（由 kyuubi 脚本内部调用） | 无需手工执行 |
bin/docker-image-tool.sh | 构建官方 Kyuubi 镜像（对应《Docker Compose 部署指南》篇） | 构建用 |
三、前置条件
- Kyuubi 已安装并可用
/opt/kyuubi/bin/kyuubi start启动（安装见《Ubuntu 22.04 安装 Apache Kyuubi 1.12.0 指南》）。 JAVA_HOME已配置（kyuubi-env.sh 或环境变量）。- 管理类工具（kyuubi-admin、kyuubi-ctl）要求 Server 的 REST 前端已启用：
kyuubi.frontend.protocols包含REST（1.12 默认已包含），端口默认 10099。 - 批处理提交示例需要 Spark 发行版（
$SPARK_HOME/examples/jars/spark-examples_2.12-3.5.8.jar，Spark 自带示例 jar）。
四、Kyuubi 服务管理（bin/kyuubi）
4.1 命令总览
/opt/kyuubi/bin/kyuubi --help
实测回显：
Usage: bin/kyuubi command
commands:
start - Run a Kyuubi server as a daemon
restart - Restart Kyuubi server as a daemon
run - Run a Kyuubi server in the foreground
stop - Stop the Kyuubi daemon
kill - Stop the Kyuubi daemon forcefully
status - Show status of the Kyuubi daemon
-h | --help - Show this help message
各子命令还支持 --conf key=value 在启动时注入配置（与 kyuubi-defaults.conf 等效，仅本次启动生效）。
4.2 启动服务（start）
/opt/kyuubi/bin/kyuubi start
实测回显（启动横幅之后第一行即日志文件路径）：
Starting org.apache.kyuubi.server.KyuubiServer, logging to /opt/kyuubi/logs/kyuubi-root-org.apache.kyuubi.server.KyuubiServer-kyuubi-u22.out
??_ _
| | | | / VVVV / ____|__ __(_) | __ \
| | | | / VVVV | (___ | | _ _ _| |__) |
| | | |/ VVVV \___ \ | | | | | | | | _ /
| | | / VVVV ____) | | | | | |_| | | | \ \
\/_/\/_/ `/___/> \/___/ \/___/ \/___/ \/_/
/\___/
\/__\/
4.3 查看状态（status）
/opt/kyuubi/bin/kyuubi status
运行中实测回显：
Kyuubi is running (pid: 8728)
已停止时实测回显：
Kyuubi is not running
💡 说明：status 通过 PID 文件
/opt/kyuubi/pid/kyuubi-root-org.apache.kyuubi.server.KyuubiServer.pid判定进程状态；ps -p <pid> -o comm=输出非 java 即认为未运行。
4.4 重启服务（restart）
/opt/kyuubi/bin/kyuubi restart
实测回显（restart 内部依次执行 stop 与 start）：
Restarting Kyuubi
随后可执行 bin/kyuubi status 确认新 PID（实测回显 Kyuubi is running (pid: 8728)）。
4.5 停止服务（stop）
/opt/kyuubi/bin/kyuubi stop
实测回显：
Stopping org.apache.kyuubi.server.KyuubiServer
⚠️ 注意：stop 先发 SIGTERM、10 秒后 SIGKILL；若进程实际已退出但状态残留（如系统未回收进程表项），可能报
Failed to stop kyuubi after 10 seconds。此时确认进程不存在后删除 PID 文件/opt/kyuubi/pid/kyuubi-root-org.apache.kyuubi.server.KyuubiServer.pid即可恢复。
4.6 前台运行与强制结束（run / kill）
bin/kyuubi run：前台模式启动（日志直接输出到终端），配合 systemd 的Type=simple或前台排障使用；容器镜像默认启动命令即./bin/kyuubi run。bin/kyuubi kill：跳过优雅停止，直接强制结束进程（相当于 kill -9，之后需手工清理 PID 文件）。
五、SQL 客户端（bin/kyuubi-beeline）
5.1 连接方式
JDBC URL 格式：jdbc:hive2://<服务地址>:10009[/库名][;#参数=值]，账号密码用 -n / -p 传入：
/opt/kyuubi/bin/kyuubi-beeline -u "jdbc:hive2://localhost:10009" -n root -p q1w2e3r4
常用参数：
| 参数 | 说明 |
|---|---|
-u <url> | JDBC 连接串 |
-n <用户名> | 会话用户（决定引擎共享与 work/<用户> 目录归属） |
-p <密码> | 密码（默认 NONE 认证下仅作占位） |
-e "<sql>" | 直接执行单条 SQL |
-f <file.sql> | 执行 SQL 脚本文件 |
💡 说明：旧脚本
bin/beeline已被标记废弃，执行时会提示使用bin/kyuubi-beeline并自动转发。
5.2 执行单条 SQL（-e）
/opt/kyuubi/bin/kyuubi-beeline -u "jdbc:hive2://localhost:10009" -n root -p q1w2e3r4 -e "SHOW DATABASES;"
实测回显（引擎已常驻时）：
+------------+
| namespace |
+------------+
| default |
+------------+
1 row selected (0.988 seconds)
Beeline version 1.12.0 by Apache Kyuubi
Closing: 0: jdbc:hive2://localhost:10009
⚠️ 注意：首次连接会触发 SQL 引擎冷启动（实测约 40–60 秒），beeline 前部会混入引擎启动 INFO 日志；引擎常驻后连接与查询为亚秒级。
5.3 执行多条 SQL（脚本方式）
/opt/kyuubi/bin/kyuubi-beeline -u "jdbc:hive2://localhost:10009" -n root -p q1w2e3r4 << 'EOSQL'
CREATE DATABASE IF NOT EXISTS testdb;
CREATE TABLE IF NOT EXISTS testdb.student (id INT, name STRING, age INT) USING parquet;
INSERT INTO testdb.student VALUES (1, "zhangsan", 20), (2, "lisi", 21);
SELECT * FROM testdb.student;
SHOW DATABASES;
EOSQL
实测回显（前三条 DDL/DML 各返回空 Result 表，随后为数据与库列表）：
+---------+
| Result |
+---------+
+---------+
+---------+
| Result |
+---------+
+---------+
+---------+
| Result |
+---------+
+---------+
+-----+-----------+------+
| id | name | age |
+-----+-----------+------+
| 1 | zhangsan | 20 |
| 2 | lisi | 21 |
+-----+-----------+------+
+------------+
| namespace |
+------------+
| default |
| testdb |
+------------+
5.4 会话级参数注入
JDBC URL 中 ;#key=value 注入会话参数，并用 SET 验证（实测回显）：
/opt/kyuubi/bin/kyuubi-beeline -u "jdbc:hive2://localhost:10009/default;#spark.sql.shuffle.partitions=200" -n root -p q1w2e3r4 -e "SET spark.sql.shuffle.partitions;"
+-------------------------------+--------+
| key | value |
+-------------------------------+--------+
| spark.sql.shuffle.partitions | 200 |
+-------------------------------+--------+
六、管理工具（bin/kyuubi-admin）
kyuubi-admin 通过 REST API（默认 http://localhost:10099）管理 Server 与引擎节点，支持 basic 认证。注意参数顺序：动作（list/delete/refresh）在前，连接选项在后。
6.1 命令总览
/opt/kyuubi/bin/kyuubi-admin --help
实测回显：
kyuubi 1.12.0
Usage: kyuubi-admin [list|delete|refresh] [options]
-b, --verbose Print additional debug output.
--hostUrl <value> Host url for rest api.
--authSchema <value> Auth schema for rest api, valid values are basic, spnego.
--username <value> Username for basic authentication.
--password <value> Password for basic authentication.
--spnegoHost <value> Spnego host for spnego authentication.
--hs2ProxyUser <value> The value of hive.server2.proxy.user config.
--conf <value> Kyuubi config property pair, formatted key=value.
Command: list [engine|server]
Command: list engine [options]
List all the engine nodes for a user
-et, --engine-type <value>
The engine type this engine belong to.
-es, --engine-subdomain <value>
The engine subdomain this engine belong to.
-esl, --engine-share-level <value>
The engine share level this engine belong to.
Command: list server
List all the server nodes
Command: delete [engine]
Delete resources.
Command: delete engine [options]
Delete the specified engine node for user.
-et, --engine-type <value>
The engine type this engine belong to.
-es, --engine-subdomain <value>
The engine subdomain this engine belong to.
-esl, --engine-share-level <value>
The engine share level this engine belong to.
Command: refresh [config] <args>...
Refresh the resource.
Command: refresh config [<configType>]
Refresh the config with specified type.
<configType> The valid config type can be one of the following: hadoopConf, userDefaultsConf, kubernetesConf, unlimitedUsers, denyUsers, denyIps.
-h, --help Show help message and exit.
6.2 查看 Server 节点（list server）
/opt/kyuubi/bin/kyuubi-admin list server --hostUrl http://localhost:10099 --username root --password q1w2e3r4
实测回显：
Server Node List (total 1)
╔═══════════╤═══════════════╤═════════════════════════╤═════════╗
║ Namespace │ Instance │ Attributes │ Status ║
╠═══════════╪═══════════════╪═════════════════════════╪═════════╣
║ /kyuubi │ 0.0.0.0:10009 │ serverUri=0.0.0.0:10009 │ Running ║
║ │ │ version=1.12.0 │ ║
║ │ │ sequence=0000000000 │ ║
╚═══════════╧═══════════════╧═════════════════════════╧═════════╝
1 row(s)
多实例 HA 部署时该表会列出全部存活实例，可用于巡检。
6.3 查看引擎节点（list engine）
需指定引擎类型与共享级别（与实际配置一致）：
/opt/kyuubi/bin/kyuubi-admin list engine --hostUrl http://localhost:10099 --username root --password q1w2e3r4 --engine-type SPARK_SQL --engine-share-level USER
实测回显（引擎 URL 端口为引擎 JVM 随机端口，每次拉起不同）：
Engine Node List (total 1)
╔════════════════════════════════════════════╤══════════════════╤═══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║ Namespace │ Instance │ Attributes ║
╠════════════════════════════════════════════╪══════════════════╪═══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╣
║ ╔════════════╤════════════╤═══════════╗ │ │ refId=9828b5da-bca1-40b6-b07e-4b8b7335fe1f ║
║ ║ EngineType │ ShareLevel │ Subdomain ║ │ │ kyuubi.engine.url=kyuubi-u22:37579 ║
║ ╠════════════╪════════════╪═══════════╣ │ │ spark.driver.memory=1g ║
║ ║ SPARK_SQL │ USER │ default ║ │ │ kyuubi.engine.id=local-1791733346234 ║
║ ╚════════════╧════════════╧═══════════╝ │ │ version=1.12.0 ║
║ │ │ sequence=0000000001 ║
║ │ │ serverUri=kyuubi-u22:34813 ║
║ │ │ spark.executor.memory= ║
╚════════════════════════════════════════════╧══════════════════╧═════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
1 row(s)
💡 实测说明：若查询结果为
(empty) / 0 row(s)，检查是否漏传--engine-type/--engine-share-level（默认引擎常驻于SPARK_SQL / USER / default域）；也可用kyuubi-beeline先跑一条 SQL 拉起引擎再查。delete engine可强制摘除指定引擎节点（下个会话会重新拉起，常用于让新引擎配置生效）。
七、批处理与运维工具（bin/kyuubi-ctl）
kyuubi-ctl 同样通过 REST API 操作，核心能力是批处理作业（batch）的提交与全生命周期管理。
7.1 命令总览
/opt/kyuubi/bin/kyuubi-ctl --help
实测回显（节选，完整输出含全部子命令）：
kyuubi 1.12.0
Usage: kyuubi-ctl [create|get|delete|list|log|submit] [options]
--hostUrl <value> Host url for rest api.
--username <value> Username for basic authentication.
--password <value> Password for basic authentication.
-f, --filename <value> Filename to use to create the resource
Command: create [batch|server] [options]
Command: get [batch|server|engine] <args>...
Command: delete [batch|server|engine] <args>...
Command: list [batch|session|server|engine]
Command: log [batch] [options] <args>...
Command: submit [batch] [options]
-h, --help Show help message and exit.
常用连接参数与 kyuubi-admin 一致：--hostUrl http://localhost:10099 --username root --password q1w2e3r4。
7.2 提交批处理（create batch）
批处理请求文件为 YAML 格式（不是 JSON），必须包含 apiVersion 与 request 两层结构，字段名为 className（注意大小写）与 configs：
cat > /tmp/spark-pi.yaml << 'EOF'
apiVersion: V1
request:
batchType: spark
name: spark-pi
resource: /opt/spark-3.5.8-bin-hadoop3/examples/jars/spark-examples_2.12-3.5.8.jar
className: org.apache.spark.examples.SparkPi
configs:
spark.master: local[*]
spark.driver.memory: 512m
args: [1000]
EOF
/opt/kyuubi/bin/kyuubi-ctl create batch -f /tmp/spark-pi.yaml --hostUrl http://localhost:10099 --username root --password q1w2e3r4
实测回显：
Batch Report (c167139e-02ee-40b4-8940-df51c0b03ced)
╔═════════════════╤══════════════════════════════════════╗
║ Key │ Value ║
╠═════════════════╪══════════════════════════════════════╣
║ Batch Id │ c167139e-02ee-40b4-8940-df51c0b03ced ║
╟─────────────────┼──────────────────────────────────────╢
║ Type │ SPARK ║
╟─────────────────┼──────────────────────────────────────╢
║ Name │ spark-pi ║
╟─────────────────┼──────────────────────────────────────╢
║ User │ root ║
╟─────────────────┼──────────────────────────────────────╢
║ State │ PENDING ║
╟─────────────────┼──────────────────────────────────────╢
╟─────────────────┼──────────────────────────────────────╢
║ Kyuubi Instance │ 0.0.0.0:10099 ║
╟─────────────────┼──────────────────────────────────────╢
║ Time Range │ 2026-10-11 15:44:21 ║
║ │ ~ ║
║ │ N/A ║
╚═════════════════╧══════════════════════════════════════╝
8 row(s)
⚠️ 踩坑记录（实测）：YAML 缺少
apiVersion时报 NPE（Cannot invoke String.toUpperCase() because the return value of Map.get(Object) is null）；字段写classname/class或配置键写conf会报classname is a required parameter for SPARK。正确字段为className与configs。
7.3 查询批处理（get batch）
/opt/kyuubi/bin/kyuubi-ctl get batch c167139e-02ee-40b4-8940-df51c0b03ced --hostUrl http://localhost:10099 --username root --password q1w2e3r4
实测回显（与 create 相同的 Batch Report 结构，可跟踪 State 从 PENDING 变化）：
Batch Report (c167139e-02ee-40b4-8940-df51c0b03ced)
╔═════════════════╤══════════════════════════════════════╗
║ Key │ Value ║
╠═════════════════╪══════════════════════════════════════╣
║ Batch Id │ c167139e-02ee-40b4-8940-df51c0b03ced ║
╟─────────────────┼──────────────────────────────────────╢
║ Type │ SPARK ║
╟─────────────────┼──────────────────────────────────────╢
║ Name │ spark-pi ║
╟─────────────────┼──────────────────────────────────────╢
║ User │ root ║
╟─────────────────┼──────────────────────────────────────╢
║ State │ PENDING ║
7.4 列出批处理（list batch）
/opt/kyuubi/bin/kyuubi-ctl list batch --hostUrl http://localhost:10099 --username root --password q1w2e3r4
实测回显（两批作业的历史，含 CANCELED 记录）：
Batch List (from 0 total 2)
╔══════════════════════════════════════╤═══════╤══════════╤══════╤══════════╤══════════════════════╤═════════════════╤═════════════════════╗
╠══════════════════════════════════════╪═══════╪══════════╪══════╪══════════╪══════════════════════╪═════════════════╪═════════════════════╣
║ eb47959b-fb4c-4456-a533-1cf118df1826 │ SPARK │ spark-pi │ root │ CANCELED │ App State: NOT_FOUND │ 0.0.0.0:10099 │ 2026-10-11 14:46:27 ║
║ │ │ │ │ │ │ │ ~ ║
║ │ │ │ │ │ │ │ 2026-10-11 14:53:36 ║
╟──────────────────────────────────────┼───────┼──────────┼──────┼──────────┼──────────────────────┼─────────────────┼─────────────────────╢
║ c167139e-02ee-40b4-8940-df51c0b03ced │ SPARK │ spark-pi │ root │ PENDING │ │ 0.0.0.0:10099 │ 2026-10-11 15:44:21 ║
║ │ │ │ │ │ │ │ ~ ║
支持过滤参数：--batchType、--batchUser、--batchState、--batchName、--size 等。
7.5 查看批处理日志（log batch）
/opt/kyuubi/bin/kyuubi-ctl log batch <批次ID> --size 100 --hostUrl http://localhost:10099 --username root --password q1w2e3r4
实测说明：作业仍在 PENDING（spark-submit 尚未落定）时该命令会报 Error: Error fetching batch logs: Api request failed for http://localhost:10099/api/v1/batches/<批次ID>/localLog?size=100&from=0；作业进入 RUNNING/FINISHED 后即可取回日志（SparkPi 成功日志关键行为 Pi is roughly 3.1416476714164765，实测输出于服务端日志 /opt/kyuubi/work/root/kyuubi-spark-batch-submit.log.0）。加 --forward 可持续跟踪。
7.6 取消批处理（delete batch）
/opt/kyuubi/bin/kyuubi-ctl delete batch <批次ID> --hostUrl http://localhost:10099 --username root --password q1w2e3r4
实测回显（提交刚落定时会被拒绝，稍后重试即可取消）：
{
"success" : false,
}
Error: Failed to delete batch c167139e-02ee-40b4-8940-df51c0b03ced, its current state is PENDING
取消成功后 list batch 中该作业 State 变为 CANCELED（实测回显见 7.4 节首行）。
💡 实测说明：本机 local 模式下 SparkPi 作业计算实际已完成（服务端日志可见 Pi 结果），但批次 State 停留在 PENDING——local 模式缺少 YARN/K8s 应用状态回传通道，属预期行为；生产批处理请对接 YARN/K8s 资源管理器，State 会正常流转 FINISHED。
7.7 服务与引擎节点操作
kyuubi-ctl 同样支持节点级操作（用法同 kyuubi-admin，ZK 直连模式下还可用 -zk <quorum> 绕过 REST）：
# 查看指定用户的引擎节点
/opt/kyuubi/bin/kyuubi-ctl get engine -u root -et SPARK_SQL -esl USER --hostUrl http://localhost:10099 --username root --password q1w2e3r4
# 删除指定引擎节点（强制重建引擎）
/opt/kyuubi/bin/kyuubi-ctl delete engine -u root -et SPARK_SQL -esl USER --hostUrl http://localhost:10099 --username root --password q1w2e3r4
# 查看在线会话
/opt/kyuubi/bin/kyuubi-ctl list session --hostUrl http://localhost:10099 --username root --password q1w2e3r4
submit batch 是 create + get + log 的组合命令，加 --waitCompletion true 时前台阻塞等待作业进入终止态。
八、其他辅助工具
8.1 kyuubi-zk-cli
ZooKeeper 客户端包装脚本，语法与 zkCli 一致，用于检查服务发现节点（对接外部 ZooKeeper 时）：
/opt/kyuubi/bin/kyuubi-zk-cli -server zk1:2181 ls /kyuubi
单机模式下 Kyuubi 使用内嵌 ZooKeeper（2181），引擎/服务节点信息也可通过 kyuubi-admin 的 REST 接口查看（见 6.2、6.3 节），无需手工连 ZK。
8.2 stop-application.sh
按 YARN applicationId 强制终止应用（内部调用 yarn application -kill，要求环境有 yarn 命令或 HADOOP_HOME）：
/opt/kyuubi/bin/stop-application.sh application_1234567890123_0001
local 模式无 YARN 时执行会报 Error: Cannot find yarn command!（实测），该脚本仅用于 YARN/K8s 生产环境的批处理善后。
九、日志与进程排查
9.1 日志文件布局
| 路径 | 内容 |
|---|---|
/opt/kyuubi/logs/kyuubi-root-org.apache.kyuubi.server.KyuubiServer-kyuubi-u22.out | Kyuubi Server 主日志（文件名格式 kyuubi-<用户>-<主类>-<主机名>.out） |
/opt/kyuubi/work/root/kyuubi-spark-sql-engine.log.0 | Spark SQL 引擎日志（root 用户的引擎，编号滚动） |
/opt/kyuubi/work/root/kyuubi-spark-batch-submit.log.0 | 批处理 spark-submit 输出日志 |
/opt/kyuubi/work/root/derby.log / metastore_db/ | 内置 Derby 元数据库日志与数据 |
/opt/kyuubi/work/root/spark-warehouse/ | local 模式下表数据落盘目录 |
/opt/kyuubi/work/server_operation_logs/<批次ID>/ | 批处理操作审计日志（按批次/操作 ID 分层） |
/opt/kyuubi/pid/ | PID 文件（kyuubi-root-org.apache.kyuubi.server.KyuubiServer.pid） |
💡 说明：多用户场景下每个用户的引擎日志在
/opt/kyuubi/work/<用户>/下；work/root仅为 root 用户示例。日志滚动由KYUUBI_MAX_LOG_FILES（默认 5）控制。
9.2 进程与 JVM 排查
# 查看 Kyuubi 相关 JVM 进程
jps
实测回显（KyuubiServer 为服务进程，SparkSubmit 为 SQL 引擎进程）：
5284 Jps
4740 KyuubiServer
4922 SparkSubmit
# 验证 JVM 启动参数（堆内存、模块开放等）
jps -v | grep KyuubiServer
实测回显（节选，可见 -Xms256m -Xmx512m）：
8728 KyuubiServer -Xms256m -Xmx512m -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/opt/kyuubi/logs -XX:+IgnoreUnrecognizedVMOptions -Dio.netty.tryReflectionSetAccessible=true --add-opens=java.base/java.lang=ALL-UNNAMED
# 查看监听端口
sudo netstat -tlnp | grep java
实测回显（10009 JDBC、10099 REST、10019 指标、2181 内嵌 ZK）：
tcp6 0 0 172.17.0.9:2181 :::* LISTEN 4740/java
tcp6 0 0 :::10099 :::* LISTEN 4740/java
tcp6 0 0 :::10009 :::* LISTEN 4740/java
tcp6 0 0 :::10019 :::* LISTEN 4740/java
9.3 典型排查路径
- 连接不上 10009：
bin/kyuubi status确认进程 →netstat确认监听与防火墙 → Server 主日志搜ERROR。 - 查询慢或引擎启动失败：
bin/kyuubi-admin list engine看引擎是否注册 →work/root/kyuubi-spark-sql-engine.log.0看引擎日志 → 检查SPARK_HOME与 Java 版本。 - 批处理 PENDING/失败：
kyuubi-ctl get batch <ID>看 State →work/root/kyuubi-spark-batch-submit.log.<N>看 spark-submit 输出 →work/server_operation_logs/<批次ID>/看审计记录。 - 配置未生效：
jps -v验证 JVM 参数 →work/root下引擎是否重建（旧引擎常驻）→ 必要时kyuubi-admin delete engine强制重建。
十、注意事项
kyuubi-admin/kyuubi-ctl的动作子命令必须放在选项之前（list server --hostUrl ...正确；--hostUrl ... list server会报Unknown argument 'list'，实测踩坑）。- REST 管理接口依赖
kyuubi.frontend.protocols包含REST；若只保留THRIFT_BINARY，管理工具将无法连接 10099。 kyuubi-ctl批处理 YAML 必须含apiVersion: V1，字段为className与configs（见 7.2 节踩坑记录）。- beeline 的
-p密码在 NONE 认证下不校验；启用 LDAP/Kerberos 后密码错误会直接拒绝连接。 bin/kyuubi run前台运行时终止终端会结束服务，生产环境请用start（systemd 管理）。
十一、常见问题（FAQ）
Q1：首次 beeline 连接为什么很慢？
首连触发 Spark 引擎冷启动（spark-submit 独立 JVM），实测约 40–60 秒；期间 tail -f /opt/kyuubi/work/root/kyuubi-spark-sql-engine.log.0 可观察进度。引擎常驻后复用。
Q2：kyuubi-ctl/kyuubi-admin 报 Unknown argument？
动作顺序问题。正确写法是 kyuubi-admin list server --hostUrl http://localhost:10099 ...，选项放在动作之后。
Q3：kyuubi-ctl create batch 报 NPE（Map.get 返回 null）？
YAML 缺少 apiVersion: V1 字段。同时确认 className（驼峰）与 configs（复数）字段名，否则会报 classname is a required parameter for SPARK。
Q4：批处理一直 PENDING、delete 也失败？
local 模式没有 YARN/K8s 应用状态回传，State 可能停在 PENDING（作业实际在本地已执行完）。刚提交时 delete batch 可能报 its current state is PENDING，稍候重试即可变为 CANCELED；生产环境请对接 YARN/K8s。日志可通过 work/root/kyuubi-spark-batch-submit.log.0 查看。
Q5：bin/kyuubi stop 提示 Failed to stop？
先确认进程是否真实存在：ps -p $(cat /opt/kyuubi/pid/kyuubi-root-org.apache.kyuubi.server.KyuubiServer.pid) -o pid,stat,comm。若进程已退出仅为状态残留，删除 PID 文件即可；若存活则 kill -9 后删除 PID 文件。
Q6：beeline 报 Connection refused？
依次确认：Server 进程存在（bin/kyuubi status）、10009 在监听（netstat -tlnp | grep 10009）、kyuubi.frontend.bind.host 设置为 0.0.0.0（远程访问时）、URL 端口与协议匹配（Thrift Binary 用 10009，不是 REST 的 10099）。
十二、参考链接
- Kyuubi 官方文档 Command Line Tools：https://kyuubi.readthedocs.io/en/v1.12.0/operations/operation_management.html
- Kyuubi REST API：https://kyuubi.readthedocs.io/en/v1.12.0/operations/rest_api.html
- Beeline 基础用法：https://cwiki.apache.org/confluence/display/Hive/HiveServer2+Clients
- 相关文档：《Ubuntu 22.04 安装 Apache Kyuubi 1.12.0 指南》《Apache Kyuubi 1.12.0 配置参数详解》《Apache Kyuubi 1.12.0 Docker Compose 部署指南》