Apache Qpid Docker Compose 部署指南

目标：使用 Apache 官方镜像 apache/qpid-broker-j（10.1.1）通过 Docker Compose 一键部署 Qpid Broker-J 消息代理，覆盖镜像选型、环境变量注入管理员账号、数据卷持久化、JVM 堆限制、等价 docker run 与运维排障。以下步骤与回显在 Docker 25+ / Compose v5.5.1 环境实测。

一、环境信息

• 操作系统：Linux x86_64（内核 6.8）
• Docker：25+（实测 docker compose version 为 Docker Compose version v5.5.1）
• Apache Qpid Broker-J：10.1.1（官方镜像 apache/qpid-broker-j:10.1.1，与 latest 同一构建 build 49098be941a6e6c5c5fc17759c30e0e1e0331c80）
• 镜像内 JDK：OpenJDK 25.0.4+7（JAVA_VERSION 环境变量标注）
• 容器内运行用户：uid 1001（qpid）+ gid 0（root 组）
• 端口：5672（AMQP）、8080（HTTP 管理台/REST API）
• 部署目录：/opt/qpid-compose（含 docker-compose.yml 与 data/work 数据卷）

二、镜像选型说明

官方镜像关键信息（docker inspect 实测）：

entrypoint=[/bin/sh -c exec /qpid-broker-j/entrypoint.sh]
workdir=/qpid-broker-j
exposed=5672/tcp, 8080/tcp
user=1001:root
env: JAVA_VERSION=jdk-25.0.4+7 | JAVA_GC=-XX:+UseG1GC | JAVA_MEM=-Xmx300m -XX:MaxDirectMemorySize=200m | JAVA_OPTS= | QPID_ADMIN_USER=admin | QPID_ADMIN_PASSWORD=admin

💡 说明：镜像内置工作目录 /qpid-broker-j/work，首次启动时 entrypoint 把 /qpid-broker-j/work-init 下的初始配置复制为运行配置，并以 sed 把 broker.acl 中的账号占位串替换为 QPID_ADMIN_USER 的值；镜像版 config.json 模板已默认开启 HTTP Basic 认证，curl -u 开箱可用。

三、前置条件

• 宿主机已安装 Docker 与 Docker Compose 插件，且当前用户在 docker 组或具备 root 权限。
• 宿主机可访问 Docker Hub（拉取 apache/qpid-broker-j:10.1.1，约 400MB 压缩体积）。
• 宿主机 5672/8080 端口空闲（被占用时按第七章 FAQ 调整映射）。
• 部署目录可写：mkdir -p /opt/qpid-compose/data/work，并保证 uid 1001 可写（实测 chmod 777 或 chown 1001:0 均可）。

四、部署步骤

4.1 创建部署目录与 compose 文件

mkdir -p /opt/qpid-compose/data/work && cd /opt/qpid-compose
vi docker-compose.yml

写入以下内容（与实测文件一致；宿主机 8080 被其他服务占用时，把管理台映射改为 "15680:8080"，本篇验证回显即来自该映射）：

services:
  qpid-broker:
    image: apache/qpid-broker-j:10.1.1
    container_name: qpid-broker
    ports:
      - "5672:5672"
      - "8080:8080"
    environment:
      QPID_ADMIN_USER: admin
      QPID_ADMIN_PASSWORD: q1w2e3r4
      JAVA_MEM: "-Xms256m -Xmx512m -XX:MaxDirectMemorySize=256m"
    volumes:
      - ./data/work:/qpid-broker-j/work
    restart: unless-stopped

4.2 拉取镜像并启动

docker compose up -d

实测回显（镜像已预先 pull 时）：

 Network qpid-compose_default Creating
 Network qpid-compose_default Created
 Container qpid-broker Creating
 Container qpid-broker Created
 Container qpid-broker Starting
 Container qpid-broker Started

镜像未拉取过时，先执行 docker compose pull：

docker pull apache/qpid-broker-j:10.1.1

实测回显末行：

Status: Downloaded newer image for apache/qpid-broker-j:10.1.1
docker.io/apache/qpid-broker-j:10.1.1

4.3 查看状态与启动日志

