Apache Qpid 常用 CLI 命令与工具详解

目标：整理 Apache Qpid Broker-J 10.1.1 日常运维的命令行工具链——启停脚本、主类参数、REST API 调用、协议握手自检与 JVM 参数核对，命令即实测命令、输出即实测输出。所有回显均在 Ubuntu 22.04.5 实测环境采集。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（x86_64）
Java：OpenJDK 17.0.20.1（含 openjdk-17-jdk-headless 提供 jps）
Apache Qpid Broker-J：10.1.1（安装目录 /opt/qpid）
工作目录：QPID_WORK=/var/qpidwork
管理端口：AMQP 5672、HTTP 管理台 8080（HTTP Basic 认证已开启）
管理账号：admin / q1w2e3r4

二、工具概览

工具/命令	路径	用途
qpid-server	`/opt/qpid/bin/qpid-server`	启动代理（前台进程，内部转交 qpid-run）
qpid-run	`/opt/qpid/bin/qpid-run`	JVM 命令组装核心，支持 -run: 调试选项
qpid.stop	`/opt/qpid/bin/qpid.stop`	按 pid 或按用户优雅停止代理
qpid.stopall	`/opt/qpid/bin/qpid.stopall`	停止当前用户全部代理实例
Main 主类	`org.apache.qpid.server.Main`	版本查询、初始配置导出、端口属性、管理模式
curl + REST API	系统自带	管理与监控全部 Broker 实体
python3 socket	系统自带	AMQP 端口协议握手自检
jps / ps	JDK / procps	核对 JVM 参数生效值

三、前置条件

Broker-J 已安装（见《Apache Qpid 安装指南》），QPID_HOME、QPID_WORK 可用。
HTTP Basic 认证已开启且 admin 账号已创建（REST 调用依赖）。
安装 procps（ps）、iproute2（ss）、curl、python3；核对 JVM 参数需 openjdk-17-jdk-headless 提供 jps。

四、工具详解

4.1 qpid-server：启动代理

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

启动回显关键行：

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

常用环境变量（脚本内识别，启动前 export）：

变量	示例	作用
QPID_WORK	/var/qpidwork	工作目录（配置/消息/日志/pid）
QPID_JAVA_MEM	-Xms256m -Xmx512m -XX:MaxDirectMemorySize=256m	覆盖默认堆参数
QPID_OPTS	-Dqpid.amqp_port=5673	追加 JVM 参数
QPID_PID_FILENAME	qpid-server.pid	pid 文件名

JVM 参数生效核对（三种方式实测均可）：

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

实测回显：

5399 Main -DPNAME=QPBRKR -XX:+UseG1GC -XX:+HeapDumpOnOutOfMemoryError -Xms256m -DQPID_HOME=/opt/qpid -DQPID_WORK=/var/qpidwork
-Xms256m
-Xmx512m
-XX:MaxDirectMemorySize=256m
LISTEN 0      1024               *:8080            *:*    users:(("java",pid=5399,fd=107))
LISTEN 0      1024               *:5672            *:*    users:(("java",pid=5399,fd=83))

4.2 qpid-run：JVM 组装与调试选项

qpid-server 最后一步会 source bin/qpid-run 并以 org.apache.qpid.server.Main 为主类 exec 启动。qpid-run 自带 -run: 选项（传给 qpid-server 同样生效）：

选项	作用
-run:debug	回显完整 classpath 与 java 命令后启动
-run:classpath	仅打印 classpath
-run:print	仅打印将要执行的 java 命令
-run:help	打印选项帮助

实测 QPID_JAVA_MEM 覆盖优先级（qpid-run 日志）：

Info: QPID_JAVA_MEM not set. Defaulting to JAVA_MEM -Xmx512m -XX:MaxDirectMemorySize=1536m

设置 QPID_JAVA_MEM=-Xms256m -Xmx512m -XX:MaxDirectMemorySize=256m 后该行变为使用自定义值，jps -v 可见三段参数（见 4.1 回显）。

4.3 qpid.stop 与 qpid.stopall：停止代理

不带参数停止当前用户全部实例：

USER=root /opt/qpid/bin/qpid.stop

实测回显：

Found Qpid Broker-J processes with PIDs: 5794 6475
Shutting down Qpid Broker-J with PID '5794'
Shutting down Qpid Broker-J with PID '6475'
Waiting for up to 360 seconds for process(es) to shutdown...
Qpid Broker-J process(es) terminated successfully

按 pid 精确停止单个实例（pid 来自 QPID_WORK/qpid-server.pid）：

