Ubuntu 22.04 安装 Apache XTable 0.4 指南

目标：在 Ubuntu 22.04 服务器上完成 Apache XTable 0.4.0-incubating 的安装，覆盖两种安装方案（Maven Central 便利二进制、源码构建）、前置环境（JDK / Spark）、版本兼容矩阵、验证命令、升级与卸载，以及安装过程的全部实测排障。安装完成后可按《Apache XTable 0.4 集成使用指南》跑通三格式互转闭环。

一、版本选型与对照

1.1 版本选择

Apache XTable 处于孵化阶段，0.4.0-incubating 为当前最新官方版本（第四个 Apache 发行版）。0.4.0 新增 xtable-spark-runtime 独立 spark-submit 运行入口、Paimon/Parquet 只读源、Delta Kernel 支持，并将 Iceberg 升级到 1.9.2、Avro 升级到 1.12.0。

1.2 制品清单（0.4.0-incubating 实测）

制品	获取方式	大小（实测）	用途
`xtable-spark-runtime_2.12-0.4.0-incubating.jar`	Maven Central	4462701 字节	可运行入口（spark-submit）与作业内 API
`xtable-hudi-support-extensions_2.12-0.4.0-incubating-bundled.jar`	Maven Central	10995267 字节	Hudi 表写读支持扩展（字段 ID 注入等）
`xtable-core_2.12-0.4.0-incubating.jar`	Maven Central	库 jar	库依赖（构建工具按需引用）
`apache-xtable-0.4.0-incubating.src.tgz`	dlcdn.apache.org	567760 字节	源码发行包（方案二）

⚠️ 重要：0.4.0 没有可运行的 xtable-utilities bundled jar。官方下载页称可从 release tag 构建 xtable-utilities_2.12-<version>-bundled.jar，但实测解包 0.4.0 源码后不存在 xtable-utilities 模块（模块列表见第六节），该构建指引只适用于 main 分支（0.5.0-SNAPSHOT）。0.4.0 的可运行形态是 spark-submit 的 XTableSparkSync、作业内 XTableSyncService API 与 REST 服务。

1.3 兼容矩阵（实测确认）

组件	版本	说明
运行时 JDK	8+（实测 OpenJDK 17.0.20.1）	编译目标为 Java 8
Spark	3.4.x / 3.5+（实测 3.4.4）	3.4.x 走 delta-core（Delta Standalone 语义）；3.5+ 自动启用 Delta Kernel
Hudi	0.14.0（0.4.0 构建矩阵）	1.x 包不兼容（实测 `NoSuchMethodError`，见第九节）
Iceberg	1.9.2	同步用 `iceberg-core`，Spark SQL 读端用 `iceberg-spark-runtime-3.4_2.12`
Delta	delta-core 2.4.0（Spark 3.4）/ Delta Kernel 4.0.0（3.5+）	`--usedeltakernel` 可强制 Kernel
Avro	1.12.0（Iceberg 1.9.2 依赖）	需替换 Spark 自带的 avro-1.11.1.jar（第四节）
源码构建 JDK	11（官方要求）	实测 JDK 17 构建失败（lombok delombok），见第六节

二、安装路径选择

方案一（推荐）：Maven Central 便利二进制。下载官方发布的 spark-runtime jar（约 4.3 MB）+ 按需 --packages 引入引擎库，配合本机 Spark 运行。适合绝大多数场景。
方案二：源码构建。官方源码发行包 + Maven Wrapper 全量构建，产出各模块 jar。适合需要修改源码、构建 REST 服务或离线环境统一制品的场景。

两种方案都需要先完成第三节的前置环境。

三、前置环境

3.1 安装 JDK 17

sudo apt-get update
sudo apt-get install -y openjdk-17-jdk-headless curl wget

实测验证：

java -version

实测回显：

openjdk version "17.0.20.1" 2026-08-18
OpenJDK Runtime Environment (build 17.0.20.1+1-1-22.04-Ubuntu)

3.2 安装 Spark 3.4.4

cd /opt
sudo wget https://dlcdn.apache.org/spark/spark-3.4.4/spark-3.4.4-bin-hadoop3.tgz
sudo tar -xzf spark-3.4.4-bin-hadoop3.tgz
sudo mv spark-3.4.4-bin-hadoop3 spark

