Apache Karaf 常用 CLI 命令与工具详解
详解 Apache Karaf 4.4.12 的常用 CLI 命令与工具,覆盖 bin/karaf、bin/start、bin/client 启动脚本与 feature/bundle/system/log/config/shell/instance 七大命令族,全部命令均在 Ubuntu 22.04 实测。
Apache KarafApache Karaf2026/10/12
Apache Karaf 常用 CLI 命令与工具详解
目标：详解 Apache Karaf 4.4.12 的常用命令行工具与控制台命令族，覆盖启动脚本（
bin/karaf、bin/start、bin/status、bin/stop）、远程客户端（bin/client）以及 feature、bundle、system、log、config、shell、instance 七大命令族。全部命令与回显均在 Ubuntu 22.04 安装实例（/opt/karaf/apache-karaf）实测采集，逐行照抄。
一、环境信息
| 项目 | 值 |
|---|---|
| 操作系统 | Ubuntu 22.04.5 LTS / amd64 |
| Apache Karaf | 4.4.12 |
| JDK | OpenJDK 17.0.20.1（/usr/lib/jvm/java-17-openjdk-amd64） |
| 安装目录 | /opt/karaf/apache-karaf |
| JVM 堆 | -Xms256m -Xmx512m（bin/setenv 配置） |
| SSH 控制台 | TCP 8101（默认账号 admin / 密码 q1w2e3r4） |
| HTTP 端口 | TCP 8181（安装 http feature 后） |
二、工具概览
Karaf 的命令行工具分为两层：bin/ 下的启动/连接脚本（操作系统层面执行）与 OSGi 控制台命令（进入 Karaf shell 后执行，格式为 scope:command）。
2.1 bin/ 启动与连接脚本
| 脚本 | 用途 | 典型用法 |
|---|---|---|
bin/karaf | 前台交互式启动并直接进入控制台 | bin/karaf |
bin/start | 后台守护进程方式启动 | bin/start |
bin/status | 查看实例运行状态 | bin/status |
bin/stop | 停止后台实例 | bin/stop |
bin/client | 连接 SSH 控制台（8101）执行命令 | printf 'feature:list\n' | bin/client -u admin -p q1w2e3r4 |
2.2 控制台命令族总览
| 命令族（scope） | 核心命令 | 用途 |
|---|---|---|
feature | list / repo-list / info / install / repo-remove / repo-add | 功能特性管理 |
bundle | list / install / start / stop / uninstall / info | OSGi 模块生命周期管理 |
system | property / framework / start-level / shutdown | 系统属性与框架控制 |
log | get / set / display / clear | 日志级别与查看 |
config | list / edit / property-set / update | ConfigAdmin 配置管理 |
shell | info / threads / echo / date / exec / completion / head | 命令行辅助与系统信息 |
instance | list / create / start / stop / destroy | 多实例管理 |
💡 说明：控制台支持管道过滤，如
feature:list | grep Started；[cmd] --help可查看任意命令的参数说明。
三、前置条件
- 已按《Ubuntu 22.04 安装 Apache Karaf 4.4.12 指南》完成安装，实例位于
/opt/karaf/apache-karaf； - 已创建控制台账号（本文使用
admin/q1w2e3r4，见安装指南 4.5 节）； - 实例已启动（
bin/status返回Running ...）； - 本文所有控制台命令均通过
bin/client以标准输入方式执行，通用形式：
cd /opt/karaf/apache-karaf
printf '<命令>\n' | bin/client -u admin -p q1w2e3r4
💡 说明：
-u指定用户、-p指定密码；命令通过管道传入后输出结果并自动退出，适合脚本化运维。也可用bin/karaf进入交互式控制台直接输入命令。
四、工具详解
4.1 bin/karaf 前台启动与控制台
前台启动会打印横幅并挂起当前终端，Ctrl+D 或输入 logout 退出：
cd /opt/karaf/apache-karaf
bin/karaf
实测回显：
__ __ ____
/ //_/____ __________ _/ __/
/ ,< / __ `/ ___/ __ `/ /_
/ /| |/ /_/ / / / /_/ / __/
/_/ |_|\__,_/_/ \__,_/_/
Apache Karaf (4.4.12)
Hit '<tab>' for a list of available commands
and '[cmd] --help' for help on a specific command.
Hit '<ctrl-d>' or type 'system:shutdown' or 'logout' to shutdown Karaf.
karaf@root()>
4.2 bin/start、bin/status、bin/stop 守护进程管理
生产环境推荐后台守护方式，三件套实测：
cd /opt/karaf/apache-karaf
bin/start
sleep 20
bin/status
实测回显：
Running ...
停止实例：
cd /opt/karaf/apache-karaf
bin/stop
bin/status
实测回显：
Not Running ...
用 jps -v 确认堆参数已随进程生效（-Xms256m -Xmx512m 在列）：
jps -v | grep -i karaf
实测回显（进程参数行）：
3765 Main -Xms256m -Xmx512m -XX:+HeapDumpOnOutOfMemoryError --add-reads=java.xml=java.logging --add-exports=java.base/org.apache.karaf.specs.locator=java.xml,ALL-UNNAMED --patch-module=java.base=/opt/karaf/apache-karaf/lib/endorsed/org.apache.karaf.specs.locator-4.4.12.jar --patch-module=java.xml=/opt/karaf/apache-karaf/lib/endorsed/org.apache.karaf.specs.java.xml-4.4.12.jar --add-opens=java.base/java.security=ALL-UNNAMED --add-opens=java.base/java.net=ALL-UNNAMED --add-opens=java.base/java.lang=ALL-UNNAMED --add-opens=java.base/java.util=ALL-UNNAMED --add-opens=java.naming/javax.naming.spi=ALL-UNNAMED --add-opens=java.rmi/sun.rmi.transport.tcp=ALL-UNNAMED --add-exports=java.base/sun.net.www.protocol.file=ALL-UNNAMED --add-exports=java.base/sun.net.www.protocol.ftp=ALL-UNNAMED --add-exports=java.base/sun.net.www.protocol.http=ALL-UNNAMED --add-exports=java.base/sun.net.www.protocol.https=ALL-UNNAMED --add-exports=java.base/sun.net.www.protocol.jar=ALL-UNNAMED --add-exports=java.base/sun.net.www.content.text=ALL-UNNAMED
4.3 bin/client 远程连接与非交互执行
bin/client 通过 SSH 连接 8101 控制台。首次连接实测（横幅 + 登录提示符）：
cd /opt/karaf/apache-karaf
printf 'feature:repo-list\n' | bin/client -u admin -p q1w2e3r4
实测回显：
__ __ ____
/ //_/____ __________ _/ __/
/ ,< / __ `/ ___/ __ `/ /_
/ /| |/ /_/ / / / /_/ / __/
/_/ |_|\__,_/_/ \__,_/_/
Apache Karaf (4.4.12)
Hit '<tab>' for a list of available commands
and '[cmd] --help' for help on a specific command.
Hit 'system:shutdown' to shutdown Karaf.
Hit '<ctrl-d>' or type 'logout' to disconnect shell from current session.
admin@root()> feature:repo-list
Repository | URL
-------------------------+----------------------------------------------------------------
standard-4.4.12 | mvn:org.apache.karaf.features/standard/4.4.12/xml/features
spring-4.4.12 | mvn:org.apache.karaf.features/spring/4.4.12/xml/features
pax-jms-1.1.3 | mvn:org.ops4j.pax.jms/pax-jms-features/1.1.3/xml/features
openjpa-3.2.2 | mvn:org.apache.openjpa/openjpa-features/3.2.2/xml/features
enterprise-4.4.12 | mvn:org.apache.karaf.features/enterprise/4.4.12/xml/features
aries-jpa-2.7.3 | mvn:org.apache.aries.jpa/jpa-features/2.7.3/xml/features
specs-4.4.12 | mvn:org.apache.karaf.features/specs/4.4.12/xml/features
org.ops4j.pax.web-8.0.35 | mvn:org.ops4j.pax.web/pax-web-features/8.0.35/xml/features
org.ops4j.pax.jdbc-1.5.7 | mvn:org.ops4j.pax.jdbc/pax-jdbc-features/1.5.7/xml/features
org.ops4j.pax.cdi-1.1.4 | mvn:org.ops4j.pax.cdi/pax-cdi-features/1.1.4/xml/features
framework-4.4.12 | mvn:org.apache.karaf.features/framework/4.4.12/xml/features
pax-transx-0.5.4 | mvn:org.ops4j.pax.transx/pax-transx-features/0.5.4/xml/features
💡 说明：默认已注册 12 个 feature 仓库。
feature:repo-list输出与etc/org.apache.karaf.features.cfg的featuresRepositories对应。
4.4 feature 命令族
feature:list 查看特性清单（全量约 172 行，通常配合管道过滤，下列为已启动子集）：
cd /opt/karaf/apache-karaf
printf 'feature:list | grep Started\n' | bin/client -u admin -p q1w2e3r4
实测回显（当前已启动的 feature，共 18 行）：
feature | 4.4.12 | x | Started | standard-4.4.12 | Features Support
shell | 4.4.12 | x | Started | standard-4.4.12 | Karaf Shell
deployer | 4.4.12 | x | Started | standard-4.4.12 | Karaf Deployer
bundle | 4.4.12 | x | Started | standard-4.4.12 | Provide Bundle support
config | 4.4.12 | x | Started | standard-4.4.12 | Provide OSGi ConfigAdmin support
diagnostic | 4.4.12 | x | Started | standard-4.4.12 | Provide Diagnostic support
instance | 4.4.12 | x | Started | standard-4.4.12 | Provide Instance support
jaas | 4.4.12 | x | Started | standard-4.4.12 | Provide JAAS support
log | 4.4.12 | x | Started | standard-4.4.12 | Provide Log support
package | 4.4.12 | x | Started | standard-4.4.12 | Package commands and mbeans
service | 4.4.12 | x | Started | standard-4.4.12 | Provide Service support
system | 4.4.12 | x | Started | standard-4.4.12 | Provide System support
kar | 4.4.12 | x | Started | standard-4.4.12 | Provide KAR (KARaf archive) support
ssh | 4.4.12 | x | Started | standard-4.4.12 | Provide a SSHd server on Karaf
management | 4.4.12 | x | Started | standard-4.4.12 | Provide a JMX MBeanServer and a set of MBeans in
eventadmin | 4.4.12 | x | Started | standard-4.4.12 | OSGi Event Admin service specification for event-
pax-url-wrap | 2.7.1 | | Started | standard-4.4.12 | Wrap URL handler
wrap | 2.7.1 | x | Started | standard-4.4.12 | Transition feature to pax-url-wrap
feature:info 查看特性详情：
printf 'feature:info http\n' | bin/client -u admin -p q1w2e3r4
实测回显：
Description:
Transition feature for backward compatibility
Feature has no configuration
Feature has no configuration files
Feature depends on:
pax-web-http 0.0.0
Feature has no bundles.
Feature has no conditionals.
feature:install 安装特性（安装 http 后 Jetty 监听 8181）：
printf 'feature:install http\n' | bin/client -u admin -p q1w2e3r4
安装成功无输出；验证 HTTP 服务已就绪：
curl -s -o /dev/null -w "HTTP %{http_code}\n" http://127.0.0.1:8181/system/console
实测回显（未登录返回 401 属正常）：
HTTP 401
feature:repo-remove / feature:repo-add 仓库摘除与回加（离线场景可走本地 Maven 仓库 URL）：
printf 'feature:repo-remove enterprise-4.4.12\nfeature:repo-list | grep enterprise\nfeature:repo-add mvn:org.apache.karaf.features/enterprise/4.4.12/xml/features\nfeature:repo-list | grep enterprise\n' | bin/client -u admin -p q1w2e3r4
实测回显：
admin@root()> feature:repo-remove enterprise-4.4.12
admin@root()> feature:repo-list | grep enterprise
admin@root()> feature:repo-add mvn:org.apache.karaf.features/enterprise/4.4.12/xml/features
Adding feature url mvn:org.apache.karaf.features/enterprise/4.4.12/xml/features
admin@root()> feature:repo-list | grep enterprise
enterprise-4.4.12 | mvn:org.apache.karaf.features/enterprise/4.4.12/xml/features
💡 说明：
repo-remove按仓库名（名称-版本）摘除，成功无输出；repo-add支持完整 Maven URL 或仓库坐标。
4.5 bundle 命令族
bundle:list 查看模块清单。注意默认阈值为 50，只显示 start-level ≥ 50 的 bundle，看全量务必加 -t 0：
cd /opt/karaf/apache-karaf
printf 'bundle:list -t 0\n' | bin/client -u admin -p q1w2e3r4
实测回显（全新实例共 53 个 bundle，全量）：
ID | State | Lvl | Version | Name
---+----------+-----+--------------------+-------------------------------------
0 | Active | 0 | 7.0.5 | System Bundle, Fragments: 1
1 | Resolved | 1 | 4.4.12 | Apache Karaf :: Features :: Extensi
2 | Active | 5 | 2.7.1 | OPS4J Pax Url - mvn:
3 | Active | 5 | 4.4.12 | Apache Karaf :: OSGi Services :: Ev
4 | Active | 8 | 2.3.5 | OPS4J Pax Logging - API
5 | Active | 8 | 2.3.5 | OPS4J Pax Logging - Log4Jv2 impleme
6 | Active | 8 | 2.4.3 | Jansi
7 | Active | 9 | 3.7.4 | Apache Felix File Install
8 | Active | 9 | 1.2.0.202109301733 | org.osgi:org.osgi.util.function
9 | Active | 9 | 1.0.2 | Apache Felix Coordinator Service
10 | Active | 9 | 1.0.14 | Apache Felix Converter
11 | Active | 9 | 1.3.0.202212101352 | org.osgi:org.osgi.util.promise
12 | Active | 9 | 1.2.4 | Apache Felix Metatype Service
13 | Active | 10 | 1.9.26 | Apache Felix Configuration Admin Se
14 | Active | 11 | 1.0.16 | Apache Felix Configurator Service
15 | Active | 11 | 1.2.16 | Apache Sling Commons Johnzon Wrappe
16 | Active | 11 | 1.2.8 | Apache Felix Configuration Admin Va
17 | Active | 11 | 4.4.12 | Apache Karaf :: ConfigAdmin :: Core
18 | Active | 11 | 1.0.8 | Apache Felix Configuration Json
19 | Active | 15 | 4.4.12 | Apache Karaf :: Features :: Core
20 | Active | 30 | 1.86 | bcpkix
21 | Active | 30 | 1.86 | bcprov
22 | Active | 30 | 1.86 | bcutil
23 | Active | 30 | 1.1.5 | Apache Aries JMX API
24 | Active | 30 | 1.1.8 | Apache Aries JMX Core
25 | Active | 30 | 1.2.0 | Apache Aries Whiteboard support for
26 | Active | 20 | 1.1.3 | Apache Aries Util
27 | Active | 30 | 4.4.12 | Apache Karaf :: Bundle :: Core
28 | Active | 30 | 4.4.12 | Apache Karaf :: ConfigAdmin :: Comm
29 | Active | 26 | 4.4.12 | Apache Karaf :: Deployer :: Features
30 | Active | 24 | 4.4.12 | Apache Karaf :: Deployer :: Karaf A
31 | Active | 24 | 4.4.12 | Apache Karaf :: Deployer :: Wrap No
32 | Active | 30 | 4.4.12 | Apache Karaf :: Diagnostic :: Core
33 | Active | 80 | 4.4.12 | Apache Karaf :: OSGi Services :: Ev
34 | Active | 30 | 4.4.12 | Apache Karaf :: Features :: Command
35 | Active | 30 | 4.4.12 | Apache Karaf :: Instance :: Core
36 | Active | 30 | 4.4.12 | Apache Karaf :: JAAS :: Command
37 | Active | 30 | 4.4.12 | Apache Karaf :: JAAS :: Config
38 | Active | 30 | 4.4.12 | Apache Karaf :: JAAS :: Modules
39 | Active | 30 | 4.4.12 | Apache Karaf :: KAR :: Core
40 | Active | 30 | 4.4.12 | Apache Karaf :: Log :: Core
41 | Active | 30 | 4.4.12 | Apache Karaf :: Management
42 | Active | 30 | 4.4.12 | Apache Karaf :: Package :: Core
43 | Active | 30 | 4.4.12 | Apache Karaf :: Service :: Core
44 | Active | 30 | 4.4.12 | Apache Karaf :: Shell :: Various Co
45 | Active | 30 | 4.4.12 | Apache Karaf :: Shell :: Core
46 | Active | 30 | 4.4.12 | Apache Karaf :: Shell :: SSH
47 | Active | 30 | 4.4.12 | Apache Karaf :: System :: Core
48 | Active | 30 | 2.19.0 | Apache Mina SSHD :: OSGi
49 | Active | 30 | 2.19.0 | Apache Mina SSHD :: SCP
50 | Active | 30 | 2.19.0 | Apache Mina SSHD :: SFTP
51 | Active | 30 | 3.30.17 | JLine Bundle
52 | Active | 10 | 2.7.1 | OPS4J Pax Url - wrap:
💡 说明：
Name列在终端宽度内自动截断，可用bundle:info <ID>看完整名。OSGi 框架为 Apache Felix Framework 7.0.5（ID 0 System Bundle）。
bundle:install / bundle:start / bundle:stop / bundle:uninstall 全生命周期（全新实例下新装 bundle ID 为 53）：
cd /opt/karaf/apache-karaf
printf 'bundle:install mvn:org.apache.felix/org.apache.felix.eventadmin/1.6.4\nbundle:list -t 0 53\nbundle:start 53\nbundle:list -t 0 53\nbundle:stop 53\nbundle:list -t 0 53\nbundle:uninstall 53\nbundle:list -t 0 53\n' | bin/client -u admin -p q1w2e3r4
实测回显：
admin@root()> bundle:install mvn:org.apache.felix/org.apache.felix.eventadmin/1.6.4
Bundle ID: 53
admin@root()> bundle:list -t 0 53
ID | State | Lvl | Version | Name
---+-----------+-----+---------+-----------------------------------------------
53 | Installed | 80 | 1.6.4 | Apache Felix EventAdmin
admin@root()> bundle:start 53
admin@root()> bundle:list -t 0 53
START LEVEL 100 , List Threshold: 0
ID | State | Lvl | Version | Name
---+--------+-----+---------+--------------------------------------------------
53 | Active | 80 | 1.6.4 | Apache Felix EventAdmin
admin@root()> bundle:stop 53
admin@root()> bundle:list -t 0 53
START LEVEL 100 , List Threshold: 0
ID | State | Lvl | Version | Name
---+----------+-----+---------+------------------------------------------------
53 | Resolved | 80 | 1.6.4 | Apache Felix EventAdmin
admin@root()> bundle:uninstall 53
admin@root()> bundle:list -t 0 53
Bundle 53 is invalid
START LEVEL 100 , List Threshold: 0
ID | State | Lvl | Version | Name
---+-------+-----+---------+---------------------------------------------------
💡 说明：状态机
Installed → Active → Resolved → 卸载；卸载后查询该 ID 返回Bundle 53 is invalid且表格无行，表示已彻底移除。
4.6 system 命令族
system:property 查看/设置系统属性：
cd /opt/karaf/apache-karaf
printf 'system:property karaf.version\nsystem:property karaf.name\n' | bin/client -u admin -p q1w2e3r4
实测回显：
admin@root()> system:property karaf.version
4.4.12
admin@root()> system:property karaf.name
root
system:framework 查看 OSGi 框架、system:start-level 查看启动级别：
printf 'system:framework\nsystem:start-level\n' | bin/client -u admin -p q1w2e3r4
实测回显：
admin@root()> system:framework
Current OSGi framework is felix
admin@root()> system:start-level
Level 100
system:shutdown 关闭实例。默认交互确认，非交互（管道）方式必须加 -f 强制执行，否则读到 EOF 报错：
printf 'system:shutdown\n' | bin/client -u admin -p q1w2e3r4
实测回显（未加 -f，管道输入无应答导致报错）：
admin@root()> system:shutdown
Confirm: halt instance root (yes/no):
Error executing command: org.jline.reader.EndOfFileException
printf 'system:shutdown -f\n' | bin/client -u admin -p q1w2e3r4
sleep 10
bin/status
bin/start
sleep 22
bin/status
实测回显（强制关闭后 Not Running ...，再 bin/start 恢复 Running ...）：
admin@root()> system:shutdown -f
admin@root()>
Not Running ...
Running ...
💡 说明：
system:shutdown常用参数：-f跳过确认强制关闭、-h停机、-r重启、-c清理 data 目录后重启、-cc仅清理缓存目录后重启；time参数支持hh:mm绝对时间、+m分钟延迟与now（等同 0）。关停后用bin/start重新拉起即可。
4.7 log 命令族
log:get 查看当前日志级别：
cd /opt/karaf/apache-karaf
printf 'log:get\n' | bin/client -u admin -p q1w2e3r4
实测回显：
admin@root()> log:get
Logger | Level
------------------------+------
ROOT | INFO
audit | TRACE
org.apache.aries.spifly | WARN
org.apache.sshd | INFO
log:display 查看日志（-n 限制条数、--no-color 关闭着色）：
printf 'log:display -n 5 --no-color\n' | bin/client -u admin -p q1w2e3r4
实测回显：
admin@root()> log:display -n 5 --no-color
13:01:21.052 INFO [sshd-SshServer[3a435046](port=8101)-nio2-thread-2] Session admin@/127.0.0.1:37382 authenticated
13:03:50.274 INFO [sshd-SshServer[3a435046](port=8101)-nio2-thread-1] Session admin@/127.0.0.1:51552 authenticated
13:04:18.674 INFO [sshd-SshServer[3a435046](port=8101)-nio2-thread-2] Session admin@/127.0.0.1:55172 authenticated
13:04:32.695 INFO [sshd-SshServer[3a435046](port=8101)-nio2-thread-2] Session admin@/127.0.0.1:57124 authenticated
13:04:40.038 INFO [sshd-SshServer[3a435046](port=8101)-nio2-thread-1] Session admin@/127.0.0.1:35580 authenticated
log:set 动态调整日志级别（改 DEBUG 排障后记得改回 INFO）：
printf 'log:set DEBUG\nlog:get\nlog:display -n 3 --no-color\nlog:set INFO\nlog:get\n' | bin/client -u admin -p q1w2e3r4
实测回显：
admin@root()> log:set DEBUG
admin@root()> log:get
Logger | Level
------------------------+------
ROOT | DEBUG
audit | TRACE
org.apache.aries.spifly | WARN
org.apache.sshd | INFO
admin@root()> log:display -n 3 --no-color
13:04:40.038 INFO [sshd-SshServer[3a435046](port=8101)-nio2-thread-1] Session admin@/127.0.0.1:35580 authenticated
13:04:40.503 INFO [CM Configuration Updater (Update: pid=org.ops4j.pax.logging)] Sending Event Admin notification (configuration successful) to org/ops4j/pax/logging/Configuration
13:04:40.521 INFO [CM Configuration Updater (Update: pid=org.ops4j.pax.logging)] Sending Event Admin notification (configuration successful) to org/ops4j/pax/logging/Configuration
admin@root()> log:set INFO
admin@root()> log:get
Logger | Level
------------------------+------
ROOT | INFO
audit | TRACE
org.apache.aries.spifly | WARN
org.apache.sshd | INFO
💡 说明：日志文件默认落在
data/log/karaf.log，log:set立即生效无需重启；log:clear清空内存环形缓冲区。持久化级别的修改方式见《Apache Karaf 配置参数详解》。
4.8 config 命令族
config:list 查看配置。管道（非交互）模式下 PID 需配合 grep 过滤（括号过滤语法只在交互控制台可用）：
cd /opt/karaf/apache-karaf
printf 'config:list | grep -A8 "service.pid = org.apache.karaf.shell"\n' | bin/client -u admin -p q1w2e3r4
实测回显：
sftpEnabled = true
sshHost = 0.0.0.0
sshIdleTimeout = 1800000
sshPort = 8101
sshRealm = karaf
sshRole = ssh
----------------------------------------------------------------
Pid: org.apache.karaf.webconsole
config:edit / config:property-set / config:update 修改配置（示例将 SSH 端口设回 8101，等值修改无副作用）：
printf 'config:edit org.apache.karaf.shell\nconfig:property-set sshPort 8101\nconfig:update\n' | bin/client -u admin -p q1w2e3r4
实测回显（命令无输出即成功，config:update 会把改动写回 etc/org.apache.karaf.shell.cfg）：
admin@root()> config:update
admin@root()>
⚠️ 注意：在管道模式下直接执行
config:list (org.apache.karaf.shell)会报Error executing command: Missing opening parenthesis，请改用上文的grep过滤写法或进入交互控制台操作。
4.9 shell 命令族
shell:info 查看运行时全量信息（含 JVM 与堆内存，是核对 512MB 堆上限的便捷方式）：
cd /opt/karaf/apache-karaf
printf 'shell:info\n' | bin/client -u admin -p q1w2e3r4
实测回显：
Karaf version 4.4.12
Karaf home /opt/karaf/apache-karaf
Karaf base /opt/karaf/apache-karaf
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
Vendor Ubuntu
Pid 3765
Uptime 13 minutes
Process CPU time 6 minutes
Process CPU load 0.00
System CPU load 0.00
Open file descriptors 138
Max file descriptors 65,535
Total compile time 30.345 seconds
Threads
Live threads 86
Daemon threads 58
Peak 100
Total started 556
Memory
Current heap size 96,054 kbytes
Maximum heap size 524,288 kbytes
Committed heap size 283,648 kbytes
Pending objects 0
Garbage collector Name = 'G1 Young Generation', Collections = 4250, Time = 10.665 seconds
Garbage collector Name = 'G1 Old Generation', Collections = 0, Time = 0.000 seconds
Classes
Current classes loaded 11,966
Total classes loaded 11,967
Total classes unloaded 1
Operating system
Name Linux version 6.8.0-138-generic
Architecture amd64
Processors 12
Total physical memory 4,194,304 kbytes
Free physical memory 3,198,944 kbytes
💡 说明：
Maximum heap size 524,288 kbytes即 512MB，与bin/setenv的-Xmx512m一致。
shell:echo、shell:date、shell:completion：
printf 'shell:echo hello karaf\nshell:date\nshell:completion\n' | bin/client -u admin -p q1w2e3r4
实测回显：
admin@root()> shell:echo hello karaf
hello karaf
admin@root()> shell:date
Oct Sun 11 13:07:15 2026
admin@root()> shell:completion
GLOBAL
shell:exec 调用操作系统命令（在 Karaf 进程内执行并回显结果）：
printf 'shell:exec ls /opt/karaf\n' | bin/client -u admin -p q1w2e3r4
实测回显：
admin@root()> shell:exec ls /opt/karaf
apache-karaf
shell:head 读取文件前 N 行、shell:threads 查看线程栈：
printf 'shell:head -n 3 /opt/karaf/apache-karaf/etc/org.apache.karaf.shell.cfg\n' | bin/client -u admin -p q1w2e3r4
printf 'shell:threads | tail -n 6\n' | bin/client -u admin -p q1w2e3r4
实测回显（shell:head）：
admin@root()> shell:head -n 3 /opt/karaf/apache-karaf/etc/org.apache.karaf.shell.cfg
################################################################################
#
实测回显（shell:threads | tail -n 6，截取 RMI 接收线程栈尾部）：
at java.base@17.0.20.1/java.net.ServerSocket.accept(ServerSocket.java:532)
at org.apache.karaf.management.ConnectorServerFactory$LocalOnlyServerSocket.accept(ConnectorServerFactory.java:543)
at java.rmi@17.0.20.1/sun.rmi.transport.tcp.TCPTransport$AcceptLoop.executeAcceptLoop(TCPTransport.java:413)
at java.base@17.0.20.1/sun.rmi.transport.tcp.TCPTransport$AcceptLoop.run(TCPTransport.java:377)
at java.base@17.0.20.1/java.lang.Thread.run(Thread.java:840)
4.10 instance 命令族
Karaf 支持单安装目录下管理多个子实例。instance:create / instance:start / instance:list：
cd /opt/karaf/apache-karaf
printf 'instance:create node1\ninstance:start node1\ninstance:list\n' | bin/client -u admin -p q1w2e3r4
实测回显（root 实例 8101/1099/44444，新实例 node1 自动分配 8102/1100/44445）：
SSH Port | SSH Host | RMI Registry | RMI Registry Host | RMI Server | RMI Server Host | State | PID | Name
---------+----------+--------------+-------------------+------------+-----------------+----------+------+-----
8101 | 0.0.0.0 | 1099 | 127.0.0.1 | 44444 | 127.0.0.1 | Started | 3765 | root
8102 | 0.0.0.0 | 1100 | 127.0.0.1 | 44445 | 127.0.0.1 | Starting | 8057 | node1
instance:stop / instance:destroy 停止并销毁：
printf 'instance:stop node1\ninstance:destroy node1\ninstance:list\n' | bin/client -u admin -p q1w2e3r4
实测回显：
admin@root()> instance:list
SSH Port | SSH Host | RMI Registry | RMI Registry Host | RMI Server | RMI Server Host | State | PID | Name
---------+----------+--------------+-------------------+------------+-----------------+---------+------+-----
8101 | 0.0.0.0 | 1099 | 127.0.0.1 | 44444 | 127.0.0.1 | Started | 3765 | root
💡 说明：子实例数据位于
instances/目录；destroy 会同时清理该实例的目录与端口占用，成功后instance:list只剩 root。
五、注意事项
bundle:list默认阈值 50，只有 start-level ≥ 50 的 bundle 会显示，看全量务必加-t 0，避免误判「bundle 缺失」。- 管道（非交互）模式下的语法差异：
config:list (PID)括号过滤不可用，需用grep过滤；system:shutdown必须加-f，否则确认提示读到 EOF 报EndOfFileException。 feature:install http之后才能安装依赖 HTTP Service 的特性（如webconsole），顺序颠倒会报osgi.implementation=osgi.http依赖缺失。log:set的级别调整立即生效但重启后回到配置文件默认值；需要持久化请改etc/org.ops4j.pax.logging.cfg。- 新装 bundle 的 ID 取决于当前 bundle 总数（全新实例为 53 起），文中示例 ID 请按实际回显替换。
- 堆内存验证三板斧：
jps -v | grep -i karaf、shell:info的 Memory 段、ps -ef | grep [j]ava，三者任一均可看到-Xms256m -Xmx512m。
六、常见问题（FAQ）
Q1：bin/client 连接报 Failed to get the session. 或提示 Closed？
SSH 控制台（8101）尚未就绪。刚 bin/start 后等待 20–30 秒再连；确认 etc/org.apache.karaf.shell.cfg 的 sshPort/sshHost 未改，且账号已在 etc/users.properties 配置。
Q2：命令报 Command not found 或 gogo: CommandNotFoundException？
三类原因：一是命令所属 feature 未安装（未装 http 时没有 HTTP 相关命令）；二是命令名记错，用 [cmd] --help 核对；三是刚完成 feature 安装触发了 bundle refresh，个别命令注销后未即时重注册，等待片刻或重新连接即可恢复。
Q3：feature:install webconsole 报 Unable to resolve root 依赖缺失？
未先安装 http feature。完整报错关键段为 missing requirement [webconsole/4.4.12] osgi.implementation; osgi.implementation=osgi.http; version:Version=1.1.0，按序执行 feature:install http 再装 webconsole 即可。
Q4：log:display 输出太多怎么办？
用 -n <条数> 限流（如 log:display -n 20 --no-color，实测有效），或配合管道 grep 过滤关键字；实时跟踪用交互控制台的 log:tail（Ctrl+C 退出）。
Q5：如何在脚本里一次性执行多条命令？
把多条命令写进输入流即可，逐行执行：
cd /opt/karaf/apache-karaf
cat > /tmp/cmds.txt <<EOF
feature:list | grep Started
bundle:list -t 0 | head -n 5
EOF
bin/client -u admin -p q1w2e3r4 < /tmp/cmds.txt
七、参考链接
- Apache Karaf 官方手册（Commands）：https://karaf.apache.org/manual/latest/
- Apache Karaf 官网：https://karaf.apache.org
- 相关文档：《Ubuntu 22.04 安装 Apache Karaf 4.4.12 指南》《Apache Karaf 配置参数详解》
章节目录