Ubuntu 22.04 安装 Apache Gluten 指南

Apache Gluten 通过将 Spark SQL 的物理计划转换为 Substrait 并交由原生向量化引擎（默认 Velox）执行来加速查询，对上层 DataFrame/SQL 完全透明。它没有独立服务进程，集成方式是在既有 Spark 上装载一个 bundle JAR 并开启 GlutenPlugin。本文在 Ubuntu 22.04 上完成从 JDK 17、Spark 3.5.5 到 Gluten 1.7.0 的完整部署与真实验证。

一、前置条件

1.1 版本对应关系

组件	本文版本	说明
Apache Gluten	1.7.0 (incubating)	预编译包 `apache-gluten-1.7.0-bin-spark-3.5.tar.gz`
Apache Spark	3.5.5	Gluten 1.7.0 官方 fully tested 版本
JDK	17	Gluten 1.7.0 字节码为 class file 61，仅 JDK 17 可加载
Scala	2.12	对应 bundle 名 `spark3.5_2.12`
Velox 原生库	随 bundle 提供	`linux/amd64/libgluten.so`、`linux/amd64/libvelox.so`

Gluten 1.7.0 同时提供 Spark 3.3 / 3.4 / 4.0 / 4.1 的预编译包，务必选择与本地 Spark 大版本一致的 bundle。

1.2 系统与硬件要求

x86_64 架构，CPU 支持 AVX2；
内存建议 ≥ 8 GB，磁盘预留 ≥ 4 GB（Spark 解压约 430 MB，Gluten bundle 约 175 MB）；
需要可访问 Apache 归档站与 APT 源。

二、安装 JDK 17 与 Maven

2.1 更新软件索引

# apt-get update -y
Get:1 http://archive.ubuntu.com/ubuntu jammy InRelease [270 kB]
...
Fetched 24.6 MB in 6s (4,100 kB/s)

2.2 安装 JDK 17 与常用工具

# DEBIAN_FRONTEND=noninteractive apt-get install -y openjdk-17-jdk maven curl tar wget
...
Setting up openjdk-17-jdk:amd64 (17.0.20.1+1-post-1ubuntu1~22.04) ...

验证：

# export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
# export PATH=$JAVA_HOME/bin:$PATH
# java -version
openjdk version "17.0.20.1" 2026-08-18
OpenJDK Runtime Environment (build 17.0.20.1+1-post-1ubuntu1-22.04-Ubuntu)
OpenJDK 64-Bit Server VM (build 17.0.20.1+1-post-1ubuntu1-22.04-Ubuntu, mixed mode, sharing)

# mvn -version
Apache Maven 3.6.3
Maven home: /usr/share/maven

如需在同一主机保留其他 JDK，可用 update-alternatives --config java 切换。

三、安装 Apache Spark 3.5.5

3.1 下载与解压

cd /opt
curl -L -o spark-3.5.5-bin-hadoop3.tgz \
  https://archive.apache.org/dist/spark/spark-3.5.5/spark-3.5.5-bin-hadoop3.tgz
tar -xzf spark-3.5.5-bin-hadoop3.tgz
mv spark-3.5.5-bin-hadoop3 spark

3.2 校验 Spark 版本

