Apache Qpid 安装指南

目标：在真实 Ubuntu 22.04 服务器上从零安装 Apache Qpid Broker-J 10.1.1（纯 Java 实现的 AMQP 消息代理），覆盖前置依赖、官方二进制下载与校验、解压部署、首次启动验证、管理台认证、systemd 托管与常见故障排查。以下命令与回显均在 Ubuntu 22.04.5 LTS 真实环境逐步实测。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（x86_64）
Java：OpenJDK 17.0.20.1（openjdk-17-jre-headless，验证 jps 需另装 openjdk-17-jdk-headless）
Apache Qpid Broker-J：10.1.1（官方 bin.tar.gz 二进制包，build 49098be941a6e6c5c5fc17759c30e0e1e0331c80）
安装目录：/opt/qpid
工作目录：QPID_WORK=/var/qpidwork
默认端口：AMQP 5672、HTTP 管理台 8080
运行用户：root（方案B演示独立用户 qpid）

💡 说明：Apache Qpid Broker-J 是 Qpid 家族中的纯 Java 消息代理（旧称 Java Broker），支持 AMQP 0-8/0-9/0-9-1/0-10/1.0 多协议版本，本篇实测版本为官方当前最新稳定版 10.1.1。

二、前置条件

一台 Ubuntu 22.04 服务器，具备 root 权限。
服务器可访问 Apache 软件分发站 dlcdn.apache.org（或归档站 archive.apache.org）。
安装基础工具：wget、tar、unzip、curl、net-tools/iproute2（端口验证）、procps。
安装 JDK：推荐 openjdk-17-jdk-headless（含 jps，便于核对 JVM 参数）；仅运行代理安装 openjdk-17-jre-headless 即可。
磁盘空间：安装包约 41MB，解压后约 100MB，工作目录预留 1GB 以上。

三、版本选型说明

组件	推荐版本	说明
Apache Qpid Broker-J	10.1.1	官方当前最新稳定版；`dlcdn.apache.org/qpid/broker-j/` 目录下仅保留最新版，历史版本到 `archive.apache.org/dist/qpid/broker-j/` 获取
二进制包格式	`bin.tar.gz`（或 `bin.zip`）	官方提供 `bin.tar.gz`、`bin.zip` 两种二进制包，另有 `src.tar.gz` 源码包
OpenJDK	17（LTS）	实测 Ubuntu 22.04 仓库的 17.0.20.1 运行稳定；Apache 官方 Qpid 最新构建内置 JDK 25，说明新版 JVM 兼容良好
端口	AMQP 5672 / HTTP 8080	默认值，可通过配置属性 `qpid.amqp_port`、`qpid.http_port` 覆盖

查询官方分发目录确认可用版本：

curl -s https://dlcdn.apache.org/qpid/broker-j/ | grep -oE "href=\"[0-9.]+/\"" | sort -u

实测回显：

href="10.1.1/"

四、安装方案A：官方 bin.tar.gz 在线安装（推荐）

4.1 安装基础依赖

apt-get update -qq
DEBIAN_FRONTEND=noninteractive apt-get install -y \
    openjdk-17-jre-headless wget tar curl net-tools procps

验证版本回显：

# 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)

4.2 下载与 SHA-512 校验

cd /opt
wget https://dlcdn.apache.org/qpid/broker-j/10.1.1/binaries/apache-qpid-broker-j-10.1.1-bin.tar.gz
sha512sum apache-qpid-broker-j-10.1.1-bin.tar.gz
curl -s https://dlcdn.apache.org/qpid/broker-j/10.1.1/binaries/apache-qpid-broker-j-10.1.1-bin.tar.gz.sha512

实测回显（两行校验值完全一致即通过）：

