ADMQ RabbitMQ 用户手册

产品版本： ADMQ RabbitMQ 2.0 日期： 2026-06

1. 产品概述

ADMQ RabbitMQ 是金蝶 Apusic 推出的企业级消息中间件，主要特性包括：

统一授权管理：集成 Apusic License 体系
多平台运行时：内置多种 Linux 平台的 Erlang 运行时，无需单独安装 Erlang
管控台集成：内置 Apusic 管控台 Agent（端口 58181），支持集中监控
简化运维：统一的 admq 命令行、systemd 服务集成、自动日志轮转

适用场景

场景	说明
企业应用集成	通过 AMQP 0.9.1 协议对接 Java/.NET/Python 应用
IoT 设备接入	通过 MQTT 3.1.1/5.0 接入传感器和设备
消息总线	使用 Topic/Fanout 交换机构建事件驱动架构
流处理	使用 RabbitMQ Streams 实现可重放消息流
微服务解耦	使用 Work Queue 实现异步任务分发

2. 协议支持

ADMQ RabbitMQ 支持以下协议：

2.1 AMQP（Advanced Message Queuing Protocol）

协议版本	状态	端口
AMQP 0-9-1	✅ 完整支持	5672 / 5671（TLS）
AMQP 1.0	✅ 插件支持	5672

AMQP 0-9-1 是 RabbitMQ 的原生协议，提供完整的消息路由、确认、事务功能。

2.2 MQTT

协议版本	状态	端口
MQTT 3.1	✅ 支持	1883 / 8883（TLS）
MQTT 3.1.1	✅ 支持	1883 / 8883（TLS）
MQTT 5.0	✅ 支持	1883 / 8883（TLS）
MQTT over WebSocket	✅ 支持	15675

重要说明： RabbitMQ 的 MQTT 支持通过 rabbitmq_mqtt 插件实现，是协议转换适配器，不是原生 MQTT Broker。MQTT 消息在内部被转换为 AMQP 消息路由到 Exchange，可与 AMQP 消费者互通。

MQTT 插件的功能限制（与专用 MQTT Broker 相比）：

功能	ADMQ RabbitMQ（插件）	ADMQ MQTT（原生）
实现方式	插件转换 MQTT → AMQP	原生 MQTT 实现
保留消息（Retained Message）	❌ 不支持	✅ 完整支持
遗嘱消息（Last Will）	✅ 支持	✅ 支持
QoS 0 / QoS 1	✅ 支持	✅ 支持
QoS 2（精确一次）	⚠️ 降级为 QoS 1 处理	✅ 完整支持
百万级并发连接	❌ 不适合（Queue 开销大）	✅ 专为此设计
与 AMQP 消费者互通	✅ 天然互通	❌ 需额外桥接
适合场景	少量 IoT 设备 + 企业应用混用	大规模 IoT 设备接入

选型建议：

主要业务是 IoT 大规模设备接入 → 使用 ADMQ MQTT
主要业务是企业应用集成（AMQP），偶尔有 MQTT 设备接入 → 使用 ADMQ RabbitMQ（本产品）

2.3 STOMP

协议版本	状态	端口
STOMP 1.0	✅ 支持	61613
STOMP 1.1	✅ 支持	61613
STOMP 1.2	✅ 支持	61613
STOMP over WebSocket	✅ 支持	15674

2.4 RabbitMQ Stream Protocol

功能	状态
Stream Protocol	✅ 支持
Stream 管理 API	✅ 支持
消费者偏移追踪	✅ 支持

2.5 HTTP（管理 API）

RESTful Management API：端口 15672
Prometheus 指标暴露：端口 15692

3. 端口说明

端口	协议	用途	默认状态
5672	AMQP 0-9-1	应用消息连接	✅ 启用
5671	AMQP 0-9-1 + TLS	加密消息连接	需配置证书
15672	HTTP	管理控制台 & REST API	✅ 启用
15671	HTTPS	管理控制台（加密）	需配置证书
1883	MQTT	MQTT 设备连接	需开启插件
8883	MQTT + TLS	MQTT 加密连接	需配置证书
15675	WebSocket (MQTT)	浏览器 MQTT	需开启插件
61613	STOMP	STOMP 连接	需开启插件
15674	WebSocket (STOMP)	浏览器 STOMP	需开启插件
25672	Erlang 分布式	集群节点通信	✅ 集群内部
58181	HTTP	Apusic 管控台 Agent	✅ 启用

安全提示： 生产环境请通过防火墙规则限制 25672 和 58181 端口的外部访问。

4. 安装与目录结构

4.1 目录结构

