Apache Kyuubi 1.12.0 配置参数详解

目标：系统梳理 Apache Kyuubi 1.12.0 的配置体系，包括主配置文件 kyuubi-defaults.conf、环境变量文件 kyuubi-env.sh、引擎级参数的四种传递方式，并按 Server / Frontend / 认证 / 引擎 / 会话 / 操作 / 高可用 / 指标监控分类给出参数表与生产模板。文中默认值均以 Kyuubi 1.12.0 官方文档（Configuration Settings）与发行版自带配置模板为准，关键结论均在本机实测验证。

一、环境信息

• Apache Kyuubi：1.12.0（binary 版，构建信息 Scala 2.12 / Spark 3.5.8 / Hadoop 3.4.3 / Hive 3.1.3）
• Java：OpenJDK 17.0.20.1；Spark 引擎：3.5.8（local 本地模式）
• 主配置：/opt/kyuubi/conf/kyuubi-defaults.conf；环境变量：/opt/kyuubi/conf/kyuubi-env.sh
• 参数权威参考：Kyuubi 1.12.0 官方文档 Configuration Settings（docs/configuration/settings.md，发行版 conf/kyuubi-defaults.conf.template 内含精简默认列表）
• 实测演示账号：root / q1w2e3r4

二、前置条件

1. 已按《Ubuntu 22.04 安装 Apache Kyuubi 1.12.0 指南》完成安装并启动（/opt/kyuubi，服务进程 KyuubiServer）。
2. 修改配置前建议备份：cp /opt/kyuubi/conf/kyuubi-defaults.conf /opt/kyuubi/conf/kyuubi-defaults.conf.bak。
3. 修改后重启生效：/opt/kyuubi/bin/kyuubi restart（systemd 部署用 systemctl restart kyuubi-server）。

三、参数查看与修改方式

Kyuubi 的参数分为三类作用域：

3.1 kyuubi-defaults.conf（Server 与引擎默认配置）

格式为 key 空格 value，# 开头为注释，value 不需要引号（带空格的 KV 型 value 除外）：

# Kyuubi Server
kyuubi.frontend.bind.host              0.0.0.0
kyuubi.frontend.protocols              THRIFT_BINARY,REST

# SQL engine (Spark)
kyuubi.engine.share.level              USER
spark.master                           local[*]
spark.driver.memory                    1g

原生 Spark 参数（spark.*）写在同一文件中，Kyuubi 拉起引擎时自动透传给 Spark，等效于写入 Spark 的 spark-defaults.conf。Hadoop/Hive 参数（hadoop.*、hive.*）同理透传。变更后重启 Server 生效：

/opt/kyuubi/bin/kyuubi restart

实测回显（restart 内部执行 stop + start）：

Restarting Kyuubi

3.2 kyuubi-env.sh（环境变量）

控制 Server 进程的运行环境（详见 5.9 节），由 bin/load-kyuubi-env.sh 在启动时加载，不存在时使用默认值并打印 Warn: Not find kyuubi environment file。

3.3 JDBC URL 会话级传参

在 URL 后追加 ;#key=value 可注入会话级参数，实测验证：

/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    |
+-------------------------------+--------+

3.4 SET 语句运行时修改

连接建立后可用 SET 修改当前会话参数（优先级高于引擎默认值）：

SET spark.driver.memory=2g;        -- 引擎启动前设置的参数影响引擎 JVM
SET spark.sql.shuffle.partitions=800;

3.5 用户级默认参数（多租户隔离）

Kyuubi 支持按用户定制参数，键格式为 ___用户名___.参数名（用户名前后各三个下划线），可写在 kyuubi-defaults.conf 中，对指定用户的全部会话生效：

# 用户 alice 的会话默认使用 YARN 队列 queue1
___alice___.spark.master=yarn
___alice___.spark.yarn.queue=queue1

四、参数总览（核心参数速查表）

五、核心参数分类详解

5.1 Server 服务参数

💡 实测说明：连接数限制与黑名单参数在 Server 启动时加载，配合 kyuubi.server.administrators=root,admin 可将 root、admin 加入管理用户。

5.2 Frontend 前端参数

💡 实测说明：启动日志会打印各前端绑定信息，如 Initializing KyuubiTBinaryFrontend on 0.0.0.0:10009 with [9, 999] worker threads、Exposing REST endpoint at: http://0.0.0.0:10099；Prometheus 指标端口 10019 由 Metrics 参数（5.7 节）控制。

5.3 Authentication 认证参数

⚠️ 安全提示：默认 NONE 模式下 beeline 传 -n root -p q1w2e3r4 仅将 root 作为会话用户（决定引擎共享与工作目录归属），密码不校验；生产环境务必启用 LDAP 或 KERBEROS。

