管控台使用者手冊

# 前言

本文檔為金蝶Apusic分佈式消息隊列for MQTT（Apusic Distributed Message Queue，簡稱：ADMQ for MQTT）管控臺產品的用戶手冊，詳細介紹 ADMQ for MQTT產品Web管控臺的功能使用、配置方法及管理操作等內容。

# 適用對象

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

# 術語說明

術語 說明
Cluster MQTT 集群，由多個 MQTT 節點組成
Node MQTT 集群中的單個服務節點
Client MQTT 客戶端，包括髮布者和訂閱者
ClientID MQTT 客戶端唯一標識
Topic 主題，消息的分類標識
QoS 服務質量等級，定義消息傳遞的可靠性
Retain 保留消息標誌
Will 遺囑消息
Clean Session 是否清除會話
ACL 訪問控制列表
Authenticator 認證器
Authorization Source 授權源

# 管理面入口

# 訪問地址

在瀏覽器地址欄輸入以下 URL 進入 ADMQ 管控臺登錄頁面：

http://{console_ip}:12305
1

其中 {console_ip} 為管控臺服務器 IP 地址。

image-20260701182155357

# 核心概念

在使用 ADMQ MQTT 之前，建議先理解以下幾個核心概念：

# 主題（Topic）

主題是 MQTT 中消息的邏輯分類單元，生產者向主題發佈消息，消費者訂閱主題接收消息。

  • 主題使用 / 分隔層級，例如 sensor/living-room/temperature。
  • 支持兩種通配符：
    • +：匹配單個層級，例如 sensor/+/temperature。
    • #：匹配零個或多個層級，必須位於主題末尾，例如 sensor/#。

# QoS（服務質量等級）

QoS 定義了消息傳遞的可靠性等級。

QoS 等級 名稱 說明 典型場景
0 最多一次 消息只發一次，不保證到達 高頻、可容忍丟失的Telemetry數據
1 至少一次 消息保證到達，可能重複 一般業務消息
2 恰好一次 消息保證到達且不重複 對一致性要求極高的場景

# 保留消息（Retained Message）

保留消息是 MQTT 的一項特殊機制：

  • 發佈者發送保留消息時，Broker 會為該主題保留最後一條保留消息。
  • 新的訂閱者訂閱該主題時，會立即收到這條保留消息。
  • 常用於設備狀態、配置下發等場景。
  • 發送一條空的保留消息可以清除該主題的保留消息。

# 清除會話（Clean Session）與會話保持

  • 清除會話為 true：客戶端斷開連接後，Broker 不保存其訂閱關係和未確認消息。
  • 清除會話為 false：Broker 保存訂閱關係、未確認消息和 QoS 1/2 的離線消息，客戶端重連後可恢復。
  • MQTT 5.0 中對應概念為 Clean Start 和 Session Expiry Interval。

# 遺囑消息（Will Message）

遺囑消息在客戶端異常斷開連接時由 Broker 自動發佈：

  • 客戶端連接時預設遺囑主題、遺囑內容、QoS、Retain。
  • 當連接異常斷開且未發送 DISCONNECT 時，Broker 自動發佈遺囑消息。
  • 常用於設備上下線狀態通知。

# ACL（訪問控制列表）

ACL 用於控制客戶端對 MQTT 資源的訪問權限：

  • 主體：全部、用戶名、客戶端 ID。
  • 動作：發佈（publish）、訂閱（subscribe）、全部（all）。
  • 權限：允許（allow）、拒絕（deny）。
  • 主題：支持通配符。
  • QoS/Retain 限制：可進一步限制允許的 QoS 等級和 Retain 行為。

# 認證器（Authenticator）

認證器定義了客戶端連接時如何驗證身份：

  • Password-Based：基於用戶名密碼認證，數據源可以是內置數據庫、MySQL、PostgreSQL、HTTP 等。
  • JWT：基於 JSON Web Token 認證。
  • SCRAM：基於 SCRAM 挑戰響應機制。

# 授權源（Authorization Source）

授權源定義了 ACL 規則的數據來源：

  • built_in_database：內置數據庫，支持在平臺上直接管理規則。
  • file：通過 acl.conf 文件配置。
  • HTTP/MySQL/PostgreSQL 等：外部數據源。
  • 多個授權源按排序優先級依次匹配。

# 消息流轉示意圖

发布者 ──→ MQTT Broker
              ├── 主题匹配 ──→ 订阅者 A（QoS 0）
              ├── 主题匹配 ──→ 订阅者 B（QoS 1）
              └── 保留消息存储 ──→ 新订阅者立即收到
1
2
3
4

# 概覽

對應菜單：概覽 → 概覽

概覽頁面是進入某個 MQTT 集群后的首頁，用於快速瞭解集群的資源規模與連接狀態。

概覽頁面由兩部分組成：

  1. 資源概覽：以統計卡片形式展示當前集群的關鍵資源指標（如連接數、主題數、訂閱數、保留消息數等，具體項以集群返回為準）。
  2. 連接信息：以表格形式展示集群的連接端點及在線狀態。

