Apache Qpid 配置参数详解

目标：讲清 Apache Qpid Broker-J 10.1.1 的完整配置体系——环境变量、命令行配置属性、工作目录中 config.json 的各类配置实体、日志规则与消息存储默认值，并给出可直接落地的生产配置模板。所有参数与回显均在 Ubuntu 22.04.5 实测环境采集。

一、环境信息

• 操作系统：Ubuntu 22.04.5 LTS（x86_64）
• Java：OpenJDK 17.0.20.1
• Apache Qpid Broker-J：10.1.1（安装目录 /opt/qpid，工作目录 QPID_WORK=/var/qpidwork）
• 配置存储：/var/qpidwork/config.json（modelVersion 9.1）
• 默认端口：AMQP 5672、HTTP 管理台 8080
• 管理账号：admin / q1w2e3r4（HTTP Basic 认证已开启）

二、前置条件

• 已按《Apache Qpid 安装指南》完成 Broker-J 安装并能启动。
• 熟悉 JSON 语法；config.json 为标准 JSON，可直接用 python3 -m json.tool 校验。
• 修改配置前先停止代理或通过 REST API 修改，避免代理运行时回写覆盖手工改动。

三、参数查看与修改方式

3.1 三层配置来源（优先级从高到低）

1. Java 系统属性 / 命令行：-prop name=value 设置配置属性，系统属性同名优先；
2. 环境变量：QPID_HOME、QPID_WORK、QPID_JAVA_MEM、QPID_JAVA_GC、QPID_OPTS 等，由启动脚本翻译为系统属性与 JVM 参数；
3. config.json 配置存储：全部 Broker 实体（端口、认证、日志、虚拟主机）的最终生效值。

3.2 查看当前生效配置

python3 -m json.tool /var/qpidwork/config.json

实测输出顶层结构（键顺序即文件顺序）：

id
name
modelVersion
authenticationproviders
brokerloggers
plugins
ports
virtualhostnodes

通过 REST API 读取运行态属性：

curl -s -u admin:q1w2e3r4 http://localhost:8080/api/latest/broker | python3 -c "import json,sys; d=json.load(sys.stdin); print(d['name'], d['state'], d['version'])"

实测回显：

Broker ACTIVE 10.1.1

3.3 修改方式与生效规则

⚠️ 注意：-prop qpid.amqp_port=10000 只影响全新工作目录首次初始化时生成的端口值；配置存储已存在时端口以 config.json 为准，改端口直接编辑对应 ports 段。

四、参数总览

五、核心参数分类详解

5.1 环境变量与启动脚本参数

/opt/qpid/bin/qpid-server 脚本内置默认并支持覆盖：

-prop 配置属性实测（全新工作目录 + 换端口）：

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

实测 ss -tlnp 回显：

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

5.2 端口配置（ports 段）

默认生成两个端口实体，均绑定认证提供器 plain：

• AMQP 端口：port 字段引用配置属性 qpid.amqp_port（默认 5672），挂三个虚拟主机别名 defaultAlias、hostnameAlias、nameAlias，分别支持空主机名、按主机名、按名称寻址虚拟主机；
• HTTP 端口：port 引用 qpid.http_port（默认 8080），protocols 固定 ["HTTP"]。

修改示例：把 AMQP 换成 5673，编辑 config.json 的 AMQP 端口对象 "port" : "5673" 后重启，ss -tlnp | grep 5673 应出现 LISTEN 行。

5.3 认证提供器与用户（authenticationproviders）

默认生成 Plain 提供器（名称 plain），内建用户：

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

type: managed 表示用户由代理托管（配置存储内管理，REST API 可增删改）。生产改造（实测可用）：追加 admin 用户并设置口令 q1w2e3r4，随后 REST 验证 admin:q1w2e3r4 返回 200、错误口令 401。

通过 REST 创建用户（免停服）：

curl -s -o /dev/null -w "create appuser -> %{http_code}\n" -u admin:q1w2e3r4 -X PUT -d '{"type":"managed","password":"app123456"}' http://localhost:8080/api/latest/user/plain/appuser
curl -s -o /dev/null -w "appuser login -> %{http_code}\n" -u appuser:app123456 http://localhost:8080/api/latest/broker
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)])"

实测回显：

create appuser -> 201
appuser login -> 200
['guest', 'appuser', 'admin']

5.4 HTTP 管理台插件（plugins 段）

MANAGEMENT-HTTP 插件即 Web 管理台与 REST API 的载体，关键属性：

打开 Basic 认证后的实测对照：

开启前：curl -u guest:guest http://localhost:8080/api/latest/broker -> 401
开启后：curl -u admin:q1w2e3r4 http://localhost:8080/api/latest/broker -> 200

💡 说明：HTTPS 监听下 Basic 认证默认开启；仅配置 HTTP 监听时才需要手工打开该属性。

5.5 日志配置（brokerloggers）

默认两组记录器：

• logfile（type File）：写入 QPID_WORK/log/qpid.log，实测启动后即生成该文件；
• memory（type Memory）：仅内存环形缓冲，供管理台查看。