5.4 Engine 引擎参数

💡 实测说明：USER 级别下首个会话触发引擎冷启动（实测约 40–60 秒，受 kyuubi.session.engine.initialize.timeout 约束，超时报引擎连接失败）；同一用户后续会话复用常驻引擎。引擎注册信息可通过 REST API 查看（见《常用 CLI 命令与工具详解》篇 kyuubi-admin 一节）。

5.5 Session 与 Operation 参数

5.6 HA 高可用参数

⚠️ 注意：1.12.0 实测未配置 kyuubi.ha.addresses 时，Server 会自动拉起内嵌 ZooKeeper 并监听 2181（日志：EmbeddedZookeeper is started at <ip>:2181，数据目录 /opt/kyuubi/embedded_zookeeper）；多实例高可用部署必须配置外部 ZooKeeper 集群。

5.7 Metrics 指标监控参数

实测验证（Prometheus 指标端口随 Server 启动，netstat -tlnp 可见 10019 监听；日志输出 Prometheus metrics HTTP server has started at http://<ip>:10019/.）：

curl -s http://localhost:10019/metrics | head -n 3

实测回显：

# HELP kyuubi_memory_usage_pools_CodeHeap__non_nmethods__max Generated from Dropwizard metric import (metric=kyuubi.memory_usage.pools.CodeHeap-'non-nmethods'.max, type=com.codahale.metrics.jvm.MemoryUsageGaugeSet$$Lambda$356/0x00007e97e0356b88)
# TYPE kyuubi_memory_usage_pools_CodeHeap__non_nmethods__max gauge
kyuubi_memory_usage_pools_CodeHeap__non_nmethods__max 5840896.0

5.8 Spark 引擎参数（原生参数透传）

Kyuubi 1.12 对 Spark 引擎的调优直接透传原生 spark.* 参数，四种设置途径（优先级从低到高）：

1. Spark 自身的 spark-defaults.conf：$SPARK_HOME/conf/spark-defaults.conf，所有引擎共享；
2. kyuubi-defaults.conf：写入 spark.xxx，该 Server 拉起的所有引擎共享；
3. JDBC URL：;#spark.xxx=yyy，单会话生效；
4. SET 语句：会话内生效，优先级最高。

常用透传参数：

用户级默认配合示例（把某用户的引擎固定到指定队列）：

___alice___.spark.master=yarn
___alice___.spark.yarn.queue=prod_queue
___bob___.spark.master=local[2]

Spark 引擎专属的 Kyuubi 参数（少量，作用于引擎行为）：

5.9 环境变量（kyuubi-env.sh）

由 bin/load-kyuubi-env.sh 加载，常用变量与映射的系统属性：

实测样例（本机实测配置，堆限制 256–512MB）：

export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export SPARK_HOME=/opt/spark-3.5.8-bin-hadoop3
export KYUUBI_LOG_DIR=/opt/kyuubi/logs
export KYUUBI_PID_DIR=/opt/kyuubi/pid
export KYUUBI_JAVA_OPTS="-Xms256m -Xmx512m -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/opt/kyuubi/logs"

jps -v 验证堆参数生效（实测回显节选）：

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

⚠️ 注意：KYUUBI_JAVA_OPTS 不要手工写 --add-opens，bin/load-kyuubi-env.sh（第 70–88 行）会自动按 JDK 版本追加全部模块开放参数。

六、生产配置模板

6.1 单机/中小规模模板（local 模式，功能验证与小团队共享）

# ===== Server =====
kyuubi.frontend.bind.host              0.0.0.0
kyuubi.frontend.protocols              THRIFT_BINARY,REST
kyuubi.authentication                  NONE
kyuubi.server.limit.connections.per.user          10
kyuubi.server.limit.connections.per.ipaddress     20

# ===== Engine =====
kyuubi.engine.type                     SPARK_SQL
kyuubi.session.engine.share.level      USER
spark.master                           local[*]
spark.driver.memory                    1g
spark.sql.shuffle.partitions           200
spark.sql.adaptive.enabled             true

# ===== Session / Operation =====
kyuubi.session.idle.timeout            PT6H
kyuubi.operation.idle.timeout          PT3H

配套 kyuubi-env.sh：

export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export SPARK_HOME=/opt/spark-3.5.8-bin-hadoop3
export KYUUBI_LOG_DIR=/opt/kyuubi/logs
export KYUUBI_PID_DIR=/opt/kyuubi/pid
export KYUUBI_JAVA_OPTS="-Xms256m -Xmx512m -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/opt/kyuubi/logs"

