安裝手冊

# 前言

本文檔為金蝶Apusic分佈式消息隊列for MQTT（Apusic Distributed Message Queue，簡稱：ADMQ for MQTT）的安裝手冊，提供產品各種部署模式（含單機、集群）在各操作系統、容器環境的安裝部署過程指導以及相關配置說明。

# 適用對象

本文檔適用於IT信息化業務負責人、研發經理、軟件項目經理、軟件架構師、運維工程師。

# 相關文檔

瞭解更多ADMQ for MQTT產品相關的信息，請參閱以下ADMQ for MQTT產品手冊文檔集：

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

# 技術支持

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

  • 網址：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》，【快速入門】章節。

# 環境準備

# 系統要求

組件 最低要求 推薦配置
CPU 4 核 8 核及以上
內存 8 GB 16 GB 及以上
磁盤 100 GB SSD 500 GB 及以上 SSD
網絡 1 Gbps 10 Gbps
操作系統 Linux (CentOS 7+, Ubuntu 18.04+, 麒麟, 統信) -

# 依賴軟件

軟件 版本要求 說明
OpenSSL 1.1.1+ SSL/TLS 加密依賴
Java 1.8+ 管控臺運行依賴(已內置)

# 網絡要求

端口 用途 說明
1883 MQTT TCP 標準 MQTT 接入
8883 MQTT over SSL 加密 MQTT 接入
8083 MQTT over WebSocket WebSocket 接入
8084 MQTT over WSS 加密 WebSocket 接入
14567 MQTT over QUIC QUIC 協議接入
18083 MQTT Http API 管理後臺API
4370 集群節點間通信 集群節點間通信
5370 集群節點間通信（SSL） 集群節點間通信（SSL）

# 單機部署

# 安裝 ADMQ for MQTT

1.修改主機名稱

要求是 FQDN（完全限定域名）：如 mqtt.apusic.com

 # 查看主机名称 
 hostname  
 # 修改主机名 
 hostname mqtt.apusic.com
1
2
3
4

2.解壓安裝包

# 解压安装包
mkdir -p /apusic
tar zxvf ADMQ-V2.0.6.587-MQTT-20260617.tar.gz -C /apusic/
cd /apusic/admq-mqtt
1
2
3
4

3.修改節點名稱、監聽端口等信息（可選）

vi config/mqtt.conf
---
# 节点名称,name修改为完全限定域名
node {
  name = "emqx@mqtt.apusic.com"
  cookie = "mqttpnuvjvgg"
}

# MQTT TCP 监听
listeners.tcp.default {
  bind = "10.0.0.196:1883"
  max_connections = 1024000
}

# WebSocket 监听
listeners.ws.default {
  bind = "10.0.0.196:8083"
  max_connections = 1024000
}

# WebSocket over TLS 监听
listeners.wss.default {
  bind = "10.0.0.196:8084"
  max_connections = 512000
}
---
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

4.授權許可

將獲取到的 license.xml 文件上傳至部署目錄根路徑

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

5.啟動服務

bin/admq-daemon start mqtt server
1

6.服務驗證

  • 檢查進程狀態
ps -ef | grep admq-mqtt
1

image-20260702141411116

  • 檢查端口監聽

使用 netstat 確認 1883 端口是否處於 LISTEN 狀態：

ss -nltp | grep 1883
1

預期輸出：

image-20260702141553489

# 集群部署

# 集群架構說明

ADMQ for MQTT 支持以下集群模式：

集群模式 節點數 說明
普通集群 3+ 無狀態節點集群，支持水平擴展
高可用集群 3+ 多節點部署，自動故障轉移

# 集群部署步驟

1.各節點安裝ADMQ for MQTT

參考單機安裝步驟在各節點安裝ADMQ for MQTT，先不用啟動

提示：各節點的hostname需要設置不同的域名

2.配置各節點 hosts 文件

# /etc/hosts
192.168.1.101 mqtt1.apusic.com
192.168.1.102 mqtt2.apusic.com
192.168.1.103 mqtt3.apusic.com
1
2
3
4

3.配置各節點 Erlang Cookie

# 创建data目录
cd /apusic/admq-mqtt
mkdir -p data
# 设置 Erlang Cookie 
echo "mqttpnuvjvgg" > data/.erlang.cookie
1
2
3
4
5

4.配置各節點集群發現

以下是某一節點的配置示例

# 节点名称（每台不同，格式：emqx@IP或主机名）
node {
    name = "emqx@mqtt1.apusic.com"
    cookie = "mqttpnuvjvgg"   # 和上一步的Cookie保持一致
}

# 集群配置（所有节点完全一致）
cluster {
    discovery_strategy = static
    static {
        seeds = ["emqx@mqtt1.apusic.com", "emqx@mqtt2.apusic.com", "emqx@mqtt3.apusic.com"]
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13

5.啟動各節點服務

bin/admq-daemon start mqtt server
1

6.驗證集群狀態

bin/admq mqtt admin ctl cluster status
1

# 常見問題及排查

# 服務啟動失敗

可能原因 解決方案
端口衝突 檢查 1883、8883、8083、8084、18083 端口是否被佔用
權限不足 確保 admq-mqtt 目錄權限正確
內存不足 檢查系統內存，確保滿足最低要求

# 集群加入失敗

可能原因 解決方案
Erlang Cookie 不一致 確保所有節點的 .erlang.cookie 內容一致
網絡不通 檢查節點間網絡連通性和防火牆設置
主機名解析失敗 確保 /etc/hosts 或 DNS 配置正確

# 客戶端無法連接

可能原因 解決方案
監聽器未啟動 檢查監聽器管理頁面，確認監聽器已啟用
認證失敗 檢查用戶名密碼、認證器配置
ACL 權限不足 檢查 ACL 規則是否允許對應主題訪問
防火牆阻擋 開放 MQTT 相關端口
编辑页面 (opens new window)
#安裝手冊

← 快速入門→