安裝手冊

# 前言

本文檔為金蝶Apusic分散式訊息佇列for RocketMQ（Apusic Distributed Message Queue for RocketMQ，簡稱：ADMQ for RocketMQ）的安裝手冊，提供產品各種部署模式（含單機、雙主、多主多從）在各作業系統、容器環境的安裝部署過程指導以及相關配置說明。

# 適用對象

本文檔適用於IT資訊化業務負責人、研發經理、軟體專案經理、軟體架構師、運維工程師。

# 相關文檔

了解更多ADMQ for RocketMQ產品相關的資訊，請參閱以下ADMQ for RocketMQ產品手冊文件集：

序號 手冊文檔 說明
1 金蝶Apusic分散式訊息佇列for RocketMQ 快速使用手冊 簡單介紹了如何快速上手使用ADMQ for RocketMQ 。
2 金蝶Apusic分散式訊息佇列for RocketMQ 安裝手冊 詳細介紹如何在各作業系統上安裝ADMQ for RocketMQ，以及ADMQ for RocketMQ服務啟停等操作。
3 金蝶Apusic分散式訊息佇列for RocketMQ 訊息引擎使用者手冊 詳細介紹 ADMQ for RocketMQ 訊息引擎相關功能的使用、配置、管理及配套工具的使用方法。
4 金蝶Apusic分散式訊息佇列for RocketMQ 管控台使用者手冊 詳細介紹ADMQ for RocketMQ管控台相關功能的使用和操作說明。
5 金蝶Apusic分散式訊息佇列for RocketMQ 開發手冊 詳細介紹基於各開發語言進行ADMQ for RocketMQ客戶端應用開發的說明。
6 金蝶Apusic分散式訊息佇列for RocketMQ 遷移手冊 詳細介紹從RocketMQ遷移到ADMQ for RocketMQ的說明。
7 金蝶Apusic分散式訊息佇列for RocketMQ 運維手冊 詳細介紹ADMQ for RocketMQ的監控、運維、安全加固等運維說明。
8 金蝶Apusic分散式訊息佇列for RocketMQ 效能最佳化手冊 詳細介紹ADMQ for RocketMQ效能調優的說明。

# 技術支援

ADMQ for RocketMQ產品提供全面的技術支援服務，您可以透過以下方式獲得技術支援：

  • 網址：www.apusic.com
  • 電話：400-855-5800
  • 郵箱：support@apusic.com
  • 金蝶雲社群：https://vip.kingdee.com/?productId=73&productLineId=14&lang=zh-CN

您在取得技術支援時，請提供如下資訊：

  1. 您的姓名

  2. 公司資訊與聯絡方式

  3. 作業系統及其版本

  4. 產品版本號

  5. 出現異常及錯誤的日誌、截圖等詳細資訊

ADMQ for Kafka支援透過管控台部署，請參考《金蝶Apusic分散式訊息佇列V2.0.6_統一管控台使用者手冊.pdf》，【快速入門】章節。

# 部署架構

rocketmq_architecture_3

# ADMQ for RocketMQ網路部署特點

  • NameServer是一個幾乎無狀態節點，可叢集部署，節點之間無任何資訊同步。

  • Broker部署相對複雜，Broker分為Master與Slave，一個Master可以對應多個Slave，但是一個Slave只能對應一個Master，Master與Slave的對應關係透過指定相同的BrokerName，不同的BrokerId來定義，BrokerId為0表示Master，非0表示Slave。Master也可以部署多個。每個Broker與NameServer叢集中的所有節點建立長連線，定時註冊Topic資訊到所有NameServer。注意：當前RocketMQ版本在部署架構上支援一Master多Slave，但只有BrokerId=1的從伺服器才會參與訊息的讀負載。

  • Producer與NameServer叢集中的其中一個節點（隨機選擇）建立長連線，定期從NameServer獲取Topic路由資訊，並向提供Topic服務的Master建立長連線，且定時向Master傳送心跳。Producer完全無狀態，可叢集部署。

  • Consumer與NameServer叢集中的其中一個節點（隨機選擇）建立長連線，定期從NameServer獲取Topic路由資訊，並向提供Topic服務的Master、Slave建立長連線，且定時向Master、Slave傳送心跳。Consumer既可以從Master訂閱訊息，也可以從Slave訂閱訊息，消費者在向Master拉取訊息時，Master伺服器會根據拉取偏移量與最大偏移量的距離（判斷是否讀老訊息，產生讀I/O），以及從伺服器是否可讀等因素建議下一次是從Master還是Slave拉取。

