Apache Karaf 配置参数详解

目标：详解 Apache Karaf 4.4.12 的配置体系，包括配置文件位置、核心参数含义、修改方式与生效范围、JVM 堆限制、生产配置模板和常见排障。所有参数与默认值均在 Ubuntu 22.04 安装实例（/opt/karaf/apache-karaf）实测核对。

一、环境信息

二、前置条件

1. 已按《Ubuntu 22.04 安装 Apache Karaf 4.4.12 指南》部署好实例并能启动；
2. 具备读写 etc/ 目录的权限（root 或同一属主账号）；
3. 会使用 bin/client 或 bin/karaf 进入控制台（用户 admin / 密码 q1w2e3r4）。

三、参数查看与修改方式

3.1 配置文件修改流程

先备份，再编辑，后重载/重启：

cd /opt/karaf/apache-karaf/etc
cp org.apache.karaf.shell.cfg org.apache.karaf.shell.cfg.bak
vi org.apache.karaf.shell.cfg

💡 说明：config/feature/bundle 级配置可在控制台热改或需重启，详见各参数小节；.properties 中 # 开头为注释，空行忽略。

3.2 控制台内查看与修改配置（config 命令族）

查看某个 PID（Persistent ID，即文件名去掉结尾）的全部配置：

cd /opt/karaf/apache-karaf
printf 'config:list | grep -A8 "service.pid = org.apache.karaf.shell"\n' | bin/client -u admin -p q1w2e3r4

实测回显（该 PID 的属性段）：

   sftpEnabled = true
   sshHost = 0.0.0.0
   sshIdleTimeout = 1800000
   sshPort = 8101
   sshRealm = karaf
   sshRole = ssh

控制台内修改并提交：

printf 'config:edit org.apache.karaf.shell\nconfig:property-set sshPort 8101\nconfig:update\n' \
  | bin/client -u admin -p q1w2e3r4

💡 说明：config:update 提交会同步写回 etc/ 下对应文件；SSH/JMX/HTTP 端口类改动仍需重启实例完全生效。

四、参数总览

五、核心参数分类详解

5.1 SSH 控制台（org.apache.karaf.shell.cfg）

sshPort = 8101
sshHost = 0.0.0.0
sshRealm = karaf

• sshPort：SSH 控制台监听端口（默认 8101）。
• sshHost：绑定地址，0.0.0.0 表示所有网卡，生产可改 127.0.0.1 仅本机访问。
• sshRealm：密码认证使用的 JAAS 域，默认 karaf。

⚠️ 修改 sshPort/sshHost 后必须重启实例生效。

5.2 JMX 管理（org.apache.karaf.management.cfg）

rmiRegistryPort = 1099
rmiServerPort = 44444
serviceUrl = service:jmx:rmi://${rmiServerHost}:${rmiServerPort}/jndi/rmi://${rmiRegistryHost}:${rmiRegistryPort}/karaf-${karaf.name}

• rmiRegistryPort：RMI 注册表端口（默认 1099），JConsole 连接入口。
• rmiServerPort：RMI 服务端口（默认 44444）。
• serviceUrl：JMX 服务 URL 模板，按需替换主机与端口。

💡 生产若对外暴露 JMX，务必配置认证与 TLS；默认仅绑本机。

5.3 HTTP/HTTPS（org.ops4j.pax.web.cfg）

org.osgi.service.http.enabled = true
org.osgi.service.http.port = 8181
org.osgi.service.http.secure.enabled = false
#org.osgi.service.http.port.secure = 8443

• org.osgi.service.http.port：HTTP 监听端口（默认 8181），Web 管理台与业务 HTTP 服务都走它。
• org.osgi.service.http.secure.enabled：是否启用 HTTPS，默认 false；启用时另配 port.secure（默认 8443）与 keystore。

5.4 feature（org.apache.karaf.features.cfg）

featuresRepositories = \
    mvn:org.apache.karaf.features/standard/4.4.12/xml/features, \
    mvn:org.apache.karaf.features/spring/4.4.12/xml/features, \
    mvn:org.apache.karaf.features/enterprise/4.4.12/xml/features, \
    mvn:org.apache.karaf.features/specs/4.4.12/xml/features, \
    mvn:org.apache.karaf.features/framework/4.4.12/xml/features

• 定义 Karaf 启动时注册的 feature 仓库，可追加第三方 feature URL。
• 启动已安装 feature 清单在此文件或由 feature:install 写入运行时存储。

5.5 日志（org.ops4j.pax.logging.cfg）

log4j2.rootLogger.level = INFO

• 通过 log4j2 配置，控制台/文件日志路径默认 data/log/*。
• 常见级别：DEBUG（排障）、INFO（默认）、WARN/ERROR（收敛）。

5.6 JVM 与内存（bin/setenv）

JVM 参数不在 etc/，而在 bin/setenv，用 JAVA_OPTS 控制堆：

grep -nE "JAVA_OPTS|JAVA_HOME" /opt/karaf/apache-karaf/bin/setenv

实测回显：

39:export JAVA_OPTS="-Xms256m -Xmx512m -XX:+HeapDumpOnOutOfMemoryError"
40:export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64

• -Xms：初始堆；-Xmx：最大堆。
• 生产建议 -Xms256m -Xmx512m，配合 -XX:+HeapDumpOnOutOfMemoryError。

💡 验证生效：jps -v | grep -i karaf 应看到 -Xms256m -Xmx512m；或控制台 shell:info 查看 Maximum heap size（512MB=524288 KB）。

六、生产配置模板

适用场景：16GB 内存、NVMe SSD 单机，承载数十个轻量业务 bundle 的 OSGi 运行时。

SSH 收拢到内网

# etc/org.apache.karaf.shell.cfg
sshHost = 127.0.0.1
sshPort = 8101

JMX 约定端口

# etc/org.apache.karaf.management.cfg
rmiRegistryPort = 1099
rmiServerPort = 44444

HTTP 固定 8181

# etc/org.ops4j.pax.web.cfg
org.osgi.service.http.port = 8181

堆控制 256–512MB

# bin/setenv
export JAVA_OPTS="-Xms256m -Xmx512m -XX:+HeapDumpOnOutOfMemoryError"

⚠️ 若实例上业务 bundle 较多或涉及大批量数据处理，可把 -Xmx 提到 512–1024MB 区间，但保持初始/最大堆一致避免频繁扩容抖动。

七、常见问题（FAQ）

Q1：改了 org.apache.karaf.shell.cfg 的端口为何不生效？

SSH/JMX/HTTP 端口在进程启动时初始化，必须重启实例（bin/stop && bin/start）后生效。

Q2：如何确认当前生效的内存？

jps -v | grep -i karaf 看 -Xms/-Xmx；或控制台 shell:info 看 Maximum heap size。

Q3：feature 装不上，报依赖缺失？

多数是缺少前置 feature 或仓库未注册，先在 org.apache.karaf.features.cfg 确认 featuresRepositories 是否包含目标特性，再按依赖顺序 feature:install。

Q4：错误地改了配置导致起不来？

用修改前备份 .bak 覆盖恢复，或把对应 .cfg 删掉让 Karaf 重建默认值后重启。

八、参考链接

• Apache Karaf 官方配置文档：https://karaf.apache.org/manual/latest/
• 默认分发配置目录：https://github.com/apache/karaf/tree/main/assembly/src/main/resources/etc