Ubuntu 22.04 安装 Apache OpenJPA 3.2.2 指南

目标：在 Ubuntu 22.04 服务器上完成 Apache OpenJPA 3.2.2（Java 持久化 API JPA 的实现库，以 Maven 依赖 / jar 形态提供，非独立服务）的安装与验证。本文给出 JDK 11 环境准备、2.x/3.x/4.x 版本选型对照、Maven 依赖引入与「官方二进制包」两种安装方案、构建期实体增强、CRUD 运行验证与卸载方式。所有命令与回显均在 Ubuntu 22.04.5 LTS + OpenJDK 11.0.32.1 环境实测通过。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（VERSION_CODENAME=jammy）
架构：x86_64
Java：OpenJDK 11.0.32.1（openjdk-11-jdk-headless，Ubuntu 官方源）
构建工具：Apache Maven 3.6.3（Ubuntu 官方源）
OpenJPA 版本：3.2.2（JPA 2.2 规范，javax.persistence API，当前 3.x 主线最新）
数据库：H2 2.2.224（主用，内存库）、Derby 10.14.2.0（备选，官方包内置）
演示账号：root
示例工程目录：/root/openjpa-demo/
官方二进制包目录：/opt/apache-openjpa-3.2.2/

💡 说明：Apache OpenJPA 是一个发布为 Java jar 库的 JPA（Java Persistence API）实现组件（org.apache.openjpa.*），本身没有可执行守护进程或监听端口，所谓「安装」本质是准备好 JDK/构建环境并把 OpenJPA 的 jar 以依赖或 classpath 方式引入到你的 Java 工程。

二、前置条件

2.1 更新软件源

sudo apt-get update

2.2 安装 JDK 11 与 Maven

OpenJPA 3.x 的最低要求是 JDK 11，Ubuntu 22.04 官方源已内置：

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

验证 JDK 与 Maven：

java -version
javac -version
mvn -version

实测回显：

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

javac 11.0.32.1

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

⚠️ 注意：程序输出中文需 UTF-8 终端环境，否则可能出现乱码。登录 shell 或运行前执行：
export LANG=C.UTF-8 LC_ALL=C.UTF-8

三、版本选型说明

3.1 官方发布目录探测

通过 Apache 官方下载目录探测当前发布版本：

curl -sL https://downloads.apache.org/openjpa/ | grep -oE 'href="[0-9.]*/"'

实测返回的版本目录：

2.2.2/
2.4.3/
3.2.2/
4.0.1/
4.1.1/

3.2 Maven Central 版本列表

curl -sL https://repo1.maven.org/maven2/org/apache/openjpa/openjpa/maven-metadata.xml | grep -oE '<version>[^<]+</version>' | sed 's/<[^>]*>//g' | tail -25

实测返回（3.x/4.x 部分）：

3.0.0
3.1.0
3.1.1
3.1.2
3.2.0
3.2.1
3.2.2
4.0.0
4.0.1
4.1.0
4.1.1

3.3 版本对照与选择建议

版本线	JPA 规范	API 包名	所需 JDK	适用场景	结论
2.4.3	JPA 1.0/2.0	javax.persistence	JDK 8	存量老工程	兼容老项目
3.2.2	JPA 2.2	javax.persistence	JDK 11+	生产使用 JDK 11/17	本文选用
4.1.1	JPA 3.1	jakarta.persistence	JDK 17+	迁移 Jakarta EE 9+	新项目用 4.x

💡 版本选择建议：先确认服务器 JDK。若为 JDK 11 或 17，选择 3.x（3.2.2），API 为 javax.persistence；若为 JDK 17 且计划迁移 Jakarta EE（jakarta.persistence），选择 4.x（4.1.1）。本指南全程按 JDK 11 + OpenJPA 3.2.2 实测。

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

OpenJPA 官方推荐通过 Maven/Gradle 以依赖方式引入，便于统一版本、传递依赖与构建期增强。本方案从零创建 Maven 工程并验证 OpenJPA 可用。

4.1 创建 Maven 工程

mkdir -p /root/openjpa-demo
cd /root/openjpa-demo
mkdir -p src/main/java/demo
mkdir -p src/main/resources/META-INF

