Ubuntu 22.04 安装 Apache PLC4X 1.0.0 指南

目标：在 Ubuntu 22.04 服务器上完成 Apache PLC4X 1.0.0（Java 工业协议通讯库 plc4j，以 SDK 依赖引入 + 示例应用形态提供，非独立服务）的安装与验证。本文给出 JDK 21 环境准备、版本选型、Maven 依赖引入（官方推荐）、离线 jar 包、源码发行包校验三种方案，以及编译验证与卸载方式。所有命令与回显均在 Ubuntu 22.04.5 + JDK 21 环境实测通过。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（VERSION_CODENAME=jammy）
架构：x86_64
Java：OpenJDK 21.0.12.1（openjdk-21-jdk-headless，Ubuntu 官方源）
构建工具：Apache Maven 3.6.3（Ubuntu 官方源）
PLC4X 版本：1.0.0（plc4j-api 1.0.0，2026-09 发布的 1.x 正式版）
演示账号：root
示例工程目录：/root/plc4x-demo/
离线依赖目录：/opt/plc4x/lib/

💡 说明：Apache PLC4X 的 Java 实现以 org.apache.plc4x 系列 jar 发布，本身没有可执行守护进程或服务端口，所谓「安装」本质是准备好 JDK/构建环境，并把 plc4j 的 jar 以依赖或 classpath 方式引入你的 Java 工程。

二、前置条件

2.1 更新软件源并安装编译环境

sudo apt-get update

sudo apt-get install -y openjdk-21-jdk-headless maven wget curl unzip

2.2 验证 JDK 21 与 Maven

PLC4X 1.0.0 的驱动构件（plc4j-driver-* 与 plc4j-spi-*）编译目标为 class 文件版本 65.0，必须 JDK 21 运行；安装后先确认默认 JVM：

java -version

实测回显：

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

mvn -version

实测回显：

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

⚠️ 注意：mvn -version 的 Java version 必须是 21。若显示 17 之类，说明默认 JVM 未指向 JDK 21，请在当前会话执行：
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64
export PATH=$JAVA_HOME/bin:$PATH

三、版本选型说明

3.1 从 Maven Central 探测当前版本

curl -s https://repo1.maven.org/maven2/org/apache/plc4x/plc4j-api/maven-metadata.xml | grep -E "latest|release|lastUpdated"

实测回显：

    <latest>1.0.0</latest>
    <release>1.0.0</release>
    <lastUpdated>20260907071437</lastUpdated>

metadata 中已发布的历史版本（<versions> 列表摘录）：0.9.0、0.9.1、0.10.0、0.11.0、0.12.0、0.13.0、0.13.1、1.0.0。

3.2 从 Apache 官方下载目录探测发行包

curl -s https://dlcdn.apache.org/plc4x/1.0.0/ | grep -oE "href=\"[^\"]+\""

实测回显：

href="/plc4x/"
href="README"
href="RELEASE_NOTES"
href="apache-plc4x-1.0.0-cyclonedx.json"
href="apache-plc4x-1.0.0-cyclonedx.json.asc"
href="apache-plc4x-1.0.0-cyclonedx.xml"
href="apache-plc4x-1.0.0-cyclonedx.xml.asc"
href="apache-plc4x-1.0.0-source-release.zip"
href="apache-plc4x-1.0.0-source-release.zip.asc"
href="apache-plc4x-1.0.0-source-release.zip.sha512"

3.3 选型对照

版本	Maven Central 状态	运行 JDK 要求（实测 class 版本）	适用场景	结论
1.0.0	latest/release	驱动与 SPI 构件 65.0（JDK 21），api 构件 61.0	新项目、生产首选 1.x 正式版	本指南选用
0.13.1 及更早	仅历史版本	0.x 各版本要求不同，升级前先核对官方发行说明	存量项目兼容	按需

💡 版本选择建议：PLC4X 官方仅发布源码发行包，二进制统一走 Maven Central。新装环境直接选 1.0.0，并确认 JVM 为 JDK 21（1.0.0 驱动构件实测 class 版本 65.0，用 JDK 17 会抛 UnsupportedClassVersionError，见常见问题）。

四、方案 A：Maven 项目依赖引入（官方推荐）

4.1 配置 Maven 镜像加速（可选）

国内网络环境建议在 /root/.m2/settings.xml 配置镜像加速依赖下载：

mkdir -p /root/.m2
cat > /root/.m2/settings.xml <<'XML'
<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0">
  <mirrors>
    <mirror>
      <id>aliyunmaven</id>
      <mirrorOf>central</mirrorOf>
      <name>Aliyun Maven Mirror</name>
      <url>https://maven.aliyun.com/repository/public</url>
    </mirror>
  </mirrors>
</settings>
XML

4.2 创建 Maven 工程

mkdir -p /root/plc4x-demo/src/main/java/demo
cd /root/plc4x-demo

4.3 编写 pom.xml