頁面右上角提供 刷新 按鈕，用於手動拉取最新數據。

# 資源概覽

資源概覽區展示當前集群的核心資源統計值，用於快速評估集群負載與規模。指標隨集群實際返回動態渲染，常見包括：

  • 在線連接數
  • 主題（Topic）數量
  • 訂閱數量
  • 保留消息數量

數值為拉取時刻的快照，點擊右上角 刷新 可更新。

# 連接信息

連接信息表展示當前集群對外提供服務的接入點，字段如下：

列 說明
集群名稱 集群的名稱
集群類型 集群的中間件類型（MQTT / EMQX）
連接地址 集群的接入地址，多個地址分行展示
連接狀態 在线 / 离线 徽標，反映平臺與集群的連通性
功能 該接入點的用途說明

連接地址 即業務客戶端接入 Broker 時使用的地址，可結合 系統配置 → 監聽器 中的端口信息一起使用。

# 常見用途

  • 每日巡檢時快速確認集群是否在線、資源規模是否異常。
  • 為業務方提供接入地址。
  • 作為進入其他功能模塊前的整體狀態參考。

# 用戶與權限

對應菜單：用戶與權限

本章涵蓋用戶、權限、黑名單相關的三個功能：用戶管理、權限管理（ACL）、黑名單管理。

# 用戶管理

對應菜單：用戶與權限 → 用戶管理

管理存儲在內置數據庫認證器中的 MQTT 用戶，支持新增、編輯、刪除，並可同步到 MQTT 集群。

# 前置條件

用戶依賴內置數據庫認證器。若尚未創建，頁面會顯示提示"暫無可用的 built-in database 認證器，請先去【認證器管理】創建"，並提供 前往認證器管理 按鈕。請先在 系統配置 → 認證器管理 創建 Built-in Database 認證器。

# 頂部篩選

  • 認證器：下拉選擇目標 built_in_database 認證器（可搜索）。所有用戶操作均作用於所選認證器。
  • 搜索用戶名：按用戶名模糊搜索。

# 用戶列表

列 說明
用戶名 客戶端登錄用的用戶名
是否超級用戶 是（紅色標籤）/ 否
描述 備註信息
創建時間 用戶創建時間
操作 編輯 / 刪除

# 操作說明

工具欄

  • 新增：打開新增抽屜創建用戶。
  • 同步到 MQTT：打開"用戶同步預覽"，展示將要新增、刪除、更新的用戶（列：用戶名、是否超級用戶），確認後推送到集群。

新增 / 編輯用戶（抽屜）

字段 類型 必填 說明
所屬認證器 只讀 — 顯示當前認證器
用戶名 文本 是 編輯時不可修改
密碼 密碼 新增必填 編輯時留空表示不修改
是否超級用戶 單選 — 是 / 否，默認否
描述 多行文本 否 最長 4096 字符

提示：普通業務賬號建議不開啟超級用戶。超級用戶會繞過所有 ACL 檢查。新增或修改用戶後，需點擊 同步到 MQTT 才會在集群上生效。

# 權限管理（ACL）

對應菜單：用戶與權限 → 權限管理

管理內置數據庫授權源中的 ACL 規則，控制客戶端對主題的發佈/訂閱權限。支持按用戶名、客戶端 ID 或全局配置規則。

# 前置條件

ACL 規則依賴內置數據庫授權源。若尚未創建，頁面會提示"暫無可用的 built-in database 授權源，請先去【授權源管理】創建"，並提供 前往授權源管理 按鈕。請先在 系統配置 → 授權源管理 創建 Built-in Database 授權源。

# 頂部篩選與標籤頁

  • 授權源：下拉選擇目標 built_in_database 授權源（可搜索）。
  • 權限：允许 / 拒绝。
  • 動作：发布 / 订阅 / 全部。
  • 用戶名 / 客戶端ID：按主體過濾（標籤不同隨標籤頁變化）。
  • 標籤頁：全部规则 / 用户名规则 / 客户端ID规则。切換標籤會重置分頁、篩選與選擇。

# 規則列表

不同標籤頁列略有差異：

列 說明
用戶名 / 客戶端ID 僅在對應標籤頁顯示
權限 允许（綠）/ 拒绝（紅）
動作 發佈 / 訂閱 / 全部
主題 規則匹配的主題（支持通配符）
QoS 允許的 QoS，不限制 表示不限制
Retain 允许 / 禁止 / 不限制
創建時間 規則創建時間
描述 備註
操作 編輯 / 刪除

# 操作說明

工具欄

  • 新增：打開新增抽屜。
  • 同步到 MQTT：將 ACL 規則推送到集群生效。
  • 批量刪除（N）：勾選多行後出現，批量刪除所選規則。

新增 / 編輯規則（抽屜，標題隨主體類型變化）