两组各含 4 条包含规则（brokerloginclusionrules）：

调整示例：把 ROOT 提到 INFO 以便排障，编辑规则 "level" : "INFO"；新增独立审计日志则追加一个 File 记录器对象。实现层为 slf4j 2.0.19 + logback 1.6.3（lib 目录实测可见），但常规调整无需 logback 配置文件，全部由 brokerloggers 驱动。

5.6 虚拟主机节点与消息存储（virtualhostnodes）

默认节点 default（type JSON，defaultVirtualHostNode 为 true），首次启动时物化：

/var/qpidwork/default/config/default.json    # 虚拟主机配置存储
/var/qpidwork/default/messages/              # BDB 消息存储

实测 default.json 关键内容：

{
  "type" : "BDB",
  "name" : "default",
  "exchanges" : [ {
      "name" : "amq.direct", "type" : "direct"
  }, {
      "name" : "amq.fanout", "type" : "fanout"
  }, {
      "name" : "amq.match", "type" : "headers"
  }, {
      "name" : "amq.topic", "type" : "topic"
  } ]
}

REST 验证：

curl -s -u admin:q1w2e3r4 http://localhost:8080/api/latest/virtualhost/default | python3 -c "import json,sys; d=json.load(sys.stdin)[0]; print(d['name'], d['type'], d['state'])"

实测回显：

default BDB ACTIVE

多虚拟主机：向 virtualhostnodes 追加新节点对象（或 REST PUT /api/latest/virtualhostnode），重启后按 AMQP 端口别名（nameAlias）用不同虚拟主机名寻址。

5.7 队列与容量默认值

新装代理（本指南环境）队列默认不设容量上限；官方预置虚拟主机模板 context 中内置：

queue.defaultMaximumQueueDepthMessages = 1000
queue.defaultMaximumQueueDepthBytes = 1048576

按需在虚拟主机 context 或单队列属性上覆盖。durable 队列持久化验证实测：创建 orders 队列（"durable":true 返回 201），重启代理后队列列表仍在。

六、生产配置模板

适用场景：4核8GB 以上服务器、NVMe SSD、单实例 1000 连接以内的中型消息平台；JVM 堆锁定 256-512MB 区间（大业务量时按需放大堆外 Direct 内存）。

systemd 单元（/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

config.json 生产要点（实测可用的组合）：

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

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

要点核对清单：

1. 管理口令必须改掉默认 guest/guest，并为业务应用单独建账号；
2. httpBasicAuthenticationEnabled 打开后，建议为 8080 增加反向代理或改用 HTTPS 监听；
3. 堆参数用 systemd Environment= 注入并加双引号（不加引号实测只剩 -Xms256m 生效）；
4. Restart=on-failure + RestartSec=10 保证异常退出自拉起；
5. 数据目录（QPID_WORK）与程序目录分离，纳入备份计划（config.json + default/ + log/）。

七、常见问题

Q1：改了 config.json 不生效？ 确认代理已停止后再编辑；代理运行时会按内存态回写 config.json，手工修改会被覆盖。热修改走 REST API，例如更新队列 durable 属性：curl -u admin:q1w2e3r4 -X PUT -d '{"durable":true}' http://localhost:8080/api/latest/queue/default/default/orders（实测返回 201）。

Q2：-prop qpid.amqp_port=10000 改端口为何无效？ 配置存储已初始化（config.json 已存在）时端口已固化，-prop 只作用于首次初始化。已有实例直接编辑 config.json 的 ports 段或用 REST API 修改端口实体。

Q3：curl 一律 401？ HTTP 监听的 Basic 认证默认关闭（详见 5.4 节）。在 httpManagement 插件加 "httpBasicAuthenticationEnabled": true 重启即可；默认账号是 guest/guest，没有 admin。

Q4：堆参数 -Xmx 丢失？ systemd Environment= 含空格必须整体加引号，实测不加引号时 JVM 命令行只剩 -Xms256m。用 /proc/<pid>/cmdline 或 jps -v 验证最终值。

Q5：qpid.log 里 ROOT 级别日志太少排不了障？ 默认 ROOT 为 WARN。把 brokerloggers 中 Root 规则级别改为 INFO（或临时加 Console 记录器）后重启，org.apache.qpid.* 已默认 INFO，无需其他改动。

八、参考链接

• Broker-J 10.1.1 用户手册：https://qpid.apache.org/releases/qpid-broker-j-10.1.1/book/index.html
• 配置属性章节（Table 5.1 Base Configuration Properties）：https://qpid.apache.org/releases/qpid-broker-j-10.1.1/book/Java-Broker-Initial-Configuration-Configuration-Properties.html
• HTTP 插件属性（7.17 HTTP Plugin）：https://qpid.apache.org/releases/qpid-broker-j-10.1.1/book/Java-Broker-Management-Managing-Plugin-HTTP.html
• 初始配置示例：https://qpid.apache.org/releases/qpid-broker-j-10.1.1/book/Java-Broker-Initial-Configuration-Example.html