最小依赖组合：plc4j-api（API 与驱动管理器）+ plc4j-driver-simulated（内置模拟 PLC 驱动，无需真实硬件即可验证）。用 <dependencyManagement> 统一锁定版本为 1.0.0：

<?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>demo</groupId>
    <artifactId>plc4x-demo</artifactId>
    <version>1.0-SNAPSHOT</version>
    <packaging>jar</packaging>

    <properties>
        <maven.compiler.source>21</maven.compiler.source>
        <maven.compiler.target>21</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.apache.plc4x</groupId>
                <artifactId>plc4j-api</artifactId>
                <version>1.0.0</version>
            </dependency>
            <dependency>
                <groupId>org.apache.plc4x</groupId>
                <artifactId>plc4j-driver-simulated</artifactId>
                <version>1.0.0</version>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <dependencies>
        <dependency>
            <groupId>org.apache.plc4x</groupId>
            <artifactId>plc4j-api</artifactId>
        </dependency>
        <dependency>
            <groupId>org.apache.plc4x</groupId>
            <artifactId>plc4j-driver-simulated</artifactId>
        </dependency>
    </dependencies>
</project>

⚠️ 注意：plc4j-api 与 plc4j-driver-* 必须使用同一版本号，混用不同版本会出现运行时类不兼容。

4.4 编译验证

先放一个最小主类：

cat > /root/plc4x-demo/src/main/java/demo/HelloPlc4x.java <<'JAVA'
package demo;

public class HelloPlc4x {
    public static void main(String[] args) {
        System.out.println("plc4x-demo skeleton");
    }
}
JAVA

export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64
export PATH=$JAVA_HOME/bin:$PATH
export MAVEN_OPTS="-Xms256m -Xmx512m"
cd /root/plc4x-demo
mvn clean compile

实测结果：BUILD SUCCESS，退出码 0。

本地仓库 ~/.m2/repository/org/apache/plc4x/ 下会生成 plc4j-api 1.0.0 的 jar 与 pom；mvn dependency:list 显示的传递依赖如下：

构件	作用
plc4j-api-1.0.0.jar	公共 API：PlcDriverManager、连接、消息与取值接口
plc4j-driver-simulated-1.0.0.jar	模拟 PLC 驱动（内置内存设备）
plc4j-spi-drivers-1.0.0.jar	驱动框架 SPI（ConnectionBase、消息实现）
plc4j-spi-values-1.0.0.jar	PlcValue 值体系
plc4j-spi-buffers-api / byte	字节读写缓冲
plc4j-spi-config / fields / utils	配置、字段、工具 SPI
plc4j-transports-api	传输层抽象
plc4j-utils-audit-log-api	审计日志 API（1.0.0 新增）
slf4j-api-2.0.18.jar	日志门面

五、方案 B：离线 jar 包（无 Maven 构建环境）

在只有 Java 运行环境、不能执行 Maven 构建的服务器上，可在一台联网机器用 mvn dependency:copy-dependencies 导出依赖 jar 集，再整体拷贝到目标服务器的固定目录，用 javac/java 以 classpath 方式使用。

5.1 导出离线 jar 集

在能运行 Maven 的机器上（本文在验证环境直接执行）：

cd /root/plc4x-demo
mvn dependency:copy-dependencies -DoutputDirectory=/opt/plc4x/lib

实测结果：命令成功，/opt/plc4x/lib 生成 26 个 jar（含 plc4j-api-1.0.0.jar、plc4j-driver-simulated-1.0.0.jar、plc4j-spi-* 系列、slf4j-api 2.0.18、commons-lang3 3.20.0 等）。

ls /opt/plc4x/lib | wc -l

实测回显：

5.2 用 javac 直接编译、java 直接运行

mkdir -p /opt/plc4x/classes
javac -encoding UTF-8 -cp "/opt/plc4x/lib/*" -d /opt/plc4x/classes /root/plc4x-demo/src/main/java/demo/HelloPlc4x.java

实测回显：编译成功无输出。

java -Xms256m -Xmx512m -cp "/opt/plc4x/classes:/opt/plc4x/lib/*" demo.HelloPlc4x

实测回显（源码为完整示例时）：

[1] Registered protocol codes: [simulated]
[2] isConnected = true

⚠️ 注意：-cp "/opt/plc4x/lib/*" 的通配符必须加双引号，否则被 shell 展开；驱动发现依赖 ServiceLoader，jar 集必须整体拷贝、缺一不可。

六、方案 C：源码发行包获取与校验

6.1 下载并校验 sha512

mkdir -p /opt/plc4x/src
cd /opt/plc4x/src
wget https://dlcdn.apache.org/plc4x/1.0.0/apache-plc4x-1.0.0-source-release.zip
wget https://dlcdn.apache.org/plc4x/1.0.0/apache-plc4x-1.0.0-source-release.zip.sha512
sha512sum apache-plc4x-1.0.0-source-release.zip

实测回显：

