SQL Apache Kyuubi 的多引擎统一 SQL Gateway 配置与认证集成

kyuubi 连接 hiveserver2 兼容引擎需后端暴露标准 hs2 thrift 接口并正确路由：trino 要启用 hive-server2.enabled=true 且用 thrift-server（默认10000），spark 必须用官方 spark-sql-thriftserver 并补全 hive-service-rpc 依赖；ldap 认证需服务端配置 kyuubi.authentication=ldap、客户端 jdbc url 显式加 auth=ldap、jvm 指定 jaas 路径；trino 会话不兼容需禁用 kyuubi 会话复用（idle.timeout=0ms）及 trino 端 session-check-interval=0s。

如何让 Kyuubi 连上 HiveServer2 兼容的引擎（如 Trino、Spark SQL）

Kyuubi 本身不执行 SQL，它只做协议转发和会话管理。要支持多引擎，关键不是“配置 Kyuubi”，而是让每个后端引擎暴露标准的 HiveServer2（HS2）Thrift 接口，并确保 Kyuubi 能正确路由到对应实例。

常见错误是直接把 Trino 的 http 端口（8080）或 Spark Thrift Server 的非 HS2 兼容端口填进 kyuubi.engine.spark.thrift.port —— 这会导致连接失败或协议解析异常。

• Trino 必须启用 hive-server2 协议：在 config.properties 中设 hive-server2.enabled=true，并确认启动了 thrift-server（默认端口 10000）
• Spark SQL 引擎需用官方 spark-sql-thriftserver，不是自定义的 JDBC server；Kyuubi 官方只验证过 spark-sql-thriftserver 的 HS2 兼容性
• 引擎必须开启 SASL 认证（哪怕用 NOSASL 模式），否则 Kyuubi 无法完成初始握手；检查日志中是否有 TTransportException: SASL negotiation failed

为什么 Kyuubi 的 LDAP 认证总是 fallback 到匿名登录

LDAP 配置生效的前提是 Kyuubi 启动时加载了正确的 JAAS 配置，且客户端连接时明确声明了 auth=LDAP —— 缺一不可。很多团队只改了服务端配置，却没在 JDBC URL 里加参数。

典型现象：日志显示 Authentication method: ANONYMOUS，即使 kyuubi.authentication=LDAP 已设。

• JDBC URL 必须显式带 auth=LDAP，例如：jdbc:hive2://localhost:10009/;auth=LDAP
• kyuubi.authentication=LDAP 只控制服务端是否允许该方式，不自动启用它
• JAAS 配置文件（如 kyuubi-jaas.conf）路径必须通过 JVM 参数传入：-Djava.security.auth.login.config=/path/to/kyuubi-jaas.conf，不能只放 classpath 下
• LDAP bind DN 和密码若含特殊字符（如 /、@），需 URL 编码，否则 JAAS 解析失败静默降级

Spark 引擎在 Kyuubi 下提交作业失败：ClassNotFoundException: org.apache.hive.service.cli.thrift.ThriftCLIService

这个错说明 Spark 引擎进程缺失 HiveServer2 协议栈依赖，本质是 classpath 不完整。Kyuubi 提交的是标准 HS2 请求，但 Spark 自带的 spark-sql-thriftserver 默认不打包 Hive 服务类。

根本原因不是 Kyuubi 配置错，而是 Spark 发行版选择或依赖未对齐。

• 必须使用 Apache Spark 官方二进制包（非云厂商定制版），并确认包含 hive-service-rpc 模块
• 启动 Thrift Server 时需显式加 Hive 依赖：--jars /path/to/hive-service-rpc-*.jar
• Spark 3.4+ 默认禁用 Hive 支持，需在 spark-defaults.conf 中设 spark.sql.hive.thriftServer.singleSession=true 并启用 spark.sql.hive.enableVectorizedReader=true
• 如果混用 Kyuubi 1.9+ 和 Spark 3.2，注意 hive-service-rpc 版本需与 Kyuubi 编译时的 Hive 版本一致（通常为 3.1.3），否则类签名不匹配

Trino 引擎返回 InvalidSessionHandle 或频繁断连

这是 Kyuubi 与 Trino 的会话生命周期不兼容导致的。Trino 的 HS2 实现不完全遵循 Hive 规范：它不维护长期会话状态，而 Kyuubi 默认按 Hive 模式重用会话句柄。

结果就是第一次查询成功，后续操作报 InvalidSessionHandle，或连接几秒后自动关闭。

• 必须关闭 Kyuubi 端的会话复用：设置 kyuubi.server.session.idle.timeout=0ms（禁用空闲超时） + kyuubi.server.session.check.interval=0ms
• Trino 端需设 hive-server2.session-check-interval=0s，否则其内部会清理“过期”会话
• 避免在同一个 Kyuubi session 中跨多个 Trino catalog 查询；Trino 的 HS2 对 catalog 切换支持弱，容易触发状态不一致
• 不要用 Kyuubi 的 SET 命令去改 Trino 特有会话属性（如 set session join_distribution_type = 'broadcast'），Trino 不识别 Hive 风格的 SET 协议字段

多引擎统一的关键不在 Kyuubi 多配几个参数，而在于每个后端是否真正符合 HS2 协议语义 —— 表面能连上，不等于能稳定跑完复杂查询。协议细节偏差往往在并发或长会话时才暴露。