# /opt/spark/bin/spark-submit --version
      ____              __
     / __/__  ___ _____/ /__
    _\ \/ _ \/ _ `/ __/  '_/
   /___/ .__/\_,_/_/ /_/\_\   version 3.5.5
      /_/

Using Scala version 2.12.18, OpenJDK 64-Bit Server VM, 17.0.20.1

四、部署 Apache Gluten 预编译包

4.1 下载 Gluten bundle

cd /opt
curl -L -o apache-gluten-1.7.0-bin-spark-3.5.tar.gz \
  https://mirrors.tuna.tsinghua.edu.cn/apache/gluten/1.7.0/apache-gluten-1.7.0-bin-spark-3.5.tar.gz
tar -xzf apache-gluten-1.7.0-bin-spark-3.5.tar.gz
mkdir -p /opt/gluten
cp apache-gluten-1.7.0-bin-spark-3.5/gluten-velox-bundle-spark3.5_2.12-linux_amd64-1.7.0.jar /opt/gluten/

4.2 查看包内容

# ls -lh /opt/gluten/
-rw-r--r-- 1 root root 175M gluten-velox-bundle-spark3.5_2.12-linux_amd64-1.7.0.jar

# jar tf /opt/gluten/gluten-velox-bundle-spark3.5_2.12-linux_amd64-1.7.0.jar | grep 'GlutenPlugin.class'
org/apache/gluten/GlutenPlugin.class

Gluten 1.7.0 的插件入口类为 org.apache.gluten.GlutenPlugin（较老版本曾使用 org.apache.gluten.execution.GlutenPlugin）。

4.3 源码构建要点（可选）

官方预编译二进制在 CentOS 7 上静态链接并用 Xeon 平台构建，跨平台可能不保证最优兼容，生产环境可自建：

# 依赖：JDK 17、Maven、gcc/g++ 11+、cmake、ninja-build、python3
git clone https://github.com/apache/gluten.git
cd gluten
git checkout v1.7.0
./dev/buildbundle-veloxbe.sh --build_type=Release
# 产物：package/target/gluten-velox-bundle-spark3.5_2.12-linux_amd64-1.7.0.jar

buildbundle-veloxbe.sh 的 --build_type 控制 Debug/Release，--enable_vcpkg 控制依赖获取方式，--spark_version 指定目标 Spark 版本。该步骤未在本文环境执行，仅作要点说明。

五、版本验证

启动 Spark 时把 org.apache.gluten 日志级别调至 INFO，可确认三方版本一致：

INFO SubstraitBackend: Gluten build info:
==============================================================
Gluten Version: 1.7.0
GCC Version: GCC: (GNU) 13.2.0
Java Version: 17
Scala Version: 2.12.18
Spark Version: 3.5.5

校验项	期望值	获取方式
Spark 版本	3.5.5	`spark-submit --version`
JDK 版本	17	`java -version`
Gluten 版本	1.7.0	启动日志 Gluten build info
原生库	libgluten.so / libvelox.so	日志 `Successfully loaded library`

六、最小插件加载与 SQL 作业

6.1 关键 JVM 参数

JDK 17 下必须开放 Gluten 原生回调所需的内部 API，否则报 sun.misc.Unsafe or java.nio.DirectByteBuffer.<init>(long, int) not available：

export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export PATH=$JAVA_HOME/bin:$PATH
JVM_OPTS='--add-opens=java.base/java.nio=ALL-UNNAMED --add-opens=java.base/java.lang=ALL-UNNAMED --add-opens=java.base/sun.nio.ch=ALL-UNNAMED -Dio.netty.tryReflectionSetAccessible=true'

6.2 运行最小 SQL 作业

准备 /root/test.sql：

SELECT count(*) AS cnt, sum(id) AS s FROM range(1000000);

运行（JVM 堆 512 MB）：

/opt/spark/bin/spark-sql --master 'local[4]' --driver-memory 512m \
  --conf spark.plugins=org.apache.gluten.GlutenPlugin \
  --conf spark.memory.offHeap.enabled=true \
  --conf spark.memory.offHeap.size=1g \
  --conf spark.shuffle.manager=org.apache.spark.shuffle.sort.ColumnarShuffleManager \
  --jars /opt/gluten/gluten-velox-bundle-spark3.5_2.12-linux_amd64-1.7.0.jar \
  --conf "spark.driver.extraJavaOptions=$JVM_OPTS" \
  --conf "spark.executor.extraJavaOptions=$JVM_OPTS" \
  -f /root/test.sql

6.3 作业回显

1000000 499999500000

结果与预期一致，退出码 0。

6.4 插件加载与原生算子验证

启动日志关键行：

INFO GlutenDriverPlugin: Gluten components:
Component velox
INFO JniLibLoader: Successfully loaded library linux/amd64/libgluten.so
INFO JniLibLoader: Successfully loaded library linux/amd64/libvelox.so
INFO VeloxListenerApi: Memory overhead is not set. Setting it to 402653184 automatically.
INFO VeloxListenerApi: Gluten is running with Spark local mode. Skip running static initializer for executor.
INFO VeloxBackend: Gluten SQL Tab has been attached.

对同一查询执行 EXPLAIN 并临时关闭 AQE，可见原生算子：

== Physical Plan ==
VeloxColumnarToRow
+- ^(2) HashAggregateTransformer(keys=[], functions=[count(1), sum(id#7L)], isStreamingAgg=false, ...)
   +- ColumnarExchange SinglePartition, ENSURE_REQUIREMENTS, ... , [shuffle_writer_type=hash], ...
      +- VeloxResizeBatches 1024, 2147483647, 10485760
         +- ^(1) FlushableHashAggregateTransformer(keys=[], functions=[partial_count(1), partial_sum(id#7L)], ...)
            +- ColumnarRange 0, 1000000, 1, 4, 1000000, [id#7L]

出现 VeloxColumnarToRow、HashAggregateTransformer、ColumnarExchange、ColumnarRange 等节点，说明算子已下推到 Velox。默认开启 AQE 时初始计划仍显示朴素 Spark 算子，需 --conf spark.sql.adaptive.enabled=false 才能直观看到。

6.5 常见报错速查

报错	原因	处理
`UnsupportedClassVersionError ... class file version 61.0`	以 JDK 8/11 运行 Gluten 1.7.0	改用 JDK 17
`sun.misc.Unsafe or java.nio.DirectByteBuffer.<init>(long, int) not available`	JDK 17 未开放内部 API	追加 6.1 中的 `--add-opens` 参数
`Spark runtime version x is not matched with Gluten's fully tested version 3.5.5`	Spark 小版本非官方验证版本	换用 Spark 3.5.5（仅告警）
`Excluding runtime-incompatible component: velox-iceberg`	未引入 Iceberg 依赖	正常告警，可忽略

七、卸载

7.1 卸载 Gluten

rm -rf /opt/gluten /opt/apache-gluten-1.7.0-bin-spark-3.5
rm -f /opt/apache-gluten-1.7.0-bin-spark-3.5.tar.gz

若配置写入了 spark-defaults.conf，删除其中 spark.plugins、spark.memory.offHeap.*、spark.shuffle.manager 等行。

7.2 卸载 Spark

rm -rf /opt/spark /opt/spark-3.5.5-bin-hadoop3.tgz

7.3 卸载 JDK 与 Maven

# apt-get -y remove --purge openjdk-17-jdk maven
# apt-get -y autoremove