字段 類型 必填 說明
所屬授權源 只讀 — 顯示當前授權源
用戶名 文本 是 僅"用戶名規則"時顯示
客戶端 ID 文本 是 僅"客戶端ID規則"時顯示
權限 下拉 是 允許 / 拒絕
動作 下拉 是 發佈 / 訂閱 / 全部
主題 文本 是 例如 sensor/# 或 +/+/temp
QoS 限制 數字 否 -1~2，-1 表示不限制
Retain 限制 數字 否 -1 不限制、0 禁止、1 允許
描述 多行文本 否 最長 4096 字符

提示：規則新增或修改後需點擊 同步到 MQTT 生效。若已配置規則仍被拒絕，可在 客戶端管理 → 詳情 中點擊"清除授權緩存"強制刷新。

# 黑名單管理

對應菜單：用戶與權限 → 黑名單管理

對客戶端 ID、用戶名、IP 地址等維度進行封禁，支持精確匹配、正則/CIDR 規則匹配，並可設置過期時間。黑名單直接作用於集群，無需選擇認證器/授權源。

# 頂部篩選

  • 類型：客戶端 ID / 用戶名 / IP 地址 / 客戶端 ID 規則 / 用戶名規則 / IP 範圍。
  • 封禁值：按封禁值搜索。

# 黑名單列表

列 說明
類型 封禁維度（不同類型不同顏色標籤）
封禁值 被封禁的具體值或規則
過期時間 到期時間；無則顯示 永久；已過期顯示紅色"（已過期）"
原因 封禁原因，空則顯示 -
創建時間 封禁創建時間
操作 編輯 / 刪除

# 操作說明

工具欄

  • 新增：打開新增抽屜。
  • 同步：打開"黑名單同步預覽"，展示將要新增/刪除的條目（列：類型、封禁值、原因），確認後同步到集群。

新增 / 編輯封禁（抽屜）

字段 類型 必填 說明
類型 下拉 是 客戶端 ID / 用戶名 / IP 地址 / 客戶端 ID 規則 / 用戶名規則 / IP 範圍
封禁值 文本 是 佔位提示隨類型變化（見下）
過期時間 日期時間 否 留空表示永久
原因 多行文本 否 封禁原因

封禁值格式與校驗

類型 輸入示例 校驗
客戶端 ID 具體客戶端 ID —
用戶名 具體用戶名 —
IP 地址 192.168.1.1 必須為合法 IPv4/IPv6
客戶端 ID 規則 / 用戶名規則 正則表達式 必須為合法正則
IP 範圍 192.168.1.0/24 必須為合法 CIDR

提示：新增或修改後需點擊 同步 使封禁在集群生效。已過期條目在列表中以紅色標註，可手動刪除。

# 資源管理

對應菜單：資源管理

本章涵蓋 Topic 管理、訂閱管理、消息管理、客戶端管理四個功能。

# Topic 管理

對應菜單：資源管理 → Topic 管理

管理集群主題，展示各主題的 QoS、Retain、來源、狀態與所在節點。支持手動創建、編輯、刪除，以及單條/批量發送消息。

# 頂部篩選

  • 搜索 Topic：按主題名模糊搜索。

# Topic 列表

列 說明
Topic 主題名
QoS 默認 QoS
Retain 是否保留消息
來源 主題來源
狀態 主題狀態
所在節點 主題所在的集群節點
描述 備註
創建時間 創建時間
操作 發送消息 / 編輯 / 刪除

# 操作說明

工具欄

  • 新增：創建主題。
  • 同步：預覽與集群的差異（新增/刪除/更新）並同步。
  • 批量發佈：一次向多個主題發佈消息。

新增 / 編輯 Topic（抽屜）

字段 類型 必填 說明
Topic 文本 是 編輯時不可修改
默認 QoS 數字 — 0~2，僅新增時可填，默認 0
是否保留消息 單選 — 是 / 否，僅新增時可填，默認否
描述 多行文本 否 最長 4096 字符

發送消息（行內"發送消息"抽屜）

字段 類型 必填 說明
Topic 文本（只讀） — 當前行主題
消息內容 文本 是 消息 Payload
QoS 單選 — 0 / 1 / 2
保留消息 單選 — 是 / 否

批量發佈（工具欄"批量發佈"抽屜）

以可編輯表格逐行填寫待發送消息，列包括 Topic、Payload、QoS、Retain。提供 添加消息 增行、確認發佈 提交；僅剩一行時不可刪除。

# 訂閱管理

對應菜單：資源管理 → 訂閱管理

管理客戶端訂閱關係，按客戶端 ID 與主題展示 QoS、來源、狀態、所在節點。支持手動添加與刪除訂閱。

# 頂部篩選

  • 搜索客戶端ID：按客戶端 ID 模糊搜索。
  • 搜索 Topic：按主題模糊搜索。

# 訂閱列表

