Apache Kyuubi 1.12.0 Docker Compose 部署指南

目标：使用官方镜像 apache/kyuubi:1.12.0 通过 Docker Compose 快速部署 Apache Kyuubi，挂载 Spark 3.5.8 作为 SQL 引擎，完成数据持久化配置，并用 kyuubi-beeline 通过 jdbc:hive2://localhost:10009 完成 SQL 全链路验证。本文全部命令与回显均在 Docker 29.8.1 + Compose v2 实测环境验证通过。

一、环境信息

Docker：29.8.1 / Docker Compose：v5.5.1
镜像：apache/kyuubi:1.12.0（digest sha256:dc5fa35defda018887ae6867e573fe62a502b96fe0b960d5176f5b88c651d823，约 1.66GB）
SQL 引擎：Spark 3.5.8（宿主机目录 ./spark 以只读方式挂载进容器）
部署目录：/opt/data/quzuo/kyuubi-compose
容器名：kyuubi-server（hostname 同名，容器内日志与主机名一致）
映射端口：10009（Thrift Binary JDBC）、10099（REST API）
数据卷：kyuubi-compose_kyuubi-logs（日志）、kyuubi-compose_kyuubi-work（引擎工作目录与元数据，实现持久化）
实测演示账号：root / q1w2e3r4（Kyuubi 默认认证方式为 NONE，不校验密码，密码仅按客户端惯例传入）

二、镜像选型说明

Kyuubi 官方在 Docker Hub 提供 apache/kyuubi 镜像，与源码版本同步发布。1.12.0 镜像的关键特性（实测 docker inspect 与启动日志确认）：

项目	实测值	说明
镜像 tag	1.12.0	与社区最新稳定版一致
基础 JDK	Eclipse Temurin 8（`1.8.0_492`）	启动日志 Version 行显示 Java: 1.8.0_492，Kyuubi 1.12 支持 Java 8
运行用户	10009（kyuubi）	非 root 运行，挂载目录注意权限
默认启动命令	`./bin/kyuubi run`	前台运行模式，适配容器
内置 Spark	无	镜像未内置 Spark 发行版，必须通过挂载目录 + `SPARK_HOME` 环境变量提供
服务发现	内嵌 ZooKeeper（2181，仅容器内）	未配置外部 `kyuubi.ha.addresses` 时自动启动，无需映射到宿主机
暴露端口	10009 / 10099	Thrift Binary（JDBC）与 REST 前端

⚠️ 关键结论：官方镜像不带 Spark，若不挂载 SPARK_HOME，SQL 引擎无法启动（beeline 首次查询会一直报引擎连接失败）。本文方案为：宿主机准备 Spark 3.5.8 目录，挂载到容器 /opt/spark 并注入 SPARK_HOME=/opt/spark。

三、前置条件

已安装 Docker 24+ 与 Docker Compose v2 插件（docker compose version 可执行）。
宿主机可访问国内镜像站（下载 Spark 包）与 Docker Hub（或已配置镜像加速拉取 apache/kyuubi）。
宿主机端口 10009、10099 未被占用。
磁盘空间 ≥ 3GB（镜像 1.66GB + Spark 383MB 压缩包 + 运行数据）。

四、部署步骤

4.1 目录规划

mkdir -p /opt/data/quzuo/kyuubi-compose/conf
cd /opt/data/quzuo/kyuubi-compose

最终目录结构：

conf/               # Kyuubi 配置文件（kyuubi-defaults.conf），挂载为容器 /opt/kyuubi/conf
docker-compose.yml  # 编排文件
spark/              # Spark 3.5.8 发行版目录，挂载为容器 /opt/spark

4.2 准备 Spark 引擎发行版

下载 Spark 3.5.8 并解压到部署目录（约 383MB）：

cd /opt/data/quzuo/kyuubi-compose
wget http://mirror.nju.edu.cn/apache/spark/spark-3.5.8/spark-3.5.8-bin-hadoop3.tgz
tar zxf spark-3.5.8-bin-hadoop3.tgz
mv spark-3.5.8-bin-hadoop3 spark
rm spark-3.5.8-bin-hadoop3.tgz
ls

实测回显：

conf  spark

💡 说明：Spark 包 sha512 实测值 5d5d2e6e111182ee1210d4a46a17ae27107c7ccc70433da0ded3d8197e027f949b00445bb5678ed0c1d5c59f12993d9b9ed12e43686d5aad89a9ec570e93a083；Kyuubi 1.12.0 官方支持 Spark 3.3–3.5、4.0–4.2，其中 3.5.8 为其默认构建版本（Scala 2.12），兼容性最好。

4.3 编写 Kyuubi 配置文件

创建 conf/kyuubi-defaults.conf（容器内 /opt/kyuubi/conf 目录本身为空，直接写入即可）：

