安裝手冊

# 前言

本文档為金蝶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 Kafka支援透過管控臺部署，請參考《金蝶Apusic分散式訊息佇列V2.0.6_統一管控臺使用者手冊.pdf》，【快速入門】章節。

# 部署架構

# 整體架構

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	Prometheus 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`)