安装手册

# 前言

本文档为金蝶Apusic分布式消息队列for RabbitMQ（Apusic Distributed Message Queue，简称：ADMQ for RabbitMQ）的安装手册，提供产品各种部署模式（含单机、集群）在各操作系统、容器环境的安装部署过程指导以及相关配置说明。

# 适用对象

本文档适用于IT信息化业务负责人、研发经理、软件项目经理、软件架构师、运维工程师。

# 相关文档

了解更多ADMQ for RabbitMQ产品相关的信息，请参阅以下ADMQ for RabbitMQ产品手册文档集：

序号	手册文档	说明
1	金蝶Apusic分布式消息队列for RabbitMQ 快速使用手册	简单介绍了如何快速上手使用ADMQ for RabbitMQ 。
2	金蝶Apusic分布式消息队列for RabbitMQ 安装手册	详细介绍如何在各操作系统上安装ADMQ for RabbitMQ，以及ADMQ for RabbitMQ服务启停等操作。
3	金蝶Apusic分布式消息队列for RabbitMQ 消息引擎用户手册	详细介绍 ADMQ for RabbitMQ 消息引擎相关功能的使用、配置、管理及配套工具的使用方法。
4	金蝶Apusic分布式消息队列for RabbitMQ 管控台用户手册	详细介绍ADMQ for RabbitMQ管控台相关功能的使用和操作说明。
5	金蝶Apusic分布式消息队列for RabbitMQ 开发手册	详细介绍基于各开发语言进行ADMQ for RabbitMQ客户端应用开发的说明。
6	金蝶Apusic分布式消息队列for RabbitMQ 迁移手册	详细介绍从RabbitMQ迁移到ADMQ for RabbitMQ的说明。
7	金蝶Apusic分布式消息队列for RabbitMQ 运维手册	详细介绍ADMQ for RabbitMQ的监控、运维、安全加固等运维说明。
8	金蝶Apusic分布式消息队列for RabbitMQ 性能优化手册	详细介绍ADMQ for RabbitMQ性能调优的说明。

# 技术支持

ADMQ for RabbitMQ产品提供全面的技术支持服务，您可以通过以下方式获得技术支持：

网址：www.apusic.com
电话：400-855-5800
邮箱：support@apusic.com
金蝶云社区：https://vip.kingdee.com/?productId=73&productLineId=14&lang=zh-CN

您在取得技术支持时，请提供如下信息：

您的姓名
公司信息与联系方式
操作系统及其版本
产品版本号
出现异常及错误的日志、截图等详细信息

# 部署架构

# 整体架构

ADMQ for RabbitMQ 采用模块化设计，整体架构由以下核心组件组成：

┌─────────────────────────────────────────────────────────────┐
│                        客户端层                               │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │ 生产者应用   │  │ 消费者应用   │  │ 管控台/Web管理       │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
└────────────────────────┬────────────────────────────────────┘
                         │ AMQP/MQTT/STOMP
┌────────────────────────▼────────────────────────────────────┐
│                     消息引擎层                                │
│  ┌───────────────────────────────────────────────────────┐  │
│  │              ADMQ for RabbitMQ 节点                    │  │
│  │  ┌─────────────┐  ┌─────────────┐  ┌──────────────┐  │  │
│  │  │  连接层      │  │  交换机      │  │   队列        │  │  │
│  │  │ Connection  │  │  Exchange   │  │   Queue      │  │  │
│  │  └─────────────┘  └─────────────┘  └──────────────┘  │  │
│  │                                                        │  │
│  │  ┌─────────────┐  ┌─────────────┐  ┌──────────────┐  │  │
│  │  │   路由层     │  │  镜像队列    │  │  持久化存储   │  │  │
│  │  │   Router    │  │Mirror Queue │  │  Mnesia/ETS  │  │  │
│  │  └─────────────┘  └─────────────┘  └──────────────┘  │  │
│  └───────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────────┐
│                      集群通信层                               │
│  ┌───────────────────────────────────────────────────────┐  │
│  │              Erlang Distribution 网络                  │  │
│  │            (节点间元数据同步与心跳检测)                  │  │
│  └───────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

# 组件说明

