Ubuntu 22.04 安装 Apache Wayang 指南

一、环境信息

本文全部步骤在 Ubuntu 22.04 真实环境中执行并验证通过，环境信息如下：

项目	内容
操作系统	Ubuntu 22.04.5 LTS
Java	OpenJDK 17.0.20.1（build 17.0.20.1+1-1-22.04-Ubuntu）
Maven	Apache Maven 3.6.3
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）。Maven Central 上当前稳定版本为 1.1.1，本文以此为准；0.7.x 线为旧版本，模块与 API 均有差异。

二、前置条件

服务器可访问互联网，以下地址可达：
- Ubuntu APT 软件源（archive.ubuntu.com 或内网源）
- Maven 中央仓库：https://repo1.maven.org/maven2/
磁盘剩余空间不少于 2 GB（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 版本选择

查询 org.apache.wayang:wayang-core 在 Maven Central 的发布列表：

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 仅在维护存量代码时考虑。

3.2 后端依赖矩阵

后端模块	引擎与版本	额外依赖	适用场景
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 即可完整跑通。wayang-spark local 单进程方式的完整实测见《Apache Wayang 快速入门与集成示例》。

3.3 JDK 版本要求

Wayang 版本	JDK 要求	实测结论
1.0.0 / 1.1.0 / 1.1.1	Java 17	Ubuntu 源内 OpenJDK 17 编译运行全部通过
0.7.0 / 0.7.1	Java 8/11	未在本文验证

Ubuntu 22.04 官方源同时提供 openjdk-11-jdk 与 openjdk-17-jdk，直接安装 openjdk-17-jdk 即可，无需手动配置下载源。

四、部署步骤

4.1 安装 OpenJDK 17 与 Maven

Ubuntu 22.04 的 APT 源内自带 JDK 17 与 Maven，一条命令完成安装：

apt-get update
apt-get install -y openjdk-17-jdk maven

实测回显（节选）：

Setting up openjdk-17-jdk:amd64 (17.0.20.1+1-1-22.04-Ubuntu) ...
Setting up maven (3.6.3-1) ...

验证版本：

java -version

实测回显：

openjdk version "17.0.20.1" 2026-08-18
OpenJDK Runtime Environment (build 17.0.20.1+1-1-22.04-Ubuntu)
OpenJDK 64-Bit Server VM (build 17.0.20.1+1-1-22.04-Ubuntu, mixed mode, sharing)

mvn -version | head -3

实测回显：

Apache Maven 3.6.3
Maven home: /usr/share/maven
Java version: 17.0.20.1, vendor: Ubuntu, runtime: /usr/lib/jvm/java-17-openjdk-amd64

若机器上存在多个 JDK，可用 update-alternatives --config java 交互选择默认版本；并建议把 JAVA_HOME 写入 /etc/profile.d/jdk17.sh（这是 JAVA_OPTS/MAVEN_OPTS 类环境变量的推荐修改位置）：

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

4.2 创建 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.3 引入 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：通用算子与数据类型（Tuple2、TextFileSource 等）。
wayang-java：Java Stream 后端。
wayang-api-scala-java：JavaPlanBuilder fluent 构建器。1.x 里该类已不在 wayang-java 中，缺失时编译报 package org.apache.wayang.api does not exist（实测踩坑，见第八节）。

4.4 编写 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.5 编译打包

将 Maven JVM 堆限定在 256-512 MB（写入 /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

首次构建会下载约 150 MB 依赖到 /root/.m2/repository。dependency:copy-dependencies 把依赖复制到 target/lib，供 java -cp 通配符引用。

4.6 运行验证

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 次等）。

在任务运行期间另开会话验证 JVM 堆参数：

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

实测回显：