docker compose ps
docker logs qpid-broker 2>&1 | grep -E "BRK-1001|BRK-1002|MNG-1002|MNG-1004|BRK-1004"

实测回显：

NAME          STATUS        PORTS
qpid-broker   Up 24 seconds 0.0.0.0:5672->5672/tcp, [::]:5672->5672/tcp, 0.0.0.0:15680->8080/tcp, [::]:15680->8080/tcp
[Broker] BRK-1001 : Startup : Version: 10.1.1 Build: 49098be941a6e6c5c5fc17759c30e0e1e0331c80
[Broker] BRK-1002 : Starting : Listening on TCP port 5672
[Broker] MNG-1002 : Starting : HTTP : Listening on TCP port 8080
[Broker] MNG-1004 : Web Management Ready
[Broker] BRK-1004 : Qpid Broker Ready

4.4 验证 REST API（管理员口令已注入）

镜像默认 QPID_ADMIN_PASSWORD=admin，compose 中已改为 q1w2e3r4，实测旧口令立即失效：

curl -s -o /dev/null -w "admin:q1w2e3r4 -> %{http_code}\n" -u admin:q1w2e3r4 http://localhost:8080/api/latest/broker
curl -s -o /dev/null -w "admin:admin -> %{http_code}\n" -u admin:admin http://localhost:8080/api/latest/broker

实测回显：

admin:q1w2e3r4 -> 200
admin:admin -> 401

4.5 验证 AMQP 端口

python3 -c "
import socket
s = socket.create_connection(('127.0.0.1', 5672), 5)
s.sendall(b'AMQP\x00\x01\x00\x00')
print(s.recv(16))
s.close()"

实测回显（AMQP 1.0 协议头应答）：

b'AMQP\x03\x01\x00\x00'

4.6 验证 JVM 堆生效

docker exec qpid-broker sh -c 'tr "\0" "\n" < /proc/1/cmdline | grep -E "Xms|Xmx|Direct"'

实测回显（镜像默认 -Xmx300m 已被 JAVA_MEM 覆盖）：

-Xms256m
-Xmx512m
-XX:MaxDirectMemorySize=256m

浏览器访问 http://宿主机IP:8080/ 打开 Web 管理台，用 admin/q1w2e3r4 登录。

五、数据持久化说明

• 数据卷 ./data/work:/qpid-broker-j/work 承载了 Broker 全部状态：config.json（配置存储）、default.json（默认虚拟主机 BDB 配置）、messages/（BDB 消息存储）、broker.acl（访问控制）、preferences.json、日志与锁文件。
• 首次启动 entrypoint 检测到 work/config.json 不存在，会从镜像内 work-init/ 复制初始配置并替换账号占位；已有 config.json 时跳过初始化，仅使用数据卷中已有配置（日志输出 skipping broker instance creation; instance already exists）。
• 实测持久化：创建 durable 队列后 down 再 up，队列仍在。

curl -s -o /dev/null -w "create -> %{http_code}\n" -u admin:q1w2e3r4 -X PUT -d '{"durable":true}' http://localhost:8080/api/latest/queue/default/default/persistent-queue
docker compose down
docker compose up -d
sleep 24
curl -s -u admin:q1w2e3r4 http://localhost:8080/api/latest/queue/default/default | python3 -c "import json,sys; print([q['name'] for q in json.load(sys.stdin)])"

实测回显：

create -> 201
['persistent-queue']

⚠️ 注意：挂载目录属主必须允许 uid 1001 写入，否则容器内初始化失败；建议 chown -R 1001:0 /opt/qpid-compose/data/work。

六、常用环境变量表

💡 说明：环境变量在镜像 config.json 模板中以配置占位形式引用，仅在首次初始化（work 中无 config.json）时生效；改口令后想重置，需清空数据卷中的 config.json 重新初始化，或改用 REST API 修改用户口令。

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

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

官方镜像无独立 conf/ 目录，所有配置都落在数据卷 /qpid-broker-j/work 内。要固化自定义配置，两种方式：

1. 整目录持久化（本篇做法）：./data/work:/qpid-broker-j/work，config.json、default.json、broker.acl 全部落宿主机，ls 实测包含：

broker.acl
config.json
config.json.lck
default.json
default.lck
messages
preferences.json
preferences.json.lck
userPreferences.json
userPreferences.lck

