Ubuntu 22.04 安装 Apache Auron 指南

在 Ubuntu 22.04 上从零安装 Apache Auron 8.0.0-incubating 的完整实录:版本选型与校验、JDK 17 与 Rust nightly 工具链准备、auron-build.sh 完整源码构建与跳过 native 的轻量构建双方案对比、Spark 3.5.8 集成、200 万行端到端验证与七个实测 FAQ。

Apache AuronApache Auron2026/10/15

Ubuntu 22.04 安装 Apache Auron 指南

目标:在 Ubuntu 22.04 服务器上从零完成 Apache Auron 8.0.0-incubating 的获取、完整性校验、源码构建与 Spark 3.5.8 集成,产出一个可在同系统直接使用的加速 fat JAR,并跑通 200 万行聚合查询验证。全流程实测通过,文中所有命令输入与回显均为真实执行记录。

一、环境信息

项目实测环境
操作系统Ubuntu 22.04.5 LTS(x86_64)
CPU / 内存12 核 / 39 GB(Rust 编译建议至少 8 核 8 GB)
磁盘根分区 300 GB 级,全程占用约 6 GB(源码树、构建缓存、Spark 安装)
网络可访问公网;境外资源经代理 192.168.1.62:7897 转发

安装完成后的软件基线(各步实测回显):

软件版本安装方式
OpenJDK17.0.20.1apt 仓库
Rust 工具链rustc 1.88.0-nightly(50aa04180 2025-05-08)rustup,钉定 nightly-2025-05-09
gcc / protoc11.4.0 / 3.12.4apt 仓库
Apache Spark3.5.8(Scala 2.12.18)官方二进制包
Apache Auron8.0.0-incubating(fat JAR)源码构建

二、前置条件

  1. root 或 sudo 权限,全程以 root 执行。
  2. 系统包源可用。安装基础工具(unzip 与 gnupg 在最小安装中可能缺失,实测一并补齐):
apt-get update && apt-get install -y curl unzip gnupg
  1. 磁盘与内存余量:df -h /root 确认可用空间超过 15 GB(构建缓存 693 MB、Maven 本地仓库 366 MB、Spark 包及解压约 800 MB、源码树与产物约 2 GB,预留编译临时空间);free -h 确认内存至少 8 GB。
  2. 网络说明:Apache 官方下载站(downloads.apache.org)与 rustup 在境内直连较慢,本文实测统一走代理;Spark 二进制包改用境内 TUNA 镜像直连下载。若网络环境不同,删除或替换对应的代理变量即可。

三、版本选型说明

3.1 版本谱系(官方归档页实测数据)

版本发布日期状态
8.0.0-incubating2026-07-18孵化期,当前最新(本文采用)
7.0.0-incubating2026-03-04孵化期
6.0.0-incubating2025-10-17孵化期,进入 ASF 后首个发布
5.0.02025-04-28进入 ASF 前版本
4.0.1 / 4.0.02024-12-10 / 2024-10-10进入 ASF 前版本
3.0.1 及更早2024-07 起历史版本

3.2 获取渠道对比

💡 技术拓展:同一开源组件往往有多条获取渠道,Auron 的特殊性在于官方不发布任何二进制——

渠道可得内容实测结论
ASF 官方下载目录 downloads.apache.org/incubator/auron/仅源码包 tgz + asc + sha512可用,本文采用
Maven 中央仓库 repo1.maven.org/maven2/org/apache/auron/无任何坐标实测 404,不存在
GitHub 仓库源码与构建脚本,无预编译产物可用于读源码
第三方构建/分发渠道无官方背书不建议生产使用

本文采用 ASF 官方源码包 + 本机源码构建,这也是官方 Getting Started 给出的唯一安装路径。

3.3 组件兼容矩阵

组件支持范围(官方发行说明与构建脚本)本文选择
JDK8 / 11 / 1717
Spark3.0 – 3.5 系列,8.0.0 起新增 4.0 / 4.13.5.8
Scala2.12 / 2.132.12
构建方式auron-build.sh 本机构建(官方另有预置环境构建模式,本文不涉及)本机构建
目标系统产物内嵌 native 库与构建机 glibc 绑定Ubuntu 22.04 本机构建本机用

