CentOS 8 安装 Apache Wayang 指南

一、环境信息

本文所有步骤在 CentOS 8 真实环境中完整执行并验证通过，环境信息如下：

项目	内容
操作系统	CentOS Linux 8（8.5.2111，软件源指向 vault 仓库）
Java	OpenJDK 17.0.1（build 17.0.1+12-LTS）
Maven	Apache Maven 3.5.4（Red Hat 3.5.4-5）
Apache Wayang	1.1.1（Maven Central 当前最新稳定版，2026-02 发布）
后端	wayang-java（本地 Java Stream 引擎，无需任何集群）
登录账号	root（演示口令 q1w2e3r4）
工程目录	/root/wayang-demo
数据目录	/root/wayang-data

说明：Apache Wayang 自 1.0.0 起要求 Java 17（其根 POM 中 java.version 固定为 17）。旧资料中常见的 0.7.x 线（支持 Java 8/11）与本教程的 1.1.1 在模块划分和 API 上有明显差异，第六节会专门说明多版本共存。

二、前置条件

服务器可以访问互联网，且以下地址可达（安装依赖包会从这些站点下载）：
- CentOS vault 软件源：https://mirrors.tuna.tsinghua.edu.cn/centos-vault/
- Maven 中央仓库：https://repo1.maven.org/maven2/
磁盘剩余空间不少于 2 GB（Wayang 1.1.1 的 wayang-java 后端依赖约 150 MB，含 wayang-spark 后端时约 1 GB）。
以 root 账号登录服务器执行全部命令（演示口令 q1w2e3r4）。

验证网络连通性：

curl -sI https://repo1.maven.org/maven2/ | head -1

实测回显：

HTTP/2 200

三、版本选型

3.1 Wayang 版本选择

通过 Maven Central 查询 org.apache.wayang:wayang-core 的发布版本：

curl -s "https://search.maven.org/solrsearch/select?q=g:org.apache.wayang+AND+a:wayang-core&core=gav&rows=10&wt=json" | python3 -c "import json,sys; d=json.load(sys.stdin); [print(x['v']) for x in d['response']['docs']]"

实测回显（截取）：

1.1.1
1.1.0
1.0.0
0.7.1
0.7.0
0.6.0

推荐选择 1.1.1：它是当前最新稳定版，已全面适配 Java 17。0.7.1 是 1.x 之前的最后版本，仅建议维护存量代码时使用。

3.2 后端依赖矩阵

Wayang 通过插件（Plugin）机制对接不同执行引擎，各后端模块的依赖关系如下（依据 1.1.1 发布到 Maven Central 的 POM 实证）：

后端模块	引擎与版本	额外依赖	适用场景
wayang-java	JDK 内置 Stream	无	单机开发、测试、小数据量任务，零外部部署
wayang-spark	Spark 3.4.4（Scala 2.12）	hadoop-client 3.3.6、hadoop-common 3.3.6	单机 local 模式或 Spark 集群
wayang-flink	Flink 1.19.1	flink-dist 相关	Flink 集群
wayang-postgres	PostgreSQL JDBC	wayang-jdbc-template	数据库下推运算
wayang-sqlite3	SQLite JDBC	wayang-jdbc-template	轻量数据库下推

新手建议从 wayang-java 后端开始：它只依赖 JDK 自身，装好 JDK 与 Maven 即可完整跑通，无需部署 Spark 或任何集群。本文主体使用 wayang-java 后端，wayang-spark 的 local 单进程运行方式在《Apache Wayang 快速入门与集成示例》中有完整实测。

3.3 JDK 版本要求

Wayang 版本	JDK 要求	实测结论
1.0.0 / 1.1.0 / 1.1.1	Java 17（根 POM `java.version=17`）	OpenJDK 17.0.1 编译运行全部通过
0.7.0 / 0.7.1	Java 8/11	未在本文验证

四、部署步骤

4.1 安装 OpenJDK 17

yum install -y java-17-openjdk-devel

实测回显（节选）：

Installed:
  java-17-openjdk-devel-1:17.0.1.0.12-2.el8_5.x86_64
  java-17-openjdk-1:17.0.1.0.12-2.el8_5.x86_64
  ...
Complete!

关键一步：切换系统默认 Java。 CentOS 8 通常预装 Java 8，安装后执行 java -version 仍会显示 1.8，必须用 alternatives 手动切换：

alternatives --set java java-17-openjdk.x86_64
alternatives --set javac java-17-openjdk.x86_64
java -version

实测回显：

