Apache OFBiz 24.09.07 常用 CLI 命令与工具详解

目标：详解 Apache OFBiz 24.09.07 的命令行工具体系：gradlew 构建任务（Gradle 8.14.5）、ofbiz 主命令（状态/启停/数据加载/测试/端口偏移）、数据与用户任务（loadAll、loadAdminUserLogin、createTenant 等）、清理与插件任务，以及 systemd 托管下的启停命令。所有命令与回显均在 Ubuntu 22.04 实测环境逐条采集。

一、环境信息

安装目录：/opt/ofbiz，Gradle 版本 8.14.5（gradlew wrapper 自动下载，JVM 17.0.20.1）
命令入口：/opt/ofbiz/gradlew（构建与任务入口）、/opt/ofbiz/build/install/ofbiz/bin/ofbiz（发行版脚本）
管理端口：127.0.0.1:10523（--status/--shutdown 经此通信）
运行日志：runtime/logs/ofbiz.log；后台输出：console.log

二、工具概览

工具/入口	用途	常用度
`./gradlew`	全部 Gradle 任务入口（构建、数据、清理、插件）	核心
`ofbiz` 主命令（经 `gradlew ofbiz --args="..."` 传参）	启停/状态/数据加载/测试/端口偏移	核心
`./gradlew installDist` 生成的 `bin/ofbiz`	发行版启动脚本（免 Gradle），支持 `JAVA_OPTS`	生产推荐
`systemctl`（systemd 托管）	开机自启与启停	生产常用
`jps -v`	验证 JVM 参数与进程	运维辅助

三、前置条件

已安装 OFBiz 24.09.07（见安装指南），cd /opt/ofbiz 后执行命令。
首次执行 gradlew 会下载 Gradle 8.14.5 发行版与依赖，需外网。
--status/--shutdown 需要 OFBiz 已启动过且管理端口 10523 存活。

四、命令详解

4.1 gradlew 基础命令

./gradlew --version

回显（节选）：

Gradle 8.14.5
Launcher JVM:  17.0.20.1 (Ubuntu 17.0.20.1+1-1-22.04-Ubuntu)
Daemon JVM:    /usr/lib/jvm/java-17-openjdk-amd64 (no JDK specified, using current Java home)

./gradlew tasks

回显（OFBiz Server / Cleaning / Plugin 任务清单）：

OFBiz Server tasks
------------------
createTenant - Create a new tenant in your environment
loadAdminUserLogin - Create admin user with temporary password equal to ofbiz. You must provide userLoginId
loadAll - Load default data; meant for OFBiz development, testing, and demo purposes
loadTenant - Load data using tenantId
terminateOfbiz - Force termination of any running OFBiz servers, only use if "--shutdown" command fails
testIntegration - Run OFBiz integration tests; You must run loadAll before running this task

Cleaning tasks
--------------
cleanAll - Execute all cleaning tasks.
cleanCatalina - Clean Catalina data in runtime/catalina/work
cleanData - Clean all DB data (Derby) under runtime/data
cleanDownloads - Clean all downloaded files
cleanFooterFiles - clean generated footer files
cleanIndexes - Remove search indexes (e.g. Lucene) from runtime/indexes
cleanLogs - Clean all logs in runtime/logs
cleanNpm - Clean installed node modules
cleanOutput - Clean runtime/output directory
cleanTempfiles - Remove file in runtime/tempfiles
cleanUploads - Remove uploaded files.
cleanXtra - Clean extra generated files like .rej, .DS_Store, etc.

OFBiz Plugin tasks
------------------
createPlugin - create a new plugin component based on specified templates
installPlugin - executes plugin install task if it exists
pullPlugin - Download and install a plugin with all dependencies
pushPlugin - push an existing plugin to local maven repository
removePlugin - Uninstall a plugin and delete its files
uninstallPlugin - executes plugin uninstall task if it exists

Rules
-----
Pattern: clean<TaskName>: Cleans the output files of a task.
Pattern: ofbiz <Commands>: Execute OFBiz startup commands
Pattern: ofbizBackground <Commands>: Execute OFBiz startup commands in background and output to console.log

查看任务详情：

./gradlew help --task ofbiz
./gradlew help --task loadAll
./gradlew help --task loadAdminUserLogin