配置环境变量（写入 /root/.bashrc 或 /etc/profile.d/spark.sh）：

export SPARK_HOME=/opt/spark
export PATH=$SPARK_HOME/bin:$PATH
export PYSPARK_PYTHON=python3

实测验证：

spark-submit --version

实测回显（节选）：

version 3.4.4
Using Scala version 2.12.17, OpenJDK 64-Bit Server VM, 17.0.20.1

⚠️ 若 3.4.4 已从 dlcdn 下架，可从 Apache 归档下载同版本：https://archive.apache.org/dist/spark/spark-3.4.4/spark-3.4.4-bin-hadoop3.tgz。

3.3 安装 Python 3（读端脚本需要）

sudo apt-get install -y python3 python3-pip

实测：python3 --version 回显 Python 3.10.12。

四、方案一：Maven Central 便利二进制安装（推荐）

4.1 下载 XTable 制品

sudo mkdir -p /opt/xtable
cd /opt/xtable
sudo curl -O https://repo1.maven.org/maven2/org/apache/xtable/xtable-spark-runtime_2.12/0.4.0-incubating/xtable-spark-runtime_2.12-0.4.0-incubating.jar

如需读端/写端 Hudi 扩展支持，追加下载：

cd /opt/xtable
sudo curl -O https://repo1.maven.org/maven2/org/apache/xtable/xtable-hudi-support-extensions_2.12/0.4.0-incubating/xtable-hudi-support-extensions_2.12-0.4.0-incubating-bundled.jar

实测验证（大小）：