admq-rabbitmq/
├── bin/                        # 命令行工具
│   ├── admq                    # 主命令入口
│   ├── admq-daemon             # 守护进程管理
│   ├── admq-upgrade            # 升级工具
│   └── rabbitmq/               # RabbitMQ 子命令
│       ├── server              # 启动服务
│       ├── admin               # 管理操作
│       └── cluster             # 集群管理
├── config/                     # 用户配置目录
│   ├── rabbitmq.conf           # 主配置文件
│   ├── rabbitmq.conf.j2        # Jinja2 配置模板
│   ├── rabbitmq-admin.conf     # 管控台配置
│   └── rabbitmq-admin.conf.j2  # 管控台配置模板
├── jdk/                        # Java 运行时
├── logs/                       # 日志目录
├── rabbitmq/                   # RabbitMQ 核心（不建议直接修改）
│   ├── core/                   # RabbitMQ 程序文件
│   ├── exec/                   # Erlang 运行时（多平台）
│   └── libs/                   # Java 扩展库
└── service/
    └── admq-rabbitmq.service   # systemd 服务配置

4.2 环境要求

项目	要求
操作系统	Linux（EL7/EL8/EL9，x86_64 或 aarch64）
Java	无需单独安装（内置 JDK）
Erlang	无需单独安装（内置运行时）
内存	建议 4GB 以上
磁盘	建议 50GB 以上（含日志和消息存储）
文件句柄	建议 ulimit -n 65536

5. 快速启动

5.1 启动服务

bash

# 方式一：直接启动
bin/admq rabbitmq server

# 方式二：守护进程模式启动
bin/admq-daemon rabbitmq start

# 方式三：systemd 服务（生产推荐）
systemctl start admq-rabbitmq

5.2 停止服务

bash

# 守护进程停止
bin/admq-daemon rabbitmq stop

# systemd
systemctl stop admq-rabbitmq

5.3 重启服务

bash

bin/admq-daemon rabbitmq restart
# 或
systemctl restart admq-rabbitmq

5.4 验证启动成功

bash

# 查看进程
ps aux | grep rabbitmq

# 查看管理控制台（需要网络访问）
curl http://localhost:15672/api/overview -u admq:apusic_123

# 查看 Apusic 管控台
curl http://localhost:58181/health

5.5 默认账号

账号	密码	说明
`admq`	`apusic_123`	默认管理员账号

重要： 生产环境请立即修改默认密码。

6. 配置说明

主配置文件：config/rabbitmq.conf

6.1 网络配置

ini

# AMQP 监听端口（默认 5672）
listeners.tcp.default = 5672

# 集群通信端口
cluster_formation.classic_config.nodes.1 = rabbit@node1
cluster_formation.classic_config.nodes.2 = rabbit@node2

# 管理控制台端口
management.tcp.port = 15672
management.tcp.ip = 0.0.0.0

6.2 认证配置

ini

# 认证方式（默认内置数据库）
auth_backends.1 = rabbit_auth_backend_internal

# 默认用户（首次启动创建）
default_user = admq
default_pass = apusic_123

支持的认证后端：

后端	配置值
内置数据库	`rabbit_auth_backend_internal`
LDAP	`rabbit_auth_backend_ldap`
HTTP 外部认证	`rabbit_auth_backend_http`
OAuth2	`rabbit_auth_backend_oauth2`
证书认证	`rabbit_auth_mechanism_ssl`

6.3 资源限制

ini

# 内存高水位（超过后停止接收消息）
vm_memory_high_watermark.absolute = 16GB

# 磁盘最小空闲空间（低于后停止接收消息）
disk_free_limit.absolute = 10GB

# 最大消息大小（字节，默认 128MB）
max_message_size = 134217728

# 最大连接数
connection_max = 10000

# 最大 Channel 数
channel_max = 2048

6.4 日志配置

ini

# 控制台日志
log.console = false

# 文件日志
log.file.enabled = true
log.file = server.log
log.file.level = info

# 日志轮转
log.file.rotation.date = $D0      # 每日轮转
log.file.rotation.count = 5       # 保留 5 个文件
log.file.rotation.compress = true # 压缩

6.5 Jinja2 模板部署

如使用自动化部署，可通过模板生成配置：

bash

# 安装 Jinja2（Python 环境）
pip install jinja2

# 渲染配置模板
python3 -c "
import jinja2
with open('config/rabbitmq.conf.j2') as f:
    tmpl = jinja2.Template(f.read())
print(tmpl.render(
    listeners_tcp_default=5672,
    default_user='admq',
    default_pass='YourStrongPassword',
    vm_memory_high_watermark_absolute='8GB'
))
" > config/rabbitmq.conf

