CentOS 8 安装 Apache Gluten 指南

Apache Gluten 是一个可插拔的中间层，把 Spark SQL 的物理计划转换后交给原生向量化引擎（默认 Velox）执行，从而在不修改业务查询的前提下提升聚合、连接、排序等算子的性能。Gluten 没有独立守护进程，其“安装”本质是在既有 Spark 上集成一个 bundle JAR 并开启插件。本文在 CentOS 8 上完成 JDK 17、Spark 3.5.5 与 Gluten 1.7.0 的部署与验证，全部命令与回显均来自真实运行。

一、前置条件

1.1 版本对应关系

Gluten 对 Spark、JDK、Scala 版本有强绑定，安装前必须对齐：

组件	本文版本	说明
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 版本为 Spark 3.5.5
JDK	17	Gluten 1.7.0 字节码为 class file 61，必须 JDK 17；JDK 11/8 无法加载
Scala	2.12	对应 bundle 名 `spark3.5_2.12`
Velox 原生库	随 bundle 提供	`libgluten.so`、`libvelox.so`

Gluten 1.7.0 另外提供面向 Spark 3.3 / 3.4 / 4.0 / 4.1 的预编译包，文件名形如 apache-gluten-1.7.0-bin-spark-3.4.tar.gz，选用时务必让 bundle 的 Spark 大版本与本地 Spark 一致。

1.2 系统与硬件要求

x86_64 架构，CPU 支持 AVX2 指令集；
至少 8 GB 内存、4 GB 可用磁盘（Spark 解压约 430 MB，Gluten bundle 约 175 MB）；
centos8 官方源已下线，需要先将软件源指向 vault 归档地址（见 2.1）。

二、安装 JDK 17 与 Maven

2.1 配置 CentOS 8 软件源

CentOS Linux 8 已进入 EOL，需将源指向 vault。创建两个仓库文件：

cat > /etc/yum.repos.d/CentOS-Linux-BaseOS.repo <<'EOF'
[BaseOS]
name=CentOS Linux 8 - BaseOS
baseurl=https://mirrors.tuna.tsinghua.edu.cn/centos-vault/8.5.2111/BaseOS/x86_64/os/
gpgcheck=1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-centosofficial
enabled=1
EOF

cat > /etc/yum.repos.d/CentOS-Linux-AppStream.repo <<'EOF'
[AppStream]
name=CentOS Linux 8 - AppStream
baseurl=https://mirrors.tuna.tsinghua.edu.cn/centos-vault/8.5.2111/AppStream/x86_64/os/
gpgcheck=1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-centosofficial
enabled=1
EOF

验证源可用：

# dnf -q repolist
repo id                         repo name
AppStream                       CentOS Linux 8 - AppStream
BaseOS                          CentOS Linux 8 - BaseOS

2.2 安装 JDK 17

# dnf -y install java-17-openjdk-devel
...
Installed:
  java-17-openjdk-devel-1:17.0.1.0.12-2.el8_5.x86_64
Complete!

配置环境变量并验证：

# export JAVA_HOME=/usr/lib/jvm/java-17-openjdk
# export PATH=$JAVA_HOME/bin:$PATH
# java -version
openjdk version "17.0.1" 2021-10-19 LTS
OpenJDK Runtime Environment 18.9 (build 17.0.1+12-LTS)
OpenJDK 64-Bit Server VM 18.9 (build 17.0.1+12-LTS, mixed mode, sharing)

如需保留多个 JDK，可用 alternatives --config java 切换默认版本。

2.3 安装 Maven

Maven 仅用于源码构建 Gluten 时使用，采用预编译包时可选装：

# dnf -y install maven
# mvn -version
Apache Maven 3.5.4 (Red Hat 3.5.4-5)
Maven home: /usr/share/maven
Java version: 17.0.1, vendor: Red Hat, Inc.

三、安装 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.1

四、部署 Apache Gluten 预编译包

4.1 下载 Gluten bundle

从 Apache 官方下载站或清华 TUNA 站点获取（两者内容一致，校验 SHA-512 后使用）：

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 -E 'GlutenPlugin.class|libvelox.so'
org/apache/gluten/GlutenPlugin.class
linux/amd64/libvelox.so

可见 Gluten 1.7.0 的插件入口类为 org.apache.gluten.GlutenPlugin，原生库为 linux/amd64/libvelox.so 与 linux/amd64/libgluten.so。

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
# 仅构建 Velox 后端 bundle（首次会拉取 Velox 并编原生库，耗时较久）
./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 并把 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 参数

Gluten 1.7.0 在 JDK 17 下必须开放 Arrow/Velox 用到的 JDK 内部 API，否则会报 sun.misc.Unsafe or java.nio.DirectByteBuffer.<init>(long, int) not available：

export JAVA_HOME=/usr/lib/jvm/java-17-openjdk
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);

以 local[4] 模式运行（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

结果正确（1,000,000 行求和等于 499,999,500,000），退出码为 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 VeloxBackend: Gluten SQL Tab has been attached.

把同一查询交给 EXPLAIN，并临时关闭 AQE 即可看到 Gluten 原生算子：

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

== 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、ColumnarRange 等节点即表示算子已被原生引擎接管。注意：默认开启 AQE 时初始物理计划仍显示朴素 Spark 算子，需关闭 AQE（--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-delta`	未引入 Delta/Paimon 等依赖	正常告警，可忽略

七、卸载

7.1 卸载 Gluten

Gluten 不写入系统目录，只要移除 JAR 并去掉相关 --conf 即可：

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

# dnf -y remove java-17-openjdk-devel maven
# rm -rf /usr/lib/jvm/java-17-openjdk*