列 說明
客戶端ID 點擊可跳轉到客戶端管理並定位該客戶端
Topic 訂閱的主題
QoS 訂閱 QoS
來源 訂閱來源
狀態 訂閱狀態
所在節點 訂閱所在節點
操作 刪除

# 操作說明

工具欄

  • 新增：手動添加訂閱。
  • 同步：打開"訂閱同步預覽"，展示新增/更新/刪除差異，確認後同步。

手動添加訂閱（抽屜）

字段 類型 必填 說明
客戶端 ID 文本 是 目標客戶端
Topic 文本 是 訂閱主題
QoS 下拉 是 QoS 0 / 1 / 2
描述 多行文本 否 備註

刪除提示：若該訂閱在集群上仍存在，刪除時將同時取消客戶端的該條訂閱。

# 消息管理

對應菜單：資源管理 → 消息管理

消息管理是一個容器頁，包含三個標籤頁：保留消息、主題重寫、自動訂閱。

# 保留消息

標籤頁：消息管理 → 保留消息

展示 Broker 上存儲的保留消息，可查看解碼後的內容並刪除。

頂部篩選：搜索 Topic。

列表

列 說明
Topic 主題名
客戶端 ID 發佈該保留消息的客戶端
QoS 消息 QoS
Retain 保留標誌
操作 查看內容 / 刪除
  • 查看內容：拉取保留消息詳情並解碼 Payload，在彈窗（標題"保留消息內容 - {topic}"）中展示，支持複製。
  • 刪除：刪除該保留消息。發送一條空的保留消息也可清除。

# 主題重寫

標籤頁：消息管理 → 主題重寫

管理主題重寫規則，在訂閱/發佈/全部動作時對主題進行重定向或轉換。

頂部篩選：動作類型（訂閱 / 發佈 / 全部）、源主題 / 目標主題搜索。

列表

列 說明
動作 訂閱 / 發佈 / 全部
源主題 匹配的源主題
目標主題 重寫後的目標主題
正則表達式 匹配用正則
排序 規則匹配順序
操作 編輯 / 刪除

工具欄：新增、同步到 MQTT。

新增 / 編輯規則（抽屜）

字段 類型 必填 說明
動作 下拉 是 訂閱 / 發佈 / 全部
源主題 文本 是 源主題
目標主題 文本 是 目標主題
正則表達式 文本 是 匹配正則
排序 數字 否 ≥0，值越小越先匹配

# 自動訂閱

標籤頁：消息管理 → 自動訂閱

管理自動訂閱規則，客戶端連接後自動訂閱指定主題。

頂部篩選：QoS（0 / 1 / 2）、主題搜索。

列表

列 說明
主題 自動訂閱的主題
QoS 訂閱 QoS
No Local 是否不接收自己發佈的消息
Retain As Published 是否保留髮布時的 Retain 標誌
Retain Handling 保留消息處理策略
排序 匹配順序
操作 編輯 / 刪除

工具欄：新增、同步到 MQTT。

新增 / 編輯規則（抽屜）

字段 類型 必填 說明
主題 文本 是 自動訂閱主題
QoS 下拉 是 QoS 0 / 1 / 2
No Local 下拉 是 否(0) / 是(1)
Retain As Published 下拉 是 否(0) / 是(1)
Retain Handling 下拉 是 0-發送保留消息 / 1-不發送保留消息 / 2-不發送且後續不接收
排序 數字 否 ≥0

# 客戶端管理

對應菜單：資源管理 → 客戶端管理

管理在線的 MQTT 客戶端連接，展示客戶端 ID、用戶名、IP、連接時間、Keepalive、清除會話與協議。支持單個/批量斷開連接，以及查看連接詳情。

# 頂部篩選

  • 搜索客戶端ID：按客戶端 ID 搜索。
  • 搜索用戶名：按用戶名搜索。

# 客戶端列表

列 說明
客戶端ID 客戶端標識
用戶名 登錄用戶名
IP 地址 客戶端 IP（含端口時顯示為 IP:port）
連接時間 建連時間
Keepalive 心跳保活間隔
清除會話 Clean Session / Clean Start
協議 協議名與版本
操作 詳情 / 斷開

# 操作說明

工具欄

  • 批量斷開（N）：勾選多行後可用，批量斷開所選連接。

行內操作

  • 詳情：打開連接詳情抽屜（見下）。
  • 斷開：斷開該連接。

# 連接詳情

點擊"詳情"打開抽屜（標題"連接詳情 - {clientId}"），含四個標籤頁：

  • 連接詳情：只讀展示客戶端 ID、用戶名、IP、連接時間、Keepalive、清除會話、協議等；提供 清除授權緩存 按鈕（強制刷新該客戶端的授權緩存）。
  • 訂閱管理：客戶端當前訂閱列表（列：Topic、QoS、NL、RAP、RH、操作）。提供 添加訂閱（Topic、QoS、No Local、Retain As Published、Retain Handling），行內可 取消訂閱。
  • 飛行中消息：正在投遞中的消息（列：ID、Topic、QoS、Payload、發送時間），支持"加載更多"。
  • 消息隊列：排隊待投遞的消息（列：ID、Topic、QoS、Payload、發送時間），支持"加載更多"。

