每天认识一个组件：SQL网关Apache Kyuubi

一、引言

在传统大数据平台中，Spark 是事实上的通用计算引擎之一，但直接使用 Spark API 对普通数据分析用户并不友好。用户需要理解 Scala、Java、Python、Spark 配置、YARN 或 Kubernetes 资源模型、executor 数量、内存、队列、依赖冲突等问题，这也导致使用门槛高、数据安全风险、客户端兼容性复杂和启动延迟等障碍。

Spark ThriftServer 曾经提供 HiveServer2 兼容的 Thrift/JDBC/ODBC 服务，让用户可以用 SQL 访问 Spark SQL。但 Spark ThriftServer 本质上是一个单 Spark 应用：所有连接和查询共享同一个 Driver、同一个 Spark 应用生命周期、同一个全局用户身份和资源队列，这会带来 Driver 瓶颈、资源隔离不足、多租户能力弱、高可用能力不足、UDF 影响服务稳定性等问题。

Kyuubi 的出现可以理解为数据平台服务化演进的一步：它保留 JDBC/SQL 的低门槛入口，但把后端执行环境拆成可按用户、连接或其他共享域隔离的 Engine。这样，SQL 服务不再只是"一个常驻 Spark 应用"，而是"一个网关服务管理多个可弹性创建和复用的执行引擎"。

yaml 复制代码

传统 Spark 使用路径

用户
 |
 | 需要理解代码、依赖、队列、资源、存储、权限
 v
Spark/Flink 作业提交
 |
 v
YARN / Kubernetes / HDFS / HMS / Lakehouse 表格式



Kyuubi 使用路径

用户 / BI 工具 / SQL IDE
 |
 | JDBC / ODBC / REST / SQL
 v
Kyuubi Server
 |
 | 自动管理会话、权限、Engine、资源
 v
Spark / Flink / Hive / Trino / Doris 等引擎
 |
 v
HDFS / 对象存储 / Hive Metastore / Iceberg / Hudi / Delta / Paimon 等

二、Kyuubi 是什么

Kyuubi 是一个位于客户端和计算引擎之间的统一网关，它构建在 Spark、Flink、Doris、Hive、Trino、StarRocks 等现代计算框架之上，用来查询分布在多台机器和异构数据源中的海量数据。

从用户视角看，Kyuubi 像一个"数据库服务入口"：用户通过 JDBC、ODBC、Beeline、BI 工具或 REST API 连接它，然后提交 SQL 或管理请求。从平台管理员视角看，Kyuubi 是一个"统一控制面"：认证、授权、审计、连接管理、Engine 生命周期、资源配置、高可用、服务升级都可以在服务端集中治理。

这也是 Kyuubi 与普通 SQL 引擎的区别：Kyuubi 自身并不试图替代 Spark SQL、Flink SQL 或 Trino，而是将这些引擎服务化、网关化、多租户化。

Kyuubi 的核心组件可以简化为四层：客户端层、Kyuubi Server 层、Engine 层和底层数据/资源层。Kyuubi Server 负责处理客户端连接和执行请求；连接在 Kyuubi 内部被维护为 Session，执行请求被维护为 Operation，并绑定到对应 Session。

Kyuubi 最关键的架构设计是 Server 与 Engine 的松耦合。Kyuubi Server 负责接受连接、认证用户、管理 Session 和 Operation；Engine 则是真正执行 SQL 的运行时环境，常见情况下可以理解为一个由 Kyuubi 管理的 Spark SQL 应用。这些 SparkContext 本质上是远程查询执行引擎程序，负责 SQL 编译、优化、执行，以及与 Hive Metastore、HDFS 等服务交互。

这种拆分带来两个直接收益。第一，Kyuubi Server 本身不需要在启动时占用大量集群计算资源，Kyuubi 启动时不会占用 Cluster Manager 资源，如果没有活跃 Session 与 SparkContext 交互，也会归还所有资源。第二，某个用户的 Engine 出问题，也不会直接拖垮 Kyuubi Server 或其他用户的 Engine。

yaml 复制代码

一次 SQL 请求的简化过程

Client
  |
  | 1. 打开 JDBC 连接
  v
Kyuubi Server
  |
  | 2. 认证用户，创建 Session
  v
Session
  |
  | 3. 查找该用户共享域下是否已有 Engine
  |      |
  |      +-- 有：复用 Engine
  |      |
  |      +-- 无：创建新 Engine
  v
Kyuubi Engine
  |
  | 4. 解析、优化、执行 SQL
  v
底层计算与存储系统
  |
  | 5. 返回结果
  v
Client

三、多租户隔离

Kyuubi 的多租户能力体现在控制面和数据面两个层次。控制面上，Kyuubi Server 提供集中认证层，支持 LDAP、Kerberos 等协议来保护客户端与服务端之间的通信；数据面上，Kyuubi Engine 使用经过信任的客户端身份来实例化，资源申请、数据访问和元数据访问都发生在对应 Engine 内。

与 Spark ThriftServer 的"单应用、单全局用户"模式不同，Kyuubi 可以基于客户端连接请求创建不同 Spark 应用，并将这些应用放入不同共享域中。默认情况下服务发现层中用于存储 Engine 地址的 namespace 会按用户隔离，不同用户不能跨 namespace 访问彼此的 Engine。

四、高可用与负载均衡

Kyuubi 的高可用方案依赖 ZooKeeper 做服务发现和实例注册。Kyuubi 在 HA 模式下使用 Apache ZooKeeper 管理多个冗余服务实例，当一个或多个组件发生故障时，其他服务实例可以继续提供服务。

