Apache Auron 8.0.0-incubating 常用配置与命令详解

目标：把 Apache Auron 8.0.0-incubating 日常使用会碰到的两类东西一次讲透——构建与运行命令（auron-build.sh 参数、产物核验、spark-sql 调用与日志观察），以及配置体系（必配五项、官方配置清单、逐项实测行为）；本文实验部分全部实测通过，官方配置清单为如实引用并注明来源。

Auron 的可配置面有两层：构建期（选 Spark/Scala 版本与组件组合）和运行期（Spark 配置项控制总开关、算子粒度开关、数据源开关与内存/洗牌参数）。本文先给命令侧，再给配置侧，最后用四组开关实验展示「配置改了之后到底发生了什么」。

一、环境信息

本节先固定可复现的基线环境，本文实测命令均在此环境执行。

操作系统：Ubuntu 22.04.5 LTS（x86_64）
JDK：OpenJDK 17.0.20.1
Spark：3.5.9（本地模式，/root/spark）
Auron：8.0.0-incubating（fat jar auron-spark-3.5_2.12-pre-linux-x86_64-8.0.0-incubating.jar，44.6 MB，内含 libauron.so，--pre profile 构建）
测试数据：本地 Parquet 表 t1（300 万行）与维表 t2（2000 行，join 实验用，键 k）
工作目录：/root/auron（源码与构建）、/root/spark、/root/sql

ls -lh /root/spark/jars/ | grep auron

-rw-r--r-- 1 root root  43M Oct 15 07:27 auron-spark-3.5_2.12-pre-linux-x86_64-8.0.0-incubating.jar

二、构建命令详解

2.1 auron-build.sh 参数总表

./auron-build.sh --help 实测输出（与本文相关的部分，节选）：

Usage: ./auron-build.sh [OPTIONS] <maven build options>
Build Auron project with specified Maven profiles

Options:
  --pre                    Activate pre-release profile
  --release                Activate release profile
  --clean <true|false>     Clean before build (default: true)
  --skiptests <true|false> Skip unit tests (default: true)
  --sparktests <true|false> Run spark tests (default: false)
  --flinktests <true|false> Run flink tests (default: false)
  --tpcds <true|false>     Run tpcds test (default: false)
  --sparkver <VERSION>     Specify Spark version (e.g. 3.0,3.1,3.2,3.3,3.4,3.5,4.0,4.1)
  --flinkver <VERSION>     Specify Flink version (e.g. 1.18)
  --scalaver <VERSION>     Specify Scala version (e.g. 2.12,2.13)
  --celeborn <VERSION>     Specify Celeborn version (e.g. 0.5,0.6)
  --uniffle <VERSION>      Specify Uniffle version (e.g. 0.10)
  --paimon <VERSION>       Specify Paimon version (e.g. 1.2)
  --iceberg <VERSION>      Specify Iceberg version (e.g. 1.10.1)
  --hudi <VERSION>         Specify Hudi version (e.g. 0.15)
  -h, --help               Show this help message

参数	取值与作用
`--pre` / `--release`	产物 profile；`--pre` 产物名带 `-pre` 标记（本文实测组合），`--release` 为发布口径
`--sparkver`	3.0–4.1 任一；决定 shims 模块与产物名中的 Spark 版本号
`--scalaver`	2.12 / 2.13
`--celeborn` / `--uniffle`	打入对应 RSS（远程洗牌服务）客户端适配（0.5/0.6、0.10）
`--paimon` / `--iceberg` / `--hudi`	打入表格式连接器适配（1.2 / 1.10.1 / 0.15）
`--flinkver`	切到 Flink 支持线（1.18）构建 auron-flink 产物
`--clean` / `--skiptests` / `--sparktests` / `--tpcds`	构建过程控制；CI 里 tpcds 验证即 `--tpcds true`
`-D…`	透传给 Maven 的属性；8.0.0-incubating 有已知解析坑，见 2.2

本文基线命令（第 1 篇实测通过）：

export PATH=/root/.cargo/bin:$PATH
./auron-build.sh --pre --sparkver 3.5 --scalaver 2.12 --skiptests true

[INFO] BUILD SUCCESS

2.2 `-D` 参数透传的坑与变通