2. 初始配置注入：额外挂载 ./conf-init:/qpid-broker-j/work-init，放入自定义 config.json/default.json 模板；仅首次初始化生效，适合批量部署同构实例。

九、等价 docker run 运行方式

不用 compose 时，等价命令：

docker run -d --name qpid-broker \
  -p 5672:5672 -p 8080:8080 \
  -e QPID_ADMIN_USER=admin \
  -e QPID_ADMIN_PASSWORD=q1w2e3r4 \
  -e "JAVA_MEM=-Xms256m -Xmx512m -XX:MaxDirectMemorySize=256m" \
  -v /opt/qpid-compose/data/work:/qpid-broker-j/work \
  apache/qpid-broker-j:10.1.1

实测（同参独立容器）：REST admin:q1w2e3r4 返回 200，/proc/1/cmdline 含 -Xms256m -Xmx512m -XX:MaxDirectMemorySize=256m，宿主机挂载目录生成 broker.acl、config.json、default.json 等文件，与 compose 行为完全一致。

十、常用运维命令

docker compose ps                       # 状态与端口映射
docker compose logs --tail 20 qpid-broker   # 最近日志
docker compose restart qpid-broker      # 重启实例
docker compose stop qpid-broker         # 停止（保留容器）
docker compose down                     # 停止并移除容器与网络（数据卷保留）
docker compose up -d                    # 重新拉起
docker stats qpid-broker                # 资源占用
docker exec qpid-broker id              # 查看运行用户（实测 uid=1001(qpid) gid=0(root)）

实测 docker compose restart qpid-broker 后日志再次出现 MNG-1004 : Web Management Ready 与 BRK-1004 : Qpid Broker Ready：

qpid-broker  | 2026-10-12T01:24:28,136Z INFO  [Broker-Config] (q.m.m.ready) - [Broker] MNG-1004 : Web Management Ready
qpid-broker  | [Broker] BRK-1004 : Qpid Broker Ready

十一、常见问题（FAQ）

Q1：docker compose up -d 报 failed to bind host port 0.0.0.0:8080/tcp: address already in use？ 宿主机 8080 被其他服务占用（实测本机被 haproxy 占用）。改映射为 "15680:8080" 等空闲端口即可；AMQP 端口同理。若报 Bind for 0.0.0.0:8081 failed: port is already allocated，说明端口已被另一个 Docker 实例占用，换端口或停掉对方。

Q2：容器不断重启，日志见 Permission denied？ 数据卷目录 uid 1001 无写权限。执行 chown -R 1001:0 /opt/qpid-compose/data/work（或 chmod 777）后 docker compose up -d 重新初始化。

Q3：修改了 QPID_ADMIN_PASSWORD 但登录仍用旧口令？ 账号在首次初始化时写入了数据卷的 config.json，之后环境变量不再生效。清空数据卷重新初始化（会丢配置，先备份），或通过 REST API 更新用户口令。

Q4：管理台/REST 返回 401？ 镜像版默认口令是 admin/admin；若按本篇覆盖为 q1w2e3r4，用新口令。密码输错实测返回 401，口令正确返回 200。

Q5：如何确认代理已就绪？ docker logs qpid-broker 2>&1 | grep "BRK-1004" 看到 Qpid Broker Ready；或 REST curl -u admin:q1w2e3r4 http://localhost:8080/api/latest/broker 返回 200 且 state 为 ACTIVE。

Q6：如何升级版本？ 改 compose 中镜像 tag（如 apache/qpid-broker-j 更新版本号），docker compose pull && docker compose up -d；数据卷中 config.json 含 modelVersion，新版会自动做配置升级，升级前务必备份整个 data/work 目录。

十二、参考链接

• 官方镜像 Docker Hub 页：https://hub.docker.com/r/apache/qpid-broker-j
• Broker-J 10.1.1 用户手册：https://qpid.apache.org/releases/qpid-broker-j-10.1.1/book/index.html
• REST API 章节：https://qpid.apache.org/releases/qpid-broker-j-10.1.1/book/Java-Broker-Management-Channel-REST-API.html
• Docker Compose 官方文档：https://docs.docker.com/compose/