Apache Karaf Docker Compose 部署指南

目标：使用官方 apache/karaf 镜像以 Docker Compose 一键部署 Apache Karaf 4.4.12，覆盖镜像选型、端口与 JVM 堆配置、deploy/ 热部署与账号/日志持久化、等价 docker run、常用运维命令与常见问题。全部命令与回显均在 Docker 29.8.1 + Compose v5.5.1 环境实测采集。

一、环境信息

项目	值
宿主操作系统	Ubuntu 22.04.5 LTS / amd64
Docker	29.8.1（Docker Compose version v5.5.1）
Apache Karaf 镜像	`apache/karaf:4.4.12`（508MB）
镜像内置 JDK	OpenJDK 11.0.32.1（Temurin，`JAVA_HOME=/opt/java/openjdk`）
Karaf 安装路径	`/opt/apache-karaf`（镜像内 `KARAF_HOME`）
暴露端口	8101（SSH 控制台）/ 8181（HTTP）/ 1099、44444（JMX）/ 9999
镜像启动命令	Entrypoint `/__cacert_entrypoint.sh`，Cmd `karaf run`（前台运行）
JVM 堆	`-Xms256m -Xmx512m`（经 `JAVA_OPTS` 环境变量注入）
管理账号	`admin` / 密码 `q1w2e3r4`

二、镜像选型说明

Apache Karaf 官方在 Docker Hub 发布 apache/karaf 镜像，与发行版同源。选型要点：

候选	结论
`apache/karaf:4.4.12`（官方）	推荐。与官方 tar.gz 发行版一致，内置 Temurin JDK 11，前台运行（`karaf run`），自带 8101/8181/1099/44444/9999 端口声明
`apache/karaf:latest`	追踪最新主线，版本随上游漂移，生产不建议
自建 Dockerfile（tar.gz + JDK 17）	需要固定 JDK 17 时自建；维护成本高，非必需

镜像关键元数据（docker inspect 实测）：

docker inspect apache/karaf:4.4.12 --format '{{json .Config.Entrypoint}} | {{json .Config.Cmd}} | {{json .Config.Env}} | {{json .Config.ExposedPorts}}'

实测回显：

["/__cacert_entrypoint.sh"] | ["karaf","run"] | ["PATH=/opt/java/openjdk/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/opt/apache-karaf/bin","JAVA_HOME=/opt/java/openjdk","LANG=en_US.UTF-8","LANGUAGE=en_US:en","LC_ALL=en_US.UTF-8","JAVA_VERSION=jdk-11.0.32.1+1","KARAF_INSTALL_PATH=/opt","KARAF_HOME=/opt/apache-karaf","KARAF_EXEC=exec"] | {"1099/tcp":{},"44444/tcp":{},"8101/tcp":{},"8181/tcp":{},"9999/tcp":{}}

💡 说明：镜像内置 JDK 11.0.32.1（Karaf 4.4.x 支持 JDK 11+），karaf run 前台运行便于容器托管；未声明任何 VOLUME，持久化需自行挂载。镜像默认 etc/users.properties 无启用账号，需挂载自己的账号文件。

三、前置条件

已安装 Docker 24+ 与 Docker Compose v2+（本文实测 29.8.1 / v5.5.1）；
宿主机 8101/8181/1099/44444 端口未被占用（ss -tln | grep -E ':(8101|8181|1099|44444) ' 无输出即空闲）；
能访问 Docker Hub（或已配置镜像加速）拉取 apache/karaf:4.4.12：

docker pull apache/karaf:4.4.12

实测回显：

Digest: sha256:096d8fe5ac57cb5dbc33d2411a04e88d10d4705dbc0b08a685a571e77bc8fe02
Status: Downloaded newer image for apache/karaf:4.4.12
docker.io/apache/karaf:4.4.12

四、部署步骤

4.1 目录与账号准备

创建部署工作区，准备热部署目录、挂载用账号文件：

mkdir -p /opt/karaf-compose/deploy /opt/karaf-compose/etc /opt/karaf-compose/data/log
cd /opt/karaf-compose
printf 'admin = q1w2e3r4,_g_:admingroup\n_g_\\:admingroup = group,admin,manager,viewer,systembundles,ssh\n' > etc/users.properties

💡 说明：admin 属于 admingroup，具备完整控制台权限；该文件将覆盖镜像内默认的 etc/users.properties（默认无启用账号）。

4.2 编写 docker-compose.yml

在 /opt/karaf-compose/docker-compose.yml 写入：