组件	说明	功能
连接层	Connection	处理客户端连接、协议解析、安全认证
交换机	Exchange	接收消息并根据路由规则分发到队列
队列	Queue	存储消息，支持普通队列和 Quorum Queues
镜像队列	Mirror Queue	集群模式下同步队列数据到多个节点
持久化存储	Mnesia/ETS	存储元数据、配置信息和持久化消息
集群通信	Erlang Distribution	节点间通信，同步元数据和集群状态

# 部署模式

ADMQ for RabbitMQ 支持以下部署模式：

部署模式	节点数	适用场景	高可用性
单机部署	1 节点	开发测试、低吞吐量场景	无
普通集群	2+ 节点	生产环境，需要横向扩展	元数据高可用
镜像队列集群	3+ 节点	生产环境，消息数据高可用	元数据+数据高可用

# 架构特点

分布式设计：支持多节点集群部署，元数据自动同步
高可用性：支持镜像队列，确保消息数据在节点故障时不丢失
弹性扩展：可动态添加节点扩展集群处理能力
多协议支持：原生支持 AMQP 0-9-1 协议
管控分离：消息引擎与管控台可独立部署

# 环境准备

# 系统要求

组件	最低要求	推荐配置
CPU	4 核	8 核及以上
内存	8 GB	16 GB 及以上
磁盘	100 GB SSD	500 GB 及以上 SSD
网络	1 Gbps	10 Gbps
操作系统	Linux (CentOS 7+, Ubuntu 18.04+, 麒麟, 统信)	-

# 网络要求

端口	用途	说明
5672	AMQP 协议	生产者和消费者连接
5671	AMQP over SSL	SSL 加密连接
15672	Management HTTP	HTTP API 和 Web 管理界面
15671	Management HTTPS	HTTPS API 和 Web 管理界面
15692	Promtheus Metrics	监控采集指标
25672	Erlang Distribution	集群节点间通信
12305	管控台 HTTP	管控台 Web 界面（HTTP）
12306	管控台 HTTPS	管控台 Web 界面（HTTPS）

# 单机部署

本文档指导用户在 Linux 环境下完成 ADMQ RabbitMQ 的单机模式部署，包含环境准备、安装配置、授权申请、服务启动及状态验证。

# 创建部署目录

首先创建应用根目录并进入：

mkdir -p /apusic
cd /apusic

1
2

# 下载并解压软件包

从内部仓库下载指定版本的安装包并解压。

# 下载安装包
# 实施人员提供

# 解压安装包
tar zxvf ADMQ-V2.0.6.31214-RabbitMQ-20260227.tar.gz

1
2
3
4
5

# 目录结构说明

解压完成后，当前目录下将生成 admq-rabbitmq。标准目录结构如下：

admq-rabbitmq/
├── bin/              # 可执行脚本目录
├── config/           # 配置文件目录
├── data/             # 数据存储目录
├── logs/             # 日志文件目录
├── lib/              # 依赖库目录
└── license.xml       # 授权文件（需自行放置）

1
2
3
4
5
6
7

# 配置修改

# 修改主机名称

主机名称只能包含：

字母（a-z A-Z）
数字（0-9）
连字符（-）

# 查看主机名称
hostname

# 修改主机名
hostname node84

1
2
3
4
5

# 修改监听端口等信息（可选）

编辑 config/rabbitmq.conf，可以修改监听端口、用户名密码等信息。

# 示例：修改监听端口和默认用户
listeners.tcp.default = 5672
default_user = admq
default_pass = apusic_123

1
2
3
4

# 授权许可

ADMQ 产品需要 License 文件才能正常运行。

申请授权：联系管理员或通过授权平台申请对应版本的 license.xml 文件。
放置文件：将获取到的 license.xml 文件上传至部署目录根路径。

# 确认文件位置
ls -l /apusic/admq-rabbitmq/license.xml

1
2

# 启动服务

启动消息收发服务：

bin/admq-daemon start rabbitmq server

启动服务

# 服务验证

# 检查进程状态

使用 ps 命令查看进程，正常状态下应能看到相关进程：

ps -ef | grep admq-rabbitmq

预期输出示例：

检查进程

# 检查端口监听

使用 netstat 确认 5672 端口是否处于 LISTEN 状态：

netstat -nltup | grep 5672

预期输出示例：

检查端口

如果未看到输出，请检查防火墙设置或查看日志排查启动失败原因。