# 監控運維

對應菜單：監控運維

本章涵蓋監控大盤、資源監控、日誌告警三個功能。

# 監控大盤

對應菜單：監控運維 → 監控大盤

集群整體的指標監控看板，按維度以圖表形式展示指標趨勢。

  • 時間範圍：頂部時間選擇器，默認展示最近 1 小時，可自定義範圍（自動選擇分鐘/小時/天粒度）。
  • 維度標籤頁：標籤由後端配置動態生成（如集群、節點、客戶端等維度）。部分維度需要先選擇變量（下拉篩選）後展示對應圖表。
  • 無配置時展示空狀態；加載時展示骨架屏。

監控大盤的具體維度與圖表由集群監控配置決定，界面以實際返回為準。

# 資源監控

對應菜單：監控運維 → 資源監控

資源監控是一個容器頁，包含三個標籤頁：Topic 監控、節點監控、慢訂閱。

# Topic 監控

標籤頁：資源監控 → Topic 監控

監控指定主題的消息流量指標。

列表

列 說明
Topic 被監控的主題
流入消息 流入該主題的消息數
流出消息 從該主題流出的消息數
丟棄消息 丟棄數（大於 0 時紅色顯示）
操作 停止監控

工具欄：刷新、新增。

  • 新增：彈窗"添加監控 Topic"，輸入 Topic 名稱添加監控。提示：MQTT 默認最多支持 100 個 Topic Metrics，建議只監控關鍵業務主題。
  • 停止監控：移除對該主題的監控。

# 節點監控

標籤頁：資源監控 → 節點監控

展示集群各節點的運行狀態。

工具欄：刷新。

列表

列 說明
節點 節點名
狀態 运行中（綠）或異常狀態（紅）
版本 節點版本
運行時長 已運行時間
連接數 當前連接數
內存使用 內存佔用
角色 節點角色
操作 查看詳情

節點詳情（抽屜，標題"節點詳情 - {節點名}"）含三個標籤頁：

  • 節點詳情：以描述列表展示節點、狀態、角色、版本、系統描述、OTP 版本、運行時長、連接數、活躍連接數、可用/已用進程、1/5/15 分鐘負載、最大文件描述符、總/已用內存等。
  • 指標：指標名稱 / 數值。
  • 統計：統計名稱 / 數值。

# 慢訂閱

標籤頁：資源監控 → 慢訂閱

列出投遞耗時較長的慢訂閱記錄，並可配置檢測閾值。

頂部篩選：搜索客戶端ID。

工具欄

  • 清除全部記錄：確認後清空所有慢訂閱記錄。
  • 設置：打開慢訂閱設置抽屜。

列表

列 說明
客戶端ID 客戶端標識
Topic 訂閱主題
所在節點 記錄所在節點
耗時 (ms) 投遞耗時（毫秒）
創建時間 記錄時間

慢訂閱設置（抽屜）

字段 類型 必填 說明
啟用慢訂閱 開關 — 是否開啟檢測
Top K 數量 數字 是 1~1000
統計類型 下拉 是 whole / internal / response
閾值 文本 是 如 500ms、5s、1m
過期間隔 文本 是 如 300s

開啟後，當消息從 Broker 投遞到訂閱者的耗時超過閾值時，將產生慢訂閱記錄。

# 日誌告警

對應菜單：監控運維 → 日誌告警

日誌告警是一個容器頁，包含兩個標籤頁：日誌追蹤、告警。

# 日誌追蹤

標籤頁：日誌告警 → 日誌追蹤

創建並管理集群的追蹤任務（按客戶端、主題或 IP 追蹤日誌），查看並下載日誌。

頂部篩選：搜索任務名稱。

工具欄：新增。

列表

列 說明
名稱 任務名
類型 客戶端 / 主題 / IP地址
目標 追蹤目標值
開始時間 追蹤開始時間
結束時間 追蹤結束時間
內容編碼 默認 text
狀態 运行中（綠）/ 已停止 / 等待中（藍）
操作 查看日誌 / 停止（運行中）/ 刪除（非運行中）

新增追蹤任務（抽屜）

字段 類型 必填 說明
任務名稱 文本 是 任務名
追蹤類型 下拉 是 客戶端 / 主題 / IP 地址
目標值 文本 是 標籤隨類型變化（客戶端 ID / 主題 / IP 地址）
時間範圍 日期時間範圍 — 默認從當前到 30 分鐘後
日誌格式 下拉 — 文本 / JSON
內容編碼 下拉 — Text / Hex / Hidden

查看日誌（抽屜，標題"日誌內容 - {name}"）：只讀文本區展示日誌，支持 複製、下載（以 .zip 下載）。