root        5820    5818 99 14:48 ?        00:00:02 java -Xms256m -Xmx512m -cp target/wayang-demo-1.0.0.jar:target/lib/* com.example.WordCount

jps -v

实测回显：

5820 WordCount -Xms256m -Xmx512m

两处回显均确认 -Xms256m -Xmx512m 生效。

4.7 过滤聚合任务验证

创建 /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/jdk17.sh	指定 JDK 17，Maven 优先用它编译运行
MAVEN_OPTS	/etc/profile.d/wayang-maven.sh	Maven 自身 JVM 堆，实测 -Xms256m -Xmx512m
JAVA_OPTS	启动脚本内，无系统级强制位置	`java` 直跑应用时的 JVM 参数，本文在命令行直接给出

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）。覆盖方式两种：

工程内放置 src/main/resources/wayang.properties（注意：打成 jar 后从 jar 内加载该文件会抛 WayangException: Could not access jar:...!/wayang.properties，实测确认；建议运行期用显式路径加载）。
代码注入（优先级最高，实测生效）：

Configuration configuration = new Configuration("file:///root/wayang.properties");
configuration.setProperty("wayang.core.fallback.udf.cpu.lower", "777");

完整键位解析见《Apache Wayang 配置参数详解》。

5.3 Maven 本地仓库

依赖缓存位于 /root/.m2/repository；需要迁移时用 mvn -Dmaven.repo.local=/data/m2repo ... 指定。

六、升级与多版本

多版本共存：1.1.1 与 0.7.1 在本地仓库按目录隔离，改 <wayang.version> 属性并 mvn clean package 即可切换，无需卸载。
0.7.x → 1.1.1 升级适配点（实测差异）：
- JavaPlanBuilder 从 wayang-java 移到 wayang-api-scala-java；
- withUdfJars(...) 更名为 withUdfJarOf(...)；
- writeTextFile 增加编码参数，需写成 .writeTextFile(uri, formatter, "UTF-8")；
- 编译目标必须升到 Java 17。
升级后验证：重跑本文 4.6 节 WordCount，输出与 4.6 节回显一致即为迁移成功。

七、注意事项

系统若同时装有多个 JDK，务必确认 mvn -version 的 Java version 行为 17.x，否则编译 Wayang 1.x 工程必然失败。
Wayang 运行日志与统计文件默认写入 ~/.wayang/（cardinalities.json、executions.json），磁盘紧张时定期清理。
mvn dependency:copy-dependencies 不会清理 target/lib 中的历史 jar，改完依赖后建议 rm -rf target/lib 再重拷，避免旧包残留干扰排查（实测踩坑）。
仅装 JRE（openjdk-17-jre-headless）时缺少 javac，mvn package 会失败，请安装 openjdk-17-jdk。

八、常见问题

Q1：apt-get install openjdk-17-jdk 找不到软件包怎么办？先执行 apt-get update 刷新索引；仍失败则检查 /etc/apt/sources.list 中的 Ubuntu 源是否可达（实测 Ubuntu 22.04.5 官方源内含 openjdk-17-jdk 17.0.20.1）。内网服务器需换成可访问的内网源。

**Q2：**编译报 package org.apache.wayang.api does not exist 怎么办？在 pom 中补上 org.apache.wayang:wayang-api-scala-java 依赖（版本用 ${wayang.version} 与其他 Wayang 模块保持 1.1.1 一致）后重新编译。实测补依赖后 BUILD SUCCESS。

Q3：mvn package 报 invalid target release: 17 怎么办？ Maven 跑在旧 JDK 上。执行 mvn -version 看 Java version；若不是 17，用 update-alternatives --config java 切到 17 并 source /etc/profile.d/jdk17.sh 后重试。

**Q4：**运行 WordCount 报 Could not access jar:file:...wayang.properties 怎么办？这是把 wayang.properties 打进 jar 后，Configuration 默认按 jar 内路径加载失败导致（实测复现）。两种解决方式：一是不要把该文件打入 jar，改放外部路径；二是代码里显式加载 new Configuration("file:///root/wayang.properties")，实测可正常读取。

九、卸载方式

删除工程、数据与配置文件：

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

清理本地仓库中的 Wayang 构件（约 150 MB）：

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

卸载 Maven 与 OpenJDK 17：

apt-get purge -y maven openjdk-17-jdk openjdk-17-jre
apt-get autoremove -y
rm -f /etc/profile.d/jdk17.sh /etc/profile.d/wayang-maven.sh

清理 APT 缓存包（可选）：

apt-get clean

十、参考链接

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