ls -la /opt/xtable/*.jar

实测回显：

-rw-r--r-- 1 root root 10995267 Oct 15 02:05 xtable-hudi-support-extensions_2.12-0.4.0-incubating-bundled.jar
-rw-r--r-- 1 root root  4462701 Oct 15 02:03 xtable-spark-runtime_2.12-0.4.0-incubating.jar

4.2 替换 Spark 自带 Avro 为 1.12.0

Iceberg 1.9.2 依赖 Avro 1.12 的 API（LogicalTypes.timestampNanos()），而 Spark 3.4.4 自带 avro-1.11.1.jar，类加载器优先级高于运行时 --packages，直接同步 ICEBERG 表会报 NoSuchMethodError（排障实录见第九节）。替换方法：

cd /opt/spark/jars
sudo mv avro-1.11.1.jar avro-1.11.1.jar.bak
sudo curl -O https://repo1.maven.org/maven2/org/apache/avro/avro/1.12.0/avro-1.12.0.jar

实测替换后的 Avro 相关 jar：

avro-1.11.1.jar.bak
avro-1.12.0.jar
avro-ipc-1.11.1.jar
avro-mapred-1.11.1.jar

4.3 验证安装

查看 CLI 用法（命令行入口是否可用）：

spark-submit \
  --class org.apache.xtable.spark.XTableSparkSync \
  /opt/xtable/xtable-spark-runtime_2.12-0.4.0-incubating.jar \
  --help

实测回显（节选，完整内容见《Apache XTable 0.4 常用 CLI 命令与工具详解》）：

usage: xtable-spark-sync [--basepath <arg>] [--datapath <arg>]
       [--datasetconfig <path>] [--help] [--namespace <arg>]
       [--partitionspec <arg>] [--sourceformat <arg>] [--tablename <arg>]
       [--targets <arg>] [--usedeltakernel]

端到端冒烟验证（建表、同步、读回的完整闭环）见《Apache XTable 0.4 集成使用指南》。

五、运行期引擎依赖（--packages）

spark-submit 时通过 --packages 从 Maven Central 自动解析引擎库（首次运行会下载，之后走本地 ~/.ivy2 缓存）。按源/目标组合选取，实测可用组合：

# HUDI 源 → ICEBERG/DELTA 目标
--packages org.apache.hudi:hudi-spark3.4-bundle_2.12:0.14.0,org.apache.iceberg:iceberg-core:1.9.2,io.delta:delta-core_2.12:2.4.0

# ICEBERG / PARQUET 源且含 HUDI 目标（追加 hudi-java-client）
--packages org.apache.hudi:hudi-spark3.4-bundle_2.12:0.14.0,org.apache.hudi:hudi-java-client:0.14.0,org.apache.iceberg:iceberg-core:1.9.2,io.delta:delta-core_2.12:2.4.0

六、方案二：源码构建

6.1 安装 JDK 11（构建要求）

官方构建前置为 Java 11。实测用 JDK 17 构建会在 xtable-api 的 delombok 步骤失败（错误见第九节），因此构建机单独安装 JDK 11：

sudo apt-get install -y openjdk-11-jdk-headless

实测确认两个 JDK 并存：

ls /usr/lib/jvm/

实测回显：

java-11-openjdk-amd64
java-17-openjdk-amd64

6.2 下载并校验源码发行包

mkdir -p /opt/xtable/src
cd /opt/xtable/src
wget https://dlcdn.apache.org/incubator/xtable/0.4.0-incubating/apache-xtable-0.4.0-incubating.src.tgz
wget https://downloads.apache.org/incubator/xtable/0.4.0-incubating/apache-xtable-0.4.0-incubating.src.tgz.sha512
sha512sum -c apache-xtable-0.4.0-incubating.src.tgz.sha512
tar -xzf apache-xtable-0.4.0-incubating.src.tgz

实测校验回显：

apache-xtable-0.4.0-incubating.src.tgz: OK

解压后的源码目录（实测 ls，可确认没有 xtable-utilities 模块）：

AGENTS.md
DISCLAIMER-WIP
Dockerfile
LICENSE
NOTICE
README.md
lombok.config
mvnw
mvnw.cmd
pom.xml
release
spec
style
target
xtable-api
xtable-aws
xtable-core
xtable-hive-metastore
xtable-hudi-support
xtable-service
xtable-spark-runtime

6.3 全量构建

项目自带 Maven Wrapper（0.4.0 新增），无需单独安装 Maven：

cd /opt/xtable/src/apache-xtable-0.4.0-incubating
JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64 ./mvnw package -DskipTests

实测构建以 BUILD SUCCESS 结束。构建产物（find . -name '*.jar' -path '*target*' 实测，按模块归组）：

xtable-api/target/xtable-api-0.4.0-incubating.jar
xtable-core/target/xtable-core_2.12-0.4.0-incubating.jar
xtable-spark-runtime/target/xtable-spark-runtime_2.12-0.4.0-incubating.jar
xtable-hive-metastore/target/xtable-hive-metastore-0.4.0-incubating.jar
xtable-hive-metastore/target/xtable-hive-metastore-0.4.0-incubating-bundled.jar
xtable-aws/target/xtable-aws-0.4.0-incubating.jar
xtable-aws/target/xtable-aws-0.4.0-incubating-bundled.jar
xtable-hudi-support/xtable-hudi-support-extensions/target/xtable-hudi-support-extensions_2.12-0.4.0-incubating.jar
xtable-hudi-support/xtable-hudi-support-extensions/target/xtable-hudi-support-extensions_2.12-0.4.0-incubating-bundled.jar
xtable-hudi-support/xtable-hudi-support-utils/target/xtable-hudi-support-utils-0.4.0-incubating.jar
xtable-service/target/xtable-service-0.4.0-incubating.jar

其中 xtable-service/target/quarkus-app/ 为 REST 服务的完整运行目录（Quarkus 打包，quarkus-run.jar 为启动入口）。构建得到的 spark-runtime jar 与 Maven Central 发布件等效，可直接按方案一的方式使用（放入 /opt/xtable/ 后执行 --help 验证）。

七、基础配置与日常维护

7.1 目录与配置规划（实测结构）

/opt/xtable/                     # XTable jar 与多表 YAML 配置
├── xtable-spark-runtime_2.12-0.4.0-incubating.jar
├── xtable-hudi-support-extensions_2.12-0.4.0-incubating-bundled.jar
└── my_config.yaml               # 多表同步配置（--datasetconfig 用）
/opt/data/                       # 数据湖表目录
├── hudi-dataset/people          # Hudi 源表示例
├── iceberg-dataset/db/people    # Iceberg 源表示例
└── parquet-dataset/items2       # Parquet 源表示例
/opt/spark/                      # Spark 安装（jars/avro-1.12.0.jar 已替换）

环境变量（第三节已写入 .bashrc）：

export SPARK_HOME=/opt/spark
export PATH=$SPARK_HOME/bin:$PATH
export PYSPARK_PYTHON=python3

7.2 升级与多版本管理

XTable 升级：下载新版本 jar 到 /opt/xtable/，同一台机器可并存多个版本 jar（如 xtable-spark-runtime_2.12-0.3.0-incubating.jar 与 0.4.0 并存），提交时指定对应文件名即可回退。升级前阅读官方 Release Note 确认兼容矩阵变化（如 0.4.0 将 Iceberg 升至 1.9.2、Avro 升至 1.12.0）。
Spark 升级：3.4 → 3.5 时无需改同步命令，Delta 路径自动切换为 Delta Kernel（--usedeltakernel 默认启用）；替换 avro-1.11.1.jar 的动作在 3.5 发行包中同样检查一遍。
构建依赖升级：修改源码 pom.xml 中 hudi.version / iceberg.version / avro.version 属性后重新构建。

7.3 卸载

rm -rf /opt/xtable                      # 删除 XTable jar、配置与构建产物
rm -rf /opt/xtable/src                  # 源码（方案二）
cd /opt/spark/jars && mv avro-1.12.0.jar /tmp/ && mv avro-1.11.1.jar.bak avro-1.11.1.jar   # 还原 Spark 自带 Avro
# 如不再使用 Spark：
rm -rf /opt/spark && sed -i '/SPARK_HOME/d' /root/.bashrc

说明：XTable 是无状态元数据同步工具，卸载不影响已有数据文件；由它生成的目标格式元数据（metadata/、_delta_log/、.hoodie/ 扩展部分）如需清理，删除对应目录下这些子目录即可恢复为单一格式表。

八、验证清单

检查项	命令	预期
JDK	`java -version`	`openjdk version "17.0.20.1"` 或相近
Spark	`spark-submit --version`	`version 3.4.4`
Avro	`ls /opt/spark/jars	grep avro`
制品	`ls -la /opt/xtable/*.jar`	两个 jar 大小与 1.2 节一致
CLI	`spark-submit --class org.apache.xtable.spark.XTableSparkSync /opt/xtable/xtable-spark-runtime_2.12-0.4.0-incubating.jar --help`	输出 `usage: xtable-spark-sync ...`
闭环	按《Apache XTable 0.4 集成使用指南》执行	`Sync is successful` 且目标表可读回

九、常见问题（安装实测排障实录）

9.1 换用 Hudi 1.x 包报 `NoSuchMethodError`

现象（实测）：--packages 使用 hudi-spark3.4-bundle_2.12:1.2.0 时同步报：

java.lang.NoSuchMethodError: 'org.apache.hudi.common.table.HoodieTableMetaClient$Builder org.apache.hudi.common.table.HoodieTableMetaClient$Builder.setConf(org.apache.spark.SparkConf)'

原因：0.4.0 按 Hudi 0.14.0 API 构建，Hudi 1.x 移除了 setConf。解决：统一使用 hudi-spark3.4-bundle_2.12:0.14.0。

9.2 Hudi 1.x 写出的源表无法被同步

现象（实测）：

java.lang.IllegalArgumentException: Timeline layout version 2 is not supported in this version

（堆栈入口 org.apache.hudi.common.table.timeline.versioning.TimelineLayoutVersion.<init>）

原因：Hudi 1.x 默认以 timeline layout v2 写表，0.4.0 内置的 0.14.0 只支持 v1。解决：用 Hudi 0.14.0 重写源表，或升级 XTable。

9.3 ICEBERG 源同步报 `NoSuchMethodError: LogicalTypes$TimestampNanos`

现象（实测）：--packages 已带 org.apache.avro:avro:1.12.0 仍报错。原因：Spark 自带 avro-1.11.1.jar 在 $SPARK_HOME/jars，类加载器（父加载器）优先于 --packages。解决：按 4.2 节替换 jar 后重试，实测同步成功。

9.4 ICEBERG 源同步报 `ClassCastException: PartitionData cannot be cast to IndexedRecord`

原因（实测）：ICEBERG 源/目标场景引入了 iceberg-spark-runtime 包，其内置类与主类加载器的 Avro 类跨加载器冲突。解决：同步场景改用 org.apache.iceberg:iceberg-core:1.9.2（iceberg-spark-runtime 留给 Spark SQL 读端使用）。

9.5 HUDI 目标被跳过（目标列表缺 HUDI）

现象（实测）：日志出现

WARN ConversionTargetFactory: Skipping a registered ConversionTarget whose engine library is not on the classpath (java.util.ServiceConfigurationError: org.apache.xtable.spi.sync.ConversionTarget: org.apache.xtable.hudi.HudiConversionTarget Unable to get public no-arg constructor)

原因：缺少 hudi-java-client（HUDI 作目标必需）。解决：--packages 追加 org.apache.hudi:hudi-java-client:0.14.0。

9.6 JDK 17 源码构建失败

现象（实测，./mvnw package -DskipTests）：

[ERROR] Failed to execute goal org.projectlombok:lombok-maven-plugin:1.18.20.0:delombok (default) on project xtable-api: Unable to delombok: InvocationTargetException: Cannot read field "currentBindings" because "case9" is null -> [Help 1]

原因：0.4.0 的 delombok 插件与 JDK 17 不兼容（官方构建前置为 Java 11）。解决：安装 openjdk-11-jdk-headless，以 JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64 构建，实测构建通过。

9.7 按官方下载页构建 `xtable-utilities` 报 POM 不存在

现象（实测）：./mvnw -f xtable-utilities/pom.xml package -DskipTests 报：

[ERROR] [ERROR] The project ... has 1 error
[ERROR]   Child module .../xtable-utilities/pom.xml does not exist

（错误关键字 POM file xtable-utilities/pom.xml does not exist）

原因：0.4.0 源码中不存在该模块（下载页指引针对 main 分支）。解决：0.4.0 使用 spark-runtime 的 spark-submit 方式（方案一）；确需 utilities（java -jar 形态）需从 main 分支源码构建。

十、参考链接

下载页（源码包与制品清单）：https://xtable.apache.org/releases/downloads
Maven Central：https://repo1.maven.org/maven2/org/apache/xtable/
Installation（源码构建官方指引）：https://xtable.apache.org/docs/setup
Spark Runtime 使用指南：https://xtable.apache.org/docs/how-to-spark-runtime
0.4.0 发布说明：https://xtable.apache.org/releases/release-0.4.0-incubating
源码仓库：https://github.com/apache/incubator-xtable

Ubuntu 22.04 安装 Apache XTable 0.4 指南

Ubuntu 22.04 安装 Apache XTable 0.4 指南

一、版本选型与对照

1.1 版本选择

1.2 制品清单（0.4.0-incubating 实测）

1.3 兼容矩阵（实测确认）

二、安装路径选择

三、前置环境

3.1 安装 JDK 17

3.2 安装 Spark 3.4.4

3.3 安装 Python 3（读端脚本需要）

四、方案一：Maven Central 便利二进制安装（推荐）

4.1 下载 XTable 制品

4.2 替换 Spark 自带 Avro 为 1.12.0

4.3 验证安装

五、运行期引擎依赖（--packages）

六、方案二：源码构建

6.1 安装 JDK 11（构建要求）

6.2 下载并校验源码发行包

6.3 全量构建

七、基础配置与日常维护

7.1 目录与配置规划（实测结构）

7.2 升级与多版本管理

7.3 卸载

八、验证清单

九、常见问题（安装实测排障实录）

9.1 换用 Hudi 1.x 包报 NoSuchMethodError

9.2 Hudi 1.x 写出的源表无法被同步

9.3 ICEBERG 源同步报 NoSuchMethodError: LogicalTypes$TimestampNanos

9.4 ICEBERG 源同步报 ClassCastException: PartitionData cannot be cast to IndexedRecord

9.5 HUDI 目标被跳过（目标列表缺 HUDI）

9.6 JDK 17 源码构建失败

9.7 按官方下载页构建 xtable-utilities 报 POM 不存在

十、参考链接

9.1 换用 Hudi 1.x 包报 `NoSuchMethodError`

9.3 ICEBERG 源同步报 `NoSuchMethodError: LogicalTypes$TimestampNanos`

9.4 ICEBERG 源同步报 `ClassCastException: PartitionData cannot be cast to IndexedRecord`

9.7 按官方下载页构建 `xtable-utilities` 报 POM 不存在