結合部署架構圖，描述叢集工作流程：

  • 啟動NameServer，NameServer起來後監聽連接埠，等待Broker、Producer、Consumer連上來，相當於一個路由控制中心。
  • Broker啟動，跟所有的NameServer保持長連線，定時傳送心跳包。心跳包中包含當前Broker資訊(IP+連接埠等)以及儲存所有Topic資訊。註冊成功後，NameServer叢集中就有Topic跟Broker的對映關係。
  • 收發訊息前，先建立Topic，建立Topic時需要指定該Topic要儲存在哪些Broker上，也可以在傳送訊息時自動建立Topic。
  • Producer傳送訊息，啟動時先跟NameServer叢集中的其中一台建立長連線，並從NameServer中獲取當前傳送的Topic存在哪些Broker上，輪詢從佇列列表中選擇一個佇列，然後與佇列所在的Broker建立長連線從而向Broker發訊息。
  • Consumer跟Producer類似，跟其中一台NameServer建立長連線，獲取當前訂閱Topic存在哪些Broker上，然後直接跟Broker建立連線通道，開始消費訊息。

# 環境準備

# 系統要求

在開始部署之前，請確保您的環境滿足以下要求：

  • 作業系統：64 位元 Linux（推薦 CentOS 7+、Ubuntu 18.04+，國產Kylin v10+、OpenEuler 22.03+）
  • Java 版本：JDK 8及以上
  • 硬體配置：
    • 最小生產環境需要 7 台伺服器（或虛擬機器）
      • 3 台執行 Name Server
      • 4 台執行 Broker（Master 和 Slave 各 2 台）
    • 測試環境可以在一台伺服器上執行所有元件
  • 網路：所有節點之間可以相互通訊，並具有穩定的網路連線
  • DNS：可選，為所有 Broker 節點配置一個共同的 DNS 名稱

# 硬體推薦

下表提供了不同規模叢集的硬體推薦（每節點）：

元件 小型叢集 (250 個主題) 中型叢集 (1000 個主題)
Name Server • CPU: 4 核 • 記憶體: 16GB • 磁碟: 200GB SSD • CPU: 8 核 • 記憶體: 32GB • 磁碟: 500GB SSD
Broker • CPU: 8 核 • 記憶體: 32GB • 磁碟: 500GB SSD • CPU: 16 核 • 記憶體: 64GB • 磁碟: 1TB SSD

硬體選擇建議

  • Name Server 只用於元資料儲存，可以使用相對較小的伺服器
  • Broker 計算需要快速的 CPU 和網路，推薦使用 10Gbps 網路介面；儲存需要快速的儲存裝置，推薦使用 SSD 或帶電池快取的 RAID 控制器

# 依賴軟體

軟體 版本要求 說明
JDK 1.8+ Broker 和 NameServer 執行依賴
Java 17+ 管控台執行依賴

# 網路要求

連接埠 用途 說明
9876 NameServer 服務註冊與發現
10911 Broker 生產者和消費者連線
10909 Broker VIP VIP 通道
10912 Broker HA 主從複製連接埠
12305 管控台 HTTP 管控台 Web 介面（HTTP）
12306 管控台 HTTPS 管控台 Web 介面（HTTPS）

# 單機部署

# 安裝 JDK

# CentOS/RHEL
sudo yum install -y java-1.8.0-openjdk

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y openjdk-8-jdk
1
2
3
4
5
6

# 安裝 ADMQ for RocketMQ

mkdir -p /apusic
cd /apusic
# 解壓安裝包
#tar zxvf ADMQ-V2.0.6-RocketMQ-構建日期.tar.gz -C /apusic/
tar zxvf ADMQ-V2.0.6.534-RocketMQ-20260625.tar.gz -C /apusic/
cd /apusic
# 建議nameserver broker元件資料夾結構分開
unzip rocketmq-V5.3.4-all.zip
mv rocketmq-V5.3.4-all nameserver
cd /apusic/nameserver

unzip rocketmq-V5.3.4-all.zip
mv rocketmq-V5.3.4-all broker
cd /apusic/broker

# 配置環境變數，可以改成對應機器的地址
export NAMESRV_ADDR=localhost:9876

# 配置授權證書，將對應的授權證書放置到對應元件的根目錄，假設license.xml檔案（檔名需統一license.xml）放置在/opt下
cp /apusic/license.xml /apusic/nameserver
cp /apusic/license.xml /apusic/broker
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

# 啟動 NameServer

# 啟動 NameServer
bin/rocketmq start nameserver