# 告警

標籤頁：日誌告警 → 告警

展示集群的激活中與已解除告警。

頂部篩選：搜索告警名稱。

工具欄：清除全部告警（確認後清空所有告警）。

列表

列 說明
節點 觸發告警的節點
告警名稱 告警名
告警信息 告警詳情（可展開查看）
激活時間 告警激活時間
狀態 激活中（紅）/ 已解除

# 系統配置

對應菜單：系統配置

本章涵蓋認證器管理、授權源管理、監聽器、系統配置、數據備份五個功能。

# 認證器管理

對應菜單：系統配置 → 認證器管理

管理 MQTT 客戶端認證鏈，支持多種認證機制與數據源。認證器可排序、啟用/禁用，並同步到集群。

# 頂部篩選

  • 認證方式：Password Based / JWT / SCRAM。
  • 數據源：隨認證方式動態變化（內置數據庫、MySQL、PostgreSQL、Redis、HTTP、Static JWT、JWKS Endpoint 等）。
  • 查詢按鈕。

# 列表

列 說明
認證器 ID 認證器標識
認證方式 Password Based / JWT / SCRAM
數據源 後端數據源類型
用戶數量 該認證器下的用戶數
啟用 啟用/禁用開關
排序 認證鏈匹配順序
創建時間 創建時間
操作 查看 / 編輯 / 上移 / 下移 / 刪除

# 新增認證器（三步向導，整頁）

認證器的新增/編輯是整頁嚮導，非抽屜：

  1. 選擇認證方式：Password Based（用戶名/密碼）、JWT（Token）、SCRAM（挑戰響應）。
  2. 選擇數據源：
    • Password Based：Built-in Database、MySQL、PostgreSQL、Redis、HTTP
    • JWT：Static JWT、JWKS Endpoint
    • SCRAM：Built-in Database
  3. 填寫配置（隨組合不同）：

Password Based + Built-in Database：賬號類型（username/clientid）、密碼加密方式（plain/md5/sha/sha256/sha512/bcrypt/pbkdf2）、加鹽方式（prefix/suffix/disable）。

Password Based + MySQL/PostgreSQL：服務器地址、數據庫、用戶名、密碼、密碼加密方式、加鹽方式、啟用 TLS、SQL。

Password Based + Redis：部署模式（single/sentinel/cluster）、服務器地址、Sentinel 主節點名稱（sentinel 時）、數據庫、密碼、密碼加密方式、加鹽方式、啟用 TLS、命令。

Password Based + HTTP：請求方式（GET/POST）、URL、請求頭、啟用 TLS、請求體（POST 時）。

JWT（Static）：JWT 來自於（password/username）、加密方式（HMAC / 公鑰）、密鑰或公鑰、密鑰 Base64 編碼、過期後斷開連接、Payload 校驗。

JWT + JWKS Endpoint：JWT 來自於、JWKS Endpoint、刷新間隔、請求頭、啟用 TLS、過期後斷開連接、Payload。

SCRAM + Built-in Database：Algorithm（sha256/sha512）、Iteration Count（默認 4096）。

# 其他操作

  • 啟用/禁用：列表內開關切換。
  • 上移/下移：調整認證鏈順序（邊界時按鈕禁用）。
  • 同步到 MQTT：推送認證器配置到集群。
  • 查看：抽屜展示 JSON 配置。
  • 證書文件：TLS 相關字段可選擇 .crt/.key/.pem/.txt 文件上傳。

# 授權源管理

對應菜單：系統配置 → 授權源管理

管理 MQTT 授權/ACL 數據源，通過多種後端控制訪問權限。File 類型支持直接編輯 ACL 文件。

# 頂部篩選

  • 授權源類型：Built-in Database / File / HTTP / MySQL / PostgreSQL / Redis。
  • 查詢按鈕。

# 列表

列 說明
授權源類型 後端類型
啟用 啟用/禁用開關
權限規則數量 該源下規則數
排序 匹配順序
創建時間 創建時間
操作 查看 / 編輯 / 管理 acl.conf（File 類型）/ 上移 / 下移 / 刪除

# 新增授權源（兩步向導，整頁）

  1. 選擇授權源類型：Built-in Database、File、HTTP、MySQL、PostgreSQL、Redis。
  2. 填寫配置（隨類型不同）：
    • Built-in Database：最大規則數（默認 100）。
    • File：ACL 規則內容（支持上傳 .conf/.txt）。
    • HTTP：請求方式（GET/POST）、URL、請求頭、啟用 TLS、請求體（POST 時）。
    • MySQL/PostgreSQL：服務器地址、數據庫、用戶名、密碼、自動重連、啟用 TLS、SQL。
    • Redis：Redis 類型（single/sentinel/cluster）、服務器地址、數據庫、密碼、自動重連、啟用 TLS、命令。

# 其他操作

  • 啟用/禁用、上移/下移、同步到 MQTT、查看（JSON）與認證器一致。
  • 管理 acl.conf（僅 File 類型）：打開抽屜，直接編輯 ACL 文件內容。