services:
  karaf:
    image: apache/karaf:4.4.12
    container_name: karaf-server
    restart: unless-stopped
    ports:
      - "8101:8101"
      - "8181:8181"
      - "1099:1099"
      - "44444:44444"
    environment:
      - JAVA_OPTS=-Xms256m -Xmx512m
    volumes:
      - ./deploy:/opt/apache-karaf/deploy
      - ./etc/users.properties:/opt/apache-karaf/etc/users.properties
      - ./data/log:/opt/apache-karaf/data/log

💡 说明：JAVA_OPTS 环境变量会被镜像内 bin/karaf 启动脚本采用，将堆限制在 256–512MB；restart: unless-stopped 保证宿主机重启后自愈。

4.3 启动并验证

cd /opt/karaf-compose
docker compose up -d

实测回显：

 Container karaf-server Created
 Container karaf-server Starting
 Container karaf-server Started

等待约 30 秒后确认状态与端口映射：

docker compose ps

实测回显：

NAME           IMAGE                 COMMAND                  SERVICE   CREATED          STATUS          PORTS
karaf-server   apache/karaf:4.4.12   "/__cacert_entrypoin…"   karaf     30 seconds ago   Up 30 seconds   0.0.0.0:1099->1099/tcp, [::]:1099->1099/tcp, 0.0.0.0:8101->8101/tcp, [::]:8101->8101/tcp, 0.0.0.0:8181->8181/tcp, [::]:8181->8181/tcp, 0.0.0.0:44444->44444/tcp, [::]:44444->44444/tcp, 9999/tcp

进入实例确认运行状态、JDK 版本与堆参数：

docker exec karaf-server bash -c '/opt/apache-karaf/bin/status 2>&1 | tail -1; /opt/java/openjdk/bin/java -version 2>&1; ps -ef | grep [j]ava | grep -oE "\-Xms256m -Xmx512m" | head -1'

实测回显：

Running ...
openjdk version "11.0.32.1" 2026-08-18
OpenJDK Runtime Environment Temurin-11.0.32.1+1 (build 11.0.32.1+1)
OpenJDK 64-Bit Server VM Temurin-11.0.32.1+1 (build 11.0.32.1+1, mixed mode, sharing)
-Xms256m -Xmx512m

⚠️ 注意：镜像内置 JDK 为 11，bin/client 连接时可能输出 WARNING: An illegal reflective access operation has occurred 等 JDK 11 反射告警，属已知现象，不影响功能；如需 JDK 17 请自建镜像。

4.4 控制台验证与安装功能

用挂载的账号登录控制台并安装 http + webconsole feature：

docker exec karaf-server bash -c 'printf "feature:install http\nfeature:install webconsole\n" | /opt/apache-karaf/bin/client -u admin -p q1w2e3r4'

安装成功无输出。从宿主机验证 Web 管理台（未登录返回 401 属正常）：

curl -s -o /dev/null -w "HTTP %{http_code}\n" http://127.0.0.1:8181/system/console

实测回显：

HTTP 401

五、数据持久化说明

Karaf 的可持久化数据分三类，本文 compose 已覆盖全部三类：

挂载	容器内路径	内容	重建容器后
`./deploy`	`/opt/apache-karaf/deploy`	热部署 jar（FileInstall 监听）	保留，启动时自动重新安装
`./etc/users.properties`	`/opt/apache-karaf/etc/users.properties`	控制台账号	保留
`./data/log`	`/opt/apache-karaf/data/log`	运行日志 `karaf.log`、`security.log`	保留

热部署实测：将 bundle jar 放入宿主机 deploy/ 目录，FileInstall 自动安装：

wget -P /opt/karaf-compose/deploy/ https://repo1.maven.org/maven2/org/apache/felix/org.apache.felix.eventadmin/1.6.4/org.apache.felix.eventadmin-1.6.4.jar
sleep 8
docker exec karaf-server bash -c 'printf "bundle:list -t 0 | grep -i eventadmin\n" | /opt/apache-karaf/bin/client -u admin -p q1w2e3r4'

实测回显（FileInstall 自动安装后 bundle 出现在清单中）：

82 │ Resolved │  80 │ 1.6.4              │ Apache Felix EventAdmin

跨容器重建验证：docker compose down 后 up，启动日志中 FileInstall 再次自动安装挂载目录里的 jar：

2026-10-11T13:24:36,928 | INFO  | fileinstall-/opt/apache-karaf-4.4.12/deploy | fileinstall                      | 7 - org.apache.felix.fileinstall - 3.7.4 | Installing bundle org.apache.felix.eventadmin / 1.6.4

日志持久化实测：宿主机侧确认日志已落盘：

ls -la /opt/karaf-compose/data/log/

实测回显：

