Ubuntu 22.04 安装 Apache OFBiz 24.09.07 指南

目标：在真实 Ubuntu 22.04 服务器上从零安装 Apache OFBiz 24.09.07（开源企业级业务自动化平台，Java/Gradle 构建，内置 Derby 数据库），覆盖前置依赖、官方下载与校验、演示数据加载、启动验证、systemd 托管与常见失败排障。以下命令与回显均在 Ubuntu 22.04.5 真实环境逐步实测。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（x86_64）
Java：OpenJDK 17.0.20.1（openjdk-17-jdk-headless）
Apache OFBiz：24.09.07（Gradle 8.14.5 构建，.zip 官方二进制发行包，约 32.3MB）
安装目录：/opt/ofbiz
默认端口：8080（HTTP）、8443（HTTPS）、8009（AJP，仅本机监听）、10523（OFBiz 管理端口，仅本机监听）
内嵌数据库：Derby（runtime/data/derby/，含 ofbiz、ofbizolap、ofbiztenant 三个库）
运行用户：root

💡 说明：OFBiz 24.09 系列为当前 Apache 官方维护的稳定分支，24.09.07 为本指南实测的最新补丁版本（2026-06 发布）。

二、前置条件

一台 Ubuntu 22.04 服务器，root 权限，可访问外网（下载官方发行包与 Gradle 依赖）。
需安装：openjdk-17-jdk-headless（含 jps，用于验证 JVM 参数）、wget、unzip、net-tools（含 netstat）、procps。
至少 2GB 空闲内存（OFBiz JVM 堆限制在 256-512MB 后，实际常驻约 500MB），2 核以上 CPU 建议。
磁盘：安装后 /opt/ofbiz 约 2GB（含 Gradle 构建产物），runtime/data 存放 Derby 数据。

三、版本选型说明

组件	推荐版本	说明
Apache OFBiz	24.09.07	当前稳定分支最新版；官方仅发布 `.zip` 与源码包
OpenJDK	17	OFBiz 24.x 官方要求 Java 17（LTS）
Gradle	8.14.5	随发行包 `gradlew` 自动下载，无需单独安装
数据库	Derby（内置）	开箱即用，适合单机演示/中小规模；生产可换 PostgreSQL/MySQL

⚠️ 注意版本差异：OFBiz 24.x 不再提供 loadDemo 等旧版 Gradle 任务，演示数据加载统一改用 ./gradlew loadAll（见 4.6）；旧教程里的 ./gradlew loadDemo 会直接报 Task 'loadDemo' not found。

四、部署步骤

4.1 更新软件源并安装基础工具

apt-get update -qq
DEBIAN_FRONTEND=noninteractive apt-get install -y \
    openjdk-17-jdk-headless wget unzip net-tools procps

验证版本回显：

# 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)

4.2 下载官方发行包并校验

cd /opt
wget -O apache-ofbiz-24.09.07.zip \
    https://dlcdn.apache.org/ofbiz/apache-ofbiz-24.09.07.zip

真实回显（下载完成行）：

2026-10-11 19:47:18 (14.7 MB/s) - 'ofbiz-test.zip' saved [33855042/33855042]

校验 SHA512（与官方 .zip.sha512 文件一致）：

sha512sum apache-ofbiz-24.09.07.zip

回显：

6602fa1f9752629486e2e0490ef95728f75e998496ec014d3eaa87e779ee7fd71efdef1a5d76856fe7a8c238c094d5dd64580963a4a560e5b01415cdaf9e28c2  apache-ofbiz-24.09.07.zip

💡 官方下载页 https://dlcdn.apache.org/ofbiz/ ；历史版本在归档站 https://archive.apache.org/dist/ofbiz/ 。内网无法直连时可用清华镜像 https://mirrors.tuna.tsinghua.edu.cn/apache/ofbiz/ 加速。

4.3 解压并安装到 /opt/ofbiz

cd /opt
unzip -q apache-ofbiz-24.09.07.zip
mv apache-ofbiz-24.09.07 /opt/ofbiz

校验压缩包完整性（可选，回显末两行）：

    testing: apache-ofbiz-24.09.07/common.gradle   OK
No errors detected in compressed data of /opt/apache-ofbiz-24.09.07.zip.

4.4 确认版本号

cat /opt/ofbiz/VERSION

回显：

 24.09.07

顶层目录（节选）：applications/、framework/、plugins/、themes/、runtime/、gradlew、build.gradle、gradle.properties。

4.5 配置 JVM 堆内存（256-512MB）

编辑 /opt/ofbiz/gradle.properties，设置 Gradle 构建进程与 OFBiz 启动进程的堆上限（实测写入）：

org.gradle.jvmargs=-Xms256m -Xmx512m

⚠️ 若服务器内存紧张，请务必设置该项，否则 Gradle 构建进程可能因默认堆配置被 OOM 中断。

4.6 加载默认/演示数据（loadAll）

OFBiz 首次运行前需加载数据（seed 种子数据 + 演示数据）。24.x 使用 loadAll 任务：

cd /opt/ofbiz
./gradlew loadAll