f654ef368d494bc2c344ff010f5d0db78ff9d1eee9a0588f3fef4ce16597920852f8bd424808f5c2ed02e76b951929fe1736fed34d4c210ad2f4a27b18303cc0  apache-plc4x-1.0.0-source-release.zip

与官方 .sha512 文件内容（cat apache-plc4x-1.0.0-source-release.zip.sha512）逐字比对一致：

f654ef368d494bc2c344ff010f5d0db78ff9d1eee9a0588f3fef4ce16597920852f8bd424808f5c2ed02e76b951929fe1736fed34d4c210ad2f4a27b18303cc0

6.2 解压源码包

unzip -q apache-plc4x-1.0.0-source-release.zip
ls apache-plc4x-1.0.0 | wc -l

实测回显：

源码树包含 CHANGELOG.md、DEVELOPMENT.md、DEPENDENCIES、LICENSE 等 33 个顶层条目。

⚠️ 注意：官方 .sha512 文件只含哈希值、不含文件名，直接 sha512sum -c 会报 no properly formatted SHA512 checksum lines found（实测），应手工比对或把「哈希值 + 文件名」拼成标准格式后再校验。从源码完整构建耗时较长、对构建机资源要求高，日常使用建议走方案 A/B，本文未将源码构建列入验证主线。

七、多方案对比与选择建议

维度	方案 A：Maven 依赖	方案 B：离线 jar 集	方案 C：源码发行包
版本	1.0.0	1.0.0	1.0.0
是否需联网	首次构建需联网（可配镜像）	仅导出机联网，目标机离线	下载机联网
安装方式	pom 依赖自动解析传递依赖	copy-dependencies 导出后 javac/java	wget + sha512 校验 + unzip
适用场景	常规开发与持续集成	内网隔离、无构建环境	审计源码、合规留档

选择建议：可联网环境一律选方案 A；内网隔离用方案 B（导出机与目标机 JDK 大版本必须同为 21）；需要源码审计或离线合规留档再叠加方案 C。

八、配置说明

JDK：JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64，可写入 /etc/environment 持久化。
JVM 内存：示例与生产均建议 -Xms256m -Xmx512m 起（plc4j 为客户端库，堆占用与协议栈、连接数相关，先用小堆再按观测调整）。
依赖版本：所有 org.apache.plc4x 构件在 <dependencyManagement> 中统一锁定 1.0.0。
日志：plc4j 通过 SLF4J 输出，运行期加入 slf4j-simple 即可看到驱动日志，配置方法见《Apache PLC4X 1.0.0 配置参数详解》篇。

九、注意事项

⚠️ 注意：

PLC4X 1.0.0 驱动构件要求 JDK 21，JDK 17 只能加载 plc4j-api（61.0），加载驱动会抛 UnsupportedClassVersionError。

plc4j 是进程内 SDK，没有独立服务端口；安全边界由宿主 Java 应用与网络出口策略承担。

首次运行 DefaultPlcDriverManager 会通过 ServiceLoader 扫描 classpath 上的驱动 jar，删除或遗漏 plc4j-driver-* jar 会直接表现为「找不到驱动」。

十、常见问题

Q1：运行报 UnsupportedClassVersionError: org/apache/plc4x/java/simulated/SimulatedDriver has been compiled by a more recent version of the Java Runtime (class file version 65.0), this version of the Java Runtime only recognizes class file versions up to 61.0？原因：JVM 是 JDK 17（class 版本 61），而 plc4j-driver 1.0.0 编译目标为 65.0（JDK 21），实测该错误在 ServiceLoader 加载驱动阶段抛出。解决：安装 openjdk-21-jdk-headless 并切换 JAVA_HOME 后重跑（本文已按 JDK 21 验证通过）。

Q2：mvn 构建下载依赖很慢或失败？ 在 /root/.m2/settings.xml 配置镜像（见 4.1），mirrorOf 用 central。配置后本文全部依赖在数秒至数十秒内拉取完成。

Q3：sha512sum -c 报 no properly formatted SHA512 checksum lines found？ 官方 .sha512 文件只有哈希值没有文件名（实测）。手工比对，或自行构造「哈希两空格文件名」格式的校验文件后再 -c。

Q4：能只引 plc4j-api 吗？ 只引入 api 可以编译，但没有任何驱动可用，getConnection 会抛 Unable to find driver for protocol。必须至少追加一个驱动构件（本文用 plc4j-driver-simulated；接真实设备再换对应协议驱动）。

十一、卸载方式

移除工程与离线目录：

rm -rf /root/plc4x-demo /opt/plc4x
rm -rf ~/.m2/repository/org/apache/plc4x

同时移除 JDK 21 与 Maven：

sudo apt-get remove -y openjdk-21-jdk-headless maven
sudo apt-get autoremove -y

十二、参考链接

Apache PLC4X 官网：https://plc4x.apache.org/
Maven Central 构件目录：https://repo1.maven.org/maven2/org/apache/plc4x/
Apache 官方下载目录：https://dlcdn.apache.org/plc4x/
历史版本归档：https://archive.apache.org/dist/plc4x/