回显（help --task ofbiz 节选）：Type: JavaExec (org.gradle.api.tasks.JavaExec)，选项 --args Command line arguments passed to the main class.（即下文 ofbiz 主命令的传参方式）。

4.2 ofbiz 主命令（核心）

传参方式：./gradlew ofbiz --args="<命令选项>"。

帮助（-?/--help），完整回显：

./gradlew ofbiz --args="-?"

usage:  ofbiz|ofbizDebug|ofbizBackground [-? | -d | -l <key=value> | -s | -t <key=value> | -u] [-o <offset>]
    Executes OFBiz command e.g. start, shutdown, check status, etc
           Options                              Description
 -?, --help                      Prints this help screen to the user
 -l, --load-data <key=value>     Creates tables/load data e.g:
                                  -l readers=seed,demo,ext
                                  -l file=/tmp/dataload1.xml,/tmp/dataload2.xml
                                  -l dir=directory/of/files
                                  -l component=base
                                  -l delegator=default
                                  -l group=org.apache.ofbiz
                                  -l timeout=7200
                                  -l create-pks
                                  -l drop-pks
                                  -l create-constraints
                                  -l drop-constraints
                                  -l create-fks
                                  -l maintain-txs
                                  -l try-inserts
                                  -l repair-columns
                                  -l continue-on-failure
 -d, --shutdown                  Shutdown OFBiz
 -u, --start                     Start OFBiz
 -s, --status                    Gives the status of OFBiz
 -t, --test <key=value>          Runs the selected test or all if none
                                  selected e.g.: --test component=entity
                                  --test suitename=entitytests
                                  --test case=entity-query-tests
                                  --test loglevel=warning
 -o, --portoffset <offset>       Offsets all default ports for OFBiz
 note: Only one command can execute at a time. Portoffset may be appended.
    Also a command must be invoked separately for each argument e.g.
    gradlew "ofbiz --test component=somecomp --test case=somecase"

启动（-u/--start，gradlew 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,804 |main                 |ComponentContainer            |I| All components loaded
2026-10-11 19:35:03,804 |main                 |ContainerLoader               |I| [Startup] Loading containers...

端口就绪验证：netstat -tlnp | grep -E "8080|8443" → :::8443 LISTEN 13284/java、:::8080 LISTEN 13284/java。

状态查询（-s/--status）：

./gradlew ofbiz --args="--status"

回显（运行中）：

Config.java using configuration file start.properties
Set OFBIZ_HOME to - /opt/ofbiz
Current Status : Running

回显（已停止）：Current Status : OFBiz is Down。

优雅停止（-d/--shutdown）：

./gradlew ofbiz --args="--shutdown"

回显：

Config.java using configuration file start.properties
Set OFBIZ_HOME to - /opt/ofbiz
Shutting down server : OK

停止后 netstat 确认 8443/8080 关闭。若该命令失效（进程异常），用强杀任务：

./gradlew terminateOfbiz

（官方描述：Force termination of any running OFBiz servers, only use if "--shutdown" command fails）

数据加载（-l/--load-data）：

./gradlew ofbiz --args="-l readers=seed,demo,ext"

（等价于下述 loadAll 任务；其余子选项见 4.2 帮助：file=/dir=/component=/delegator=/timeout=/create-pks 等）

测试（-t/--test）：

./gradlew "ofbiz --test component=entity --test case=entity-query-tests"

（运行实体组件指定测试用例；多参数需拆成多个 --test）

端口偏移（-o/--portoffset）：

./gradlew "ofbiz --portoffset 100"

（默认端口整体 +100：HTTPS 8443→8543、HTTP 8080→8180，用于端口冲突场景）

后台启动：

./gradlew ofbizBackground

（官方规则：Execute OFBiz startup commands in background and output to console.log；日志在 /opt/ofbiz/console.log）

4.3 数据与用户任务

加载默认/演示数据：

./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

⚠️ 24.x 版本无 loadDemo 任务（旧版命名），请统一使用 loadAll。

创建管理员登录（重置 admin 密码为临时密码 ofbiz）：

./gradlew loadAdminUserLogin --args="admin"

（官方描述：Create admin user with temporary password equal to ofbiz. You must provide userLoginId）

租户相关：

./gradlew createTenant        # 创建新租户
./gradlew loadTenant --args="<tenantId>"   # 按 tenantId 加载数据