提示：內置數據庫授權源的具體 ACL 規則在 用戶與權限 → 權限管理 中維護。

# 監聽器

對應菜單：系統配置 → 監聽器

管理 MQTT Broker 的網絡監聽器，支持 TCP、SSL、WS、WSS 協議。

# 列表

列 說明
監聽器 ID 由「類型:名稱」組成，如 tcp:default
類型 TCP / SSL / WS / WSS
綁定地址 監聽地址與端口
啟用 啟用狀態
運行狀態 運行狀態
連接數 當前連接數
操作 查看 / 編輯 / 啟動 / 停止 / 重啟 / 刪除

# 新增 / 編輯監聽器

基本配置（所有類型）：

字段 說明
監聽器類型 TCP / SSL / WS / WSS，創建後鎖定
名稱 與類型組成監聽器 ID，創建後鎖定
綁定地址 如 0.0.0.0:1883 或 :1883
接受器數量 Acceptor 數量
最大連接數 支持"無限制"
掛載點 Mount point

按類型附加的標籤頁：

類型 標籤頁
TCP 代理與限流、TCP 選項
SSL 代理與限流、TCP 選項、TLS 證書、TLS 高級
WS 代理與限流、TCP 選項、WebSocket、壓縮
WSS 代理與限流、TCP 選項、TLS 證書、TLS 高級、WebSocket、壓縮

各標籤頁要點：

  • 代理與限流：代理協議開關與超時、監聽器最大連接速率、單客戶端最大發布速率/流量。
  • TCP 選項：ActiveN、Backlog、Buffer、High Watermark、發送超時、Keepalive、TCP_NODELAY、SO_REUSEADDR 等。
  • TLS 證書：TLS Cert、TLS Key、CA Cert（均支持文件上傳）。
  • TLS 高級：TLS 版本、加密套件、握手參數、OCSP Stapling 等。
  • WebSocket：路徑、空閒超時、最大幀大小、MQTT 捎帶模式、Origin 檢查與跨域、代理頭、子協議等。
  • 壓縮：上下文接管、窗口位數、內存級別、壓縮策略。

# 其他操作

  • 啟動 / 停止 / 重啟：均有二次確認。
  • 查看：以只讀方式打開抽屜，僅提供"關閉"。

# 系統配置

對應菜單：系統配置 → 系統配置

以標籤頁形式管理 Broker 各項系統配置。每個標籤頁對應一個配置分區，支持保存、重置與 JSON 預覽。

# 配置分區（標籤頁）

標籤頁 說明 關鍵配置項
告警（alarm） 告警設置 告警動作（log/publish）、歷史告警最大存儲數、告警有效期
Broker Broker 設置 全局會話註冊表、會話歷史保留時間
Dashboard 控制台設置 跨域支持、Swagger 支持、Token 過期時間、默認密碼、HTTP/HTTPS 監聽
日誌（log） 日誌設置 Console / File 日誌（啟用、級別、路徑、輪轉、格式化）、限流時間窗口
全局 Zone（global_zone） MQTT 全局行為 Keepalive、最大報文大小、會話過期、最大 QoS、Inflight、通配符/共享訂閱、持久會話、抖動檢測、強制 GC 等
系統主題（sys_topics） 系統主題事件 連接/斷開/訂閱/取消訂閱事件、心跳間隔、消息間隔
系統監控（sysmon） 系統監控閾值 Broker/OS/VM 各項水位線與檢查間隔

# 操作說明

每個標籤頁右上角提供：

  • 保存：保存當前分區配置（與原配置合併後提交）。
  • 重置：確認後恢復為 MQTT 默認值並重新加載。
  • 查看當前配置 JSON：只讀彈窗展示當前配置的 JSON。

提示：保存後集群會重新加載相關配置，通常立即生效；部分網絡相關配置（如監聽器）可能需要重啟監聽器。重置將覆蓋所有自定義配置，請謹慎操作。

# 數據備份

對應菜單：系統配置 → 數據備份

管理 MQTT Broker 的數據備份文件，支持創建、導入、上傳、下載與刪除。

# 列表

列 說明
文件名 備份文件名
節點 所在節點
大小 文件大小（B/KB/MB）
創建時間 創建時間
操作 下載 / 刪除

# 操作說明

工具欄

  • 創建備份：在集群上生成一份新的備份文件。
  • 導入：打開"導入備份"抽屜，從已有備份文件中選擇並導入。
  • 上傳：從本地上傳備份文件到集群。
  • 刷新：刷新列表。

行內操作

  • 下載：下載該備份文件到本地。
  • 刪除：刪除該備份文件（二次確認）。

# 常見問題

本章問題按功能分類，涉及頁面均以左側菜單實際路徑標註。

# 一、連接與認證