-rw-r--r-- 1 root root 42218501 Sep 20 03:54 apache-qpid-broker-j-10.1.1-bin.tar.gz
4e3cfdb570c9f64d7c5015f491c1183853592447fb81bf0b2a22e28bbdf438280ee77e822ef2e394b90f906115a56cf906c626bbdb785c3d02a55de3b86caaa1  apache-qpid-broker-j-10.1.1-bin.tar.gz
4e3cfdb570c9f64d7c5015f491c1183853592447fb81bf0b2a22e28bbdf438280ee77e822ef2e394b90f906115a56cf906c626bbdb785c3d02a55de3b86caaa1  apache-qpid-broker-j-10.1.1-bin.tar.gz

4.3 解压与目录调整

⚠️ 注意：Broker-J 10.1.1 的 tar 包内层目录是 qpid-broker/10.1.1，而不是以包名命名的目录，解压后必须手动归位。

cd /opt
tar -tzf apache-qpid-broker-j-10.1.1-bin.tar.gz | head -5
tar -xzf apache-qpid-broker-j-10.1.1-bin.tar.gz
mv qpid-broker/10.1.1 qpid
rmdir qpid-broker
ls qpid

实测回显：

qpid-broker/10.1.1/LICENSE
qpid-broker/10.1.1/NOTICE
qpid-broker/10.1.1/README.txt
qpid-broker/10.1.1/bin/
qpid-broker/10.1.1/bin/qpid-run
LICENSE  NOTICE  README.txt  bin  lib

安装包不带 conf/ 目录，初始配置内嵌在 lib/qpid-broker-core-10.1.1.jar 的 initial-config.json 中，首次启动时自动物化为工作目录下的 config.json。

4.4 准备工作目录并首次启动

mkdir -p /var/qpidwork
export QPID_WORK=/var/qpidwork
/opt/qpid/bin/qpid-server

启动回显关键行（前台启动，Ctrl+C 可中断）：