# 查看运行日志

如果服务启动异常或需监控运行状态，请查看 logs 目录下的日志文件：

# 查看实时日志
tail -f logs/server.log

# 或者查看目录结构
ls -lh logs/

1
2
3
4
5

重点关注日志中是否有 ERROR 级别的信息。

查看日志

# 创建用户

默认已经开启了认证，客户端收发消息需要添加用户名密码。

创建用户：test

设置密码：test123

bin/admq rabbitmq admin ctl add_user test test123

创建用户

# 创建虚拟主机

创建虚拟主机：test

bin/admq rabbitmq admin ctl add_vhost test

创建虚拟主机

设置权限给用户：test

bin/admq rabbitmq admin ctl set_permissions --vhost test test ".*" ".*" ".*"
bin/admq rabbitmq admin ctl set_user_tags test management

1
2

设置权限

设置用户标签

# 集群部署

# 部署规划

假设部署 3 节点 高可用集群，规划如下：

前置要求：

确保三台机器时间同步（NTP）。
关闭防火墙或开放端口：5672 , 15672 。

# 所有节点执行：基础安装

在 Node 1, Node 2, Node 3 上分别执行：

# 创建目录并解压

mkdir -p /apusic
cd /apusic
tar zxvf ADMQ-V2.0.6.31214-RabbitMQ-20260306.tar.gz
cd admq-rabbitmq

1
2
3
4

# 放置授权文件

将 license.xml 上传至 /apusic/admq-rabbitmq/ 目录。

# 修改主机名称

主机名称只能包含：

字母（a-z A-Z）
数字（0-9）
连字符（-）

# 在 Node 1 执行
hostname node171

# 在 Node 2 执行
hostname node172

# 在 Node 3 执行
hostname node173

1
2
3
4
5
6
7
8

# 修改服务器 hosts 文件

需要在 /etc/hosts 添加集群所有节点的信息。

所有节点都添加如下信息：

172.20.140.171 node171
172.20.140.172 node172
172.20.140.173 node173

1
2
3

# 配置集群（可选）

编辑 config/rabbitmq.conf，可以配置监听端口、默认用户名密码等信息。

# Node 1 配置 (`172.20.140.171`)

listeners.tcp.default = 5672
# 默认用户
default_user = admq
default_pass = apusic_123

1
2
3
4

# Node 2 配置 (`172.20.140.172`)

listeners.tcp.default = 5672
# 默认用户
default_user = admq
default_pass = apusic_123

1
2
3
4

# Node 3 配置 (`172.20.140.173`)

listeners.tcp.default = 5672
# 默认用户
default_user = admq
default_pass = apusic_123

1
2
3
4

# 启动各节点服务

依次登录 Node 1, 2, 3 执行：

cd /apusic/admq-rabbitmq
bin/admq-daemon start rabbitmq server

1
2

启动后日志如下：

启动日志

之后需要检测节点状态，确认是否启动成功。可直接查看端口是否处于监听状态。

ss -anpl | grep 5672

预期输出：

端口监听

# 创建集群

在第一个节点执行集群创建命令，把另外两个节点加入到该节点组成集群：

bin/admq rabbitmq cluster add -s 172.20.140.172:58181 -u monitor -p apusic_123
bin/admq rabbitmq cluster add -s 172.20.140.173:58181 -u monitor -p apusic_123

1
2

创建集群1

创建集群2

# 镜像模式（可选）

集群模式中，各个节点只能同步元数据，不能同步交换机、队列下的数据。在没使用 Quorum Queues 模式的情况下可以使用镜像队列同步各个节点的数据。

bin/admq rabbitmq admin ctl set_policy ha-all "^" '{"ha-mode":"all","ha-sync-mode":"automatic"}'

# 集群验证与测试

# 验证各个节点的端口状态

在每台服务器检查端口监听状态：

# 检查 5672 端口是否被监听
ss -anpl | grep 5672

1
2

预期：可以看到端口被监听。

验证端口

# 检查集群状态

在 Node1 执行：

bin/admq rabbitmq cluster status

可以看到集群中三个节点都已经添加完成。

集群状态

# 功能测试

创建用户：

创建用户：test

设置密码：test123

bin/admq rabbitmq admin ctl add_user test test123

