Apache Unomi 3.0.1 常用 CLI 命令与工具详解

Apache Unomi 3.0.1 基于 Apache Karaf 4.4.8 构建，日常运维围绕 bin 目录下的脚本工具与 Karaf 控制台命令展开。本文按「脚本工具 → 控制台命令」的顺序逐条讲解，全部命令与回显均在真实环境实测。

一、环境信息

项目	说明
操作系统	Ubuntu 22.04.5 LTS
Apache Unomi	3.0.1（安装于 /opt/unomi）
Karaf 运行时	4.4.8（system:version 实测输出）
OSGi 框架	Felix Framework 7.0.5（shell:info 实测输出）
JDK	OpenJDK 17.0.20.1
控制台端口	8102（SSH 协议，bin/client 默认连接）
管理账号	karaf / q1w2e3r4（users.properties 实测配置）

二、工具概览

/opt/unomi/bin 目录下与运维直接相关的脚本工具：

工具	用途
bin/status	查看运行状态
bin/start	以守护方式启动 Karaf
bin/stop	优雅停止 Karaf
bin/karaf	Karaf 主脚本，支持 server（前台）/ run / daemon / client / status / stop / console 子命令
bin/client	连接 Karaf 远程控制台执行命令（SSH 到 8102 端口）
bin/setenv	环境变量注入文件（JAVA_HOME、JVM 内存等）
bin/instance、bin/shell、bin/inc	多实例管理、本地 shell 等发行包附带脚本

注意：bin/karaf 不支持 start 子命令，守护启动应使用 bin/start，服务托管应使用 bin/karaf server 前台模式。

三、前置条件

已完成 Unomi 3.0.1 部署且系统完全启动（首次启动需执行过一次 unomi:start 初始化）。
使用 bin/client 前已知晓 Karaf 管理账号凭据（本文示例 karaf / q1w2e3r4）。
远程控制台 8102 端口本机可达（默认监听 0.0.0.0，生产建议限制为 127.0.0.1 或防火墙屏蔽）。
root 权限执行 bin/start、bin/stop 时注意进程属主：若 Unomi 由专用账号运行，应切换到该账号执行，避免 data 目录属主混乱。

四、工具详解

4.1 bin/status：查看运行状态

/opt/unomi/bin/status

运行中实测回显：

Running ...

停止状态实测回显：

Not Running ...

该脚本通过 instance.properties 中登记的 PID 判断进程存活。注意：以 systemd bin/karaf server 方式启动时，PID 文件写入晚于 systemd 报告 active，启动初期短暂显示 Not Running 属正常现象，以 systemctl status unomi 为准。

4.2 bin/start：守护方式启动

/opt/unomi/bin/start

执行后脚本立即返回，Karaf 在后台完成启动，随后可用 bin/status 确认。适合手工运维场景；生产环境建议使用 systemd 托管（bin/karaf server）而非 bin/start。

4.3 bin/stop：优雅停止

/opt/unomi/bin/stop

实测停止后确认进程已全部退出：

ps -ef | grep karaf.main.Main | grep -v grep | wc -l

实测回显：

4.4 bin/karaf server：前台模式启动

/opt/unomi/bin/karaf server

前台运行、日志直接输出到终端，Ctrl+C 会终止进程。systemd 服务单元以该方式作为 ExecStart（Type=simple），是生产环境推荐形态。bin/karaf 的 run 子命令与其类似，daemon 子命令用于无终端守护场景。

4.5 bin/client：连接远程控制台

bin/client 通过 SSH 连接 8102 端口进入 Karaf 控制台，修改密码后必须显式携带凭据。三种使用方式：

方式一，交互模式（进入控制台后输入命令，Ctrl+D 或 logout 退出）：

/opt/unomi/bin/client -u karaf -p q1w2e3r4

方式二，标准输入管道执行单条或多条命令（推荐，回显清晰）：

