Ubuntu 22.04 安装 Apache Karaf 4.4.12 指南
从零开始在 Ubuntu 22.04 真实服务器上部署 Apache Karaf 4.4.12（服务端 OSGi 发行运行时）,覆盖前置 JDK、官方下载校验、解压、JVM 堆限制配置、启动验证、feature/bundle 管理、卸载与常见排障。
Ubuntu 22.04 安装 Apache Karaf 4.4.12 指南
目标：在 Ubuntu 22.04 真实服务器上从零完成 Apache Karaf 4.4.12（服务端 OSGi 发行/运行时、模块化应用运行时）的安装、JVM 堆限制配置与功能验证。本文所有命令与回显均在 Ubuntu 22.04.5 LTS + OpenJDK 17 环境实测通过，安装目录为
/opt/karaf/apache-karaf，SSH 控制台端口 8101、HTTP 端口 8181。
一、环境信息
| 项目 | 值 |
|---|---|
| 操作系统 | Ubuntu 22.04.5 LTS（kernel 6.8.0-138-generic） |
| 架构 | x86_64 / amd64 |
| JDK | OpenJDK 17.0.20.1（java-17-openjdk-amd64，安装于 /usr/lib/jvm/java-17-openjdk-amd64） |
| Apache Karaf | 4.4.12（最新稳定版，2026-09 发布） |
| OSGi 框架 | Apache Felix Framework 7.0.5 |
| SSH 控制台 | TCP 8101（0.0.0.0） |
| HTTP（Jetty/Pax Web） | TCP 8181（0.0.0.0） |
| JMX（RMI Registry / RMI Server） | TCP 1099 / 44444（仅本机） |
| 安装目录 | /opt/karaf/apache-karaf |
| 管理账号 | admin / 密码 q1w2e3r4 |
💡 说明：Apache Karaf 是一个 OSGi 应用运行时，提供 shell 命令行、feature（功能特性）管理、bundle（模块）热部署等能力，常用于将多个 jar 打包为一个个 bundle 统一编排运行。
二、前置条件
- root 或具备 sudo 权限的账号：本文全程以
root执行，普通用户请在各命令前加sudo。 - JDK 11 或 17：Karaf 4.4.x 要求 Java 11 及以上，推荐安装 JDK 17。需配置
JAVA_HOME。 - 网络：需要能访问
downloads.apache.org（下载发行包）与 Maven 中央仓库repo1.maven.org（安装 feature 时拉取依赖）。 - 依赖工具：
wget（或curl）、tar、gzip。
三、版本选型说明
Apache 官方下载站点 https://downloads.apache.org/karaf/ 目前维护三条主线（实测 2026-10 目录）：
| 主线 | 当前版本 | 说明 |
|---|---|---|
| 4.4.x | 4.4.12 | 最新稳定主线，推荐生产选型，JDK 11+ 即可 |
| 4.3.x | 4.3.10 | 维护分支（End of Life 过渡） |
| 4.2.x | 4.2.16 | 旧维护分支 |
| 3.0.x | 3.0.10 | 历史兼容分支，仅 gogo 时代产物，不建议新项目使用 |
选型建议：
- 新项目统一选用 4.4.x 最新补丁版（当前 4.4.12），官方只对最新补丁进行安全修复；
- 若业务锁死旧版 API，再考虑 4.3.x；生产环境不要使用 4.2.x 及以下。
刷新版本列表的命令（获取真实可用版本）：
curl -sL https://downloads.apache.org/karaf/ | grep -oE '>[0-9]+\.[0-9]+\.[0-9]+/' | tr -d '>/'
四、部署步骤
4.1 安装 JDK 17 并配置 JAVA_HOME
export DEBIAN_FRONTEND=noninteractive
apt-get update
apt-get install -y openjdk-17-jdk wget curl tar
安装完成后确认版本与路径：
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)
确认 JDK 绝对路径（Ubuntu 上为以下任一）：
ls -d /usr/lib/jvm/java-17-openjdk-amd64
将 JAVA_HOME 与 PATH 写入全局环境（写入后重启终端或 source /etc/profile 生效）：
echo "export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64" >> /etc/profile
echo "export PATH=\$JAVA_HOME/bin:\$PATH" >> /etc/profile
source /etc/profile
校验：
echo $JAVA_HOME
实测回显：
/usr/lib/jvm/java-17-openjdk-amd64
4.2 从 Apache 官方下载发行包并校验
创建安装上级目录并下载 apache-karaf-4.4.12.tar.gz（约 35MB）：
mkdir -p /opt/downloads
cd /opt/downloads
wget https://downloads.apache.org/karaf/4.4.12/apache-karaf-4.4.12.tar.gz
实测回显（文件已下载到本地）：
apache-karaf-4.4.12.tar.gz 100%[===========================>]
ls -lh apache-karaf-4.4.12.tar.gz
实测回显：
-rw-r--r-- 1 root root 35M Sep 22 12:17 apache-karaf-4.4.12.tar.gz
下载官方 SHA-512 校验文件并校验完整性：
curl -sL https://downloads.apache.org/karaf/4.4.12/apache-karaf-4.4.12.tar.gz.sha512 \
> apache-karaf-4.4.12.tar.gz.sha512
sha512sum -c apache-karaf-4.4.12.tar.gz.sha512
实测回显（表示校验通过）：
apache-karaf-4.4.12.tar.gz: OK
💡 说明：本文实测 sha512 为
e50442276a2c475c31bf7121936a65abcee7ac79f233e5ec118a7589dd6dd780c9c4afc546e67906c77c1dff771b745144553ffa6080848b6806f0932314a26b，校验输出OK即表示与服务端一致。生产环境建议同时用签名与 KEYS 校验，这里以官方 sha512 即可满足完整性要求。
4.3 解压并重命名安装目录
mkdir -p /opt/karaf
tar -xzf /opt/downloads/apache-karaf-4.4.12.tar.gz -C /opt/karaf
mv /opt/karaf/apache-karaf-4.4.12 /opt/karaf/apache-karaf
查看顶层目录结构：
ls -la /opt/karaf/apache-karaf
实测回显：
total 64
drwxr-xr-x 9 root root 4096 Oct 11 11:41 .
drwxr-xr-x 3 root root 4096 Oct 11 11:41 ..
-rw-r--r-- 1 root root 19832 Sep 22 11:38 LICENSE
-rw-r--r-- 1 root root 2800 Sep 22 11:38 NOTICE
-rw-r--r-- 1 root root 3592 Sep 22 11:38 README.md
drwxr-xr-x 3 root root 4096 Sep 22 11:38 bin
drwxr-xr-x 3 root root 4096 Sep 22 11:38 data
drwxr-xr-x 2 root root 4096 Sep 22 11:38 deploy
drwxr-xr-x 3 root root 4096 Sep 22 11:38 etc
drwxr-xr-x 32 root root 4096 Sep 22 11:38 examples
drwxr-xr-x 6 root root 4096 Sep 22 11:38 lib
drwxr-xr-x 3 root root 4096 Sep 22 11:38 system
关键目录说明：
| 目录 | 作用 |
|---|---|
bin/ | 启动/停止/控制台客户端脚本 |
etc/ | 全部配置文件（含用户、端口、JVM、feature 源等） |
deploy/ | 热部署目录，放入 jar 会自动安装为 bundle |
data/ | 运行时数据、日志（data/log/karaf.log） |
system/ | 本地 OSGi 仓库（内置 jar 缓存） |
4.4 配置 JVM 堆限制（256–512MB）与 JAVA_HOME
Karaf 4.4.x 不再使用 etc/karafrc，JVM 参数配置在启动脚本引用到的 bin/setenv（也可以直接改 bin/karaf）。修改 bin/setenv，将 # export JAVA_OPTS（Generic JVM options 注释行）替换为以下实际配置（同时写入 JAVA_HOME）：
sed -i \
"s|# export JAVA_OPTS # Generic JVM options, for instance, where you can pass the memory configuration|export JAVA_OPTS=\"-Xms256m -Xmx512m -XX:+HeapDumpOnOutOfMemoryError\"\nexport JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64|" \
/opt/karaf/apache-karaf/bin/setenv
💡 说明：
-Xms256m为初始堆、-Xmx512m为最大堆，将堆限制在 256–512MB 区间，避免 Karaf 默认按物理内存自动扩容抢占资源；-XX:+HeapDumpOnOutOfMemoryError在 OOM 时输出 heap dump 便于排障。
确认修改已写入：
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
4.5 创建管理账号（SSH 控制台登录）
默认 etc/users.properties 中没有可用账号，需要追加一个 admin 用户用于 SSH 控制台（8101）登录。执行：
KAFAR_HOME=/opt/karaf/apache-karaf
printf 'admin = q1w2e3r4,_g_:admingroup\n_g_\\:admingroup = group,admin,manager,viewer,systembundles,ssh\n' \
>> "$KAFAR_HOME/etc/users.properties"
确认追加成功：
tail -3 /opt/karaf/apache-karaf/etc/users.properties
实测回显：
#_g_\:admingroup = group,admin,manager,viewer,systembundles,ssh
admin = q1w2e3r4,_g_:admingroup
_g_\:admingroup = group,admin,manager,viewer,systembundles,ssh
💡 说明：
admin属于admingroup，该组被授予group,admin,manager,viewer,systembundles,ssh角色，即具备完整控制台权限。
4.6 启动并进入控制台
方式 A：前台交互式启动
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export PATH=$JAVA_HOME/bin:$PATH
cd /opt/karaf/apache-karaf
bin/karaf
实测回显（进入交互式 shell，提示符为 karaf@root()>）：
__ __ ____
/ //_/____ __________ _/ __/
/ ,< / __ `/ ___/ __ `/ /_
/ /| |/ /_/ / / / /_/ / __/
/_/ |_|\__,_/_/ \__,_/_/
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()>
方式 B：后台守护进程方式（推荐生产）
cd /opt/karaf/apache-karaf
bin/start
sleep 20
bin/status
实测回显：
Running ...
用 jps -v 验证 JVM 参数与进程已带上堆限制：
jps -v | grep -i karaf
实测回显（进程参数行，-Xms256m -Xmx512m 在列）：
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.7 验证运行状态
登录控制台方式：使用 bin/client 连接 SSH 控制台端口 8101，把命令通过标准输入传入：
cd /opt/karaf/apache-karaf
printf 'feature:list | grep Started\n' | bin/client -u admin -p q1w2e3r4
实测回显（控制台横幅 + 登录后的 admin@root() 提示符，已启动 feature 共 18 行全量）：
__ __ ____
/ //_/____ __________ _/ __/
/ ,< / __ `/ ___/ __ `/ /_
/ /| |/ /_/ / / / /_/ / __/
/_/ |_|\__,_/_/ \__,_/_/
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:list | grep Started
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
查看已安装 bundle（注意默认阈值）：
printf 'bundle:list -t 0\n' | bin/client -u admin -p q1w2e3r4
💡 说明：
bundle:list默认阈值（threshold）为 50，只会打印 start-level ≥ 50 的 bundle（仅有系统 Event 服务等少数），要看全量请加-t 0。实测共 53 个 bundle（全量），列出 System Bundle（Felix 7.0.5）以及 Karaf 各核心模块。
验证端口监听（8101 SSH 控制台、8181 HTTP、1099/44444 JMX）：
while read -r _ loc _ st _; do
[ "$st" = "0A" ] || continue
port=$((16#${loc#*:}))
case $port in 8101|8181|1099|44444) printf 'tcp6 port %d listen %s\n' "$port" "${loc%:*}";; esac
done < /proc/net/tcp6
实测回显（Karaf 四个端口全量）：
tcp6 port 44444 listen 0000000000000000FFFF00000100007F
tcp6 port 8101 listen 00000000000000000000000000000000
tcp6 port 8181 listen 00000000000000000000000000000000
tcp6 port 1099 listen 0000000000000000FFFF00000100007F
4.8 安装功能特性（feature）与 bundle 实测
安装 http feature（拉起 Jetty/Pax Web，监听 8181）：
printf 'feature:install http\n' | bin/client -u admin -p q1w2e3r4
查看日志确认 Jetty 启动在 8181：
tail -5 /opt/karaf/apache-karaf/data/log/karaf.log
实测回显（关键行）：
Started default@63f245f2{HTTP/1.1, (http/1.1)}{0.0.0.0:8181}
Registering HttpService factory
Binding HTTP Service for bundle: [org.apache.karaf.http.core [54]]
安装 webconsole（Web 管理台，需先装 http）：
printf 'feature:install webconsole\n' | bin/client -u admin -p q1w2e3r4
验证 Web 管理台可访问（未登录返回 401 属正常，说明 HTTP 服务已就绪）：
curl -s -o /dev/null -w "HTTP %{http_code}\n" http://127.0.0.1:8181/system/console
实测回显：
HTTP 401
💡 说明：
http://<服务器IP>:8181/system/console是 Karaf Web 管理台地址，用admin/q1w2e3r4登录。
安装一个 bundle（bundle:install）+ 启停 + 卸载实测：
cd /opt/karaf/apache-karaf
cat > /tmp/cmds.txt <<EOF
bundle:install mvn:org.apache.felix/org.apache.felix.eventadmin/1.6.4
bundle:list -t 0 82
bundle:start 82
bundle:stop 82
bundle:uninstall 82
bundle:list -t 0 82
EOF
bin/client -u admin -p q1w2e3r4 < /tmp/cmds.txt
实测回显（截取关键输出）：
admin@root()> bundle:install mvn:org.apache.felix/org.apache.felix.eventadmin/1.6.4
Bundle ID: 82
admin@root()> bundle:list -t 0 82
82 | Active | 80 | 1.6.4 | Apache Felix EventAdmin
admin@root()> bundle:uninstall 82
admin@root()> bundle:list -t 0 82
💡 说明：安装后刚
bundle:start时状态为 Active；bundle:uninstall后再查询该 ID 无输出，表示已彻底移除。
五、配置说明（含 JVM 堆限制）
5.1 关键配置文件位置
所有配置都在 /opt/karaf/apache-karaf/etc/ 下，改动后注意部分需在客户端执行 config:update 或重启实例生效：
| 文件 | 用途 |
|---|---|
users.properties | 登录账号/组/角色（JAAS） |
org.apache.karaf.shell.cfg | SSH 控制台端口（默认 8101） |
org.apache.karaf.management.cfg | JMX 端口（1099/44444） |
org.ops4j.pax.web.cfg | HTTP/HTTPS 端口（默认 8181） |
org.apache.karaf.features.cfg | feature 仓库与启动特性 |
org.ops4j.pax.logging.cfg | 日志配置 |
bin/setenv | JVM 参数（JAVA_OPTS、JAVA_HOME），堆限制在此配置 |
5.2 JVM 堆限制核对方式
修改 bin/setenv 后，用 jps -v 确认生效（见 4.6 回显，含 -Xms256m -Xmx512m）；也可在控制台用 shell:info 查看运行时堆：
printf 'shell:info\n' | bin/client -u admin -p q1w2e3r4
实测回显（关键段，Maximum heap size 为 512MB=524288KB，Committed 为 256MB）：
Memory
Current heap size 154,367 kbytes
Maximum heap size 524,288 kbytes
Committed heap size 262,144 kbytes
六、注意事项
- 首次以 root 直接运行
bin/karaf前台启动是可以的；若在生产以 root 运行并设置了安全策略，可使用KARAF_NOROOT相关开关，本文不启用。 bundle:list默认阈值 50 只显示高 start-level 的 bundle，看全量务必-t 0，避免误判「bundle 缺失」。webconsole依赖 OSGi HTTP Service（即http/pax-webfeature），需先装http再装webconsole，否则直接装会报osgi.http依赖缺失。- 修改
etc/下用户与端口配置后需要重启实例生效；feature/bundle 级别热操作立即生效。 - 堆上限 512MB 适合轻量运行；若挂载大量业务 bundle 可适度上调，但生产仍建议控制在 512MB 左右并配合
-XX:+HeapDumpOnOutOfMemoryError。
七、常见问题（FAQ）
Q1：bin/client 提示 Closed 或连接即断开？
SSH 服务器 8101 未就绪时会出现。确认 sshHost/sshPort、是否已 bin/start 且等待约 10–20s，再重试；改用标准输入喂命令（printf 'feature:list\n' | bin/client -u admin -p q1w2e3r4）更稳定。
Q2：bundle:list 只看到一两个 bundle？
因为默认阈值 50 过滤掉了多数底层 bundle，惯例加 -t 0 查看全量。
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：如何改 SSH 控制台端口？
编辑 etc/org.apache.karaf.shell.cfg 的 sshPort，重启生效。
八、卸载与清理
停止实例：
cd /opt/karaf/apache-karaf
bin/stop
bin/status
实测回显：
Not Running ...
删除安装目录与下载缓存：
rm -rf /opt/karaf/apache-karaf
rm -rf /opt/downloads/apache-karaf-4.4.12.tar.gz
若同时清除环境变量引用，删除 /etc/profile 中新增的两行 JAVA_HOME/PATH 导出即可。
九、参考链接
- Apache Karaf 官方下载：https://downloads.apache.org/karaf/
- Apache Karaf 官网：https://karaf.apache.org
- 发行包签名/校验：https://downloads.apache.org/karaf/4.4.12/
- Maven 中央仓库：https://repo1.maven.org/maven2/