System Properties set to -DQPID_HOME=/opt/qpid -DQPID_WORK=/var/qpidwork
QPID_OPTS set to
Using QPID_CLASSPATH /opt/qpid/lib/*:/opt/qpid/lib/plugins/*:/opt/qpid/lib/opt/*
Info: QPID_JAVA_GC not set. Defaulting to JAVA_GC -XX:+UseG1GC -XX:+HeapDumpOnOutOfMemoryError
Info: QPID_JAVA_MEM not set. Defaulting to JAVA_MEM -Xmx512m -XX:MaxDirectMemorySize=1536m
[Broker] BRK-1006 : Using configuration : /var/qpidwork/config.json
[Broker] BRK-1001 : Startup : Version: 10.1.1 Build: 49098be941a6e6c5c5fc17759c30e0e1e0331c80
[Broker] BRK-1010 : Platform : JVM : Ubuntu version: 17.0.20.1+1-1-22.04-Ubuntu OS : Linux version: 6.8.0-138-generic arch: amd64 cores: 12
[Broker] BRK-1011 : Maximum Memory : Heap : 536,870,912 bytes Direct : 1,610,612,736 bytes
[Broker] BRK-1017 : Process : PID : 4774
[Broker] BRK-1002 : Starting : Listening on TCP port 5672
[Broker] MNG-1001 : Web Management Startup
[Broker] MNG-1002 : Starting : HTTP : Listening on TCP port 8080
[Broker] MNG-1004 : Web Management Ready
[Broker] BRK-1004 : Qpid Broker Ready

💡 说明：BRK-1004 : Qpid Broker Ready 即启动成功标志；日志同时写入 QPID_WORK/log/qpid.log。默认堆即 -Xmx512m（BRK-1011 行显示 Heap 536,870,912 字节），符合 256-512MB 的内存控制要求。

4.5 验证监听端口

另开一个终端：

ss -tlnp | grep -E "5672|8080"

实测回显：

LISTEN 0      1024               *:8080            *:*    users:(("java",pid=4774,fd=106))
LISTEN 0      1024               *:5672            *:*    users:(("java",pid=4774,fd=82))

4.6 开启 HTTP Basic 认证并创建管理员账号

Broker-J 默认 HTTP 管理台只启用 SASL 认证，Basic 认证默认关闭；默认配置里只有一个内置用户 guest/guest。要让 curl -u 与脚本化运维可用，先停掉代理，编辑工作目录中的 config.json：

/opt/qpid/bin/qpid.stop

用编辑器修改 /var/qpidwork/config.json 两处：在 MANAGEMENT-HTTP 插件对象中加入 "httpBasicAuthenticationEnabled": true；在 plain 认证提供器的 users 数组中追加管理员用户。修改后两个片段如下：

"plugins" : [ {
    "type" : "MANAGEMENT-HTTP",
    "name" : "httpManagement",
    "httpBasicAuthenticationEnabled" : true
} ]

"users" : [ {
    "name" : "guest",
    "type" : "managed",
    "password" : "guest"
}, {
    "name" : "admin",
    "type" : "managed",
    "password" : "q1w2e3r4"
} ]

重新启动：

export QPID_WORK=/var/qpidwork
/opt/qpid/bin/qpid-server

4.7 REST API 验证

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:wrongpass -> %{http_code}\n" -u admin:wrongpass http://localhost:8080/api/latest/broker
curl -s -u admin:q1w2e3r4 http://localhost:8080/api/latest/broker | head -c 300

实测回显：

admin:q1w2e3r4 -> 200
admin:wrongpass -> 401
{
  "id" : "fae7ae98-8677-47c4-b0b7-7a83bc3b3abb",
  "name" : "Broker",
  "type" : "Broker",
  "desiredState" : "ACTIVE",
  "state" : "ACTIVE",
  "durable" : true,

创建并删除一个临时队列，验证写操作：

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/orders
curl -s -u admin:q1w2e3r4 http://localhost:8080/api/latest/queue/default/default | head -c 200

实测回显：

create -> 201
[ {
  "id" : "e9cae429-349a-44e4-9fad-3ca1152d36fd",
  "name" : "orders",
  "type" : "standard",
  "desiredState" : "ACTIVE",
  "state" : "ACTIVE",
  "durable" : true,

浏览器访问 http://服务器IP:8080/ 可打开 Web 管理台登录页，用 admin/q1w2e3r4 登录。

4.8 AMQP 端口握手验证

不装任何客户端，用系统自带 Python 对 5672 端口做 AMQP 1.0 协议头握手：

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

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

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

五、安装方案B：官方 bin.zip 包 + 独立运行用户

适合生产环境需要最小权限运行、或仅能拿到 zip 包的场景。程序目录沿用方案A已解压的 /opt/qpid（zip 与 tar.gz 内容一致）。

5.1 下载解压 zip 包（验证包内结构与 tar.gz 一致）

cd /tmp
wget -q https://dlcdn.apache.org/qpid/broker-j/10.1.1/binaries/apache-qpid-broker-j-10.1.1-bin.zip
unzip -q apache-qpid-broker-j-10.1.1-bin.zip
ls -d qpid-broker/10.1.1 && ls qpid-broker/10.1.1/bin

实测回显：

qpid-broker/10.1.1
qpid-run  qpid-server  qpid-server.bat  qpid.stop  qpid.stopall

5.2 创建独立运行用户与数据目录

useradd -r -s /sbin/nologin qpid
id qpid
mkdir -p /var/lib/qpiddata
chown -R qpid:qpid /var/lib/qpiddata

实测回显：

uid=999(qpid) gid=999(qpid) groups=999(qpid)

5.3 以 qpid 用户启动

⚠️ 注意：若方案A的代理已占用 5672/8080，第二实例会因端口冲突退出，日志出现 MNG-1003 : Shutting down : HTTP : port -2 与 BRK-1005 : Stopped；此时可用 -prop 换端口，或将方案A实例先停掉。

su -s /bin/bash qpid -c "export QPID_WORK=/var/lib/qpiddata && /opt/qpid/bin/qpid-server -prop qpid.amqp_port=10000 -prop qpid.http_port=10001"

另开终端验证（进程属主为 qpid）：

ss -tlnp | grep -E ":10000|:10001"
ps -o user,pid,args -p 8043 | tail -1

实测回显：

LISTEN 0      1024               *:10000            *:*    users:(("java",pid=8043,fd=81))
LISTEN 0      1024               *:10001            *:*    users:(("java",pid=8043,fd=109))
qpid     8043 java -server -DPNAME=QPBRKR -XX:+UseG1GC -XX:+HeapDumpOnOutOfMemoryError -Xmx512m

5.4 停止

su -s /bin/bash qpid -c "QPID_WORK=/var/lib/qpiddata /opt/qpid/bin/qpid.stop"

实测回显：

Found Qpid Broker-J process with PID: 8043
Qpid Broker-J process(es) terminated successfully

六、多方案对比与选择建议

维度	方案A：bin.tar.gz	方案B：bin.zip + 独立用户
版本	10.1.1（官方最新）	10.1.1（包内结构与 tar.gz 一致）
是否需联网	需访问 dlcdn.apache.org	需访问 dlcdn.apache.org（可离线拷贝 zip）
安装方式	tar 解压 + root 运行	unzip 解压 + 专用低权用户运行
端口	默认 5672/8080	可用 `-prop` 指定，如 10000/10001
托管方式	systemd（见第七章）	手工前台或自定义 systemd 单元
优点	步骤最少、与官方文档一致	最小权限、数据目录独立
适用场景	测试与常规部署	生产多实例、安全合规要求

选择建议：单实例快速部署选方案A并用 systemd 托管；生产环境多实例或安全要求高时选方案B，为每实例规划独立 QPID_WORK 与端口。

七、systemd 托管（生产推荐）

7.1 编写单元文件

创建 /etc/systemd/system/qpid-server.service：

[Unit]
Description=Apache Qpid Broker-J 10.1.1
Documentation=http://qpid.apache.org/releases/qpid-broker-j-10.1.1/book/
After=network.target

[Service]
Type=simple
User=root
Environment=QPID_HOME=/opt/qpid
Environment=QPID_WORK=/var/qpidwork
Environment="QPID_JAVA_MEM=-Xms256m -Xmx512m -XX:MaxDirectMemorySize=256m"
ExecStart=/opt/qpid/bin/qpid-server
ExecStop=/opt/qpid/bin/qpid.stop
Restart=on-failure
RestartSec=10
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

⚠️ 注意：QPID_JAVA_MEM 含空格，Environment= 必须整体加双引号。实测不加引号时 systemd 按空格拆分环境变量，最终 JVM 命令行里只剩 -Xms256m，-Xmx512m 与 MaxDirectMemorySize 全部丢失。

7.2 启动并设置开机自启

systemctl daemon-reload
systemctl enable qpid-server
systemctl start qpid-server
sleep 25
systemctl is-active qpid-server
ss -tlnp | grep -E "5672|8080"

实测回显：

Created symlink /etc/systemd/system/multi-user.target.wants/qpid-server.service → /etc/systemd/system/qpid-server.service.
active
LISTEN 0      1024               *:8080            *:*    users:(("java",pid=5399,fd=107))
LISTEN 0      1024               *:5672            *:*    users:(("java",pid=5399,fd=83))

7.3 JVM 堆生效验证

jps -v | grep -i qpbrkr
tr "\0" "\n" < /proc/$(cat /var/qpidwork/qpid-server.pid)/cmdline | grep -E "Xms|Xmx|Direct"

实测回显（两种方式都能看到 -Xms256m -Xmx512m 生效）：

5399 Main -DPNAME=QPBRKR -XX:+UseG1GC -XX:+HeapDumpOnOutOfMemoryError -Xms256m -DQPID_HOME=/opt/qpid -DQPID_WORK=/var/qpidwork
-Xms256m
-Xmx512m
-XX:MaxDirectMemorySize=256m

💡 说明：jps -v 会打印完整 classpath 参数，此处摘录核对堆配置的关键行；/proc 方式按参数逐行展示更直观。

7.4 常用 systemctl 运维命令

systemctl restart qpid-server
systemctl stop qpid-server
systemctl status qpid-server
journalctl -u qpid-server -n 20

实测 systemctl restart qpid-server 后再执行 systemctl is-active qpid-server 回显 active，且 5672/8080 重新处于 LISTEN 状态（本次重启实测端口监听进程数量为 2）。

八、配置说明（安装后必改项）

8.1 目录与环境变量

目录/变量	说明
`/opt/qpid`	安装目录，`bin` 启停脚本 + `lib` 全部 jar，无 `conf/` 目录
`QPID_HOME`	系统属性 `qpid.home_dir` 来源，默认由启动脚本设为安装目录
`QPID_WORK`	工作目录（配置存储、消息存储、日志、pid 文件都在这里），未设时默认为用户 home
`/var/qpidwork/config.json`	运行时配置存储（Broker 全部实体配置）
`/var/qpidwork/default/config/default.json`	默认虚拟主机的配置存储（含 amq.direct/amq.fanout/amq.match/amq.topic 四个内置交换器）
`/var/qpidwork/default/messages`	BDB 消息存储目录
`/var/qpidwork/log/qpid.log`	主日志文件
`/var/qpidwork/qpid-server.pid`	进程 pid 文件
`/var/qpidwork/preferences.json`	用户偏好存储（版本号 9.1）

8.2 管理员账号与密码

默认仅有 guest/guest。生产必须按 4.6 节追加 admin 用户并设置强密码（本指南演示口令为 q1w2e3r4），并在 brokerloggers 同级处按需追加 ACL 访问控制。修改 config.json 后需重启代理生效。

8.3 JVM 堆内存调整

三种改法（任选其一）：

环境变量：export QPID_JAVA_MEM="-Xms256m -Xmx512m -XX:MaxDirectMemorySize=256m" 后运行 qpid-server（脚本中 QPID_JAVA_MEM 优先于默认 JAVA_MEM）；
systemd 单元：见 7.1 节 Environment= 行（注意引号）；
直接改 /opt/qpid/bin/qpid-server 中默认 JAVA_MEM 行（不推荐，升级会丢）。

改完必须用 7.3 节命令验证生效值，不允许只改不验。

8.4 端口调整

端口由配置属性 qpid.amqp_port（默认 5672）、qpid.http_port（默认 8080）控制。配置存储已初始化后改端口，直接编辑 config.json 中对应 ports 段的 port 字段并重启；全新 QPID_WORK 首次启动时也可用 -prop 注入：

QPID_WORK=/tmp/qpidtest /opt/qpid/bin/qpid-server -prop "qpid.amqp_port=10000" -prop "qpid.http_port=10001"

实测回显（ss 验证）：

LISTEN 0      1024               *:10000            *:*    users:(("java",pid=5979,fd=82))
LISTEN 0      1024               *:10001            *:*    users:(("java",pid=5979,fd=84))

日志关键行：

[Broker] MNG-1002 : Starting : HTTP : Listening on TCP port 10001
[Broker] BRK-1004 : Qpid Broker Ready

九、注意事项

qpid-server 是前台进程，验证阶段可直接跑；生产务必用 systemd 托管。
停止脚本 bin/qpid.stop 会向进程发 SIGTERM 优雅停机，并等待最多 360 秒；它会停止当前用户的所有 Broker 实例，多实例环境按用户隔离或传入 pid。
修改 config.json 必须在代理停止或通过 REST API 进行；代理运行时会回写该文件，手工编辑覆盖会丢失。
日志由 config.json 的 brokerloggers 控制（File/Memory/Console 三类记录器 + logger 名与级别包含规则），默认 qpid.log 已含 org.apache.qpid.* INFO 与 ROOT WARN 规则。
JVM 堆保持 256-512MB 区间，Direct Memory 按需另配；MaxDirectMemorySize 影响 AMQP 缓冲区，过小会限制吞吐。

十、常见问题（FAQ）

Q1：curl -u admin:admin http://localhost:8080/api/latest/broker 返回 401？ 10.1.1 的 HTTP 管理台默认只开 SASL 认证、Basic 认证默认关闭，且默认内置用户是 guest/guest 而不是 admin/admin。按 4.6 节在 httpManagement 插件加 "httpBasicAuthenticationEnabled": true 并追加 admin 用户后重启即可；实测开启后 admin:q1w2e3r4 返回 200、错误口令返回 401。

Q2：tar 解压后找不到程序目录？ 包内层目录是 qpid-broker/10.1.1，用 tar -tzf 先确认，再按 4.3 节 mv qpid-broker/10.1.1 /opt/qpid 归位。

Q3：执行 bin/qpid.stop 提示 No Qpid Broker-J process found running 且前面有 pgrep 用法帮助输出？ 脚本用 pgrep -f -U "$USER" 找进程，当前 shell 未设置 USER 环境变量时会触发 pgrep 参数错误。显式带上环境变量：USER=root /opt/qpid/bin/qpid.stop，实测即输出 Found Qpid Broker-J process with PID 行并正常终止。

Q4：systemd 启动后 jps -v 只看到 -Xms256m，-Xmx 不见了？ Environment=QPID_JAVA_MEM=-Xms256m -Xmx512m -XX:MaxDirectMemorySize=256m 等号后的值含空格且未加引号，systemd 把空格后的内容当成了新的环境变量定义。改为 Environment="QPID_JAVA_MEM=-Xms256m -Xmx512m -XX:MaxDirectMemorySize=256m" 后 daemon-reload 重启，实测三段参数全部出现在进程命令行。

Q5：启动即退出，日志出现 MNG-1003 : Shutting down : HTTP : port -2？ 端口被其他进程占用导致绑定失败（port -2 表示代理启动中止）。用 ss -tlnp | grep -E "5672|8080" 排查占用方，换端口（-prop qpid.amqp_port=10000 -prop qpid.http_port=10001，实测可行）或停掉占用进程后重启。

Q6：用 -mm 进入管理模式报 Cannot resolve some objects: [GenericUnresolvedConfiguredObject{class=HttpPortImpl, unresolvedObjects=[NameDependency{AuthenticationProvider, "MANAGEMENT_MODE_AUTHENTICATION" }]}]？ 10.1.1 在全新工作目录直接 -mm 启动会缺这个认证提供器。解法：先用 -cic /tmp/mm-ic.json 导出初始配置副本，向其 authenticationproviders 追加 {"name":"MANAGEMENT_MODE_AUTHENTICATION","type":"Plain","users":[{"name":"mm_admin","type":"managed","password":"mm_admin"}]}，再以 -icp /tmp/mm-ic.json -mm -mmhttp 18080 启动。实测启动后仅监听 18080（AMQP 端口不开放），curl http://localhost:18080/ 返回 200。

Q7：jps 命令不存在？ openjdk-17-jre-headless 不含 jps，安装 openjdk-17-jdk-headless 后即可；或改用 /proc/<pid>/cmdline 方式核对 JVM 参数。

十一、卸载方式

systemctl stop qpid-server
systemctl disable qpid-server
rm /etc/systemd/system/qpid-server.service
systemctl daemon-reload
rm -rf /opt/qpid /var/qpidwork /var/lib/qpiddata
rm -f /opt/apache-qpid-broker-j-10.1.1-bin.tar.gz
userdel qpid

若只是换版本升级：停服后替换 /opt/qpid 目录即可，QPID_WORK 内的配置与消息存储保留；跨大版本升级前先备份 config.json，Broker-J 启动时会按 modelVersion 自动做配置升级（实测首启日志含 Broker store has model version 升级记录行）。

十二、参考链接

Apache Qpid 官方站点：https://qpid.apache.org/
Broker-J 10.1.1 用户手册：https://qpid.apache.org/releases/qpid-broker-j-10.1.1/book/index.html
下载页（含校验文件）：https://dlcdn.apache.org/qpid/broker-j/10.1.1/binaries/
历史版本归档：https://archive.apache.org/dist/qpid/broker-j/
REST API 章节：https://qpid.apache.org/releases/qpid-broker-j-10.1.1/book/Java-Broker-Management-Channel-REST-API.html