# Q1：客戶端連接時提示認證失敗，如何排查？

  1. 確認客戶端使用的用戶名、密碼正確。
  2. 進入 系統配置 → 認證器管理，確認已啟用內置數據庫認證器或對應的外部認證器。
  3. 進入 用戶與權限 → 用戶管理，確認用戶存在且所屬認證器正確。
  4. 查看 監控運維 → 日誌告警 → 告警 及節點日誌，確認是否有認證相關錯誤。

# Q2：為什麼修改用戶密碼後客戶端還能連接？

修改用戶後需要在 用戶與權限 → 用戶管理 點擊 "同步到 MQTT"，否則新密碼不會生效。若用戶已在線，可進入 資源管理 → 客戶端管理 手動斷開連接，強制客戶端重連。

# Q3：超級用戶和普通用戶有什麼區別？

超級用戶會繞過所有 ACL 檢查，擁有所有主題的發佈和訂閱權限。普通用戶需要在 用戶與權限 → 權限管理 顯式配置 ACL 規則才能訪問指定主題。

# 二、主題與訂閱

# Q4：訂閱了主題但收不到消息，如何排查？

  1. 確認客戶端已成功連接且訂閱關係已建立（資源管理 → 客戶端管理 → 詳情 → 訂閱管理）。
  2. 進入 資源管理 → 訂閱管理，確認訂閱的 Topic 和 QoS 正確。
  3. 檢查 用戶與權限 → 權限管理，確認用戶/客戶端 ID 對對應主題有 订阅 或 全部 權限。
  4. 檢查 資源管理 → 消息管理 → 主題重寫 / 自動訂閱，確認沒有意外改寫訂閱關係。
  5. 查看 監控運維 → 資源監控 → Topic 監控，確認消息有流入。

# Q5：保留消息有什麼作用？如何清除？

保留消息會在新訂閱者訂閱時立即收到，常用於狀態同步。清除方式：

  • 發送一條空的保留消息到該主題。
  • 在 資源管理 → 消息管理 → 保留消息 頁面手動刪除。

# Q6：QoS 0 和 QoS 1 的訂閱者會收到同一條消息嗎？

會。QoS 是發佈者和訂閱者之間的協商結果，消息會按訂閱者指定的 QoS 等級投遞，而不是發佈者指定的 QoS。

# 三、認證授權

# Q7：ACL 規則已配置但仍提示無權限，怎麼辦？

  1. 在 用戶與權限 → 權限管理 確認已選擇 built_in_database 授權源。
  2. 確認規則已點擊 "同步到 MQTT"。
  3. 檢查 系統配置 → 授權源管理 中授權源排序，確認前置授權源沒有產生衝突規則。
  4. 在 資源管理 → 客戶端管理 → 詳情 中點擊 "清除授權緩存"，強制刷新緩存。

# Q8：多個授權源如何匹配？

多個授權源按 系統配置 → 授權源管理 中的排序依次匹配，匹配成功後停止。同一授權源內的規則也按順序匹配。建議將更具體的規則排在前面。

# 四、監控與運維

# Q9：如何查看 MQTT 集群的實時運行狀態？

進入 監控運維 → 資源監控 → 節點監控 查看各節點狀態；進入 監控運維 → 監控大盤 查看集群整體指標趨勢。

# Q10：慢訂閱記錄如何產生的？

在 監控運維 → 資源監控 → 慢訂閱 → 設置 中開啟檢測後，當消息從 Broker 投遞到訂閱者的耗時超過設定閾值時，會產生慢訂閱記錄。可在同一頁面查看記錄並調整閾值。

# Q11：為什麼 Topic 監控只能添加 100 個？

MQTT 集群對 Topic Metrics 數量有限制，默認最多 100 個。建議只監控關鍵業務主題（監控運維 → 資源監控 → Topic 監控）。

# Q12：日誌追蹤和告警在哪裡查看？

進入 監控運維 → 日誌告警：日志追踪 標籤頁可創建按客戶端/主題/IP 的追蹤任務並下載日誌；告警 標籤頁展示集群激活中與已解除的告警。

# 五、系統配置

# Q13：修改系統配置後多久生效？

在 系統配置 → 系統配置 保存後，集群會重新加載相關配置，通常立即生效。部分網絡相關配置（如監聽器地址）可能需要在 系統配置 → 監聽器 重啟對應監聽器。

# Q14：重置系統配置會有什麼影響？

重置會將配置恢復為 MQTT 默認值，覆蓋所有自定義配置。請在操作前確認已在 系統配置 → 數據備份 備份重要配置。

# 六、其他

# Q15：文檔中提到的 MQTT 與 ADMQ MQTT 是什麼關係？

ADMQ MQTT（Open MQTT / EMQX）是 ADMQ Manager 平臺對 MQTT 集群的統一管理模塊，文檔中兩者根據上下文使用，均指平臺中的 MQTT 管理能力。

编辑页面 (opens new window)
#管控臺用戶手冊

← 核心引擎使用者手冊→