openjdk version "17.0.1" 2021-10-19 LTS
OpenJDK Runtime Environment 21.9 (build 17.0.1+12-LTS)
OpenJDK 64-Bit Server VM 21.9 (build 17.0.1+12-LTS, mixed mode, sharing)

配置 JAVA_HOME，写入 /etc/profile.d/java17.sh（这是 JAVA_OPTS/MAVEN_OPTS 类环境变量的推荐修改位置之一）：

cat > /etc/profile.d/java17.sh << 'EOF'
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk
export PATH=$JAVA_HOME/bin:$PATH
EOF
source /etc/profile.d/java17.sh
javac -version

实测回显：

javac 17.0.1

4.2 安装 Maven

yum install -y maven
mvn -version | head -3

实测回显：

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., runtime: /usr/lib/jvm/java-17-openjdk-17.0.1.0.12-2.el8_5.x86_64

注意 Java version 一行必须是 17.x。如果显示 1.8，说明 JAVA_HOME 未生效，重新执行 4.1 节的 source 命令即可。

4.3 创建 Maven 工程

mkdir -p /root/wayang-demo/src/main/java/com/example /root/wayang-data
cat > /root/wayang-data/input.txt << 'EOF'
Apache Wayang is a cross platform data processor
wayang can run on java streams and spark
Apache Wayang mixes java and spark backends
big data with wayang big data
EOF

4.4 引入 Wayang 依赖

创建 /root/wayang-demo/pom.xml（完整内容如下）：

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.example</groupId>
    <artifactId>wayang-demo</artifactId>
    <version>1.0.0</version>
    <packaging>jar</packaging>

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <maven.compiler.source>17</maven.compiler.source>
        <maven.compiler.target>17</maven.compiler.target>
        <wayang.version>1.1.1</wayang.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.apache.wayang</groupId>
            <artifactId>wayang-core</artifactId>
            <version>${wayang.version}</version>
        </dependency>
        <dependency>
            <groupId>org.apache.wayang</groupId>
            <artifactId>wayang-basic</artifactId>
            <version>${wayang.version}</version>
        </dependency>
        <dependency>
            <groupId>org.apache.wayang</groupId>
            <artifactId>wayang-java</artifactId>
            <version>${wayang.version}</version>
        </dependency>
        <dependency>
            <groupId>org.apache.wayang</groupId>
            <artifactId>wayang-api-scala-java</artifactId>
            <version>${wayang.version}</version>
        </dependency>
    </dependencies>
</project>

依赖说明：

wayang-core：引擎内核，含 Configuration、WayangContext、优化器。
wayang-basic：通用算子（Map、Filter、ReduceBy、TextFileSource 等）。
wayang-java：Java Stream 后端及其 ExecutionOperator 实现。
wayang-api-scala-java：fluent 风格的 JavaPlanBuilder 构建器。1.x 中该类已从 wayang-java 移到本模块，漏引会在编译期报 package org.apache.wayang.api does not exist（实测踩坑，见第八节 FAQ）。

4.5 编写 WordCount 任务

创建 /root/wayang-demo/src/main/java/com/example/WordCount.java：

package com.example;

import org.apache.wayang.api.JavaPlanBuilder;
import org.apache.wayang.basic.data.Tuple2;
import org.apache.wayang.core.api.Configuration;
import org.apache.wayang.core.api.WayangContext;
import org.apache.wayang.java.Java;

import java.util.Arrays;
import java.util.Collection;

public class WordCount {
    public static void main(String[] args) {
        WayangContext wayang = new WayangContext(new Configuration())
                .withPlugin(Java.basicPlugin());

        Collection<Tuple2<String, Integer>> result = new JavaPlanBuilder(wayang)
                .withJobName("WordCount")
                .withUdfJarOf(WordCount.class)
                .readTextFile("file:///root/wayang-data/input.txt")
                .flatMap(line -> Arrays.asList(line.toLowerCase().split("\\W+")))
                .filter(word -> !word.isEmpty())
                .map(word -> new Tuple2<>(word, 1))
                .reduceByKey(Tuple2::getField0,
                        (t1, t2) -> new Tuple2<>(t1.getField0(), t1.getField1() + t2.getField1()))
                .collect();

        result.forEach(t -> System.out.println(t.getField0() + ": " + t.getField1()));
    }
}

4.6 编译打包

设定 Maven 自身 JVM 的堆范围（256-512 MB）并编译，MAVEN_OPTS 写入 /etc/profile.d/wayang-maven.sh 以便每次登录自动生效：

cat > /etc/profile.d/wayang-maven.sh << 'EOF'
export MAVEN_OPTS="-Xms256m -Xmx512m"
EOF
source /etc/profile.d/wayang-maven.sh
cd /root/wayang-demo
mvn package dependency:copy-dependencies -DoutputDirectory=target/lib