echo "system:version" | /opt/unomi/bin/client -u karaf -p q1w2e3r4

实测回显：

4.4.8

方式三，命令作为参数直接执行（仅适合不含空格、括号、引号的简单命令）：

/opt/unomi/bin/client -u karaf -p q1w2e3r4 unomi:start

批量执行多条命令时，用 printf 将多行命令经管道一次传入（config:edit 系列必须整批传入，见 4.9 节）。

4.6 系统信息命令：system:version 与 shell:info

system:version 输出 Karaf 版本（注意 4.4.8 中不存在 shell:version 命令）：

echo "system:version" | /opt/unomi/bin/client -u karaf -p q1w2e3r4

shell:info 输出运行时全景信息：

echo "shell:info" | /opt/unomi/bin/client -u karaf -p q1w2e3r4

实测回显（节选）：

Karaf
  Karaf version               4.4.8
  Karaf home                  /opt/unomi
  OSGi Framework              org.apache.felix.framework-7.0.5

JVM
  Java Virtual Machine        OpenJDK 64-Bit Server VM version 17.0.20.1+1-1-22.04-Ubuntu
  Version                     17.0.20.1
  Pid                         60124
  Max file descriptors        65,535
Threads
  Live threads                110

4.7 bundle:list：查看 OSGi 模块

echo "bundle:list" | /opt/unomi/bin/client -u karaf -p q1w2e3r4

实测共 219 个 bundle，全部 Active。过滤 Unomi 自身模块：

echo "bundle:list" | /opt/unomi/bin/client -u karaf -p q1w2e3r4 | grep -i unomi

实测回显（节选）：

177 │ Active   │  75 │ 3.0.1        │ Apache Unomi :: Specification API
178 │ Active   │  75 │ 3.0.1        │ Apache Unomi :: Common Classes
181 │ Active   │  85 │ 3.0.1        │ Apache Unomi :: Extensions :: Lists :: A

首次初始化完成前执行该命令，会看到大量 bundle 处于 Resolved 状态，这是 3.x 首启的正常现象，执行 unomi:start 后全部转为 Active。

4.8 feature:list -i：查看已安装特性

echo "feature:list -i" | /opt/unomi/bin/client -u karaf -p q1w2e3r4 | grep -i unomi

实测回显（节选）：

unomi-groovy-actions                 │ 3.0.1            │          │ Started │ unomi-groovy-actions
unomi-kar                            │ 3.0.1            │          │ Started │ unomi-kar
unomi-rest-ui                        │ 3.0.1            │          │ Started │ unomi-kar

4.9 config 系列：查看与在线修改配置

查看指定配置（过滤条件含括号，必须整体加引号并经标准输入传入）：

echo 'config:list "(service.pid=org.apache.unomi.persistence.elasticsearch)"' | /opt/unomi/bin/client -u karaf -p q1w2e3r4

实测回显（节选）：

Pid:            org.apache.unomi.persistence.elasticsearch
   cluster.name = contextElasticSearch
   elasticSearchAddresses = localhost:9200
   minimalElasticsearchVersion = 9.0.3
   sslEnable = false

在线修改参数（config:edit、config:property-set、config:update 必须在同一次会话依次执行，实测将 defaultQueryLimit 改为 20）：

printf 'config:edit org.apache.unomi.persistence.elasticsearch\nconfig:property-set defaultQueryLimit 20\nconfig:update\n' | /opt/unomi/bin/client -u karaf -p q1w2e3r4

修改结果由 fileinstall 回写到 etc/org.apache.unomi.persistence.elasticsearch.cfg（grep 实测 defaultQueryLimit = 20），并自动重载生效，无需重启服务。恢复默认值时按同样方法改回 10。

4.10 log:display：查看日志

echo "log:display -n 2" | /opt/unomi/bin/client -u karaf -p q1w2e3r4

实测回显（示例）：