4.2 编写 pom.xml 并引入 OpenJPA 依赖

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

    <properties>
        <maven.compiler.source>11</maven.compiler.source>
        <maven.compiler.target>11</maven.compiler.target>
        <openjpa.version>3.2.2</openjpa.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.apache.openjpa</groupId>
            <artifactId>openjpa</artifactId>
            <version>${openjpa.version}</version>
        </dependency>
        <dependency>
            <groupId>com.h2database</groupId>
            <artifactId>h2</artifactId>
            <version>2.2.224</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.openjpa</groupId>
                <artifactId>openjpa-maven-plugin</artifactId>
                <version>${openjpa.version}</version>
                <configuration>
                    <includes>demo/Employee.class</includes>
                </configuration>
                <executions>
                    <execution>
                        <id>enhancer</id>
                        <phase>process-classes</phase>
                        <goals>
                            <goal>enhance</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>

⚠️ 注意：openjpa-maven-plugin 的 enhance 目标绑定在 process-classes 阶段，因此构建必须执行到该阶段（如 mvn process-classes、mvn package、mvn install），单独的 mvn compile 不会触发实体增强。

4.3 编写 persistence.xml 与实体类

src/main/resources/META-INF/persistence.xml（H2 内存库，自动建表）：

<?xml version="1.0" encoding="UTF-8"?>
<persistence xmlns="http://xmlns.jcp.org/xml/ns/persistence"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/persistence http://xmlns.jcp.org/xml/ns/persistence/persistence_2_2.xsd"
             version="2.2">
    <persistence-unit name="openjpa-demo">
        <class>demo.Employee</class>
        <properties>
            <property name="javax.persistence.jdbc.driver" value="org.h2.Driver"/>
            <property name="javax.persistence.jdbc.url" value="jdbc:h2:mem:testdb;DB_CLOSE_DELAY=-1"/>
            <property name="javax.persistence.jdbc.user" value="sa"/>
            <property name="javax.persistence.jdbc.password" value=""/>
            <property name="openjpa.jdbc.DBDictionary" value="h2"/>
            <property name="openjpa.Log" value="DefaultLevel=WARN, Tool=INFO, SQL=TRACE"/>
            <property name="openjpa.jdbc.SynchronizeMappings" value="buildSchema"/>
        </properties>
    </persistence-unit>
</persistence>

实体类 src/main/java/demo/Employee.java（JPA 注解映射）：

package demo;

import javax.persistence.Column;
import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.GenerationType;
import javax.persistence.Id;
import javax.persistence.Table;

@Entity
@Table(name = "employees")
public class Employee {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private long id;

    @Column(nullable = false, length = 64)
    private String name;

    @Column(length = 32)
    private String department;

    private double salary;

    public Employee() {
    }

    public Employee(String name, String department, double salary) {
        this.name = name;
        this.department = department;
        this.salary = salary;
    }

    public long getId() { return id; }
    public void setId(long id) { this.id = id; }
    public String getName() { return name; }
    public void setName(String name) { this.name = name; }
    public String getDepartment() { return department; }
    public void setDepartment(String department) { this.department = department; }
    public double getSalary() { return salary; }
    public void setSalary(double salary) { this.salary = salary; }

    @Override
    public String toString() {
        return String.format("Employee[id=%d, name=%s, department=%s, salary=%.2f]",
                id, name, department, salary);
    }
}

4.4 构建并增强实体

cd /root/openjpa-demo
mvn -q clean process-classes

实测回显（增强日志）：

79  openjpa-demo  INFO   [main] openjpa.Tool - Enhancer running on type "class demo.Employee".

验证增强结果（增强后的类实现 org.apache.openjpa.enhance.PersistenceCapable）：

javap -p target/classes/demo/Employee.class | head -5

实测回显：