README 示例把 -DskipBuildNative 直接跟在脚本参数后面，实测该写法在 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, prepare-package, package, pre-integration-test, integration-test, post-integration-test, verify, install, deploy, pre-site, site, post-site, site-deploy. -> [Help 1]

（GNU 风格 -- 分隔符也被脚本拒绝：ERROR: Unknown option '--'。）

变通写法（实测有效）：在 -D 参数前放一个单横线的 Maven 原生参数（如 -T1），触发脚本停止选项解析、把剩余参数原样透传：

./auron-build.sh --pre --sparkver 3.5 --scalaver 2.12 --skiptests true -T1 -DskipBuildNative

[INFO] Compiling locally with maven args: ./build/mvn clean install -DskipTests -Ppre -Pspark-3.5 -Pscala-2.12  -T1 -DskipBuildNative

该写法的产物不含原生库（14 MB，libauron.so 条目数为 0），运行加速查询会报 NoClassDefFoundError: Could not initialize class org.apache.auron.jni.AuronCallNativeWrapper——只可用于 JVM 侧编译验证，能力边界详见第 5 篇。

2.3 产物与构建元数据

产物命名规则：auron-spark-<Spark大版本>_<Scala版本>-<profile>-<系统>-<架构>-<项目版本>.jar。核验两个关键条目：

unzip -l target/auron-spark-3.5_2.12-pre-linux-x86_64-8.0.0-incubating.jar | grep -E 'libauron|auron-build-info'
unzip -p target/auron-spark-3.5_2.12-pre-linux-x86_64-8.0.0-incubating.jar auron-build-info.properties

106048720  2025-06-09 20:48   libauron.so
      158  2025-06-09 20:48   auron-build-info.properties
spark.version=3.5
rust.version=1.88.0-nightly
java.version=17.0.20.1
project.version=8.0.0-incubating
scala.version=2.12
build.timestamp=2026-10-15T07:02:49Z

构建启动时脚本也会把同一份元数据打印到控制台（实测节选）：

[INFO] Build configuration (from common/src/main/resources/auron-build-info.properties):
[INFO]   spark.version : 3.5
[INFO]   rust.version : 1.88.0-nightly
[INFO]   java.version : 17.0.20.1
[INFO]   project.version : 8.0.0-incubating
[INFO]   scala.version : 2.12
[INFO] Compiling locally with maven args: ./build/mvn clean install -DskipTests -Ppre -Pspark-3.5 -Pscala-2.12

💡 技术拓展：build.timestamp 与 jar 内元数据来自源码树里的资源文件模板，构建时由脚本注入实际值；Spark UI 的 Auron 页签（spark.auron.ui.enabled=true 时出现）读取同一份元数据展示构建信息，多版本 jar 共存时用它确认「跑的是哪一个」。

三、Spark 侧配置体系

3.1 必配五项

spark-defaults.conf 中的官方推荐最小配置（第 1 篇实测通过）：