cat > conf/kyuubi-defaults.conf << 'EOF'
kyuubi.frontend.bind.host              0.0.0.0
kyuubi.engine.share.level              USER
spark.master                           local[*]
EOF

参数说明：

参数	取值	说明
`kyuubi.frontend.bind.host`	0.0.0.0	监听容器内所有网卡，确保端口映射后宿主机可访问
`kyuubi.engine.share.level`	USER	同用户共享一个 SQL 引擎（默认值）
`spark.master`	local[*]	Spark 引擎本地模式，无需外部 YARN/K8s

4.4 编写 docker-compose.yml

cat > docker-compose.yml << 'EOF'
services:
  kyuubi:
    image: apache/kyuubi:1.12.0
    container_name: kyuubi-server
    hostname: kyuubi-server
    restart: unless-stopped
    environment:
      - SPARK_HOME=/opt/spark
      - KYUUBI_JAVA_OPTS=-Xms256m -Xmx512m
    ports:
      - "10009:10009"
      - "10099:10099"
    volumes:
      - ./spark:/opt/spark:ro
      - ./conf:/opt/kyuubi/conf:ro
      - kyuubi-logs:/opt/kyuubi/logs
      - kyuubi-work:/opt/kyuubi/work

volumes:
  kyuubi-logs:
  kyuubi-work:
EOF

编排要点：

配置项	说明
`container_name` / `hostname`	固定容器名与主机名，便于日志定位与服务发现一致性
`environment: SPARK_HOME`	指向挂载进来的 Spark 目录，引擎据此调用 spark-submit
`environment: KYUUBI_JAVA_OPTS`	Kyuubi Server 进程 JVM 参数，本例堆限制 256–512MB
`./spark:/opt/spark:ro`	只读挂载 Spark 发行版
`./conf:/opt/kyuubi/conf:ro`	只读挂载配置目录（镜像内该目录为空）
`kyuubi-logs` / `kyuubi-work`	命名卷，持久化日志与引擎工作目录（含 Derby 元数据、表数据、引擎日志）

⚠️ 注意：镜像默认运行用户为 10009。命名卷首次挂载时会继承镜像内目录权限，无需手工 chown；若改用 bind mount 持久化 work 目录，需在宿主机执行 chown -R 10009:10009 <目录>。

4.5 启动服务

docker compose up -d

实测回显：

 Volume kyuubi-compose_kyuubi-work Created
 Volume kyuubi-compose_kyuubi-work Created
 Network kyuubi-compose_default Created
 Network kyuubi-compose_default Created
 Container kyuubi-server Creating
 Container kyuubi-server Created
 Container kyuubi-server Starting
 Container kyuubi-server Started

4.6 验证部署

（1）查看容器状态：

docker compose ps

实测回显：

NAME            IMAGE                  STATUS         PORTS
kyuubi-server   apache/kyuubi:1.12.0   Up 6 seconds   0.0.0.0:10009->10009/tcp, [::]:10009->10009/tcp, 0.0.0.0:10099->10099/tcp, [::]:10099->10099/tcp

（2）查看启动日志，确认版本与前端监听：

docker compose logs kyuubi | grep -E "Version:|Initializing KyuubiTBinary|Exposing REST endpoint"

实测回显：

kyuubi-server  | 2026-10-11 15:25:24.007 INFO main org.apache.kyuubi.server.KyuubiServer: Version: 1.12.0, Revision: d32be1f2deb34650f72f9e06802f1bbcd6626e7c (2026-07-28 18:34:11 +0800), Branch: HEAD, Java: 1.8.0_492, Scala: 2.12, Spark: 3.5.8, Hadoop: 3.4.3, Hive: 3.1.3, Flink: 1.20.5, Trino: 411
kyuubi-server  | 2026-10-11 15:25:27.436 INFO main org.apache.kyuubi.server.KyuubiTBinaryFrontendService: Initializing KyuubiTBinaryFrontend on kyuubi-server:10009 with [9, 999] worker threads
kyuubi-server  | 2026-10-11 15:25:29.328 INFO main org.apache.kyuubi.server.KyuubiRestFrontendService: Exposing REST endpoint at: http://kyuubi-server:10099

💡 说明：未挂载 conf 时日志显示 Initializing KyuubiTBinaryFrontend on kyuubi-server:10009；按 4.3 配置 kyuubi.frontend.bind.host=0.0.0.0 后该行显示为 on 0.0.0.0:10009（实测），远程访问即正常。另外镜像内没有 kyuubi-env.sh，启动时会输出 Warn: Not find kyuubi environment file /opt/kyuubi/conf/kyuubi-env.sh, using default ones...，属正常现象，环境变量通过 compose 的 environment: 注入即可。