实测回显（节选）：

[INFO] BUILD SUCCESS
[INFO] Total time:  13.968 s

mvn package 编译并生成 target/wayang-demo-1.0.0.jar。
dependency:copy-dependencies 把全部依赖复制到 target/lib，便于 java -cp 直接运行。

4.7 运行验证

java -Xms256m -Xmx512m -cp "target/wayang-demo-1.0.0.jar:target/lib/*" com.example.WordCount

实测回显：

big: 2
a: 1
data: 3
streams: 1
cross: 1
run: 1
is: 1
wayang: 4
backends: 1
processor: 1
platform: 1
with: 1
can: 1
java: 2
apache: 2
spark: 2
and: 2
mixes: 1
on: 1

对照输入文件验证：wayang 出现 4 次、data 3 次、apache/java/spark/and/big 各 2 次，统计正确。

运行瞬间用 ps 与 jps 验证堆参数确实生效（另开一个会话，在任务运行期间执行）：

ps -ef | grep "[j]ava -Xms"

实测回显：

root        1373    1339 99 15:02 ?        00:00:02 java -Xms256m -Xmx512m -cp target/wayang-demo-1.0.0.jar:target/lib/* com.example.WordCount

jps -v

实测回显：

1373 WordCount -Xms256m -Xmx512m

4.8 过滤聚合任务验证

再写一个"过滤 + 映射 + 归约"任务，验证集合数据源与 reduce 算子。创建 /root/wayang-demo/src/main/java/com/example/FilterAggregate.java：

package com.example;

import org.apache.wayang.api.JavaPlanBuilder;
import org.apache.wayang.core.api.Configuration;
import org.apache.wayang.core.api.WayangContext;
import org.apache.wayang.java.Java;

import java.util.Arrays;
import java.util.Collection;

public class FilterAggregate {
    public static void main(String[] args) {
        WayangContext wayang = new WayangContext(new Configuration())
                .withPlugin(Java.basicPlugin());

        Collection<Integer> result = new JavaPlanBuilder(wayang)
                .withJobName("FilterAggregate")
                .loadCollection(Arrays.asList(1, 2, 3, 4, 5, 6, 7, 8, 9, 10))
                .filter(n -> n % 2 == 0)
                .map(n -> n * 10)
                .reduce((a, b) -> a + b)
                .collect();

        System.out.println("sum = " + result);
    }
}

编译并运行：

mvn -q package
java -Xms256m -Xmx512m -cp "target/wayang-demo-1.0.0.jar:target/lib/*" com.example.FilterAggregate

实测回显：

sum = [300]

2、4、6、8、10 被过滤保留，各乘 10 后求和为 300，结果正确。

五、配置说明

5.1 环境变量配置

变量	推荐写入位置	作用
JAVA_HOME	/etc/profile.d/java17.sh	指定 JDK 17 路径，Maven 据此选择编译运行用的 JDK
MAVEN_OPTS	/etc/profile.d/wayang-maven.sh	控制 Maven 自身 JVM 堆，实测使用 -Xms256m -Xmx512m
JAVA_OPTS	无系统级强制位置，一般写在启动脚本里	控制 `java` 直跑应用时的 JVM 参数；本文在命令行直接给出 -Xms256m -Xmx512m

5.2 Wayang 配置文件

Wayang 的运行期配置通过 org.apache.wayang.core.api.Configuration 管理，默认会尝试加载 classpath 根目录下的 wayang.properties。内置默认值来自 wayang-core-1.1.1.jar 内的 wayang-core-defaults.properties，例如：

wayang.core.log.enabled = true
wayang.core.optimizer.reoptimize = false
wayang.core.fallback.udf.cpu.lower = 100
wayang.core.fallback.udf.cpu.upper = 1000

完整键位说明见《Apache Wayang 配置参数详解》。自定义方式：在工程 src/main/resources/wayang.properties 放置覆盖项，随包编译加载；运行期也可用代码注入：

Configuration configuration = new Configuration();
configuration.setProperty("wayang.core.log.enabled", "false");

5.3 Maven 本地仓库

依赖默认缓存到 /root/.m2/repository，wayang-java 后端首次构建后约占 150 MB。可通过 mvn -Dmaven.repo.local=/data/m2repo ... 指定其他位置。

六、升级与多版本

1.1.1 与 0.7.1 共存：两者在 Maven 本地仓库按版本号分目录存放，互不覆盖。多版本切换只需修改 pom 中的 <wayang.version> 属性，然后重新 mvn clean package。
升级到 1.1.1 的代码适配点（均为 0.7.x → 1.1.1 实测差异）：
- JavaPlanBuilder 由 wayang-java 移入 wayang-api-scala-java 模块，需调整依赖。
- 构建器方法 withUdfJars(...) 更名为 withUdfJarOf(...)。
- writeTextFile 由两参数变为三参数，新增字符编码实参，如 .writeTextFile(uri, formatter, "UTF-8")。
- Wayang 1.x 强制 Java 17，0.7.x 时代用 Java 8 编译的存量工程需先升级编译目标。
回退：如需退回 0.7.1，把 <wayang.version> 改为 0.7.1 并将 maven.compiler.source/target 降为 8 或 11 即可，无需卸载 1.1.1 相关组件。

七、注意事项

CentOS 8 已停止维护，系统软件源必须指向 vault 仓库（本文实测环境已预先配置清华 vault 源）；若 yum repolist 为空或报 404，先修复软件源再装 JDK。
系统默认 java 命令指向预装 Java 8 时，Maven 会以 Java 8 运行并导致 Wayang 1.1.1 编译失败，务必用 alternatives --set 切换（见 4.1 节）。
Wayang 运行期会生成执行日志与统计文件，默认路径在用户主目录 ~/.wayang/（如 cardinalities.json），排查问题时可优先查看。
引入 wayang-spark 后端时会连带引入 hadoop 3.3.6 全套依赖，与 Spark 3.4.4 自带的 shaded Hadoop 类冲突，需在 pom 中排除 org.apache.hadoop:hadoop-client，详见《Apache Wayang 快速入门与集成示例》第六节。

八、常见问题

**Q1：**编译报错 invalid target release: 17 或 release version 17 not supported 怎么办？原因是 Maven 运行在旧版 JDK 上。执行 mvn -version 查看 Java version 行，若非 17.x，说明 JAVA_HOME 未指向 Java 17 或系统默认 java 仍是 1.8。按 4.1 节执行 alternatives --set java java-17-openjdk.x86_64 并 source /etc/profile.d/java17.sh 后重试，实测切换后 mvn -version 回显 Java version: 17.0.1。

**Q2：**编译报 package org.apache.wayang.api does not exist 怎么办？ 1.1.x 中 JavaPlanBuilder 所在包 org.apache.wayang.api 已移到独立模块。在 pom 中补充 org.apache.wayang:wayang-api-scala-java 依赖（版本与 wayang-core 一致）后重新编译即可，实测 BUILD SUCCESS。

**Q3：**运行时报 WayangException: Job execution failed，如何定位？用完整堆栈重跑：去掉输出重定向，观察 Caused by 链。常见根因有两类：一是 NoSuchMethodError 指向 org.apache.hadoop.fs.*，属于 Hadoop 依赖冲突，排除 wayang-spark 传递的 hadoop-client；二是 IllegalAccessError ... cannot access class sun.nio.ch.DirectBuffer，属于 Spark 在 Java 17 下的模块限制，需为 JVM 增加 --add-opens java.base/sun.nio.ch=ALL-UNNAMED 等参数，完整参数清单见《Apache Wayang 快速入门与集成示例》。

**Q4：**下载依赖缓慢或超时怎么办？确认服务器能访问 https://repo1.maven.org/maven2/（实测回显 HTTP/2 200）。内网机器可通过 mvn -Dmaven.repo.local 复用已缓存仓库，或在 settings.xml 中配置可用的中央仓库代理地址后重试。

九、卸载方式

删除工程与数据：

rm -rf /root/wayang-demo /root/wayang-data /root/wayang.properties

删除 Maven 本地仓库中的 Wayang 构件（保留不影响系统，删除可释放约 150 MB）：

rm -rf /root/.m2/repository/org/apache/wayang

卸载 Maven 与 OpenJDK 17：

yum remove -y maven java-17-openjdk-devel
rm -f /etc/profile.d/java17.sh /etc/profile.d/wayang-maven.sh

若服务器还需要 Java 8，无需额外操作，alternatives 会自动回退；确认方式：

alternatives --list | grep java

十、参考链接

Apache Wayang 官网：https://wayang.apache.org/
快速上手指南：https://wayang.apache.org/docs/guide/getting-started
官方下载页：https://wayang.apache.org/docs/start/download
GitHub 仓库（apache/wayang）：https://github.com/apache/wayang
Maven Central 上 wayang-core 构件：https://repo1.maven.org/maven2/org/apache/wayang/wayang-core/
Sonatype Central（版本检索）：https://central.sonatype.com/artifact/org.apache.wayang/wayang-core