USER=root /opt/qpid/bin/qpid.stop 8043

实测回显：

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

⚠️ 注意：脚本用 pgrep -f -U "$USER" 找进程，当前 shell 缺 USER 变量时会输出 pgrep 用法帮助并提示 No Qpid Broker-J process found running；显式加 USER=root 前缀即可。脚本对进程发 SIGTERM 并最多等 360 秒。

4.4 Main 主类：版本、配置导出与高级参数

主类帮助与版本（不启动代理）：

cd /opt/qpid && java -cp "lib/*" org.apache.qpid.server.Main -v

实测回显：

Apache Qpid Broker-J Core - 10.1.1 build: 49098be941a6e6c5c5fc17759c30e0e1e0331c80 (AMQP version(s) [major.minor]: 0-8, 0-9, 0-9-1, 0-10, 1.0)

java -cp "lib/*" org.apache.qpid.server.Main -h

实测回显（完整选项表）：

 usage:  Qpid [-cic <path>] [-h] [-icp <path>] [-mm] [-mmhttp <port>]
    [-mmpass <password>] [-mmqv] [-prop <name=value>] [-props <path>] [-sp
    <path>] [-st <type>] [-v]
 -h, --help                                             print this message
 -v, --version                                          print the version information and exit
 -sp, --store-path <path>                               use given configuration store location
 -st, --store-type <type>                               use given broker configuration store type
 -cic, --create-initial-config <path>                   create a copy of the initial config file
 -icp, --initial-config-path <path>                     set the location of initial JSON config
 -mm, --management-mode                                 start broker in management mode, disabling the AMQP ports
 -mmqv, --management-mode-quiesce-virtualhostnodes      make virtual host nodes stay in the quiesced state
 -mmhttp, --management-mode-http-port <port>            override http management port in management mode
 -mmpass, --management-mode-password <password>         set the password for the management mode user mm_admin
 -prop, --config-property <name=value>                  set a configuration property
 -props, --system-properties-file <path>                set the location of initial properties file

导出初始配置副本（自定义配置的起点）：

cd /opt/qpid && java -cp "lib/*" org.apache.qpid.server.Main -cic /tmp/mm-ic.json

实测回显：

Initial config written to: /tmp/mm-ic.json

-prop 换端口启动（全新工作目录实测）：

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

实测日志与端口：

[Broker] MNG-1002 : Starting : HTTP : Listening on TCP port 10001
[Broker] BRK-1004 : Qpid Broker Ready
LISTEN 0      1024               *:10000            *:*    users:(("java",pid=5979,fd=82))
LISTEN 0      1024               *:10001            *:*    users:(("java",pid=5979,fd=84))

管理模式 -mm：用于只读维护（AMQP 端口不开放）。10.1.1 全新工作目录直接 -mm 会报 Cannot resolve some objects: [GenericUnresolvedConfiguredObject{class=HttpPortImpl, unresolvedObjects=[NameDependency{AuthenticationProvider, "MANAGEMENT_MODE_AUTHENTICATION" }]}]；解法是先用 -cic 导出初始配置，在其中追加名为 MANAGEMENT_MODE_AUTHENTICATION 的 Plain 认证提供器（含用户 mm_admin），再用 -icp 指定该配置并以 -mm -mmhttp 18080 启动。实测通过后仅监听 18080：

[Broker] MNG-1002 : Starting : HTTP : Listening on TCP port 18080
[Broker] MNG-1004 : Web Management Ready
LISTEN 0      1024               *:18080            *:*    users:(("java",pid=6475,fd=81))

4.5 curl + REST API：远程管理与监控

REST API 版本号嵌在路径中，/api/latest/ 自动指向当前版本。以下均实测通过。

查看 Broker 概要：

curl -s -u admin:q1w2e3r4 http://localhost:8080/api/latest/broker | head -c 300

实测回显：

