Alluxio 源码编译完全指南:从 Git 检出到 Maven 构建、测试与 HDFS 版本定制
Alluxio 源码编译完全指南:从 Git 检出到 Maven 构建、测试与 HDFS 版本定制
导读
本文基于当前仓库中的 Building Alluxio From Source 官方贡献者文档,完整讲解如何在本地环境中检出 Alluxio 源码、使用 Maven 完成编译打包、启动并验证构建产物,以及如何针对不同 HDFS 发行版(Apache / Cloudera / Hortonworks)定制底层存储实现。读完本文,你将掌握一套可复现的 Alluxio 源码构建流程,并了解构建系统内部各 Maven 模块、构建选项与常见故障的底层原理,为参与 Alluxio 二次开发或定制部署打下基础。
一、环境准备:所需的软件与版本约束
Alluxio 是一个基于 JVM 的大型分布式系统,其构建链路依赖以下基础工具,缺一不可:
| 软件 | 版本要求 | 说明 |
|---|---|---|
| JDK | Java 8 | 源码以 Java 8 为基准语言版本 |
| Maven | 3.3.9 或更高 | 核心构建工具 |
| Git | 任意较新版本 | 用于获取源码与切换版本分支 |
以上版本要求与当前仓库的构建配置完全一致:根 pom.xml 中声明了 <java.version>1.8</java.version> 与 <maven.version>3.3.9</maven.version> 两个关键属性,表明项目默认以 Java 8 作为编译目标、以 Maven 3.3.9 作为最低构建版本;根 POM 的 <repositories> 中还预置了 Central、Apache、Cloudera、Hortonworks(HDP)等仓库,用于解析构建 HDFS UFS 时所需的发行版依赖。
如果本地环境不具备 JDK/Maven/Git,官方还发布了预装好以上三者的 Docker 镜像 alluxio/alluxio-maven,可以直接在容器内完成构建(见下文第三节),无需在宿主机安装任何构建工具链。
提示:当前仓库根 POM 版本为
2.10.0-SNAPSHOT,并聚合了assembly、core、examples、integration、job、shell、stress、table、underfs、webui等十余个 Maven 模块,完整构建会依次编译这些子模块,因此首次构建耗时较长属正常现象。
二、检出源码:克隆仓库与切换版本
首先从 GitHub 克隆 Alluxio 主分支(master)源码,并设置环境变量 ALLUXIO_HOME 指向仓库根目录,后续所有构建与验证命令都以它为基准:
$ git clone https://github.com/Alluxio/alluxio.git
$ cd alluxio
$ export ALLUXIO_HOME=$(pwd)
默认检出的 master 分支是开发主干。如果需要构建某个特定发布版本,可先通过 git tag 列出所有版本标签,再用 git checkout <TAG_NAME> 切换到对应版本:
$ git tag
$ git checkout <TAG_NAME>
例如需要构建 2.7.3 版本时就检出 v2.7.3 对应的标签。切换标签后,构建产物的版本号(见故障排查第三节关于 buildnumber-maven-plugin 的说明)也会随之变化。
三、(可选)使用 Docker 搭建预配置构建环境
官方提供的 alluxio/alluxio-maven 镜像已内置 Java、Maven 与 Git,适合不想在宿主机安装构建工具链的开发者。启动并进入容器的完整步骤如下:
$ docker run -itd \
--network=host \
-v ${ALLUXIO_HOME}:/alluxio \
-v ${HOME}/.m2:/root/.m2 \
--name alluxio-build \
alluxio/alluxio-maven bash
$ docker exec -it -w /alluxio alluxio-build bash
需要注意两个关键挂载点:
-v ${ALLUXIO_HOME}:/alluxio:将宿主机上的源码目录映射到容器内的/alluxio,因此容器内编译出的二进制产物在容器外仍然可以访问;-v ${HOME}/.m2:/root/.m2:复用宿主机本地 Maven 缓存,避免每次构建都重新下载依赖(可选,但对离线或弱网环境非常有价值)。
构建结束后,销毁容器即可释放资源:
$ docker rm -f alluxio-build
如果宿主机已安装 JDK 与 Maven,完全可以跳过本节直接进入下一节的本地构建。
四、使用 Maven 构建:从标准命令到加速技巧
4.1 标准构建命令
在源码根目录执行 Maven 构建:
$ mvn clean install -DskipTests
-DskipTests 跳过单元测试的执行(但会保留测试代码的编译),适合只想快速产出可运行制品(jar 包、发行版目录)的场景。该命令会依次完成依赖解析、源码编译、打包,最终在 assembly 模块的 target 目录下生成完整的发行版结构。
4.2 加速构建:跳过各类检查
Maven 构建过程中默认会执行 javadoc、findbugs、checkstyle、license 等质量检查。构建大型项目时这些检查会显著拖慢速度,可以在确定代码无需复查时通过以下参数全部跳过:
$ mvn -T 2C clean install \
-DskipTests \
-Dmaven.javadoc.skip=true \
-Dfindbugs.skip=true \
-Dcheckstyle.skip=true \
-Dlicense.skip=true
其中 -T 2C 表示按 CPU 核数 × 2 并行构建(-T 为 Maven 3.3.1 起支持的多线程构建参数)。各参数含义如下:
| 参数 | 作用 |
|---|---|
-Dmaven.javadoc.skip=true |
跳过 Javadoc 文档生成 |
-Dfindbugs.skip=true |
跳过 FindBugs 静态缺陷扫描 |
-Dcheckstyle.skip=true |
跳过 Checkstyle 代码风格检查 |
-Dlicense.skip=true |
跳过 License 头检查 |
从根 pom.xml 可以看到,项目对测试执行本身也有精细配置:surefire.forkCount=2(多进程并行跑测试)、surefire.rerunFailingTestsCount=1(失败用例自动重跑一次以排除偶发性失败),这些都会影响全量构建的时长。
4.3 打包为发行版 tarball(进阶)
mvn clean install 完成后,assembly 模块负责把各子模块统一组装成发布包。根据 assembly/README.md 的说明,也可以单独执行:
$ mvn package assembly:single
该命令会在 assembly/target 下生成 alluxio-$VERSION.tar.gz 及同名解压目录,其中包含开箱即用的 bin、conf、libexec、jars 等全部运行要素——这正是官方二进制发行版的构建方式。
4.4 首次构建耗时说明
Maven 构建系统会先下载全部依赖再编译打包。如果是首次构建,下载依赖可能耗时较长;后续构建由于依赖已进入本地 .m2 仓库(Docker 模式下则落在挂载的 ${HOME}/.m2),速度会明显加快。
五、验证构建产物:本地启动与运行测试
构建成功后,可以按照官方流程在本地启动 Alluxio 并验证读写链路是否正常。
5.1 初始化与启动
# Alluxio 默认使用 ./underFSStorage 作为底层文件系统(UFS)存储目录
$ mkdir ./underFSStorage
$ ./bin/alluxio format
$ ./bin/alluxio-start.sh local SudoMount
./bin/alluxio format格式化 Master 与 Worker 的元数据与存储目录;./bin/alluxio-start.sh local SudoMount以本地模式启动全部进程(Master、Worker、Proxy 等),SudoMount表示以 sudo 挂载底层文件系统。上述脚本均位于 bin 目录下,与 bin/alluxio-start.sh、bin/alluxio-stop.sh 等启动/停止脚本对应。
5.2 确认运行状态
验证 Alluxio 是否正常运行的两种方式:
- 浏览器访问
http://localhost:19999查看 Master Web UI(Web 服务启动可能需要几秒钟); - 查看
alluxio/logs目录下的日志,其中worker.log与master.log通常最能反映问题。
5.3 运行读写测试
再通过内置测试程序验证数据能否在 Alluxio 与其 UFS 之间正常读写:
$ ./bin/alluxio runTests
该命令由 bin/alluxio 入口脚本调度,成功执行后应看到结果 Passed the test!。
5.4 停止本地集群
$ ./bin/alluxio-stop.sh local
六、构建选项:计算框架支持与 HDFS UFS 定制
6.1 计算框架支持(Compute Framework Support)
自 Alluxio 1.7 起,构建产物中位于 lib 目录下的 Alluxio client jar(文档中以 {{site.ALLUXIO_CLIENT_JAR_PATH}} 指代)默认即可供不同计算框架(如 Spark、Flink、Presto 等)使用。也就是说,只需把该 client jar 加入相应框架的 classpath 即可接入 Alluxio,无需针对每种框架单独构建——这也是后续 Spark/Flink/Presto 等集成文档(例如 docs/en/administration/Troubleshooting.md 中通过 HADOOP_CLASSPATH、SPARK_CLASSPATH、HIVE_AUX_JARS_PATH 等变量引用该 jar 的方式)能够统一生效的前提。
6.2 构建不同版本的 HDFS 底层存储(UFS)
默认情况下,Alluxio 使用 Hadoop 3.3 的 HDFS 作为底层存储实现。如需针对其他 Hadoop 大版本或具体发行版构建 UFS,可通过指定 <UFS_HADOOP_PROFILE> 与 ufs.hadoop.version 两个参数来完成:
$ mvn install -pl underfs/hdfs/ \
-P<UFS_HADOOP_PROFILE> -Dufs.hadoop.version=<HADOOP_VERSION> -DskipTests
其中 -pl underfs/hdfs/ 表示只构建 underfs/hdfs 这一个子模块。可用 profile 及覆盖的 Hadoop 大版本如下:
| Profile | 对应 Hadoop 大版本 |
|---|---|
ufs-hadoop-1 |
Hadoop 1.x |
ufs-hadoop-2 |
Hadoop 2.x |
ufs-hadoop-3 |
Hadoop 3.x(默认) |
从 underfs/hdfs/pom.xml 的源码可以印证这一机制:
- 模块内声明了默认属性
<ufs.hadoop.version>3.3.4</ufs.hadoop.version>; ufs-hadoop-3通过<activeByDefault>true</activeByDefault>被标记为默认激活的 profile,依赖org.alluxio:alluxio-shaded-hadoop的对应版本;ufs-hadoop-2profile 则切换为 Hadoop 2 系列依赖,实现“北向(master 端)与南向(UFS 端)Hadoop 版本解耦”。
一个完整示例(构建 Hadoop 3.3.4 版本并跳过所有质量检查):
$ mvn clean install -pl underfs/hdfs/ \
-Dmaven.javadoc.skip=true -DskipTests -Dlicense.skip=true \
-Dcheckstyle.skip=true -Dfindbugs.skip=true \
-Pufs-hadoop-3 -Dufs.hadoop.version=3.3.4
构建成功标志:在 ${ALLUXIO_HOME}/lib 目录下出现名为 alluxio-underfs-hdfs-<UFS_HADOOP_VERSION>-<ALLUXIO_VERSION>.jar 的 jar 文件(该命名规则同样来自 underfs/hdfs/pom.xml 中的 <lib.jar.name>${project.artifactId}-${ufs.hadoop.version}-${project.version}.jar</lib.jar.name>)。
兼容性提示:官方文档明确建议,Hadoop 版本 ≥ 3.0.0 与较新版本的 Alluxio 兼容性最佳。
6.3 各 Hadoop 发行版的构建参数
官方文档按发行版整理了对应的 -P 与 -D 组合,可直接套用:
Apache(主线发行版,所有 Apache 发布均可直接使用)
-Pufs-hadoop-1 -Dufs.hadoop.version=1.0.4
-Pufs-hadoop-1 -Dufs.hadoop.version=1.2.0
-Pufs-hadoop-2 -Dufs.hadoop.version=2.2.0
-Pufs-hadoop-2 -Dufs.hadoop.version=2.3.0
-Pufs-hadoop-2 -Dufs.hadoop.version=2.4.1
-Pufs-hadoop-2 -Dufs.hadoop.version=2.5.2
-Pufs-hadoop-2 -Dufs.hadoop.version=2.6.5
-Pufs-hadoop-2 -Dufs.hadoop.version=2.7.3
-Pufs-hadoop-2 -Dufs.hadoop.version=2.8.0
-Pufs-hadoop-2 -Dufs.hadoop.version=2.9.0
-Pufs-hadoop-2 -Dufs.hadoop.version=2.10.0
-Pufs-hadoop-3 -Dufs.hadoop.version=3.0.0
-Pufs-hadoop-3 -Dufs.hadoop.version=3.3.4
Cloudera(版本形如 $apacheRelease-cdh$cdhRelease)
-Pufs-hadoop-2 -Dufs.hadoop.version=2.3.0-cdh5.1.0
-Pufs-hadoop-2 -Dufs.hadoop.version=2.0.0-cdh4.7.0
Hortonworks(版本形如 $apacheRelease.$hortonworksRelease)
-Pufs-hadoop-2 -Dufs.hadoop.version=2.1.0.2.0.5.0-67
-Pufs-hadoop-2 -Dufs.hadoop.version=2.2.0.2.1.0.0-92
-Pufs-hadoop-2 -Dufs.hadoop.version=2.4.0.2.1.3.0-563
6.4 启用 HDFS Active Sync 的构建要求
如需启用 HDFS 元数据主动同步(Active Sync)能力,必须使用 hdfsActiveSync 属性进行构建。这一要求在源码层面有明确的印证:
- underfs/hdfs/pom.xml 中定义了
hdfsAcl、hdfsActiveSync、hdfsAclandActiveSync三个互斥 profile,分别通过 maven-compiler-plugin 的<excludes>排除或放行SupportedHdfsAclProvider.java与SupportedHdfsActiveSyncProvider.java两个类; - HdfsUnderFileSystem.java 在启动时通过反射查找类
alluxio.underfs.hdfs.activesync.SupportedHdfsActiveSyncProvider并实例化 HdfsActiveSyncProvider 接口实现;若反射失败则回退到NoopHdfsActiveSyncProvider,日志中会提示 “Cannot create SupportedHdfsActiveSyncProvider…Please upgrade to an HDFS version > 2.6.1”,即该能力要求 HDFS 版本高于 2.6.1。
Active Sync 的具体使用方式见 Active Sync for HDFS(位于统一命名空间章节)。
七、常见故障排查(Troubleshooting)
7.1 java.lang.OutOfMemoryError: Java heap space
构建过程中出现 Maven 进程堆内存溢出时,通过 MAVEN_OPTS 提升堆大小与代码缓存:
$ export MAVEN_OPTS="-Xmx2g -XX:MaxPermSize=512M -XX:ReservedCodeCacheSize=512m"
重新执行构建命令前确认该环境变量已生效即可。
7.2 运行 protolock 报错(protobuf 检查失败)
如果 Maven 输出类似以下错误:
An error occurred while running protolock: Cannot run program "/alluxio/core/transport/target/protolock-bin/protolock" (in directory "/alluxio/core/transport/target/classes"): error=2, No such file or directory
原因是构建 core/transport 模块时 protobuf 相关的代码生成被跳过,导致 protolock 工具二进制缺失。请确保不要在构建命令中加入 -Dskip.protoc 参数。从 core/transport/pom.xml 可以看到该模块默认声明 <skip.protoc>false</skip.protoc>,且通过 protobuf-maven-plugin(版本 0.6.1)执行 proto/grpc 代码生成——只有显式覆盖该属性才会触发上述问题。
7.3 buildnumber-maven-plugin 抛出 NullPointerException
如果 Maven 报错类似:
Failed to execute goal org.codehaus.mojo:buildnumber-maven-plugin:1.4:create-metadata (default) on project alluxio-core-common: Execution default of goal org.codehaus.mojo:buildnumber-maven-plugin:1.4:create-metadata failed.: NullPointerException
原因分析:buildnumber 插件基于 SCM 中的 revision 生成构建号——即从 Git hash 读取版本信息;当 SCM 检查失败(例如在非 Git 工作目录或缺少提交记录的场景下构建)时,插件会抛出 NPE。
解决办法:通过 Maven 参数 -Dmaven.buildNumber.revisionOnScmFailure 指定构建失败时的兜底版本号。例如,若 Alluxio 版本为 2.7.3,则设置:
$ mvn ... -Dmaven.buildNumber.revisionOnScmFailure=2.7.3
该参数可在 core/common/pom.xml 中找到 buildnumber-maven-plugin 的引用佐证,其完整语义可查阅 buildnumber-maven-plugin 官方文档中 revisionOnScmFailure 的说明。
八、延伸阅读
完成构建与验证后,可以继续深入以下仓库内容:
- docs/en/deploy/Running-Alluxio-Locally.md:基于构建产物(或发行版 tarball)在本地部署运行 Alluxio 的完整指南;
- docs/en/core-services/Unified-Namespace.md:统一命名空间与 HDFS Active Sync 元数据同步的机制说明;
- assembly/README.md:发行版 tarball 的组装模块说明,帮助理解构建产物目录结构的来源;
- docs/en/contributor/Contributor-Getting-Started.md:贡献者入门指南,了解从构建到提交 PR 的全流程。
本文所有命令与参数均以当前仓库(2.10.0-SNAPSHOT)的构建配置为基准,若在旧版本上操作,请以对应版本标签下的官方文档为准。