选择 8.0.0-incubating 的理由:最新版覆盖 Spark 3.0–4.1、Celeborn 0.6.3、Paimon/Iceberg/Hudi 桥接,并完成了 SF=100 的 TPC-DS 全案例验证;孵化状态意味着仍在 ASF 评估期,选型须知悉这一披露(详见 3.1)。

四、方案 A:源码构建安装(官方推荐)

4.1 方案说明

Auron 由 Java 侧(Spark 扩展)与 Rust 侧(基于 Apache Arrow-DataFusion 的 native 引擎)组成,构建脚本 auron-build.sh 会先编译 Rust native 库,再通过 Maven 把两者打包成一个 fat JAR。完整链路:

下载源码包 → sha512/gpg 校验 → 安装 JDK 17 + Rust nightly + C/C++ 工具 → auron-build.sh 完整构建 → fat JAR → 部署进 Spark

4.2 安装 JDK 17

apt-get install -y openjdk-17-jdk
java -version
openjdk version "17.0.20.1" 2025-10-21
OpenJDK Runtime Environment (build 17.0.20.1+8-Ubuntu-Ubuntu-122.04)
OpenJDK 64-Bit Server VM (build 17.0.20.1+8-Ubuntu-Ubuntu-122.04, mixed mode, sharing)

4.3 安装 Rust nightly 工具链

源码树中 rust-toolchain.toml 钉定了工具链版本(8.0.0-incubating 为 nightly-2025-05-09,组件含 rust-src、rustfmt、clippy),rustup 安装时直接指定同版本:

export http_proxy=http://192.168.1.62:7897 https_proxy=http://192.168.1.62:7897
curl --proto "=https" --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --profile minimal --default-toolchain nightly-2025-05-09 --component rust-src,rustfmt,clippy

安装完成后加载环境并确认(回显实测):

. $HOME/.cargo/env && rustc --version && cargo --version
rustc 1.88.0-nightly (50aa04180 2025-05-08)
cargo 1.88.0-nightly (7918c7eb5 2025-04-27)

4.4 安装 C/C++ 编译工具

Rust 链接与部分构建脚本需要 gcc/g++,protobuf 代码生成需要 protoc:

apt-get install -y build-essential protobuf-compiler pkg-config
gcc --version | head -1 && protoc --version
gcc (Ubuntu 11.4.0-1ubuntu1~22.04) 11.4.0
protoc 3.12.4

4.5 下载源码包并校验

从 ASF 官方目录下载源码包、签名与校验文件:

export http_proxy=http://192.168.1.62:7897 https_proxy=http://192.168.1.62:7897
mkdir -p /root/auron-src && cd /root/auron-src
curl -sO https://downloads.apache.org/incubator/auron/auron-8.0.0-incubating/apache-auron-8.0.0-incubating-source.tgz
curl -sO https://downloads.apache.org/incubator/auron/auron-8.0.0-incubating/apache-auron-8.0.0-incubating-source.tgz.asc
curl -sO https://downloads.apache.org/incubator/auron/auron-8.0.0-incubating/apache-auron-8.0.0-incubating-source.tgz.sha512
curl -s https://downloads.apache.org/incubator/auron/KEYS -o KEYS
ls -l
-rw-r--r-- 1 root root 1480746 Jul  7  2026 apache-auron-8.0.0-incubating-source.tgz
-rw-r--r-- 1 root root      866 Jul  7  2026 apache-auron-8.0.0-incubating-source.tgz.asc
-rw-r--r-- 1 root root      157 Jul  7  2026 apache-auron-8.0.0-incubating-source.tgz.sha512

sha512 对照(期望值来自官方 .sha512 文件):

cat apache-auron-8.0.0-incubating-source.tgz.sha512 && sha512sum apache-auron-8.0.0-incubating-source.tgz
apache-auron-8.0.0-incubating-source.tgz: d8dc71d5dd41dd8ff2d42c4d5c200b9643514b684fb850d7e054aca8da24c556edbe4205bfbc983d4f723593a353af18b719ed0b6efbd2ec0cd5a0e36684c097
d8dc71d5dd41dd8ff2d42c4d5c200b9643514b684fb850d7e054aca8da24c556edbe4205bfbc983d4f723593a353af18b719ed0b6efbd2ec0cd5a0e36684c097  apache-auron-8.0.0-incubating-source.tgz