（3）beeline 连接验证（在容器内执行 kyuubi-beeline；首次连接拉起 Spark 引擎，约需 40–60 秒）：

docker compose exec kyuubi ./bin/kyuubi-beeline -u "jdbc:hive2://localhost:10009" -n root -p q1w2e3r4 -e "SELECT 1 AS ok;"

实测回显：

Warn: Not find kyuubi environment file /opt/kyuubi/conf/kyuubi-env.sh, using default ones...
+-----+
| ok  |
+-----+
| 1   |
+-----+

宿主机上也可通过映射端口直连（需本机装有 beeline 类客户端）：

jdbc:hive2://<宿主机IP>:10009

（4）SQL 全链路验证（建库、建表、插入、查询）：

docker compose exec kyuubi bash -c './bin/kyuubi-beeline -u "jdbc:hive2://localhost:10009" -n root -p q1w2e3r4 << "EOSQL"
CREATE DATABASE IF NOT EXISTS compose_test;
CREATE TABLE IF NOT EXISTS compose_test.t1 (id INT, val STRING) USING parquet;
INSERT INTO compose_test.t1 VALUES (101, "compose-ok");
SELECT * FROM compose_test.t1;
EOSQL'

实测回显（DDL/DML 返回空 Result 表，此处省略前两条空表回显，仅保留查询结果）：

+------+-------------+
|  id  |     val     |
+------+-------------+
| 101  | compose-ok  |
+------+-------------+

五、数据持久化说明

Kyuubi 容器内涉及状态的数据集中在两个目录，均通过命名卷持久化：

容器路径	命名卷	内容
`/opt/kyuubi/work`	kyuubi-work	引擎工作目录：Derby 元数据库 `work/root/metastore_db`、表数据 `work/root/spark-warehouse`、引擎日志 `work/root/kyuubi-spark-sql-engine.log.0`、批处理日志等
`/opt/kyuubi/logs`	kyuubi-logs	Kyuubi Server 日志

重启（stop/start）与重建（down/up）后数据均不丢失，实测验证：

# 场景一：stop + start（容器重建前）
docker compose stop
docker compose start

实测回显：

 Container kyuubi-server Stopped
 Container kyuubi-server Started

# 场景二：down（删除容器与网络，保留卷）+ up（用原卷重建）
docker compose down
docker compose up -d

实测回显：

 Container kyuubi-server Removing
 Container kyuubi-server Removed
 Network kyuubi-compose_default Removing
 Network kyuubi-compose_default Removed
 Container kyuubi-server Started

两种场景后再次查询，compose_test.t1 数据完整保留（实测回显）：

+------+-------------+
|  id  |     val     |
+------+-------------+
| 101  | compose-ok  |
+------+-------------+

💡 说明：docker compose down 不会删除命名卷；若需彻底清空数据（包括 Derby 元数据与表数据），执行 docker compose down -v。Derby 元数据与表数据存放在 work 卷内，这就是表数据能在重建后保留的原因。

六、常用环境变量与配置说明

环境变量	示例值	说明
`SPARK_HOME`	/opt/spark	引擎 Spark 发行版位置（必须与挂载路径一致，否则引擎无法启动）
`KYUUBI_JAVA_OPTS`	-Xms256m -Xmx512m	Kyuubi Server 进程 JVM 参数（堆内存限制在此设置）
`KYUUBI_WORK_DIR_ROOT`	/opt/kyuubi/work	引擎工作目录根，与挂载的 work 卷对应
`KYUUBI_LOG_DIR`	/opt/kyuubi/logs	Server 日志目录，与挂载的 logs 卷对应

配置文件优先级：容器内无 kyuubi-env.sh 时，上述变量直接从容器环境变量读取；kyuubi-defaults.conf 通过 ./conf 目录挂载管理，修改后执行 docker compose restart kyuubi 生效。
会话级参数（如 spark.sql.shuffle.partitions）仍可通过 JDBC URL（;#参数=值）或 SET 语句覆盖，与物理机部署行为一致。

七、配置文件持久化

conf/ 目录以只读方式挂载进容器，配置修改在宿主机完成：

# 宿主机编辑配置
vim /opt/data/quzuo/kyuubi-compose/conf/kyuubi-defaults.conf

# 重启容器生效
docker compose restart kyuubi

实测回显：

 Container kyuubi-server Restarting
 Container kyuubi-server Started

⚠️ 注意：挂载为 :ro 时容器内无法写该目录（防止容器内误改配置造成漂移）。若需要挂载 kyuubi-env.sh 等额外文件，直接放入宿主机 conf/ 目录即可。

八、等价 docker run 运行方式

不用 Compose 时，等价的一条 docker run 命令（先确保 kyuubi-logs、kyuubi-work 卷存在，可复用 Compose 创建的卷）：