# 驗證狀態
tail -f logs/namesrv.log
1
2
3
4
5

# 啟動 Broker

# 配置 Broker，有些參數是預設的，可以根據需要修改，比如叢集的brokerId，根據節點數來設定
vi conf/broker.conf
1
2
# broker.conf
brokerClusterName=DefaultCluster
# （叢集節點的brokerName需要區分）
brokerName=broker-a 
brokerId=0
brokerRole=ASYNC_MASTER
flushDiskType=ASYNC_FLUSH
# （如果是叢集部署，需要填寫叢集所有節點的連接埠ip）
namesrvAddr=localhost:9876 
# Promethues開啟
enableMultiDispatch=true
enablemq=true
metricsPromExporterHost=0.0.0.0
metricsExporterType=PROM
1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 啟動 Broker
bin/rocketmq start broker

# 驗證狀態
tail -f logs/broker.log
1
2
3
4
5

# 驗證安裝

# 檢視叢集狀態
bin/mqadmin clusterList -n localhost:9876

# 檢視 Topic 列表
bin/mqadmin topicList -n localhost:9876
1
2
3
4
5

# 單機部署（單主部署）

這種方式風險較大，一旦Broker重啟或者當機時，會導致整個服務不可用。不建議線上環境使用，可以用於本地測試。

+-------------+
| NameServer1 |
+-------------+
       |                       
+-------------+ 
|  Broker-a   |
|   Master    |
+-------------+
1
2
3
4
5
6
7
8

# NameServer 部署

在 node1 上啟動 NameServer：

# node1
nohup bin/rocketmq start nameserver
1
2

# Broker 部署

Broker-a（node1）

# conf/broker-a.properties
brokerClusterName=AdmqCluster
brokerName=broker-a
brokerId=0
brokerRole=SYNC_MASTER
flushDiskType=ASYNC_FLUSH
namesrvAddr=node1:9876
# Promethues開啟
enableMultiDispatch=true
enablemq=true
metricsPromExporterHost=0.0.0.0
metricsExporterType=PROM
1
2
3
4
5
6
7
8
9
10
11
12
# node1
bin/rocketmq start broker
1
2

# 雙主部署

# 部署架構圖

+-------------+       +-------------+
| NameServer1 |       | NameServer2 |
+-------------+       +-------------+
       |                       |
+-------------+       +-------------+
|  Broker-a   |       |  Broker-b   |
|   Master    |       |   Master    |
+-------------+       +-------------+
1
2
3
4
5
6
7
8

# NameServer 部署

在 node1 和 node2 上分別啟動 NameServer：

# node1
bin/rocketmq start nameserver

# node2
bin/rocketmq start nameserver
1
2
3
4
5

# Broker 部署

Broker-a（node1）

# conf/broker-a.properties
brokerClusterName=AdmqCluster
# （叢集節點的brokerName需要區分）
brokerName=broker-a 
brokerId=0
brokerRole=ASYNC_MASTER
flushDiskType=ASYNC_FLUSH
# （如果是叢集部署，需要填寫叢集所有節點的連接埠ip）
namesrvAddr=node1:9876;node2:9876
# Promethues開啟
enableMultiDispatch=true
enablemq=true
metricsPromExporterHost=0.0.0.0
metricsExporterType=PROM
1
2
3
4
5
6
7
8
9
10
11
12
13
14

Broker-b（node2）

# conf/broker-b.properties
brokerClusterName=AdmqCluster
# （叢集節點的brokerName需要區分）
brokerName=broker-b 
brokerId=0
brokerRole=ASYNC_MASTER
flushDiskType=ASYNC_FLUSH
# （如果是叢集部署，需要填寫叢集所有節點的連接埠ip）
namesrvAddr=node1:9876;node2:9876
# Promethues開啟
enableMultiDispatch=true
enablemq=true
metricsPromExporterHost=0.0.0.0
metricsExporterType=PROM
1
2
3
4
5
6
7
8
9
10
11
12
13
14
# node1
bin/rocketmq start broker

# node2
bin/rocketmq start broker
1
2
3
4
5

# 多主多從部署

# 部署架構圖

+------------------+       +------------------+
|   NameServer1    |       |   NameServer2    |
+------------------+       +------------------+
         |                         |
+------------------+       +------------------+
|  Broker-a-Master |       |  Broker-b-Master |
+------------------+       +------------------+
         |                         |
+------------------+       +------------------+
|  Broker-a-Slave  |       |  Broker-b-Slave  |
+------------------+       +------------------+
1
2
3
4
5
6
7
8
9
10
11