两行一致,完整性通过。再做 gpg 签名验证:

gpg --import KEYS && gpg --verify apache-auron-8.0.0-incubating-source.tgz.asc apache-auron-8.0.0-incubating-source.tgz
gpg: Total number processed: 4
gpg:               imported: 4
gpg: Signature made Tue Jul  7 08:49:13 2026 UTC
gpg:                using RSA key 03BDF29842A1E3BE3D4C202BC8748C760193CC20
gpg: Good signature from "Li Zhang (Su128) <richox@apache.org>" [unknown]
gpg: WARNING: This key is not certified with a trusted signature!

Good signature 即验证通过;WARNING 属于未建立信任链的正常提示。

4.6 解压与目录结构

tar xzf apache-auron-8.0.0-incubating-source.tgz && cd apache-auron-8.0.0-incubating-source && ls
auron-build.sh    native-engine               spark-extension
Cargo.lock        pom.xml                     spark-extension-shims-spark
Cargo.toml        python/                     spark-version-annotation-macros
dev/              rust-toolchain.toml         tools
etc

(为便于阅读做了列对齐,文件名未增减;其中 rust-toolchain.toml 钉定 4.3 节使用的 nightly 版本。)

4.7 执行完整构建

核心命令(官方 Getting Started 同款):

export http_proxy=http://192.168.1.62:7897 https_proxy=http://192.168.1.62:7897
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
. $HOME/.cargo/env
cd /root/auron-src/apache-auron-8.0.0-incubating-source
./auron-build.sh --release --sparkver 3.5 --scalaver 2.12 --skiptests true --clean true

参数说明(源自 ./auron-build.sh --help 实测输出,全表见常用配置与 CLI 命令详解篇):

参数取值含义(help 原文 + 实测说明)
--pre开关Activate pre-release profile;对应 Rust debug 编译,构建快
--release开关Activate release profile;对应 Rust release 编译,运行快,生产用。与 --pre 二选一
--sparkver3.0–3.5、4.0、4.1Specify Spark version;决定 shim 模块(3.5 对应 Spark 3.5.8)
--scalaver2.12 / 2.13Specify Scala version
--skipteststrue/false(默认 true)Skip unit tests
--cleantrue/false(默认 true)Clean before build;中断续跑时才显式改 false
--threadsN | NCMaven build threads(如 4、1C),不填按 Maven 默认
--sparkteststrue/false(默认 false)Run spark tests

首次构建实测耗时约 25 分钟(12 核,含 Rust release 全量编译与 Maven 打包;依赖缓存约 693 MB Rust registry + 366 MB Maven 本地仓库)。成功尾部回显:

[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  24:44 min
[INFO] Finished at: 2026-10-15T07:59:39Z
[INFO] ------------------------------------------------------------------------

⚠️ 构建中断后不要直接用 --clean false 复跑了事:实测在 Assembly 模块复制产物的 exec 步骤会报 cp: cannot stat 'target/auron-spark-3.5_2.12-8.0.0-incubating.jar': No such file or directory(详见 FAQ Q3)。

4.8 验证构建产物

产物位置与内容(回显实测):

ls -l target/auron-spark-3.5_2.12-release-linux-x86_64-8.0.0-incubating.jar
-rw-r--r-- 1 root root 42165721 Oct 15 07:59 target/auron-spark-3.5_2.12-release-linux-x86_64-8.0.0-incubating.jar
unzip -l target/auron-spark-3.5_2.12-release-linux-x86_64-8.0.0-incubating.jar | grep -E "libauron\.so"
unzip -l target/auron-spark-3.5_2.12-release-linux-x86_64-8.0.0-incubating.jar | grep -cE "\.class"
 80822712  2025-06-09 20:48   libauron.so
7467

fat JAR 约 42 MB,内含 7467 个 class 与 81 MB 的 libauron.so(压缩后总大小 42 MB),native 引擎与 Java 侧缺一不可。

五、方案 B:轻量构建(跳过 native 引擎,备用)

5.1 适用场景与限制

轻量构建加 -DskipBuildNative,跳过整个 Rust 编译环节,产物不含 native 库。适用:只改 Java 侧代码时的编译校验、流水线里的快速编译检查。限制(实测确认):产物无法跑 native 加速——开启 spark.auron.enable 的查询会因 AurCallNativeWrapper 类初始化失败直接报错(见 5.3),并不存在自动回退。

5.2 执行轻量构建

注意:属性要直接传给源码内置的 Maven,而不是拼在 auron-build.sh 参数后(原因见 FAQ Q4):

cd /root/auron-src/apache-auron-8.0.0-incubating-source
./build/mvn clean install -DskipTests -DskipBuildNative -Prelease -Pspark-3.5 -Pscala-2.12

实测尾部回显:

[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  02:48 min
[INFO] Finished at: 2026-10-15T08:29:06Z
[INFO] ------------------------------------------------------------------------

产物对比(回显实测):

ls -l target/auron-spark-3.5_2.12-release-linux-x86_64-8.0.0-incubating.jar
unzip -l target/auron-spark-3.5_2.12-release-linux-x86_64-8.0.0-incubating.jar | grep -c "libauron.so"
-rw-r--r-- 1 root root 14350804 Oct 15 08:32 target/auron-spark-3.5_2.12-release-linux-x86_64-8.0.0-incubating.jar
0

14.4 MB、无 libauron.so(完整构建为 42.2 MB、含 native 库),构建时间从约 25 分钟降到 2 分 48 秒。

5.3 两个实测踩坑

坑一:官方 README 示例把 -DskipBuildNative 直接拼在 auron-build.sh 后面,8.0.0-incubating 中该写法会把它当作 Maven 生命周期阶段透传,实测报错:

[ERROR] Unknown lifecycle phase " -DskipBuildNative". You must specify a valid lifecycle phase or a goal in the format <plugin-prefix>:<goal> or <plugin-group-id>:<plugin-artifact-id>[:<plugin-version>]:<goal>. Available lifecycle phases are: pre-clean, clean, post-clean, validate, initialize, generate-sources, process-sources, generate-resources, process-resources, compile, process-classes, generate-test-sources, process-test-sources, generate-test-resources, process-test-resources, test-compile, process-test-classes, test, prepare-package, package, pre-integration-test, integration-test, post-integration-test, verify, install, deploy, pre-site, site, post-site, site-deploy. -> [Help 1]

解法:如 5.2 所示,改用内置 Maven 直调并显式携带 -DskipBuildNative。

坑二:做过完整构建的机器上有两处残留会让轻量构建产物继续带上 libauron.so:Rust 侧产物目录 native-engine/_build/release/libauron.so(不在 Maven 清理范围,构建脚本检测到现成 .so 会直接复用),以及上一轮 install 进 Maven 本地仓库的构件(被 shade 合并进产物)。实测解法是两处都清掉再构建:

rm -rf native-engine/_build $HOME/.m2/repository/org/apache/auron

清掉后重跑 5.2,产物实测 14,350,804 字节且不含 native 库。

六、方案对比与选择建议

维度方案 A:完整构建方案 B:轻量构建
前置依赖JDK + Rust nightly + gcc/protoc仅 JDK
实测耗时约 25 分钟2 分 48 秒
产物大小42,165,721 字节14,350,804 字节
native 引擎含 libauron.so,可加速不含,开启开关即失败
适用生产部署(官方推荐路径)Java 侧编译校验、流水线快速检查

建议:生产环境一律方案 A;方案 B 仅作为开发期辅助。本文采用方案 A 完成后续集成。

七、集成 Spark 与基础配置

7.1 安装 Spark 3.5.8

从 TUNA 镜像下载官方二进制包并校验(sha512 期望值取自官方 .sha512 文件,两者实测一致):

cd /opt
curl -sO https://mirrors.tuna.tsinghua.edu.cn/apache/spark/spark-3.5.8/spark-3.5.8-bin-hadoop3.tgz
sha512sum spark-3.5.8-bin-hadoop3.tgz
5d5d2e6e111182ee1210d4a46a17ae27107c7ccc70433da0ded3d8197e027f949b00445bb5678ed0c1d5c59f12993d9b9ed12e43686d5aad89a9ec570e93a083  spark-3.5.8-bin-hadoop3.tgz

解压并固定版本软链:

tar xzf spark-3.5.8-bin-hadoop3.tgz && ln -sfn spark-3.5.8-bin-hadoop3 spark
/opt/spark/bin/spark-submit --version 2>&1 | head -6
Welcome to
      ____              __
     / __/__  ___ _____/ /__
    _\ \/ _ \/ _ `/ __/  '_/
   /___/ .__/\_,_/_/ /_/\_\   version 3.5.8
      /_/

7.2 部署 JAR 与写入配置

把构建产物放进 Spark 的 jars 目录(注意:必须使用与本机 glibc 兼容的构建产物,跨版本复用 JAR 会触发 FAQ Q1 的报错):

cp /root/auron-src/apache-auron-8.0.0-incubating-source/target/auron-spark-3.5_2.12-release-linux-x86_64-8.0.0-incubating.jar /opt/spark/jars/

创建 /opt/spark/conf/spark-defaults.conf,写入官方推荐的最小配置(内容照抄):

spark.auron.enable true
spark.sql.extensions org.apache.spark.sql.auron.AuronSparkSessionExtension
spark.shuffle.manager org.apache.spark.sql.execution.auron.shuffle.AuronShuffleManager
spark.memory.offHeap.enabled false
spark.auron.ui.enabled true

写入 /opt/spark/conf/spark-env.sh 固定监听地址:

printf "export SPARK_LOCAL_IP=127.0.0.1\n" >> /opt/spark/conf/spark-env.sh

⚠️ JVM 堆参数位置说明:本文验证用 --driver-memory 512m(提交命令行传入,等价于 -Xms256m -Xmx256m 一类参数在 Driver 上的生效形态);集群模式下对应改 spark-defaults.conf 的 spark.executor.memory(官方建议 4g)与 spark.executor.memoryOverhead(官方建议 4096,native 内存走堆外记账,详见调优篇)。

八、安装验证(200 万行端到端)

创建 /opt/auron-demo/smoke.sql(内容照抄):

DROP TABLE IF EXISTS demo_order;
CREATE TABLE demo_order USING parquet AS
SELECT id,
       id % 6 AS l_linenumber,
       CAST(id * 1.01 AS DECIMAL(12,2)) AS l_extendedprice,
       CASE WHEN id % 3 = 0 THEN "A" WHEN id % 3 = 1 THEN "B" ELSE "C" END AS l_returnflag
FROM (SELECT explode(sequence(1, 2000000)) AS id);
SELECT l_returnflag, count(*) AS cnt, sum(l_extendedprice) AS total
FROM demo_order GROUP BY l_returnflag ORDER BY l_returnflag;

执行(stderr 单独落文件,供验证取证):

mkdir -p /opt/auron-demo && cd /opt/auron-demo
/opt/spark/bin/spark-sql --driver-memory 512m -f smoke.sql > smoke.out 2> smoke.err
echo rc=$?
rc=0

查询结果(smoke.out 实测):

A       666666  673332996666.33
B       666667  673333670000.00
C       666667  673334343333.67

200 万行按 id%3 均分三组,666,666/666,667/666,667 与预期一致。native 引擎参与执行的日志证据:

grep -cE "Start executing native plan" smoke.err
8
grep -m1 "NativeHelper: memory" smoke.err
26/10/15 08:33:35 WARN NativeHelper: memory total: 896.0 MiB, onheap: 512.0 MiB, offheap: 384.0 MiB

安装验证清单全部满足:退出码 0、结果正确、native 执行 8 次、native 内存账本输出正常。至此 Auron 安装完成。

验证点通过标准(实测值)
构建产物fat JAR 42,165,721 字节,含 libauron.so
查询退出码0
结果正确性666666/666667/666667 三组计数
native 参与Start executing native plan 8 次
native 内存账本total 896.0 MiB(onheap 512 + offheap 384)

九、常见问题(FAQ)

Q1:运行时报 UnsatisfiedLinkError ... GLIBC_2.38 not found? 实测报错原文(在 Ubuntu 22.04 上运行了更高 glibc 版本系统构建的 JAR):

java.lang.UnsatisfiedLinkError: /tmp/libauron-2949776914807434968.tmp: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.38' not found (required by /tmp/libauron-2949776914807434968.tmp)

JAR 加载时把内嵌的 libauron.so 解压到 /tmp 再装载,符号版本不能超过运行机 glibc(22.04 为 2.35)。解法:在与运行环境相同(或更低)glibc 的系统上执行第四章构建,产物仅在本系列系统内复用。

Q2:auron-build.sh 不带 --pre 或 --release 直接跑? 两者必选其一(--help 明示:--pre Activate pre-release profile / --release Activate release profile),缺失时脚本拒绝执行。生产构建用 --release。

Q3:构建中断后用 --clean false 复跑,Assembly 阶段报 cp cannot stat? 实测报错:

cp: cannot stat 'target/auron-spark-3.5_2.12-8.0.0-incubating.jar': No such file or directory

中断残留导致 shade 产物状态错位。实测解法:直接续跑最后一段 Maven(约 25 秒完成):

./build/mvn install -DskipTests -Prelease -Pspark-3.5 -Pscala-2.12 -rf :auron-spark-3.5_2.12

Q4:照 README 用 ./auron-build.sh ... -DskipBuildNative 报 Unknown lifecycle phase? 见 5.3 坑一,完整报错与解法在同节。要点:-D 属性要传给 ./build/mvn,不能拼在 auron-build.sh 后。

Q5:apt 或源码包下载反复失败、校验和不符? 实测两类现象:apt 个别包报 502 时用 apt-get install -y --fix-missing 包名 重试;大文件下载中断后断点续传产物校验不过(实测 Spark 包续传后 455 MB 且 sha512 不符),此时删除文件全新下载再校验。TUNA 等境内镜像直连通常比走代理更稳。

Q6:重跑验证脚本报表已存在? 实测报错:

[TABLE_OR_VIEW_ALREADY_EXISTS] Cannot create table or view `spark_catalog`.`default`.`demo_order` because it already exists.

本地 derby 元数据(metastore_db)持久化了建表结果。脚本首行保留 DROP TABLE IF EXISTS demo_order; 即可重复执行。

Q7:EXPLAIN 输出里看不到 Native 节点,是不是没生效? 属设计行为。Auron 在物理计划执行准备阶段做转换,EXPLAIN 打印的是转换前计划;生效与否以 Start executing native plan 日志条数为准(第八章验证方法)。

十、卸载与清理

逐条执行(本文各路径即实际安装路径):

rm -rf /opt/auron-demo
rm -f /opt/spark/jars/auron-spark-3.5_2.12-release-linux-x86_64-8.0.0-incubating.jar
rm -rf /opt/spark-3.5.8-bin-hadoop3 /opt/spark /opt/spark-3.5.8-bin-hadoop3.tgz
rm -rf /root/auron-src
rm -rf $HOME/.m2/repository/org/apache/auron
rm -rf $HOME/.cargo $HOME/.rustup
apt-get purge -y openjdk-17-jdk build-essential protobuf-compiler pkg-config unzip gnupg

第 4 条删除源码与构建缓存(约 3 GB);第 5 条清掉安装到 Maven 本地仓库的 Auron 构件(auron-core、auron-common_2.12、auron-spark-3.5_2.12 等,实测存在于该路径);第 6 条删除 Rust 工具链与缓存(约 700 MB)。Spark 与 JDK 如被其他业务共用,保留对应目录仅删 Auron 相关即可。

十一、参考链接

  1. Apache Auron 官方主页:https://auron.apache.org/
  2. 官方 Getting Started:https://auron.apache.org/documents/getting-started.html
  3. ASF 源码下载目录(含 KEYS):https://downloads.apache.org/incubator/auron/
  4. 8.0.0-incubating 发行说明:https://auron.apache.org/archives/v8.0.0-incubating.html
  5. 全部历史版本归档:https://auron.apache.org/archives/all-releases.html
  6. 官方配置项文档:https://auron.apache.org/documents/configuration.html
  7. Apache Spark 3.5.8 镜像下载:https://mirrors.tuna.tsinghua.edu.cn/apache/spark/
  8. rustup 官方安装脚本:https://sh.rustup.rs