spark.master local[*]
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.enable`（等价键 `spark.auron.enabled`）	总开关；false 时全部走 Spark 原生执行
`spark.sql.extensions`	注册 Auron 的 SQL 会话扩展，计划转换入口
`spark.shuffle.manager`	洗牌管理器换成 Auron 实现
`spark.memory.offHeap.enabled`	官方建议显式 false；原生引擎按自身配额管理堆内外内存
`spark.auron.ui.enabled`（等价键 `spark.auron.ui.enable`，默认 true）	Spark UI 中的 Auron 指标页签

三项核心（总开关、扩展、洗牌管理器）缺一不可：只开总开关而不注册扩展与洗牌管理器，会话能起但不会有任何原生转换。

3.2 官方配置清单（如实引用）

以下清单来自官方 Configuration 文档（https://auron.apache.org/documents/configuration.html ，8.0.0-incubating 站点版本），按三类归档；本文未逐项实测全部键，未实测项的默认值以官方文档为准。

运行时（Runtime，节选）：

键	类型	默认	说明（官方）
`spark.auron.enabled`（alt `spark.auron.enable`）	Boolean	true	启用原生加速
`spark.auron.ui.enabled`（alt `spark.auron.ui.enable`）	Boolean	true	Spark UI 展示 Auron 指标
`spark.auron.process.vmrss.memoryFraction`	Double	0.9	进程常驻内存（含堆内外）配额占比
`spark.auron.onHeapSpill.memoryFraction`	Double	0.9	堆内 spill 可用内存占比
`spark.auron.spill.compression.codec`	String	lz4	spill 压缩编码（lz4/snappy/gzip）
`spark.auron.shuffle.compression.targetBufSize`	Integer	4194304	洗牌压缩目标缓冲（字节，默认 4MB）
`spark.auron.suggested.batch.memSize`	Integer	8388608	记录批目标内存（字节，默认 8MB）
`spark.auron.tokio.worker.threads.per.cpu`	Integer	0	每 CPU 的 Tokio 异步线程数，0 为自动

算子开关（Operator Supports）：同一模式的整组键，默认全为 true——spark.auron.enable.aggr、.filter、.project、.sort、.expand、.generate、.union、.window、.window.group.limit、.collectLimit、.local.limit、.global.limit、.take.ordered.and.project、.broadcastExchange、.shuffleExchange、.bhj（广播哈希连接）、.shj（洗牌哈希连接）、.smj（排序合并连接）、.bnlj（笛卡尔/嵌套循环）、.scan（文件扫描）、.local.table.scan、.data.writing（数据写出，默认 false）；外加三个调控键：spark.auron.forceShuffledHashJoin（强制 SMJ→SHJ）、spark.auron.smjfallback.enable 与 spark.auron.smjfallback.rows/mem.threshold（原生 SMJ 超阈值回退 JVM）。

数据源（Data Sources，节选）：spark.auron.enable.scan.parquet、spark.auron.enable.scan.orc、spark.auron.enable.scan.orc.timestamp、spark.auron.enable.paimon.scan。

3.3 配置生效层级

同一键的三处来源优先级（Spark 通用规则，实测命令行覆盖 spark-defaults.conf 有效）：spark-sql --conf k=v > spark-defaults.conf > 内置默认值。注意 spark.auron.enable 与 spark.auron.enabled 是同一配置的两个键名，不要在两处写成相反值。

四、配置行为实测

以下每组实验都给出命令、判读依据与实测耗时；测试查询 /root/sql/q1.sql（全文）：

SELECT k, count(*) AS c, ROUND(SUM(v),1) AS s FROM t1 GROUP BY k ORDER BY k LIMIT 20;

4.1 总开关 spark.auron.enable=false

/root/spark/bin/spark-sql --conf spark.auron.enable=false --conf spark.log.level=WARN -f /root/sql/q1.sql > /tmp/q1off.out 2>/tmp/q1off.err
grep -E 'Time taken' /tmp/q1off.err | tail -1
grep -cE 'NativeHelper' /tmp/q1off.err

Time taken: 7.696 seconds, Fetched 20 row(s)
0

判读：日志中 NativeHelper 出现次数为 0（原生引擎完全未参与），同一查询开启态实测 5.569 秒（INFO 日志）/ 5.713 秒（WARN 日志），本机 local 模式收益约 26%~28%。结果逐行一致。

4.2 算子粒度开关：关闭原生 Parquet 扫描

/root/spark/bin/spark-sql --conf spark.log.level=INFO --conf spark.auron.enable.scan.parquet=false -f /root/sql/q1.sql > /tmp/q1_scanoff.out 2>/tmp/q1_scanoff.err
grep -E 'Time taken' /tmp/q1_scanoff.err | tail -1
grep -A6 'Auron convert result for current stage' /tmp/q1_scanoff.err | grep -cE 'Native[A-Za-z]+'

Time taken: 10.143 seconds, Fetched 20 row(s)
0

convert result 段的顶层节点变为（实测）：

26/10/15 07:43:56 INFO AuronSparkSessionExtension:  + AdaptiveSparkPlan (convertible=false, strategy=NeverConvert)

判读：扫描关掉后整个 Stage 被标为 NeverConvert，convert result 里一个 Native* 节点都没有（统计为 0）——Stage 内只要有一个不可转换的节点，整段回退 JVM，而不是「扫描走 JVM、聚合走原生」的混合执行。实测该配置比全开慢（10.143s vs 5.569s），因为既丢了扫描加速、聚合也回退了。

4.3 join 相关配置

join 查询 /root/sql/qjoin.sql（全文）：

SELECT t2.tag, count(*) AS c, ROUND(SUM(t1.v),1) AS s FROM t1 JOIN t2 ON t1.k = t2.k GROUP BY t2.tag ORDER BY t2.tag;

三组实测（各运行一次，spark.log.level=INFO）：

实验配置	实测耗时	convert result 中的 join 节点
默认（AQE 自动选广播，t2 仅 2000 行）	37.884 s	`NativeBroadcastExchange` + `NativeBroadcastJoin`
`--conf spark.sql.autoBroadcastJoinThreshold=-1`	19.506 s	`NativeSortMergeJoin`（另有 NativeSort/NativeShuffleExchange 等）
在上一行基础上加 `--conf spark.auron.forceShuffledHashJoin=true`	15.339 s	`NativeShuffledHashJoin`（替代 SortMergeJoin）

节点统计命令（以 SMJ 一组为例，实测）：

grep -A6 'Auron convert result for current stage' /tmp/qjoin_smj.err | grep -oE 'Native[A-Za-z]+' | sort -u

NativeFilter
NativeHashAggregate
NativeParquetScan
NativeProject
NativeShuffleExchange
NativeSort
NativeSortMergeJoin

判读：forceShuffledHashJoin=true 确实把原生 SMJ 换成了原生 SHJ（本例 SHJ 15.339s < SMJ 19.506s，连接键基数低时分桶哈希更省排序）；关闭广播后连接计划仍可全链路原生。注意：以上均为单机 local 模式单次计时，用于确认「配置生效、节点如预期替换」，不能外推为集群性能结论。

五、命令行与日志排查

5.1 spark-sql 的两种 SQL 传入方式

-f 文件 与 -e "SQL" 的差异主要在 shell 转义：交互 shell 会剥掉单层引号，-e 内联 SQL 中的字符串字面量（如 'a'）容易丢引号报 UNRESOLVED_COLUMN。本文一律用 SQL 文件方式：

/root/spark/bin/spark-sql -f /root/sql/q1.sql

5.2 日志观察命令集

日常验证/排查用这一组（INFO 级日志下）：

# 原生引擎是否加载（内存配额自报）
grep -m1 'NativeHelper' /tmp/q1on.err
26/10/15 07:34:10 WARN NativeHelper: memory total: 1408.0 MiB, onheap: 1024.0 MiB, offheap: 384.0 MiB

# 会话扩展是否注册
grep -m1 'AuronSparkSessionExtension enabled' /tmp/q1on.err
26/10/15 07:34:05 INFO AuronSparkSessionExtension: org.apache.spark.sql.auron.AuronSparkSessionExtension enabled

# 每个 Stage 的转换结果（原生物理节点）
grep -A4 'Auron convert result for current stage' /tmp/q1on.err | tail -4
26/10/15 07:34:10 INFO AuronSparkSessionExtension:  + NativeShuffleExchange (convertible=false, strategy=Default)
26/10/15 07:34:10 INFO AuronSparkSessionExtension:  +- NativeHashAggregate (convertible=false, strategy=Default)
26/10/15 07:34:10 INFO AuronSparkSessionExtension:  +-- InputAdapter (convertible=false, strategy=Default)
26/10/15 07:34:10 INFO AuronSparkSessionExtension:  +--- NativeParquetScan spark_catalog.default.t1 (convertible=false, strategy=Default)

# 全查询的原生节点种类汇总
grep -A6 'Auron convert result for current stage' /tmp/q1on.err | grep -oE 'Native[A-Za-z]+' | sort -u
NativeHashAggregate
NativeParquetScan
NativeProject
NativeShuffleExchange
NativeTakeOrdered

判读要点：Native* 节点行内标注的 convertible=false 表示「已是原生物理节点、无需再转换」；顶层 AdaptiveSparkPlan 行的 NeverConvert 是包装节点的常规输出；真正要警惕的是 convert strategy 段里普通算子出现 convertible=false，或 convert result 里一个 Native* 都没有（整段回退 JVM，见 4.2 节）。

5.3 EXPLAIN 的行为边界

printf "EXPLAIN FORMATTED SELECT u1, count(*) AS c FROM VALUES (1,'a'),(2,'b'),(1,'c') t(u1,u2) GROUP BY u1 ORDER BY u1;\n" > /root/sql/explain1.sql
/root/spark/bin/spark-sql -f /root/sql/explain1.sql

== Physical Plan ==
AdaptiveSparkPlan isFinalPlan=false
+- Sort [u1 ASC NULLS FIRST], true, 0
   +- Exchange rangepartitioning(u1 ASC NULLS FIRST, 200), ENSURE_REQUIREMENTS, [plan_id=39]
      +- HashAggregate(keys=[u1#10], functions=[count(1)])
         +- Exchange hashpartitioning(u1#10, 200), ENSURE_REQUIREMENTS, [plan_id=38]
            +- HashAggregate(keys=[u1#10], functions=[partial_count(1)])
               +- LocalTableScan [u1#10]

EXPLAIN 展示的是转换前的 Spark 原始物理计划——Auron 的替换发生在执行期（ColumnarRule 的 preColumnarTransitions 阶段），所以「EXPLAIN 里看不到 Native 节点」是设计行为，不是加速失效。

六、常见问题（FAQ）

Q1：spark.auron.enable 和 spark.auron.enabled 什么关系？ 同一配置的两个键名（官方文档标注 alternative），用哪个都行，但不要混用导致一处 true 一处 false。

Q2：为什么关掉一个算子开关（如 parquet 扫描）后其他算子也回退了？ 转换以 Stage 为单位：Stage 内所有节点都可转换才整体替换为原生计划（4.2 节实测 NeverConvert）。想「扫描走 JVM、聚合走原生」的混合模式是不存在的粒度。

Q3：-DskipBuildNative 传不进构建脚本？ 8.0.0-incubating 的参数解析缺陷（2.2 节），用 -T1 -DskipBuildNative 变通；产物仅用于编译验证。

Q4：NativeHelper 打印的 onheap/offheap 配额怎么调？ 它由执行内存推导；显式调控走 spark.auron.process.vmrss.memoryFraction 等运行时键（3.2 节清单）。内存账本与 native 侧内存管理器的深入拆解见《Apache Auron 8.0.0-incubating 进阶配置与调优详解》。

Q5：改了配置不生效？ 先确认优先级（3.3 节：命令行 > spark-defaults.conf）；再确认改的是会话级还是集群级——本文所有 --conf 实验都是新起 spark-sql 进程做的，进程内 SET 对 Auron 部分键是否热生效未实测，不建议依赖。

Q6：哪里能看到我当前 jar 的构建组合？ unzip -p auron-*.jar auron-build-info.properties（2.3 节），或 Spark UI 的 Auron 页签。

七、参考链接

官方 Configuration 文档（本文 3.2 节清单来源）：https://auron.apache.org/documents/configuration.html
官方 Getting Started 文档：https://auron.apache.org/documents/getting-started.html
8.0.0-incubating 版本说明：https://auron.apache.org/archives/v8.0.0-incubating.html
第 1 篇《Ubuntu 22.04 安装 Apache Auron 指南》（构建与环境）
第 3 篇《Apache Auron 8.0.0-incubating 快速入门与集成示例》（首次集成与最小验证）
第 5 篇《Apache Auron 8.0.0-incubating 进阶实战详解》（join 策略、窗口函数与跨机分发实验）

Apache Auron 8.0.0-incubating 常用配置与命令详解

Apache Auron 8.0.0-incubating 常用配置与命令详解

一、环境信息

二、构建命令详解

2.1 auron-build.sh 参数总表

2.2 -D 参数透传的坑与变通

2.3 产物与构建元数据

三、Spark 侧配置体系

3.1 必配五项

3.2 官方配置清单（如实引用）

3.3 配置生效层级

四、配置行为实测

4.1 总开关 spark.auron.enable=false

4.2 算子粒度开关：关闭原生 Parquet 扫描

4.3 join 相关配置

五、命令行与日志排查

5.1 spark-sql 的两种 SQL 传入方式

5.2 日志观察命令集

5.3 EXPLAIN 的行为边界

六、常见问题（FAQ）

七、参考链接

2.2 `-D` 参数透传的坑与变通