# NameServer 部署

先啟動對應的nameserver元件

./bin/rocketmq start nameserver
1

# Broker 配置

Broker-a-Master（node1）

brokerClusterName=AdmqCluster
# （叢集主節點的brokerName需要區分）
brokerName=broker-a 
brokerId=0
brokerRole=ASYNC_MASTER
flushDiskType=ASYNC_FLUSH
# （如果是叢集部署，需要填寫叢集所有節點的連接埠ip）
namesrvAddr=node1:9876;node2:9876
# Promethues開啟
enableMultiDispatch=true
enablemq=true
metricsPromExporterHost=0.0.0.0
metricsExporterType=PROM
1
2
3
4
5
6
7
8
9
10
11
12
13

Broker-a-Slave（node3）

brokerClusterName=AdmqCluster
brokerName=broker-a
# （從節點的id，由於主從的名稱相同，所以在同一個組）
brokerId=1
brokerRole=SLAVE
flushDiskType=SYNC_FLUSH
# （如果是叢集部署，需要填寫叢集所有節點的連接埠ip）
namesrvAddr=node1:9876;node2:9876
# Promethues開啟
enableMultiDispatch=true
enablemq=true
metricsPromExporterHost=0.0.0.0
metricsExporterType=PROM
1
2
3
4
5
6
7
8
9
10
11
12
13

Broker-b-Master（node2）

brokerClusterName=AdmqCluster
# （叢集主節點的brokerName需要區分）
brokerName=broker-b
brokerId=0
brokerRole=SYNC_MASTER
flushDiskType=SYNC_FLUSH
# （如果是叢集部署，需要填寫叢集所有節點的連接埠ip）
namesrvAddr=node1:9876;node2:9876
# Promethues開啟
enableMultiDispatch=true
enablemq=true
metricsPromExporterHost=0.0.0.0
metricsExporterType=PROM
1
2
3
4
5
6
7
8
9
10
11
12
13

Broker-b-Slave（node4）

brokerClusterName=AdmqCluster
brokerName=broker-b
# （從節點的id，由於主從的名稱相同，所以在同一個組）
brokerId=1
brokerRole=SLAVE
flushDiskType=SYNC_FLUSH
# （如果是叢集部署，需要填寫叢集所有節點的連接埠ip）
namesrvAddr=node1:9876;node2:9876
# Promethues開啟
enableMultiDispatch=true
enablemq=true
metricsPromExporterHost=0.0.0.0
metricsExporterType=PROM
1
2
3
4
5
6
7
8
9
10
11
12
13

命令啟動

./bin/rocketmq start broker
1

# 管控台部署

# 安裝管控台

# 解壓管控台安裝包
tar zxvf admq-manager-V2.0.6.tar.gz -C /apusic/
cd /apusic/admq-manager-V2.0.6

# 配置 NameServer 地址
vi config/application.properties
1
2
3
4
5
6
# application.properties
server.port=12306
1
2
# 啟動管控台
bin/admq-service start

# 驗證狀態
bin/admq-service status
1
2
3
4
5

# 訪問管控台

地址：http://<管控台IP>:12305(https://<管控台IP>:12306)
預設帳號：admq / 11111111
1
2

# 初始化叢集

可以直接透過管控台快速部署叢集；對於已經部署的叢集，可以透過管控接入的方式接入管理

# 常見問題及排查

# NameServer 啟動失敗

可能原因 解決方案
連接埠衝突 檢查 9876 連接埠是否被佔用
JDK 未安裝 安裝 JDK 1.8+
許可權不足 確保 admq-rocketmq 目錄許可權正確

# Broker 啟動失敗

可能原因 解決方案
NameServer 不可達 檢查 namesrvAddr 配置和網路連通性
連接埠衝突 檢查 10911 連接埠是否被佔用
磁碟空間不足 檢查磁碟空間，確保滿足最低要求
配置錯誤 檢查 broker.conf 配置是否正確

# 管控台無法訪問

可能原因 解決方案
NameServer 不可達 檢查管控台到 NameServer 的網路連通性
連接埠衝突 修改 config/application.properties 中的 server.port
防火牆阻擋 開放 12305/12306 連接埠

# 訊息傳送失敗

可能原因 解決方案
Topic 未建立 使用 mqadmin 建立 Topic
Broker 不可達 檢查 Broker 狀態和網路連通性
許可權不足 檢查 ACL 配置
磁碟已滿 清理磁碟空間或調整訊息保留策略
编辑页面 (opens new window)
#安裝手冊

← 快速入門→