快速入門

# 前言

本文檔為金蝶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. 出現異常及錯誤的日誌、截圖等詳細信息

# 快速入門

# 流程概覽

第1步：创建认证器与授权源
            │
            ↓
第2步：创建用户 ──┐
                  ├──→ 第4步：配置 ACL 权限
第3步：创建主题 ──┘            │
                               ↓
        第5步：发送测试消息验证通路 ──→ 第6步：接入业务代码
1
2
3
4
5
6
7
8

# 第1步：創建認證器與授權源

MQTT 用戶和 ACL 規則分別依賴認證器和授權源。首次使用 MQTT 集群時，需要先創建內置數據庫認證器和授權源。

  1. 進入 認證與授權 頁面（左側菜單：消息中間件 → ADMQ MQTT → 認證與授權）
  2. 在 認證器 標籤頁點擊 "新增" 按鈕
  3. 填寫：
    • 名稱：built_in_database
    • 認證方式：内置数据库
    • 描述：MQTT 内置数据库认证器
  4. 點擊 "確認"
  5. 切換到 授權源 標籤頁，點擊 "新增" 按鈕
  6. 填寫：
    • 名稱：built_in_database
    • 授權方式：内置数据库
    • 描述：MQTT 内置数据库授权源
  7. 點擊 "確認"

為什麼先做這一步？ 後續創建的用戶必須綁定到認證器，ACL 規則必須綁定到授權源；沒有認證器和授權源，用戶和權限頁面將無法選擇對應的來源。

# 第2步：創建用戶

為"設備上報系統"創建專用的 MQTT 用戶：

  1. 進入 用戶 頁面（左側菜單：消息中間件 → ADMQ MQTT → 用戶）
  2. 點擊 "新增" 按鈕
  3. 填寫：
    • 認證器：選擇已創建的 built_in_database 認證器
    • 用戶名：device-service
    • 密碼：設置一個安全密碼
    • 是否超級用戶：否
    • 描述：设备上报系统服务账号
  4. 點擊 "確認"

普通業務賬號建議不開啟超級用戶。超級用戶會繞過所有 ACL 檢查。

# 第3步：創建主題

主題是 MQTT 中消息的分類單元。為設備上報創建主題：

  1. 進入 主題 頁面（左側菜單：消息中間件 → ADMQ MQTT → 主題）
  2. 點擊 "新增" 按鈕
  3. 填寫：
    • Topic：sensor/+/temperature
    • 默認 QoS：1
    • 是否保留消息：否
    • 描述：设备温度上报主题
  4. 點擊 "確認"

主題通配符說明：+ 匹配單個層級，因此 sensor/+/temperature 可以匹配 sensor/living-room/temperature，但不能匹配 sensor/living-room/bedroom/temperature（後者需用 #）。

# 第4步：配置 ACL 權限

為用戶分配發布/訂閱主題的權限：

  1. 進入 權限 頁面（左側菜單：消息中間件 → ADMQ MQTT → 權限）
  2. 確保頂部已選擇 built_in_database 授權源
  3. 點擊 "新增" 按鈕
  4. 填寫：
    • 主體類型：用户名
    • 用戶名：device-service
    • 權限：允许
    • 動作：全部（允許發佈和訂閱）
    • 主題：sensor/#
    • QoS：-1（不限制）
    • Retain：-1（不限制）
    • 描述：设备服务可读写 sensor 下所有主题
  5. 點擊 "確認"

生效說明：ACL 規則保存後會自動生效，無需再點擊"同步到 MQTT"。

# 第5步：發送測試消息驗證通路

在接入業務代碼前，先用平臺內置的發送功能驗證消息通路是否正常：

  1. 進入 主題 頁面
  2. 在 sensor/+/temperature 行點擊 "發送消息"
  3. 填寫：
    • Payload：{"deviceId":"D001","temperature":24.5}
    • QoS：1
    • Retain：否
  4. 點擊 "確認發送"
  5. 進入 保留消息 頁面（若 Retain 為否則不會在此出現），或進入 客戶端 頁面查看是否有測試客戶端在線

驗證通過的標誌：消息發送成功且無權限拒絕提示，說明用戶認證和 ACL 配置已生效。

# 第6步：接入業務代碼

平臺側的資源已準備就緒，接下來在您的應用程序中接入 MQTT 客戶端：

連接參數：

參數 值 獲取方式
Broker 地址 集群節點 IP 管理員提供
端口 1883（TCP） 監聽器管理頁面查看
用戶名 device-service 第2步創建
密碼 您設置的密碼 第2步設置
ClientID 業務自定義 保證全局唯一

生產者示例（Java + Eclipse Paho）：

import org.eclipse.paho.client.mqttv3.MqttClient;
import org.eclipse.paho.client.mqttv3.MqttMessage;

MqttClient client = new MqttClient("tcp://localhost:1883", "publisher-001");
org.eclipse.paho.client.mqttv3.MqttConnectOptions options = new org.eclipse.paho.client.mqttv3.MqttConnectOptions();
options.setUserName("device-service");
options.setPassword("your-password".toCharArray());
client.connect(options);

MqttMessage message = new MqttMessage("{\"deviceId\":\"D001\",\"temperature\":24.5}".getBytes());
message.setQos(1);
client.publish("sensor/D001/temperature", message);

client.disconnect();
client.close();
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

消費者示例（Java + Eclipse Paho）：

MqttClient client = new MqttClient("tcp://localhost:1883", "subscriber-001");
org.eclipse.paho.client.mqttv3.MqttConnectOptions options = new org.eclipse.paho.client.mqttv3.MqttConnectOptions();
options.setUserName("device-service");
options.setPassword("your-password".toCharArray());
client.connect(options);

client.subscribe("sensor/+/temperature", 1);
client.setCallback(new org.eclipse.paho.client.mqttv3.MqttCallback() {
    public void messageArrived(String topic, MqttMessage message) {
        System.out.println("收到消息: " + topic + " -> " + new String(message.getPayload()));
    }
    public void connectionLost(Throwable cause) {}
    public void deliveryComplete(org.eclipse.paho.client.mqttv3.IMqttDeliveryToken token) {}
});
1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 後續運維操作

業務接入後，日常可通過以下功能進行運維管理：

運維場景 操作路徑 說明
查看在線客戶端 客戶端管理 查看客戶端 ID、用戶名、IP、連接時間
強制下線異常客戶端 客戶端行 → "斷開連接" 立即斷開指定連接
查看消息堆積 Topic 監控 / 監控大盤 關注流入/流出/丟棄數量
排查消費延遲 慢訂閱管理 查看消息投遞耗時較長的訂閱
處理保留消息 保留消息管理 查看或刪除不再需要的保留消息
查看系統告警 監控與統計 → 告警 查看 CPU/內存/連接數異常等告警
調整認證授權 認證與授權 修改認證器、授權源、ACL 規則

# 小結

完成上述 6 步後，您已經：

  • ✅ 創建了 MQTT 內置數據庫認證器和授權源
  • ✅ 創建了專用的 MQTT 業務用戶
  • ✅ 創建了設備上報主題
  • ✅ 配置了細粒度的 ACL 訪問控制
  • ✅ 驗證了消息通路的正確性
  • ✅ 將配置參數接入到業務代碼中

這是使用 MQTT 的最小可用閉環。後續可根據業務需要，在此基礎上擴展更多主題、用戶、ACL 規則，或配置監聽器、系統參數實現更豐富的功能。

各功能的詳細說明請參閱同目錄下的其他文檔。

编辑页面 (opens new window)
#快速使用手冊

← 管控台使用者手冊→