Compiled from "Employee.java"
public class demo.Employee implements org.apache.openjpa.enhance.PersistenceCapable {
  private long id;
  private java.lang.String name;
  private java.lang.String department;

4.5 生成运行 classpath 并验证

cd /root/openjpa-demo
mvn -q dependency:build-classpath -Dmdep.outputFile=/tmp/cp.txt
java -Xms256m -Xmx256m -cp "target/classes:$(cat /tmp/cp.txt)" demo.Main

⚠️ 说明：demo.Main 为最小验证主类（实现新增/查询/更新/删除的完整 CRUD），完整源码见《Apache OpenJPA 3.2.2 构建并运行示例应用指南》。

实测回显（H2 内存库完整 CRUD）：

== EntityManagerFactory 创建成功 ==
== 新增完成: 3 名员工已提交 ==
== JPQL 查询全部员工 (3 条) ==
   Employee[id=1, name=张三, department=研发部, salary=18000.00]
   Employee[id=2, name=李四, department=市场部, salary=15000.00]
   Employee[id=3, name=王五, department=研发部, salary=22000.00]
== 更新完成: 2 号员工部门/薪资已修改 ==
== JPQL 条件查询 研发部 (2 条) ==
   Employee[id=3, name=王五, department=研发部, salary=22000.00]
   Employee[id=1, name=张三, department=研发部, salary=18000.00]
== JPQL 聚合查询 研发部平均薪资: 20000.0 ==
== 删除完成: 3 号员工已删除 ==
== 删除后员工总数: 2 ==
== 全部 CRUD 操作执行完毕 ==

💡 说明：mvn dependency:build-classpath 生成的 classpath 文件包含 openjpa 及其传递依赖、h2 驱动，可直接用于 java -cp 启动生产形态的 Java 应用。

五、方案 B：官方二进制包（离线安装）

适合内网隔离、无法访问 Maven 仓库的服务器。

5.1 下载并校验

cd /opt
wget https://downloads.apache.org/openjpa/3.2.2/apache-openjpa-3.2.2-binary.zip
sha512sum apache-openjpa-3.2.2-binary.zip

实测回显：

7c4966183541aeff7c0ff3126d1ae46b5457a85550076edf8e05781feaeb7d6de3aeaee497c1e7a57943ee1600f70cef1be04daa90fb05c9f495c7e70c282dfc  apache-openjpa-3.2.2-binary.zip

5.2 解压并查看包结构

unzip -q apache-openjpa-3.2.2-binary.zip
ls apache-openjpa-3.2.2/

实测回显：

CHANGES.txt  LICENSE  NOTICE  README.txt  RELEASE-NOTES.html  docs  examples  lib  openjpa-3.2.2.jar  openjpa-all-3.2.2.jar

openjpa-3.2.2.jar：OpenJPA 核心 jar；
openjpa-all-3.2.2.jar：包含全部依赖的「全量 jar」，可直接 java -cp 使用；
lib/：数据库驱动与依赖（含 Derby 10.14.2.0、serp 1.15.1 等）；
examples/：官方示例（simple、openbooks、opentrader、image-gallery）；
docs/：手册文档与 schema 定义。

5.3 直接使用全量 jar 运行工具验证

java -cp /opt/apache-openjpa-3.2.2/openjpa-all-3.2.2.jar org.apache.openjpa.enhance.PCEnhancer -help

实测回显：

Usage: java org.apache.openjpa.enhance.PCEnhancer
        [-properties/-p <properties file or resource>]
        [-<property name> <property value>]*
        [-directory/-d <output directory>]
        [-addDefaultConstructor/-adc <true/t | false/f>]
        [-jdoEnhance/-jdo <true/t | false/f>]
        [-enforcePropertyRestrictions/-epr <true/t | false/f>]
        [-tmpClassLoader/-tcl <true/t | false/f>]
        <class name | .java file | .class file | .jdo file>+

💡 说明：离线环境下，将 openjpa-all-3.2.2.jar、lib/ 下的数据库驱动一并放入应用 classpath 即可编译运行，无需 Maven 仓库。

六、配置说明

6.1 persistence.xml 位置

JPA 配置载体是 src/main/resources/META-INF/persistence.xml（打包后位于 target/classes/META-INF/persistence.xml）。持久化单元名（本文 openjpa-demo）由 Persistence.createEntityManagerFactory("openjpa-demo") 引用。

6.2 JVM 内存参数（Java 进程必配）

OpenJPA 应用是 Java 进程，生产环境应显式限制堆内存。启动命令中直接指定：

java -Xms256m -Xmx256m -cp "target/classes:$(cat /tmp/cp.txt)" demo.Main

以 systemd 托管 Java 应用时（/etc/systemd/system/openjpa-demo.service）：

[Unit]
Description=OpenJPA Demo Application
After=network.target

[Service]
Type=simple
User=root
Environment=JAVA_OPTS=-Xms256m -Xmx256m
ExecStart=/usr/bin/java -Xms256m -Xmx256m -cp /root/openjpa-demo/target/classes:/root/openjpa-demo/cp.txt demo.Main
Restart=on-failure

[Install]
WantedBy=multi-user.target

⚠️ 注意：systemd 单元中每行仅允许一个 Environment=；JVM 参数集中在 JAVA_OPTS 中注入。

修改后复核实际生效堆内存（运行期间执行）：

ps -ef | grep "[j]ava" | grep -oE "java -Xms[^ ]+ -Xmx[^ ]+|demo.Main"

实测回显：

java -Xms256m -Xmx256m
demo.Main

七、注意事项

构建期增强是必做步骤：OpenJPA 默认不允许未增强实体在运行时自动优化（移除 openjpa.RuntimeUnenhancedClasses=supported 后，未增强类直接报 This configuration disallows runtime optimization）。生产环境一律使用 openjpa-maven-plugin 或 PCEnhancer 完成构建期增强。
buildSchema 仅适合开发/演示：openjpa.jdbc.SynchronizeMappings=buildSchema 会在应用启动时自动建表，生产环境建议用 MappingTool/SchemaTool 生成 DDL 后由 DBA 执行。
终端编码：中文输出需 LANG=C.UTF-8，否则控制台出现 ???? 乱码。
数据库驱动：切换数据库（如 Derby）时，必须在 classpath 提供对应驱动 jar（org.apache.derby:derby:10.14.2.0），否则报 ClassNotFoundException。

八、常见问题

Q1：运行时报 Table "EMPLOYEES" not found 怎么处理？ A：OpenJPA 默认不自动建表。开发/演示阶段在 persistence.xml 增加 <property name="openjpa.jdbc.SynchronizeMappings" value="buildSchema"/>，并确保实体已完成构建期增强。实测中两种条件满足后，启动即自动执行 CREATE TABLE employees (...) 建表成功。

Q2：运行时报 This configuration disallows runtime optimization ... not enhanced at build time or at class load time with a javaagent 怎么处理？ A：实体类未增强。执行 mvn clean process-classes（或 mvn package）触发 openjpa-maven-plugin 的 enhance 目标，增强日志为 Enhancer running on type "class demo.Employee"；也可手动执行 PCEnhancer。

Q3：为什么 mvn compile 后实体仍未增强？ A：openjpa-maven-plugin 的 enhance 目标绑定 process-classes 阶段，而 mvn compile 只执行到 compile 阶段即结束。改用 mvn process-classes、mvn package 或 mvn install。

Q4：程序中文输出变成 ???? 乱码？ A：终端 locale 非 UTF-8。运行前执行 export LANG=C.UTF-8 LC_ALL=C.UTF-8。

Q5：切换到 Derby 报 ClassNotFoundException: org.apache.derby.jdbc.EmbeddedDriver？ A：classpath 缺少 Derby 驱动。pom.xml 增加 org.apache.derby:derby:10.14.2.0 依赖并重新 mvn dependency:build-classpath，或在 java -cp 中显式加入 derby-10.14.2.0.jar。

Q6：JDK 17 服务器能否运行 OpenJPA 3.2.2？ A：可以，3.x 支持 JDK 11 及以上；但若要用 Jakarta EE 的 jakarta.persistence API，请选择 4.x（4.1.1，需 JDK 17）。

九、卸载方式

9.1 移除示例工程与官方包

rm -rf /root/openjpa-demo
rm -rf /opt/apache-openjpa-3.2.2
rm -f /opt/apache-openjpa-3.2.2-binary.zip
rm -f /tmp/cp.txt /tmp/cp-derby.txt

9.2 清理 Maven 本地仓库缓存

rm -rf /root/.m2/repository
rm -f /root/.m2/settings.xml

9.3 卸载 JDK 与 Maven

sudo apt-get -s remove openjdk-11-jdk-headless maven

实测回显（-s 为模拟卸载，确认无误后去掉 -s 真正执行）：

0 upgraded, 0 newly installed, 2 to remove and 11 not upgraded.
Remv maven [3.6.3-5]
Remv openjdk-11-jdk-headless [11.0.32.1+1-1ubuntu1~22.04]

十、参考链接

Apache OpenJPA 官方下载页：https://downloads.apache.org/openjpa/
OpenJPA 项目主页：https://openjpa.apache.org/
Maven Central OpenJPA：https://repo1.maven.org/maven2/org/apache/openjpa/openjpa/
OpenJPA 官方文档：https://openjpa.apache.org/documentation.html