集成测试（需先 loadAll）：

./gradlew testIntegration

4.4 清理任务

任务	作用
`./gradlew cleanAll`	执行全部清理（数据、日志、索引、缓存、临时文件等）
`./gradlew cleanData`	清空 Derby 数据库（runtime/data 下）
`./gradlew cleanLogs`	清空 runtime/logs 日志
`./gradlew cleanIndexes`	删除搜索索引（如 Lucene）runtime/indexes
`./gradlew cleanCatalina`	清理 runtime/catalina/work
`./gradlew cleanUploads`	删除上传文件
`./gradlew cleanTempfiles`	清理 runtime/tempfiles
`./gradlew cleanDownloads`	清理下载缓存
`./gradlew cleanNpm`	清理 node_modules
`./gradlew cleanOutput`	清理 runtime/output
`./gradlew cleanXtra`	清理 .rej/.DS_Store 等杂项

4.5 插件任务

任务	作用
`./gradlew pullPlugin --args="<插件名>"`	下载并安装插件及依赖
`./gradlew installPlugin --args="<插件名>"`	执行插件自带 install 任务
`./gradlew createPlugin`	按模板创建新插件组件
`./gradlew pushPlugin --args="<插件名>"`	推送插件到本地 Maven 仓库
`./gradlew uninstallPlugin --args="<插件名>"`	执行插件卸载任务
`./gradlew removePlugin --args="<插件名>"`	卸载并删除插件文件

4.6 发行版脚本与 systemd 启停

生成发行版并直接启停（免 Gradle 依赖，生产推荐）：

cd /opt/ofbiz && ./gradlew installDist        # BUILD SUCCESSFUL in 51s
/opt/ofbiz/build/install/ofbiz/bin/ofbiz      # 前台启动
/opt/ofbiz/build/install/ofbiz/bin/ofbiz --shutdown   # 停止
/opt/ofbiz/build/install/ofbiz/bin/ofbiz --status     # 状态

systemd 托管后（见安装指南 5.1）：

systemctl start ofbiz      # 启动
systemctl status ofbiz     # 状态（active (running)）
systemctl stop ofbiz       # 停止（inactive (dead)）
systemctl restart ofbiz    # 重启
systemctl enable ofbiz     # 开机自启

JVM 参数验证：

jps -v

回显（节选）：13284 Start ... -Xms256M -Xmx512M ...

五、注意事项

单命令执行：ofbiz 主命令一次只能执行一个命令（note: Only one command can execute at a time. Portoffset may be appended.）。
传参格式：多个 --test/--load-data 参数需拆分为多个独立 --args 片段（见帮助末尾示例）。
端口偏移与 --args 组合：./gradlew "ofbiz --portoffset 100" 中 --portoffset 需与命令同时传入。
管理端口不可用：--shutdown/--status 依赖 10523 管理端口；进程被强杀后管理端口消失，此时用 terminateOfbiz 清理残留进程文件。
数据安全：cleanData/cleanAll 会清空数据库，执行前确认已备份 runtime/data。

六、常见问题

6.1 执行 loadDemo 报 Task 'loadDemo' not found

错误回显：Task 'loadDemo' not found in root project 'ofbiz' and its subprojects.

解决：24.x 改用 ./gradlew loadAll。

6.2 --shutdown 返回 IO Error / Connection reset

定位：进程正被停止或管理端口异常；或已有多实例。

解决：等待数秒重试；仍失败用 ./gradlew terminateOfbiz。

6.3 gradlew 首次执行很慢/下载失败

定位：需下载 Gradle 8.14.5 发行版与依赖。

解决：检查外网连通；gradle/wrapper/gradle-wrapper.properties 的 distributionUrl 可切换镜像（如 mirrors.cloud.tencent.com/gradle/gradle-8.14.5-bin.zip）。

6.4 如何确认命令真实生效

解决：启动用 netstat 看 8443/8080；停止后 --status 应回显 OFBiz is Down；堆参数用 jps -v。

七、参考链接

Apache OFBiz 官方文档：https://ofbiz.apache.org/
Gradle 发行版下载：https://services.gradle.org/distributions/
本专栏相关：《Ubuntu 22.04 安装 Apache OFBiz 24.09.07 指南》《Apache OFBiz 24.09.07 配置参数详解》