真实回显（加载完成行与构建结果）：

2026-10-11 19:33:55,697 |main                 |EntityDataLoadContainer       |I| =-=-=-=-=-=-= Finished the data load with 16536 rows changed.
BUILD SUCCESSFUL in 55s
19 actionable tasks: 2 executed, 17 up-to-date

💡 loadAll 说明（./gradlew help --task loadAll 官方描述）：Load default data; meant for OFBiz development, testing, and demo purposes（加载默认数据，供开发/测试/演示使用）。首次构建需下载 Gradle 发行版与依赖，耗时较长属正常。

4.7 启动 OFBiz

cd /opt/ofbiz
./gradlew ofbiz

启动日志关键回显：

> Task :ofbiz
Config.java using configuration file start.properties
Set OFBIZ_HOME to - /opt/ofbiz
2026-10-11 19:35:03,056 |main                 |ComponentContainer            |I| Auto-Loading component directory : [/opt/ofbiz/framework]
2026-10-11 19:35:03,328 |main                 |ComponentContainer            |I| Auto-Loading component directory : [/opt/ofbiz/themes]
2026-10-11 19:35:03,406 |main                 |ComponentContainer            |I| Auto-Loading component directory : [/opt/ofbiz/applications]
2026-10-11 19:35:03,571 |main                 |ComponentContainer            |I| Auto-Loading component directory : [/opt/ofbiz/plugins]
2026-10-11 19:35:03,804 |main                 |ComponentContainer            |I| All components loaded
2026-10-11 19:35:03,804 |main                 |ContainerLoader               |I| [Startup] Loading containers...

4.8 验证监听端口

netstat -tlnp | grep -E "8080|8443"

回显：

tcp6       0      0 :::8443                 :::*                    LISTEN      13284/java
tcp6       0      0 :::8080                 :::*                    LISTEN      13284/java

另可见 127.0.0.1:8009（AJP）与 127.0.0.1:10523（OFBiz 管理端口）仅本机监听。

4.9 登录验证（默认账号 admin）

OFBiz 官方默认管理账号为 admin，默认密码 ofbiz（实测验证：该哈希值即 {SHA} 摘要 of ofbiz）。先访问登录页：

curl -sk https://localhost:8443/webtools/control/login

回显：HTTP 200，页面标题 OFBiz: Web Tools: Login。

提交登录表单：

curl -sk -c /tmp/ofbiz-cookies.txt -b /tmp/ofbiz-cookies.txt \
    -X POST https://localhost:8443/webtools/control/login \
    -d "USERNAME=admin&PASSWORD=ofbiz"

回显：HTTP 200，页面标题变为 OFBiz: Web Tools: Web Tools Main Page，即登录成功。随后访问主页面：

curl -sk -b /tmp/ofbiz-cookies.txt https://localhost:8443/webtools/control/main

回显：HTTP 200，页面标题 OFBiz: Web Tools: Web Tools Main Page。

⚠️ 生产环境请在登录后立即修改 admin 默认密码（WebTools → 用户/组 → 修改密码），并限制 8443 端口的访问来源。

五、配置说明

5.1 systemd 服务托管（开机自启 + 一键启停）

生成可执行发行版（官方脚本，免 Gradle 依赖）：

cd /opt/ofbiz
./gradlew installDist

回显：BUILD SUCCESSFUL in 51s，产物 build/install/ofbiz/bin/ofbiz（内建默认 JVM 参数 -Xms256M -Xmx512M，支持 JAVA_OPTS/OFBIZ_OPTS 覆盖）。

创建 /etc/systemd/system/ofbiz.service：

[Unit]
Description=Apache OFBiz
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/ofbiz
Environment=JAVA_OPTS=-Xms256m -Xmx512m
ExecStart=/opt/ofbiz/build/install/ofbiz/bin/ofbiz
ExecStop=/opt/ofbiz/build/install/ofbiz/bin/ofbiz --shutdown
SuccessExitStatus=143
TimeoutStopSec=180
Restart=on-failure
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

启用并启动：

systemctl daemon-reload
systemctl enable ofbiz
systemctl start ofbiz

回显（enable）：Created symlink /etc/systemd/system/multi-user.target.wants/ofbiz.service → /etc/systemd/system/ofbiz.service.

约 20-50 秒后端口就绪，查看状态：

systemctl status ofbiz --no-pager

回显：

● ofbiz.service - Apache OFBiz
     Loaded: loaded (/etc/systemd/system/ofbiz.service; enabled; vendor preset: enabled)
     Active: active (running) since Sun 2026-10-11 19:43:02 UTC; 10s ago
   Main PID: 16046 (java)

停止服务：

systemctl stop ofbiz

回显（状态变为 inactive (dead)，日志末行 Stopped Apache OFBiz.），netstat 确认 8443/8080 已关闭。

⚠️ 关于 SuccessExitStatus=143：JVM 进程收到 SIGTERM 后会先执行 OFBiz 关闭钩子完成优雅退出，但退出状态仍为 143（128+15），systemd 默认将其判定为失败（Result: exit-code）。实测在未配置该指令时 systemctl stop 偶发报 failed (Result: exit-code)；配置后稳定显示 inactive (dead)。这是 Java 服务的通用处理手法。