💡 适用场景：无 Hadoop 集群的湖仓单机、开发测试、部门级共享查询；Server 堆 512MB + 每用户引擎 Driver 1g，8GB 内存可支撑 3–5 个并发用户。

6.2 多实例 HA 模板（外部 ZooKeeper + YARN 引擎）

# ===== Server =====
kyuubi.frontend.bind.host              0.0.0.0
kyuubi.frontend.protocols              THRIFT_BINARY,REST
kyuubi.authentication                  LDAP
kyuubi.server.administrators           root,admin

# ===== HA =====
kyuubi.ha.addresses                    zk1:2181,zk2:2181,zk3:2181
kyuubi.ha.namespace                    kyuubi

# ===== Engine（YARN 模式）=====
kyuubi.engine.type                     SPARK_SQL
kyuubi.session.engine.share.level      USER
spark.master                           yarn
spark.submit.deployMode                cluster
spark.driver.memory                    2g
spark.executor.memory                  4g
spark.executor.cores                   2
spark.dynamicAllocation.enabled        true
spark.yarn.queue                       prod_queue

# ===== Engine 生命周期 =====
kyuubi.session.engine.initialize.timeout     PT5M
kyuubi.session.engine.alive.probe.enabled    true
kyuubi.session.engine.alive.probe.interval   PT10S

💡 要点：HA 模式下所有实例读写同一 ZooKeeper，客户端经 JDBC URL 连接 ZK 地址（如 jdbc:hive2://zk1:2181/;serviceDiscoveryMode=zooKeeper;zooKeeperNamespace=kyuubi）实现负载均衡与故障转移；LDAP 参数（kyuubi.ldap.*）按企业 AD/LDAP 填写。

七、常见问题（FAQ）

Q1：修改了 kyuubi-defaults.conf 但没生效？ 分三种情况：Server 级参数（如 frontend.bind.host）需 kyuubi restart；引擎级参数只对新拉起的引擎生效，旧引擎常驻，可用 kyuubi-admin 删除引擎节点或重启 Server；会话级参数优先级最高，检查是否被 JDBC URL 或 SET 覆盖。

Q2：kyuubi.engine.spark.master 配置不生效？ Kyuubi 1.12 已使用原生 Spark 参数名，应配置 spark.master（同理用 spark.driver.memory 而非 kyuubi.engine.spark.driver.memory）。旧版本文档中的 kyuubi.engine.spark.* 调优键在 1.12 已收敛为少量引擎行为参数（见 5.8 节）。

Q3：首次查询报 "Failed to connect to engine" 或超时？ 多为引擎冷启动超过了 kyuubi.session.engine.initialize.timeout（默认 PT3M）。查看引擎日志 /opt/kyuubi/work/root/kyuubi-spark-sql-engine.log.0 定位 spark-submit 失败原因；若 Spark 任务本身慢，可调大该超时。

Q4：远程客户端连接不上 10009？ 确认 kyuubi.frontend.bind.host=0.0.0.0 并重启；用 netstat -tlnp | grep 10009 确认监听 :::10009；放行防火墙后重试。若返回的 JDBC URL 是主机名而客户端无法解析，设置 kyuubi.frontend.connection.url.use.hostname=false 让服务发现返回 IP。

Q5：2181 端口是什么？可以关掉吗？ Kyuubi 1.12 在未配置 kyuubi.ha.addresses 时自动启动内嵌 ZooKeeper 用于服务发现，2181 即该进程。单机部署保留即可；要改用外部 ZK 集群，配置 kyuubi.ha.addresses 后内嵌实例不再启动。

Q6：多个用户会互相影响吗？ 默认 kyuubi.session.engine.share.level=USER 下每个用户独立引擎（独立 JVM、独立 work/<用户> 目录），互不影响；SERVER 级别共享引擎但资源互相竞争，仅适合轻量场景。引擎在 kyuubi.session.idle.timeout（默认 6 小时）无会话后自动回收。

八、参考链接

• Kyuubi 1.12.0 Configuration Settings：https://kyuubi.readthedocs.io/en/v1.12.0/configuration/settings.html
• 发行版配置模板：/opt/kyuubi/conf/kyuubi-defaults.conf.template、/opt/kyuubi/conf/kyuubi-env.sh.template
• Spark 配置参考：https://spark.apache.org/docs/3.5.8/configuration.html
• 相关文档：《Ubuntu 22.04 安装 Apache Kyuubi 1.12.0 指南》《Apache Kyuubi 1.12.0 常用 CLI 命令与工具详解》《Apache Kyuubi 1.12.0 Docker Compose 部署指南》