7. 用户与权限管理

7.1 通过管理控制台操作

访问 http://服务器IP:15672，使用管理员账号登录后，在 Admin 标签页管理用户。

7.2 通过命令行操作

bash

# 添加用户
bin/admq rabbitmq admin add_user <用户名> <密码>

# 列出所有用户
bin/admq rabbitmq admin list_users

# 设置用户角色
bin/admq rabbitmq admin set_user_tags <用户名> administrator

# 删除用户
bin/admq rabbitmq admin delete_user <用户名>

# 修改密码
bin/admq rabbitmq admin change_password <用户名> <新密码>

7.3 用户角色

角色	说明
`administrator`	完全管理权限，可管理用户/Virtual Host
`monitoring`	只读查看权限，可查看队列和连接信息
`management`	可登录管理控制台，查看自己 vhost 的信息
`policymaker`	可设置策略，无用户管理权限
`impersonator`	可模拟其他用户（OAuth2 场景）

7.4 权限设置

bash

# 设置用户对 vhost 的权限（configure/write/read）
bin/admq rabbitmq admin set_permissions -p <vhost> <用户名> ".*" ".*" ".*"

# 查看权限
bin/admq rabbitmq admin list_permissions -p <vhost>

8. Virtual Host 管理

Virtual Host（vhost）是 RabbitMQ 的多租户隔离单元，不同 vhost 之间的队列、交换机完全隔离。

bash

# 添加 vhost
bin/admq rabbitmq admin add_vhost <vhost名称>

# 列出所有 vhost
bin/admq rabbitmq admin list_vhosts

# 删除 vhost
bin/admq rabbitmq admin delete_vhost <vhost名称>

# 设置用户访问 vhost 的权限
bin/admq rabbitmq admin set_permissions -p <vhost> <用户名> ".*" ".*" ".*"

默认 vhost

默认 vhost 为 /，所有用户默认连接到 /。

9. 队列与交换机

9.1 交换机类型

类型	说明	适用场景
`direct`	精确匹配 routing key	点对点消息
`fanout`	广播到所有绑定队列	发布/订阅
`topic`	通配符匹配 routing key	分类消息路由
`headers`	基于消息头匹配	复杂路由规则

9.2 队列类型

类型	说明	特点
`classic`	经典队列（默认）	单节点或镜像，成熟稳定
`quorum`	仲裁队列	基于 Raft，强一致性，推荐生产使用
`stream`	流队列	可重放，高吞吐量

9.3 创建队列（通过 API）

bash

# 创建持久化队列
curl -X PUT http://localhost:15672/api/queues/%2F/my-queue \
  -u admq:apusic_123 \
  -H "content-type: application/json" \
  -d '{"durable": true, "arguments": {"x-queue-type": "quorum"}}'

10. 消息可靠性机制

10.1 消息持久化

java

// 声明持久化队列
channel.queueDeclare("task_queue", true, false, false, null);

// 发送持久化消息
channel.basicPublish("", "task_queue",
    MessageProperties.PERSISTENT_TEXT_PLAIN,
    message.getBytes());

10.2 消息确认（ACK）

java

// 手动确认模式（推荐）
channel.basicConsume("task_queue", false, (tag, delivery) -> {
    try {
        processMessage(delivery.getBody());
        channel.basicAck(delivery.getEnvelope().getDeliveryTag(), false);
    } catch (Exception e) {
        channel.basicNack(delivery.getEnvelope().getDeliveryTag(), false, true);
    }
}, tag -> {});

10.3 死信队列（DLQ）

配置队列在消息被拒绝或过期时转发到死信交换机：

bash

curl -X PUT http://localhost:15672/api/queues/%2F/main-queue \
  -u admq:apusic_123 \
  -H "content-type: application/json" \
  -d '{
    "durable": true,
    "arguments": {
      "x-dead-letter-exchange": "dlx",
      "x-message-ttl": 30000
    }
  }'

11. 集群部署

11.1 配置集群节点

编辑 config/rabbitmq.conf：

ini

# 静态配置集群节点
cluster_formation.peer_discovery_backend = rabbit_peer_discovery_classic_config
cluster_formation.classic_config.nodes.1 = rabbit@node1
cluster_formation.classic_config.nodes.2 = rabbit@node2
cluster_formation.classic_config.nodes.3 = rabbit@node3

集群中所有节点必须共享相同的 Erlang Cookie：

bash

# 查看当前 Cookie
cat ~/.erlang.cookie

# 或设置环境变量
export RABBITMQ_ERLANG_COOKIE=your_shared_secret

11.3 集群管理命令