5.2 JVM 内存配置汇总（三种形态）

形态	修改位置	示例
Gradle 构建/启动	`/opt/ofbiz/gradle.properties`	`org.gradle.jvmargs=-Xms256m -Xmx512m`
发行版脚本	`build/install/ofbiz/bin/ofbiz` 的 `DEFAULT_JVM_OPTS`	已内建 `-Xms256M -Xmx512M`
systemd 托管	`/etc/systemd/system/ofbiz.service` 的 `Environment=`	`Environment=JAVA_OPTS=-Xms256m -Xmx512m`

生效值实测验证（jps -v）：

13284 Start -Djdk.serialFilter=maxarray=100000;maxdepth=20;maxrefs=1000;maxbytes=500000 --add-opens=java.base/java.util=ALL-UNNAMED -Xms256M -Xmx512M -Dfile.encoding=US-ASCII -Duser.country=US -Duser.language=en -Duser.variant

5.3 端口配置

HTTP/HTTPS/AJP 端口定义在 /opt/ofbiz/framework/catalina/ofbiz-component.xml 的 catalina-container 中：

连接器	默认端口	关键属性
http-connector	8080	scheme=http、secure=false、compression=on、URIEncoding=UTF-8
https-connector	8443	SSLEnabled=true、证书库 framework/base/config/ofbizssl.jks、别名 ofbiz、口令 changeit
ajp-connector	8009	协议 AJP/1.3，仅本机监听

六、注意事项

账号密码：默认账号 admin、密码 ofbiz；密码哈希位于 framework/security/data/PasswordSecurityDemoData.xml（{SHA}47b56994...）。生产必须修改。
数据位置：Derby 数据在 /opt/ofbiz/runtime/data/derby/，日志在 /opt/ofbiz/runtime/logs/ofbiz.log；备份数据与日志即可恢复运行状态。
端口冲突：8443/8080 被占用时可用端口偏移启动：./gradlew "ofbiz --portoffset 100"（将默认端口整体 +100）。
磁盘：Gradle 构建会在 ~/.gradle 缓存依赖，/opt/ofbiz/build 为编译产物；./gradlew cleanAll 可清理。
前台 vs 后台：./gradlew ofbiz 前台运行（Ctrl+C 即停）；./gradlew ofbizBackground 后台运行并输出到 console.log。

七、常见问题

7.1 执行 loadDemo 报 Task 'loadDemo' not found

错误回显：

* What went wrong:
Task 'loadDemo' not found in root project 'ofbiz' and its subprojects.

定位：OFBiz 24.x 移除了旧版 loadDemo/loadDefaultData 等 Gradle 任务。

解决：改用 ./gradlew loadAll（加载 seed + demo 数据，见 4.6）。

7.2 systemctl stop 后状态为 failed (Result: exit-code)

错误回显：

ofbiz.service: Main process exited, code=exited, status=143/n/a
ofbiz.service: Failed with result 'exit-code'.

定位：JVM 收到 SIGTERM 后运行关闭钩子完成 OFBiz 优雅退出，但退出状态保留为 143（128+15，SIGTERM 语义），systemd 默认按失败处理。

解决：在 unit 中配置 SuccessExitStatus=143（见 5.1），此后 systemctl stop 显示 inactive (dead)。

7.3 启动后访问 https://localhost:8443/ 返回 404

定位：OFBiz 根路径未映射 Web 应用；各功能在独立路径下（如 /webtools、/catalog、/partymgr、/ecommerce）。

解决：用 https://localhost:8443/webtools/control/login 等具体路径访问。

7.4 如何确认 JVM 堆参数真实生效

解决：启动后执行 jps -v，在 Start 进程参数中应能看到 -Xms256M -Xmx512M（见 5.2 回显）；不要只改配置不验证。

7.5 内网下载官方包过慢

解决：用清华镜像 https://mirrors.tuna.tsinghua.edu.cn/apache/ofbiz/ 或归档站加速；下载后务必 sha512sum 校验。

八、卸载方式

systemctl disable --now ofbiz          # 先停止并取消开机自启（若配置了 systemd）
/opt/ofbiz/build/install/ofbiz/bin/ofbiz --shutdown   # 或命令行优雅停止
rm -rf /opt/ofbiz                     # 删除安装目录（含 runtime 数据与日志）
rm -rf /root/.gradle                  # 可选：删除 Gradle 依赖缓存
apt-get remove -y openjdk-17-jdk-headless   # 可选：卸载 JDK

九、参考链接

Apache OFBiz 官方下载：https://dlcdn.apache.org/ofbiz/
Apache OFBiz 归档站：https://archive.apache.org/dist/ofbiz/
清华镜像：https://mirrors.tuna.tsinghua.edu.cn/apache/ofbiz/
OFBiz 官方文档：https://ofbiz.apache.org/
OFBiz GitHub：https://github.com/apache/ofbiz-framework
容器/端口配置：framework/catalina/ofbiz-component.xml