total 148
drwxr-xr-x 2 root root   4096 10月 11 21:15 .
drwxr-xr-x 3 root root   4096 10月 11 21:12 ..
-rw-r--r-- 1 root root 137388 10月 11 21:19 karaf.log
-rw-r--r-- 1 root root      0 10月 11 21:15 security.log

六、常用环境变量表

环境变量	默认值	说明
`JAVA_OPTS`	镜像未设置（脚本回退默认）	传给 Karaf JVM 的参数，堆限制在此注入（如 `-Xms256m -Xmx512m`）
`EXTRA_JAVA_OPTS`	未设置	追加 JVM 参数，优先级低于 `JAVA_OPTS` 显式赋值
`JAVA_HOME`	`/opt/java/openjdk`（镜像内置）	如换用自带 JDK 的挂载目录可覆盖
`KARAF_HOME`	`/opt/apache-karaf`	Karaf 安装根目录，一般不改
`KARAF_EXEC`	`exec`	使 `karaf` 命令以 exec 方式前台运行，适配容器托管，不建议改

⚠️ 注意：docker compose restart（不重建容器）会保留容器内 data/cache，运行期通过 feature:install 装的特性重启后仍在（实测 webconsole 重启后为 Started，Web 管理台返回 401）；但 docker compose down 后 up 会重建容器、清空未挂载的 data/ 目录，运行期安装的特性将丢失。需要跨重建保留的 feature 请写进启动特性清单（见第八节）。

七、常用配置参数说明（command）

镜像 Cmd 为 karaf run，如需给 Karaf 传额外启动参数（如 --clean 清缓存启动），用 command: 覆盖：

services:
  karaf:
    image: apache/karaf:4.4.12
    command: karaf run --clean

💡 说明：--clean 会清空 data/cache 后启动（相当于全新实例）；日常排障可用，长期运行不建议。默认保持 karaf run 即可。

八、配置文件持久化（conf 挂载）

除账号文件外，etc/ 下任意配置均可按同样方式挂载覆盖。最常用的是把「启动即安装的 feature 清单」持久化：编辑宿主机 etc/org.apache.karaf.features.cfg（可先从镜像内拷出再改），在 featuresBoot 列表末尾追加目标特性：

    kar/4.4.12, \
    http, \
    webconsole

并在 compose 中追加挂载：

    volumes:
      - ./etc/org.apache.karaf.features.cfg:/opt/apache-karaf/etc/org.apache.karaf.features.cfg

实测启动日志（重建容器后，Karaf 按 featuresBoot 清单逐个安装）：

2026-10-11T13:53:14,088 | INFO  | features-3-thread-1 | FeaturesServiceImpl              | 19 - org.apache.karaf.features.core - 4.4.12 | Installing bundles:
2026-10-11T13:53:14,088 | INFO  | features-3-thread-1 | FeaturesServiceImpl              | 19 - org.apache.karaf.features.core - 4.4.12 |   mvn:org.bouncycastle/bcpkix-jdk18on/1.86

💡 说明：默认 featuresBoot 已含 instance/package/log/ssh/framework/system/eventadmin/feature/shell/management/service/jaas/deployer/diagnostic/wrap/bundle/config/kar 18 项，追加时保留原列表、仅在其后添加（如 http、webconsole），注意行尾续行符 \。

九、等价 docker run 运行方式

与上述 compose 完全等价的一条 docker run 命令：

docker run -d \
  --name karaf-server \
  --restart unless-stopped \
  -p 8101:8101 -p 8181:8181 -p 1099:1099 -p 44444:44444 \
  -e JAVA_OPTS="-Xms256m -Xmx512m" \
  -v /opt/karaf-compose/deploy:/opt/apache-karaf/deploy \
  -v /opt/karaf-compose/etc/users.properties:/opt/apache-karaf/etc/users.properties \
  -v /opt/karaf-compose/data/log:/opt/apache-karaf/data/log \
  apache/karaf:4.4.12

实测验证（启动后约 45 秒）：

docker exec karaf-run-test bash -c '/opt/apache-karaf/bin/status 2>&1 | tail -1; ps -ef | grep [j]ava | grep -oE "\-Xms256m -Xmx512m" | head -1'

实测回显：

Running ...
-Xms256m -Xmx512m

十、常用运维命令

在 compose 项目目录（/opt/karaf-compose）下执行：

命令	用途	说明
`docker compose ps`	查看服务状态	STATUS/端口映射一眼可见
`docker compose logs -f --tail 100`	跟踪启动日志	Ctrl+C 退出
`docker compose logs --tail 8`	查看最近日志	截取最近 N 行
`docker compose restart`	重启实例	保留容器层 `data/cache`，运行期安装的 feature 不丢
`docker compose down`	停止并删除实例	未挂载的 `data/` 数据随之丢弃
`docker compose up -d`	重建并启动	配合 `down` 使用
`docker exec -it karaf-server /opt/apache-karaf/bin/client -u admin -p q1w2e3r4`	进入交互控制台	Ctrl+D 退出