08:29:36.505 INFO [sshd-SshServer[39a04064](port=8102)-nio2-thread-1] Session karaf@/127.0.0.1:49936 authenticated

-n N 表示显示最近 N 条；完整日志文件位于 /opt/unomi/data/log/karaf.log。log:tail 命令可持续跟踪滚动输出，适合排查问题时使用。

4.11 unomi:start：首次初始化命令

Unomi 3.0.1 首次启动时 boot feature 只安装不启动，必须执行一次 unomi:start（官方手册快速开始第 7 步）：

echo "unomi:start" | /opt/unomi/bin/client -u karaf -p q1w2e3r4

查看命令帮助：

echo "unomi:start --help" | /opt/unomi/bin/client -u karaf -p q1w2e3r4

实测回显（节选）：

DESCRIPTION
        unomi:start

初始化成功后 karaf.log 出现 Server successfully started 31 bundles and 1 required services。该命令幂等：已启动状态下重复执行无副作用，但已初始化的实例重启后无需再执行。

4.12 system:shutdown：停止 Karaf 实例

控制台内置提示 Hit 'system:shutdown' to shutdown Karaf，该命令等效于 bin/stop，执行后 Karaf 优雅退出。以 systemd 托管的实例停止后会被 Restart 策略重新拉起（本文 unomi.service 配置 Restart=on-failure，正常退出不会自动重启），运维时需注意。

五、注意事项

系统完全启动前 bin/client 不可用：连接会报 Closed 或长时间挂起，脚本化调用务必用 timeout 30 包裹并做重试。
修改 users.properties 密码后，所有 client 调用必须携带新凭据，否则报 No more authentication methods available。
config:list 的过滤条件、含空格或括号的命令必须经标准输入管道传入，命令行参数形式会导致参数被拆分而报 InvalidSyntaxException。
bin/status 在 systemd 前台模式启动初期可能显示 Not Running（PID 文件写入滞后），判断服务状态以 systemctl status unomi 为准。
config:edit 会话状态与单次连接绑定，edit、property-set、update 必须在同一次 client 调用中完成。
8102 控制台具备完全管理权限，生产环境务必修改默认密码并限制访问来源。

六、常见问题

**Q1：**执行 shell:version 报 Command not found？ Karaf 4.4.8 没有该命令，查看版本使用 system:version，或通过 shell:info 的 Karaf version 字段获取。

**Q2：**config:list 加过滤条件报 InvalidSyntaxException: Missing opening parenthesis？过滤条件的括号被命令行解析器拆散所致。将整条命令用引号包裹后经标准输入传入：echo 'config:list "(service.pid=org.apache.unomi.persistence.elasticsearch)"' | bin/client -u karaf -p q1w2e3r4。

**Q3：**bin/client 报 Closed 或长时间无响应？多为系统尚未完全启动，等待 2-5 分钟重试并在脚本中加 timeout；若报 No more authentication methods available 则是凭据错误，核对 users.properties 中的账号密码。

**Q4：**bin/status 显示 Not Running 但服务实际正常？ PID 登记文件的写入晚于进程启动，属启动时序现象；以 systemctl status unomi 或 REST 探活（8181 端口）为准，完全启动后 bin/status 会恢复 Running。

**Q5：**config:property-set 修改后配置没有变化？确认三步在同一会话执行且以 config:update 结尾；随后用 grep 检查 etc 下对应 cfg 文件是否已回写，fileinstall 数秒内自动加载。

**Q6：**首次启动后 8181 无响应、bundle 全部 Resolved？执行一次 echo "unomi:start" | /opt/unomi/bin/client -u karaf -p q1w2e3r4 完成初始化，详见 4.11 节。

七、参考链接

Apache Karaf 官方文档（命令参考）：https://karaf.apache.org/documentation.html
Apache Unomi 官方手册（快速开始）：https://unomi.apache.org/manual/latest/
Apache Karaf 4.4.8 发布说明：https://karaf.apache.org/download#karaf-448