bash

# 查看集群状态
bin/admq rabbitmq cluster status

# 加入集群
bin/admq rabbitmq cluster join rabbit@node1

# 脱离集群
bin/admq rabbitmq cluster leave

11.4 Kubernetes 集群发现

ini

cluster_formation.peer_discovery_backend = rabbit_peer_discovery_k8s
cluster_formation.k8s.host = kubernetes.default.svc.cluster.local
cluster_formation.k8s.address_type = hostname

11.5 仲裁队列（推荐生产）

集群环境建议使用仲裁队列替代经典镜像队列：

ini

# 设置默认队列类型为仲裁
default_queue_type = quorum

12. TLS 安全配置

12.1 AMQP over TLS

ini

# 启用 TLS 监听
listeners.ssl.default = 5671

ssl_options.cacertfile = /path/to/ca_certificate.pem
ssl_options.certfile   = /path/to/server_certificate.pem
ssl_options.keyfile    = /path/to/server_key.pem
ssl_options.verify     = verify_peer
ssl_options.fail_if_no_peer_cert = true

12.2 管理控制台 HTTPS

ini

management.ssl.port       = 15671
management.ssl.cacertfile = /path/to/ca_certificate.pem
management.ssl.certfile   = /path/to/server_certificate.pem
management.ssl.keyfile    = /path/to/server_key.pem

12.3 MQTT over TLS

需在插件配置中额外设置 MQTT TLS 监听端口（8883）。

13. 监控与管理

13.1 管理控制台

访问 http://服务器IP:15672，提供：

实时队列/连接/Channel 状态
消息速率图表
手动发布/消费消息
策略管理
插件管理

13.2 REST API

bash

# 查看概览信息
curl -u admq:apusic_123 http://localhost:15672/api/overview

# 列出所有队列
curl -u admq:apusic_123 http://localhost:15672/api/queues

# 查看特定队列
curl -u admq:apusic_123 http://localhost:15672/api/queues/%2F/my-queue

# 清空队列
curl -X DELETE -u admq:apusic_123 http://localhost:15672/api/queues/%2F/my-queue/contents

13.3 Prometheus 监控

RabbitMQ 内置 Prometheus 指标端点：

bash

curl http://localhost:15692/metrics

常用指标：

指标	说明
`rabbitmq_queue_messages_ready`	待消费消息数
`rabbitmq_queue_messages_unacked`	未确认消息数
`rabbitmq_connections`	当前连接数
`rabbitmq_channels`	当前 Channel 数
`rabbitmq_node_mem_used`	内存使用量
`rabbitmq_node_disk_free`	磁盘剩余空间

13.4 Apusic 管控台 Agent

ADMQ 内置 Apusic 监控 Agent 运行在 58181 端口，与 Apusic 统一监控平台对接。

14. 日志管理

14.1 日志位置

日志文件	说明
`logs/server.log`	RabbitMQ 主日志（轮转）
`rabbitmq/logs/rabbit@*.log`	Erlang 节点日志
`logs/admq-rabbitmq-*.log`	Java 层（Apusic）日志

14.2 日志级别

ini

# 全局日志级别（debug/info/warning/error/critical/none）
log.file.level = info

# 按分类设置
log.connection.level = warning
log.channel.level = warning
log.queue.level = info

14.3 日志轮转

默认每日轮转，保留最近 5 个压缩文件，无需额外配置 logrotate。

15. 常见问题

Q1：启动时提示 "Error: epmd error for host..."

原因： 主机名无法解析，Erlang 节点通信依赖主机名。

解决： 在 /etc/hosts 中添加本机主机名的解析：

bash

echo "127.0.0.1 $(hostname)" >> /etc/hosts

Q2：连接时提示 "ACCESS_REFUSED"

原因： 用户权限不足或密码错误。

解决：

bash

# 检查用户权限
bin/admq rabbitmq admin list_permissions -p /

# 重置权限
bin/admq rabbitmq admin set_permissions -p / admq ".*" ".*" ".*"

Q3：内存告警，消息停止写入

原因： 内存使用超过 vm_memory_high_watermark 阈值。

解决：

bash

# 临时解除（需重新发布）
curl -X PUT http://localhost:15672/api/vhosts/%2F/flow-control \
  -u admq:apusic_123 -H "content-type: application/json" -d '{"value": false}'

# 永久修改配置
# 编辑 config/rabbitmq.conf：
# vm_memory_high_watermark.absolute = 32GB

Q4：集群节点脑裂（Split-brain）

原因： 网络分区导致节点失去联系后各自认为自己是主节点。

解决： 配置网络分区处理策略（推荐 pause_minority）：