logs 实测（启动完成后最近 8 行）：

docker compose logs --tail 8

实测回显：

karaf-server  | 14:05:59.353 INFO  [FelixFrameworkWiring] Disabling SLF4J API support.
karaf-server  | 14:05:59.354 INFO  [FelixFrameworkWiring] Disabling Apache Commons Logging API support.
karaf-server  | 14:05:59.355 INFO  [FelixFrameworkWiring] Disabling JULI Logger API support.
karaf-server  | 14:05:59.355 INFO  [FelixFrameworkWiring] Disabling Avalon Logger API support.
karaf-server  | 14:05:59.356 INFO  [FelixFrameworkWiring] Disabling JBoss Logging API support.
karaf-server  | 14:05:59.356 INFO  [FelixFrameworkWiring] Disabling Log4J v1 API support.
karaf-server  | 14:05:59.362 INFO  [FelixFrameworkWiring] Disabling Log4J v2 API support.
karaf-server  | 14:05:59.369 INFO  [FelixFrameworkWiring] Disabling Java Util Logging API support.

restart 实测：

docker compose restart

实测回显：

 Container karaf-server Restarting
 Container karaf-server Started

down / up 实测：

docker compose down && docker compose up -d

实测回显：

 Container karaf-server Stopping
 Container karaf-server Stopped
 Container karaf-server Removing
 Container karaf-server Removed
 Network karaf-compose_default Removing
 Network karaf-compose_default Removed
 Network karaf-compose_default Creating
 Network karaf-compose_default Created
 Container karaf-server Creating
 Container karaf-server Created
 Container karaf-server Starting
 Container karaf-server Started

💡 说明：JVM 堆占用可用 docker stats karaf-server --no-stream 观察；容器日志持续输出 GC 统计属正常现象（镜像默认 JVM 参数）。

十一、常见问题（FAQ）

Q1：up -d 后访问 http://IP:8181/system/console 打不开？

默认镜像只启动核心，未安装 http feature，8181 不会监听。按 4.4 节执行 feature:install http、feature:install webconsole，或将两者写进 featuresBoot（第八节）。

Q2：docker compose down 再 up 后，之前装的 feature 全没了？

正常现象。feature 运行态记录在未挂载的 data/cache，down 删除容器即清空。两种解法：一是把所需 feature 写进挂载的 etc/org.apache.karaf.features.cfg 的 featuresBoot 清单（第八节）；二是只挂载 deploy/，把业务 bundle 做成热部署（第五节，重建后 FileInstall 自动重装）。

Q3：控制台输出 WARNING: An illegal reflective access operation has occurred？

镜像内置 JDK 11 而部分旧库使用反射 API 触发的告警，不影响功能。确需 JDK 17 时自建镜像：以官方发行版 tar.gz（JDK 17 已验证兼容 4.4.12，参见《Ubuntu 22.04 安装 Apache Karaf 4.4.12 指南》）为基底，FROM 任意 JDK 17 基础镜像，解压至 /opt/apache-karaf 并保持 karaf run 作为启动命令。

Q4：JAVA_OPTS 设置了但堆内存没变？

确认三点：① 写在 compose 的 environment 段（缩进对齐）；② 重启容器使其生效（docker compose up -d --force-recreate）；③ 实际生效验证用 docker exec karaf-server bash -c 'ps -ef | grep [j]ava | grep -oE "\-Xms256m -Xmx512m"'，或进控制台看 shell:info 的 Memory 段。

Q5：控制台默认账号是什么？

镜像默认 etc/users.properties 未启用任何账号。必须按 4.1 节挂载自己的账号文件（如 admin / q1w2e3r4），否则 bin/client 无法登录。

Q6：启动很慢，日志停在 Installing bundle？

首次启动或重建容器后，featuresBoot 清单中未内置的 Maven 构件（如 pax-web 相关 jar）需从 Maven 中央仓库下载，网络不佳时耗时数分钟属正常；等待即可，或为实例预置 Maven 缓存目录（挂载到容器 /root/.m2/repository）跳过下载。

十二、参考链接

Apache Karaf 官方镜像（Docker Hub）：https://hub.docker.com/r/apache/karaf
Apache Karaf 官方手册（Docker/运行时）：https://karaf.apache.org/manual/latest/
相关文档：《Ubuntu 22.04 安装 Apache Karaf 4.4.12 指南》《Apache Karaf 配置参数详解》《Apache Karaf 常用 CLI 命令与工具详解》