预期输出示例：

集群创建用户

创建虚拟主机：

创建虚拟主机：test

bin/admq rabbitmq admin ctl add_vhost test

预期输出示例：

集群创建虚拟主机

设置权限给用户：test

bin/admq rabbitmq admin ctl set_permissions --vhost test test ".*" ".*" ".*"
bin/admq rabbitmq admin ctl set_user_tags test management

1
2

集群设置权限1

集群设置权限2

# 集群故障模拟与维护

# 停止服务

bin/admq-daemon stop rabbitmq server

# 常见错误排查

集群节点添加失败，节点连接失败

连接失败

解决方法：配置 /etc/hosts，添加 node172 的信息，然后重启该节点。

集群节点添加失败，节点停止失败

停止失败

解决方法：重启需要添加的节点。

# 常见问题及排查

# 服务启动失败

可能原因	解决方案
端口冲突	检查 5672、15672、25672 端口是否被占用
权限不足	确保 admq-rabbitmq 目录权限正确
内存不足	检查系统内存，确保满足最低要求
License 未放置或过期	确认 license.xml 已放置在部署目录根路径且未过期
OpenSSL 版本不兼容	Ubuntu 24.04 等系统默认使用 OpenSSL 3.x，而 Erlang crypto 模块依赖 `libcrypto.so.1.1`，需安装 OpenSSL 1.1 兼容库（`libssl1.1`），安装完成后重启服务

OpenSSL 1.1 兼容库安装示例（Ubuntu/Debian）：

# Ubuntu 24.04 需要先安装 libssl1.1
wget http://security.ubuntu.com/ubuntu/pool/main/o/openssl/libssl1.1_1.1.1f-1ubuntu2.24_amd64.deb
dpkg -i libssl1.1_1.1.1f-1ubuntu2.24_amd64.deb

1
2
3

说明：如果在 logs/rabbitmq-server-*.out 中看到类似 crypto:strong_rand_bytes 或 libcrypto.so.1.1: cannot open shared object file 的错误，即为 OpenSSL 兼容性问题。

# 集群加入失败

可能原因	解决方案
主机名不符合规范	确保主机名只包含字母、数字和连字符
网络不通	检查节点间网络连通性和防火墙设置
主机名解析失败	确保 /etc/hosts 或 DNS 配置正确
节点未正常启动	检查各节点服务是否已正常启动

# 管控台无法访问

可能原因	解决方案
端口冲突	修改 config/application.properties 中的 server.port
防火墙阻挡	开放 12305/12306 端口
服务未启动	检查管控台服务状态

# 数据源 403 错误

可能原因	解决方案
RabbitMQ 用户权限不足	使用 administrator 标签用户，配置 .* 权限
消息发送和接收异常	检查路由 key 和绑定关系是否正确

编辑页面

#安装手册

← 功能与技术规格快速使用手册→

安装手册

# 前言

# 适用对象

# 相关文档

# 技术支持

# 部署架构

# 整体架构

# 组件说明

# 部署模式

# 架构特点

# 环境准备

# 系统要求

# 网络要求

# 单机部署

# 创建部署目录

# 下载并解压软件包

# 目录结构说明

# 配置修改

# 修改主机名称

# 修改监听端口等信息（可选）

# 授权许可

# 启动服务

# 服务验证

# 检查进程状态

# 检查端口监听

# 查看运行日志

# 创建用户

# 创建虚拟主机

# 集群部署

# 部署规划

# 所有节点执行：基础安装

# 创建目录并解压

# 放置授权文件

# 修改主机名称

# 修改服务器 hosts 文件

# 配置集群（可选）

# Node 1 配置 (172.20.140.171)

# Node 2 配置 (172.20.140.172)

# Node 3 配置 (172.20.140.173)

# 启动各节点服务

# 创建集群

# 镜像模式（可选）

# 集群验证与测试

# 验证各个节点的端口状态

# 检查集群状态

# 功能测试

# 集群故障模拟与维护

# 停止服务

# 常见错误排查

# 常见问题及排查

# 服务启动失败

# 集群加入失败

# 管控台无法访问

# 数据源 403 错误

# Node 1 配置 (`172.20.140.171`)

# Node 2 配置 (`172.20.140.172`)

# Node 3 配置 (`172.20.140.173`)