在生产模式下，需要配置外部 ZooKeeper 集群地址 kyuubi.ha.addresses，多个 Kyuubi Server 实例注册到同一个 kyuubi.ha.namespace 对应的 ServerSpace。客户端可以在 JDBC URL 中指定 serviceDiscoveryMode=zooKeeper和 zooKeeperNamespace=kyuubi，从 ZooKeeper 中随机选择一个 Kyuubi 服务地址连接。

五、与 Spark ThriftServer 的差异

Spark ThriftServer 解决的是"让用户通过 SQL 使用 Spark"的问题，Kyuubi 进一步解决的是"如何在企业级多租户环境中稳定、安全、弹性地提供 SQL 服务"的问题。Kyuubi 在接口上与 Spark ThriftServer、HiveServer2 保持一致，但在多租户、高可用、客户端并发、权限控制和资源管理方面做了增强。

维度	Spark ThriftServer	Apache Kyuubi
服务形态	一个常驻 Spark 应用	网关服务 + 多个 Engine
Driver 压力	Driver 同时处理调度、连接和操作请求，容易成为瓶颈	Server 处理连接，Engine 执行 SQL，可横向扩展
多租户	全局单用户身份，隔离能力有限	可按用户或共享域创建/复用 Engine
资源隔离	通常绑定一个资源队列或池	Engine 可进入不同队列、namespace 或资源域
高可用	官方对比文档称社区版 Spark ThriftServer 不支持 HA	Kyuubi 支持基于 ZooKeeper 的 HA 和负载均衡
UDF 风险	UDF 加载在服务端，可能影响整个服务	UDF 在 Engine 侧加载，影响范围更可控

六、适用场景

Kyuubi 适合数据平台团队向多类用户提供统一 SQL 服务，尤其适合业务分析、即席查询、湖仓分析、ETL SQL 化、BI 接入、跨引擎服务化等场景。Kyuubi 可用于基础数据探索、Lakehouse formation and analytics、logical data warehouse 等场景，并支持通过 Spark、Iceberg 等组合用纯 SQL 构建和管理 Lakehouse。

场景	为什么适合 Kyuubi
企业级即席查询	用户通过 JDBC/SQL 访问，平台侧集中管理 Spark/Flink 等引擎
BI 工具接入	HiveServer2 兼容接口降低 BI、SQL IDE、Beeline 接入成本
多租户数据平台	不同用户或团队可拥有独立 Engine、队列和权限边界
湖仓 SQL 服务	可结合 Iceberg、Hudi、Delta Lake、Paimon 等表格式提供 SQL 分析入口
Spark ThriftServer 替代	当遇到 Driver 瓶颈、HA 不足、资源隔离困难时，Kyuubi 是自然演进方向
平台统一网关	管理员可在服务端集中处理认证、授权、配置、升级、监控等问题

Kyuubi 不一定适合所有 Spark 作业。如果业务需要复杂机器学习训练、强自定义代码逻辑、长时间流式任务或深度依赖 Spark RDD/DataFrame API，直接提交 Spark/Flink 作业可能更合适。Kyuubi 的优势主要集中在 SQL 化、服务化、多租户和平台治理场景。

七、部署与使用

下载 Kyuubi 发布包并解压，例如tar zxf apache-kyuubi-1.13.0-SNAPSHOT-bin.tgz；随后需要设置JAVA_HOME和SPARK_HOME，再执行bin/kyuubi start启动服务。服务启动成功后，可以从日志中找到 JDBC 地址，示例格式为jdbc:kyuubi://localhost:10009/。

bash 复制代码

# 1. 设置环境变量
echo 'export JAVA_HOME=/path/to/java' >> conf/kyuubi-env.sh
echo 'export SPARK_HOME=/path/to/spark' >> conf/kyuubi-env.sh

# 2. 启动 Kyuubi
bin/kyuubi start

# 3. 使用 Beeline 连接
bin/kyuubi-beeline -u 'jdbc:kyuubi://localhost:10009/' -n apache

# 4. 执行 SQL
SHOW DATABASES;

# 5. 退出连接
!quit

# 6. 停止服务
bin/kyuubi stop

生产环境通常需要重点关注 5 件事：外部 ZooKeeper、认证方式、Engine 共享级别、资源队列策略、日志与指标。生产模式需要外部 ZooKeeper 集群，并通过kyuubi.ha.addresses和kyuubi.ha.namespace配置多个 Kyuubi 实例注册到同一服务空间。

ini 复制代码

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

# Spark Engine 相关示例
spark.dynamicAllocation.enabled=true
spark.shuffle.service.enabled=true

客户端连接 HA 集群时，可以使用 ZooKeeper 服务发现模式。serviceDiscoveryMode=zooKeeper和zooKeeperNamespace=kyuubi，客户端会从指定 ZooKeeper 地址的/kyuubi路径下随机选择一个 Kyuubi 服务 URI。

bash 复制代码

bin/kyuubi-beeline \
  -u 'jdbc:kyuubi://zk1:2181,zk2:2181,zk3:2181/;serviceDiscoveryMode=zooKeeper;zooKeeperNamespace=kyuubi' \
  -n data_user

八、小结

Kyuubi 的核心价值不在于"又提供了一个 SQL 引擎"，而在于它把大数据计算引擎变成了可被统一接入、统一治理、按需弹性使用的服务。随着湖仓架构普及，数据平台越来越需要在一份数据之上同时承载 BI、即席查询、ETL 和数据服务，Kyuubi 可以作为 Spark ThriftServer、HiveServer2 或分散式作业入口之后的演进方案，尤其适合需要多租户隔离、高可用、统一 SQL 接入和 Lakehouse 服务化的环境。