docker volume create kyuubi-compose_kyuubi-logs
docker volume create kyuubi-compose_kyuubi-work

docker run -d --name kyuubi-server-run -p 10009:10009 -p 10099:10099 \
  -e SPARK_HOME=/opt/spark \
  -v /opt/data/quzuo/kyuubi-compose/spark:/opt/spark:ro \
  -v /opt/data/quzuo/kyuubi-compose/conf:/opt/kyuubi/conf:ro \
  -v kyuubi-compose_kyuubi-logs:/opt/kyuubi/logs \
  -v kyuubi-compose_kyuubi-work:/opt/kyuubi/work \
  apache/kyuubi:1.12.0

实测验证（复用同一数据卷，引擎重建后原表可查）：

+------+-------------+
|  id  |     val     |
+------+-------------+
| 101  | compose-ok  |
+------+-------------+

清理临时容器：

docker rm -f kyuubi-server-run

九、常用运维命令

# 查看容器状态
docker compose ps

# 实时跟踪启动/运行日志
docker compose logs -f kyuubi

# 查看最近 200 行日志
docker compose logs --tail 200 kyuubi

# 进入容器排查（日志在 /opt/kyuubi/logs，引擎日志在 /opt/kyuubi/work/root/）
docker compose exec kyuubi bash

# 容器内连接测试
docker compose exec kyuubi ./bin/kyuubi-beeline -u "jdbc:hive2://localhost:10009" -n root -p q1w2e3r4 -e "SHOW DATABASES;"

# 重启 / 停止 / 启动
docker compose restart kyuubi
docker compose stop
docker compose start

# 停止并删除容器与网络（保留数据卷）
docker compose down

# 停止并彻底清空（含数据卷，谨慎）
docker compose down -v

十、常见问题（FAQ）

Q1：首次 beeline 查询一直无响应或报引擎连接失败？ 官方镜像不内置 Spark。确认已按 4.2 节挂载 Spark 目录并设置 SPARK_HOME=/opt/spark；进容器检查 ls /opt/spark/bin/spark-submit 是否存在。另外首次连接触发引擎冷启动，实测约 40–60 秒，属正常现象。

Q2：宿主机无法访问 10009 端口？ 确认 conf/kyuubi-defaults.conf 中配置了 kyuubi.frontend.bind.host=0.0.0.0（镜像默认绑定容器主机名地址），修改后 docker compose restart kyuubi；再检查端口映射 docker compose ps 的 PORTS 列应出现 0.0.0.0:10009->10009/tcp。

Q3：如何修改 Kyuubi Server 的 JVM 堆内存？ 在 docker-compose.yml 的 environment 中调整 KYUUBI_JAVA_OPTS（如 -Xms256m -Xmx512m），docker compose up -d 重建生效。注意容器可用内存应大于 Server 堆 + 引擎 Driver 堆（spark.driver.memory，默认 1g）之和。

Q4：数据保存在哪里，如何迁移？ 元数据与表数据在 kyuubi-work 命名卷的 root/ 目录下。迁移方法：在新机器用 docker run --rm -v kyuubi-compose_kyuubi-work:/from -v /tmp/kyuubi-backup:/to alpine tar czf /to/work.tgz -C /from . 打包导出，再在新环境同名卷恢复；或改用 bind mount 固定宿主机路径（注意 chown -R 10009:10009）。

Q5：可以复用宿主机已有的 Spark 安装吗？ 可以。把 volumes 中 ./spark:/opt/spark:ro 改为宿主机实际路径（如 /opt/spark-3.5.8-bin-hadoop3:/opt/spark:ro）即可，要求该 Spark 版本在 Kyuubi 1.12 兼容范围（Spark 3.3–3.5、4.0–4.2，注意 Scala 版本匹配 2.12/2.13）。

Q6：如何对接外部 ZooKeeper / 关闭内嵌 ZooKeeper？ 在 conf/kyuubi-defaults.conf 中配置 kyuubi.ha.addresses 指向外部 ZooKeeper 集群（如 zk1:2181,zk2:2181,zk3:2181）后重启，Kyuubi 将使用外部服务发现，内嵌 ZooKeeper 不再启动。

十一、参考链接

Kyuubi 官方 Docker 文档：https://kyuubi.apache.org/docs/latest/
官方镜像 Docker Hub：https://hub.docker.com/r/apache/kyuubi/tags
官方 Dockerfile 与构建脚本：https://github.com/apache/kyuubi/tree/v1.12.0/docker
Docker Compose 官方文档：https://docs.docker.com/compose/
相关文档：《Ubuntu 22.04 安装 Apache Kyuubi 1.12.0 指南》《Apache Kyuubi 1.12.0 配置参数详解》《Apache Kyuubi 1.12.0 常用 CLI 命令与工具详解》