{
  "id" : "fae7ae98-8677-47c4-b0b7-7a83bc3b3abb",
  "name" : "Broker",
  "type" : "Broker",
  "desiredState" : "ACTIVE",
  "state" : "ACTIVE",
  "durable" : true,

创建 durable 队列（PUT）：

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

实测回显：

create -> 201

查询队列列表与详情：

curl -s -u admin:q1w2e3r4 http://localhost:8080/api/latest/queue/default/default | head -c 200

实测回显：

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

删除队列（DELETE）：

curl -s -u admin:q1w2e3r4 -X PUT -d '{"durable":false}' http://localhost:8080/api/latest/queue/default/default/tmp-queue -o /dev/null -w "create -> %{http_code}\n"
curl -s -u admin:q1w2e3r4 -X DELETE http://localhost:8080/api/latest/queue/default/default/tmp-queue -o /dev/null -w "delete -> %{http_code}\n"

实测回显：

create -> 201
delete -> 200

虚拟主机节点与用户管理：

curl -s -u admin:q1w2e3r4 http://localhost:8080/api/latest/virtualhostnode | python3 -c "import json,sys; [print(v['name'], v['state']) for v in json.load(sys.stdin)]"
curl -s -u admin:q1w2e3r4 http://localhost:8080/api/latest/user/plain | python3 -c "import json,sys; print([u['name'] for u in json.load(sys.stdin)])"

实测回显：

default ACTIVE
['guest', 'appuser', 'admin']

💡 说明：URL 层级为 /api/latest/<实体类别>/<父实体名路径>/<实体名>，如队列实体挂在虚拟主机节点 default 与虚拟主机 default 之下，路径即 /queue/default/default/orders。401 表示认证失败（口令错误或未开 Basic 认证），403 表示已认证但无权限。

4.6 python3 socket：AMQP 端口协议握手自检

不装客户端即可验证 AMQP 服务是否正常应答（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

实测回显：

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

AMQP 0-10 握手可拿到代理产品与版本字符串（发送 8 字节头 AMQP 加 0x01 0x01 0x00 0x0a）：

AMQP.......................m.....product...Apache Qpid Broker-J Core.version...10.1.1.qpid.build..(49098be941a6e6c5c5fc17759c30e0e1e0331c80.qpid.instance_name...Broker

五、注意事项

qpid-server 前台运行，终止会话即停止代理；长期运行用 systemd 托管（见《Apache Qpid 安装指南》第七章）。
qpid.stop 不带参数会停掉当前用户所有 Broker 进程，多实例环境务必按 pid 停止单实例。
REST API 写操作（PUT/POST/DELETE）直接改运行态并持久化到 config.json，避免与手工编辑并发。
REST 端口若仍为默认关闭 Basic 认证的状态，所有 curl -u 请求一律 401，先完成认证开启（见《Apache Qpid 配置参数详解》5.4 节）。
生产环境禁止把管理端口 8080 直接暴露公网，建议防火墙限制来源或加反向代理认证。

六、常见问题

Q1：qpid.stop 报 No Qpid Broker-J process found running，但进程明明在？ 当前 shell 未设置 USER。pgrep -U 收到空参数会打印用法帮助并匹配不到进程；改用 USER=root /opt/qpid/bin/qpid.stop 即可（实测成功终止）。

Q2：java -cp "lib/*" org.apache.qpid.server.Main -v 报 ClassNotFound？ 必须在 /opt/qpid 目录执行（相对 classpath），或写绝对路径 java -cp "/opt/qpid/lib/*" org.apache.qpid.server.Main -v；通配符外层要加引号防止 shell 展开。

Q3：REST 返回 401 / 403 分别是什么问题？ 401 是认证失败：口令错误，或 HTTP 监听未开 Basic 认证（默认关）。403 是认证通过但权限不足：当前用户没有对应实体的操作权限，需配置 ACL 或改用管理员账号。

Q4：-mm 管理模式启动即异常退出？ 10.1.1 已知问题：全新工作目录缺 MANAGEMENT_MODE_AUTHENTICATION 认证提供器。按 4.4 节导出初始配置并追加该提供器后用 -icp 启动，实测可正常进入管理模式（仅 HTTP 端口监听）。

Q5：如何确认代理正在监听且协议正常？ ss -tlnp | grep -E "5672|8080" 看端口，再用 4.6 节 socket 握手拿 AMQP\x03\x01\x00\x00 应答；管理面用 curl -u admin:q1w2e3r4 http://localhost:8080/api/latest/broker 返回 200 即双重确认。

七、参考链接

Broker-J 10.1.1 用户手册（Getting Started / Command Line）：https://qpid.apache.org/releases/qpid-broker-j-10.1.1/book/Java-Broker-Getting-Started-CommandLine.html
REST API 章节：https://qpid.apache.org/releases/qpid-broker-j-10.1.1/book/Java-Broker-Management-Channel-REST-API.html
HTTP 插件属性：https://qpid.apache.org/releases/qpid-broker-j-10.1.1/book/Java-Broker-Management-Managing-Plugin-HTTP.html
Apache Qpid 官方站点：https://qpid.apache.org/