ini

cluster_partition_handling = pause_minority

Q5：磁盘空间不足停止写入

原因： 剩余磁盘空间低于 disk_free_limit 阈值。

解决：

清理历史消息或扩容磁盘
调整 disk_free_limit.absolute 至合适值

ADMQ RabbitMQ 用户手册 ​

目录 ​

1. 产品概述 ​

适用场景 ​

2. 协议支持 ​

2.1 AMQP（Advanced Message Queuing Protocol） ​

2.2 MQTT ​

2.3 STOMP ​

2.4 RabbitMQ Stream Protocol ​

2.5 HTTP（管理 API） ​

3. 端口说明 ​

4. 安装与目录结构 ​

4.1 目录结构 ​

4.2 环境要求 ​

5. 快速启动 ​

5.1 启动服务 ​

5.2 停止服务 ​

5.3 重启服务 ​

5.4 验证启动成功 ​

5.5 默认账号 ​

6. 配置说明 ​

6.1 网络配置 ​

6.2 认证配置 ​

6.3 资源限制 ​

6.4 日志配置 ​

6.5 Jinja2 模板部署 ​

7. 用户与权限管理 ​

7.1 通过管理控制台操作 ​

7.2 通过命令行操作 ​

7.3 用户角色 ​

7.4 权限设置 ​

8. Virtual Host 管理 ​

默认 vhost ​

9. 队列与交换机 ​

9.1 交换机类型 ​

9.2 队列类型 ​

9.3 创建队列（通过 API） ​

10. 消息可靠性机制 ​

10.1 消息持久化 ​

10.2 消息确认（ACK） ​

10.3 死信队列（DLQ） ​

11. 集群部署 ​

11.1 配置集群节点 ​

11.2 Erlang Cookie ​

11.3 集群管理命令 ​

11.4 Kubernetes 集群发现 ​

11.5 仲裁队列（推荐生产） ​

12. TLS 安全配置 ​

12.1 AMQP over TLS ​

12.2 管理控制台 HTTPS ​

12.3 MQTT over TLS ​

13. 监控与管理 ​

13.1 管理控制台 ​

13.2 REST API ​

13.3 Prometheus 监控 ​

13.4 Apusic 管控台 Agent ​

14. 日志管理 ​

14.1 日志位置 ​

14.2 日志级别 ​

14.3 日志轮转 ​

15. 常见问题 ​

Q1：启动时提示 "Error: epmd error for host..." ​

Q2：连接时提示 "ACCESS_REFUSED" ​

Q3：内存告警，消息停止写入 ​

Q4：集群节点脑裂（Split-brain） ​

Q5：磁盘空间不足停止写入 ​

ADMQ RabbitMQ 用户手册

目录

1. 产品概述

适用场景

2. 协议支持

2.1 AMQP（Advanced Message Queuing Protocol）

2.2 MQTT

2.3 STOMP

2.4 RabbitMQ Stream Protocol

2.5 HTTP（管理 API）

3. 端口说明

4. 安装与目录结构

4.1 目录结构

4.2 环境要求

5. 快速启动

5.1 启动服务

5.2 停止服务

5.3 重启服务

5.4 验证启动成功

5.5 默认账号

6. 配置说明

6.1 网络配置

6.2 认证配置

6.3 资源限制

6.4 日志配置

6.5 Jinja2 模板部署

7. 用户与权限管理

7.1 通过管理控制台操作

7.2 通过命令行操作

7.3 用户角色

7.4 权限设置

8. Virtual Host 管理

默认 vhost

9. 队列与交换机

9.1 交换机类型

9.2 队列类型

9.3 创建队列（通过 API）

10. 消息可靠性机制

10.1 消息持久化

10.2 消息确认（ACK）

10.3 死信队列（DLQ）

11. 集群部署

11.1 配置集群节点

11.2 Erlang Cookie

11.3 集群管理命令

11.4 Kubernetes 集群发现

11.5 仲裁队列（推荐生产）

12. TLS 安全配置

12.1 AMQP over TLS

12.2 管理控制台 HTTPS

12.3 MQTT over TLS

13. 监控与管理

13.1 管理控制台

13.2 REST API

13.3 Prometheus 监控

13.4 Apusic 管控台 Agent

14. 日志管理

14.1 日志位置

14.2 日志级别

14.3 日志轮转

15. 常见问题

Q1：启动时提示 "Error: epmd error for host..."

Q2：连接时提示 "ACCESS_REFUSED"

Q3：内存告警，消息停止写入

Q4：集群节点脑裂（Split-brain）

Q5：磁盘空间不足停止写入