管控台使用者手冊

# 前言

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

# 適用對象

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

# 管理面入口

# 登錄地址

在瀏覽器地址欄輸入 http://{console_ip}:12305，進入 ADMQ 管控台登錄頁面。其中 {console_ip} 為管控台服務所在主機的 IP 地址或域名。

# 登錄流程

  1. 打開瀏覽器，訪問上述地址。
  2. 在登錄頁面輸入用戶名和密碼。
  3. 單擊登錄按鈕，驗證通過後進入系統管理首頁。
  4. 若密碼錯誤超過限制次數，賬號可能會被臨時鎖定，請聯繫管理員處理。

# 默認賬號與密碼修改

系統預置默認管理員賬號為 admq。首次登錄後，建議按以下步驟修改密碼：

  1. 單擊右上角用戶頭像，選擇個人設置或修改密碼。
  2. 輸入原密碼及新密碼，確認新密碼。
  3. 單擊保存，完成密碼修改。

建議密碼長度不小於 8 位，同時包含大小寫字母、數字及特殊字符，並定期更換。

# 權限與角色

ADMQ 管控台支持基於角色的訪問控制，常見角色包括：

  • 系統管理員：擁有全部權限，包括集群接入、用戶管理、License 管理等。
  • 運維人員：可管理集群、Topic、訂閱組、消息查詢及監控大盤等日常運維資源。
  • 只讀用戶：僅可查看資源與監控數據，無法執行創建、修改、刪除等變更操作。

# 集群管理

# 查看集群列表

  1. 登錄管控台，點擊左側菜單集群管理。
  2. 在集群列表中可以查看所有已創建的 RocketMQ 集群。
  3. 列表顯示：集群名稱、狀態、Broker 數、版本、創建時間等信息。

image-20260923171308033

# 創建集群

  1. 點擊新建按鈕。
  2. 選擇中間件類型：ADMQ RocketMQ。
  3. 選擇集群模式：
    • 單機模式：適用於開發測試環境。
    • 集群模式：適用於生產環境，支持多節點高可用部署。
  4. 選擇節點服務器。
  5. 配置 NameServer 地址。
  6. 點擊初始化集群。
  7. 等待集群初始化完成，狀態變為運行中。

創建集群前，請確保目標節點上的 NameServer 與 Broker 服務已正常啟動，且網絡連通。

# 刪除集群

  1. 在集群列表中選擇要刪除的集群。
  2. 點擊刪除按鈕。
  3. 確認刪除操作（刪除後數據不可恢復）。

# 命名空間管理

# 操作場景

命名空間是 ADMQ RocketMQ 中的一個資源管理概念。用戶不同的業務場景一般都可以通過命名空間做隔離，並且針對不同的業務場景設置專門的配置，例如消息保留時間。不同命名空間之間的 Topic 相互隔離，訂閱相互隔離，角色權限相互隔離。

本文檔指導您使用消息隊列 ADMQ RocketMQ 時，創建多個命名空間，以便在同一個集群下將 ADMQ RocketMQ 應用於不同的場景。

同一個命名空間下的 Topic 和 Group 的名稱唯一。

# 創建命名空間

  1. 登錄 ADMQ 控制台，單擊目標集群的進入業務功能，進入業務管理頁面。

  2. 在頁面上方選擇命名空間頁簽，單擊新建進入創建命名空間頁面。

  3. 在新建命名空間對話框，設置命名空間的相關屬性配置。

    image-20260923155650860

    • 命名空間名稱：設置命名空間的名稱（創建後不可修改），3-32 個字符，只能包含字母、數字及「_」和「-」。

    • 命名空間描述：命名空間的備註說明。

  4. 單擊保存完成所在集群命名空間的創建。

後續步驟：接下來就可以在該命名空間中創建 Topic 進行消息的生產和消費。

# 修改命名空間

如果需要重新修改編輯，可以通過以下步驟操作：

  1. 在命名空間列表頁，單擊操作列的編輯，進入編輯頁面。
  2. 修改說明，單擊保存完成修改。

# 刪除命名空間

如果想刪掉創建的命名空間，可以通過以下步驟操作：

  1. 在命名空間列表頁，單擊操作列的刪除。
  2. 在刪除的確認彈框中，單擊確認，即可刪除命名空間。

當命名空間內有 Topic 時，該命名空間不可被刪除。

# 主題管理

# 操作場景

Topic 是 ADMQ RocketMQ 中的核心概念。Topic 通常用來對系統生產的各類消息做一個集中的分類和管理。

在實際應用場景中，一個 Topic 往往代表著一個業務聚合，由開發者根據自身系統設計、數據架構設計來決定如何設計不同的 Topic。

# 創建 Topic

  1. 登錄 ADMQ 控制台，單擊目標集群的進入業務功能進入集群基本信息頁面。

  2. 單擊主題頁簽，選擇命名空間後，單擊新建進入創建 Topic 頁面。

  3. 在新建 Topic 對話框中，填寫以下信息。

    image-20260923171346972

    • Topic 名稱：填寫 Topic 名稱（創建後不可修改），3-64 個字符，只能包含字母、數字、「-」及「_」。

    • 類型：選擇消息類型，包括：普通、全局順序、局部順序。

    • 隊列數：選擇隊列數量。多隊列分區可以提高單 Topic 的生產消費性能，但是無法保證順序性。

    • broker：選擇創建主題的 broker 節點。

    • 描述：填寫 Topic 的說明信息。

  4. 單擊確認，在 Topic 列表中即可看見創建好的 Topic。

# 查看主題詳情

  1. 在 Topic 列表中，單擊目標 Topic 的名稱，進入主題詳情頁面，可以查看主題的基本信息和隊列的消費情況。

    image-20260923172925931

# 列表查詢 Topic

您可以在 Topic 列表頁右上角的搜索框中，通過 Topic 名稱進行搜索查詢，ADMQ RocketMQ 將會模糊匹配並呈現搜索結果。

# 編輯 Topic

  1. 在 Topic 列表中，找到需要編輯的 Topic，單擊操作欄中的編輯。
  2. 在彈出的對話框中可以對 Topic 的說明進行編輯。
  3. 單擊提交即完成對 Topic 的編輯。

# 刪除 Topic

刪除了 Topic 之後也會清除該 Topic 下積累的未消費消息，請謹慎執行。

  1. 在 Topic 列表中，找到需要刪除的 Topic，單擊操作列中的刪除。
  2. 在彈出的提示框中，單擊提交，完成刪除。

# 訂閱組管理

# 操作場景

訂閱組 Group 用於標識一類 Consumer，這類 Consumer 通常消費同一類消息，且消息訂閱的邏輯一致。

該任務指導您使用消息隊列 ADMQ RocketMQ 時在控制台上創建、刪除和查詢 Group。

# 創建訂閱組

  1. 登錄 ADMQ 控制台，單擊目標集群的進入業務功能進入集群業務管理頁面。

  2. 單擊訂閱組菜單欄，選擇命名空間後，單擊新建進入創建訂閱組頁面。

  3. 填寫訂閱組相關信息。

    image-20260923172943368

    • 訂閱組名稱：填寫訂閱組名稱（創建後不可修改），3-64 個字符，只能包含字母、數字、「-」及「_」。

    • broker：訂閱組創建的 broker 節點。

    • 描述：填寫訂閱組說明。

    • 高級設置：

      • 開啟消費：關閉後訂閱組下的所有消費會暫停，重新開啟可繼續消費。
      • 開啟廣播模式：關閉後訂閱組下的所有聲明為廣播模式的消費者會暫停，重新開啟可繼續消費。

  4. 單擊提交，完成訂閱組創建。

# 查看消費者詳情

  1. 單擊訂閱組列表，展示訂閱組的列表，顯示客戶端協議（目前僅支持 TCP 協議）、在線生產者數、在線消費者數、廣播消費。

  2. 單擊訂閱組的名稱，進入訂閱組詳情頁面，可以看到訂閱組的基本信息和連接的客戶端信息。

    • 訂閱關係：訂閱組和主題的訂閱關係。
    • 生產者客戶端：展示生產者客戶端信息。
    • 消費者客戶端：展示消費者客戶端信息。

    image-20260923173035730

# 重置消費位點

  1. 在訂閱組列表中，單擊目標訂閱組操作列的重置消費位點。
  2. 在彈窗中，可以選擇從最新位點開始或者按從指定時間點開始設定 Topic 的消費位移 offset（即指定該訂閱下的消費者從哪裡開始消費消息）。
  3. 單擊提交，完成設置。

# 訂閱組同步

在訂閱組列表中，左上角單擊同步，同步自動創建的訂閱組和通過命令創建的訂閱組（如果不手動主動同步，一般 5 分鐘定時任務同步）。

# 編輯訂閱組

  1. 在訂閱組列表中，單擊目標訂閱組操作列的編輯。
  2. 在彈窗中，對訂閱組信息和是否開啟廣播消費進行編輯。
  3. 單擊提交，完成修改。

# 刪除訂閱組

刪除 Group 後，由該 Group 標識的消費者將立即停止接收消息，該 Group 下的所有配置將會被清空，且無法恢復，請您謹慎執行該操作。

  1. 在 Group 列表中，找到需要刪除的訂閱組，單擊操作列的刪除。
  2. 在彈出的提示框中，單擊提交，完成刪除。

# 消息查詢

# 查詢消息

# 進入查詢頁面

  1. 登錄 ADMQ RocketMQ 控制台，在左側導航欄單擊消息查詢。

  2. 在消息查詢頁面，選擇好命名空間後根據頁面提示輸入查詢條件。

    • 時間範圍：選擇需要查詢的時間範圍，一般默認 2 小時，也可以自定義時間範圍。
    • 命名空間：選擇需要查詢的 Topic 所在的命名空間。
    • 主題：選擇需要查詢的 Topic。
    • 查詢方式：消息查詢功能支持三種查詢方式。

    image-20260923173159281

# 按主題查詢

選擇按主題查詢，直接展示該主題的相關消息信息，適用於查看某段時間內 Topic 的全部消息。

# 按消息 ID 查詢

選擇按消息 ID 查詢，該方式屬於精確查詢，速度快、精確匹配，適用於已記錄消息 ID 的場景。

# 按消息 Key 查詢

選擇按消息 Key 查詢，該方式屬於模糊查詢，適用於您沒有記錄消息 ID 但是設置了消息 Key 的場景。

# 死信隊列

# 操作場景

死信隊列是一種特殊的消息隊列，用於集中處理無法被正常消費的消息的隊列。當消息在達到一定重試次數後仍未能被正常消費，ADMQ RocketMQ 會判定這條消息在當前情況下無法被消費，將其投遞至死信隊列。

實際場景中，消息可能會由於持續一段時間的服務宕機、網絡斷連而無法被消費。這種場景下，消息不會被立刻丟棄，死信隊列會對這種消息進行較為長期的持久化，用戶可以在找到對應解決方案後，創建消費者訂閱死信隊列來完成對當時無法處理消息的處理。

# 特性說明

  • 當消息被投遞到死信隊列後，消息不會再被消費者正常消費。消息查詢最多可以查詢近 3 天的消息，請盡量在死信消息產生的 3 天內進行處理，否則消息可能會被刪除。
  • 一個死信隊列包含了對應的一個 Group 中所有 Topic 產生的所有死信消息。如果一個 Group 中沒有產生死信消息，則不會為其創建死信隊列，也查詢不到死信消息。

# 查詢與處理死信消息

  1. 登錄 ADMQ RocketMQ 控制台，在左側導航欄單擊無效信件佇列。
  2. 在消息查詢頁面，根據頁面提示輸入查詢條件。
    • 時間範圍：選擇需要查詢的時間範圍，支持近 30 分鐘、近 1 小時、近 6 小時、近 24 小時、近 3 天和自定義時間範圍。
    • 命名空間：選擇需要查詢的死信消息所在的命名空間。
    • 消息 ID：非必填。
      • 不填寫消息 ID：屬於模糊查詢。根據 Group ID 和死信消息產生的時間範圍，批量查詢該 Group ID 在某段時間內產生的所有死信消息。
      • 填寫消息 ID：屬於精確查詢。根據 Group ID 與 Message ID 精確定位到任意一條消息。

# 集群通道

# 跨集群數據複製和同步

通過 RocketMQ Connect 構建跨地域、跨集群的消息複製通道，不僅支持異構數據源之間的數據同步，也支持 RocketMQ 集群之間的數據複製。

# 新增通道

  1. 登錄 ADMQ RocketMQ 控制台，找到對應集群，編輯添加對應數據複製地址（RocketMQ Connect 對應 IP 端口）。

  2. 在左側導航欄單擊集群通道，查看當前的集群列表。

  3. 選擇接收通道或者發送通道，再點擊新增，進入新增通道的窗口。

  4. 填寫完對應配置後，點擊保存，創建對應通道。

# 元數據導入

# 操作場景

客戶在使用 ADMQ for RocketMQ 時，通常會面臨著存量業務的切換，例如從自建的 RocketMQ 或者其他平台的託管版 RocketMQ 遷移到 ADMQ for RocketMQ 上。

# 導出元數據文件

通過命令導出對應的元數據文件，進入對應的目錄下導出元數據的文件，根據需要導出主題、訂閱組等內容：

./bin/mqadmin exportMetadata -n {nameserver 地址及端口號} -c {RocketMQ 集群名稱} -f {導出的元數據文件的存放路徑}
1

# 創建導入任務

  1. 登錄 ADMQ RocketMQ 控制台，進入元數據導入頁面。

  2. 單擊新建任務創建對應的導入任務，導入對應的數據文件。

    image-20260923173756503

  3. 點擊提交導入，創建對應的元數據導入任務。

# 查看任務狀態

任務創建成功後，進入任務列表查看任務進度。如果數據過多時，任務需要加載一段時間。

# 監控大盤

# 監控說明

ADMQ RocketMQ 管控台的監控大盤從 Broker 與 NameServer 採集運行時指標，提供集群、節點、主題、消費者四個維度的監控視圖，幫助用戶掌握消息收發速率、吞吐量、磁盤使用、消費延遲等關鍵運行狀態。

image-20260923173831005

# 時間範圍選擇

頁面頂部提供時間範圍選擇器，支持快捷選項（最近 1 小時、最近 6 小時、最近 1 天等）和自定義時間範圍。

# 概覽

查看集群維度的關鍵監控數據，包括：

監控指標 說明
集群 TPS 集群的流入流出 TPS 總量。
集群吞吐量 集群的吞吐量（字節）。
消息存儲大小 集群消息存儲大小。
消息消費速率 每秒接收的消息數。
消息發送速率 每秒發送的消息數。
活躍連接數 集群目前活躍的連接數。
消息堆積總量 未消費的消息總數。
就緒消息數 集群準備發但還沒發的消息總數。

# 節點大盤

查看 Broker 維度的關鍵監控數據，包括：

監控指標 說明
Broker TPS Broker 的流入流出 TPS 總量。
Broker 吞吐量 Broker 的吞吐量（字節）。
CPU 使用率 Broker 節點 CPU 使用率。
消息存儲大小 Broker 節點消息存儲大小。
磁盤使用率 Broker 節點磁盤使用率。
消息消費速率 每秒接收的消息數。
消息生產速率 每秒發送的消息數。
消息保留時間 消息的保留時間。
請求處理器水位 處理器的使用情況。
存儲分發延遲 Broker 分發消息的延遲。

# 主題監控

查看主題 Topic 維度的監控數據：

監控指標 說明
消息生產速率 Topic 每秒生產的消息數。
字節流入速率 Topic 每秒流入的字節數。
平均消息大小 Topic 平均消息大小。
消息消費速率 Topic 每秒消費的消息數。
字節流出速率 Topic 每秒流出的字節數。
消息總量 Topic 的消息數量。
在途消息數 Topic 在途消息數。

# 消費者監控

查看消費者維度的監控數據：

監控指標 說明
消息生產速率 每秒生產的消息數。
消息消費速率 每秒消費的消息數。
消息堆積數目 訂閱組堆積未消費的消息數。
消費延遲 消費位點與最大位點的差值。
在途消息數 在過程中的消息數。
隊列延遲 隊列延遲。
就緒消息數 訂閱組中準備就緒但未行動的消息數。

# 常見問題

# 無法登錄管控台

  • 請確認瀏覽器地址為 http://{console_ip}:12305，且 {console_ip} 為管控台實際部署地址。
  • 檢查網絡是否連通，防火牆是否放行 12305 端口。
  • 確認用戶名和密碼是否正確，默認管理員賬號為 admq。
  • 若賬號被鎖定，請聯繫系統管理員解鎖。

# 集群創建失敗或狀態異常

  • 請確認目標節點上的 NameServer 與 Broker 服務已正常啟動。
  • 檢查管控台與目標節點之間的網絡連通性，尤其是 NameServer 端口。
  • 確認集群模式選擇與節點數量匹配，生產環境建議選擇集群模式。
  • 查看集群詳情頁的日誌或狀態提示，根據報錯信息排查。

# Topic 在列表中不可見

  • 請確認當前已選擇正確的命名空間，Topic 屬於某個命名空間。
  • 檢查是否擁有該命名空間的查看權限。
  • 嘗試刷新頁面或重新登錄。
  • 若 Topic 通過命令行創建，可能需要等待同步或手動觸發同步。

# 消息查詢不到

  • 請確認查詢的時間範圍覆蓋了消息產生的時間點。
  • 確認已選擇正確的命名空間和 Topic。
  • 若按消息 ID 查詢，請檢查消息 ID 是否完整且準確。
  • 若按消息 Key 查詢，請確認消息發送時設置了 Key。
  • 超過消息保留時間後，消息會被清理，無法查詢。

# 消費者堆積或消費延遲高

  • 在監控大盤 -> 消費者監控中查看該訂閱組的消息堆積數目與消費延遲。
  • 檢查消費者實例是否在線，網絡是否穩定。
  • 適當增加消費者實例數或調整消費線程數以提升消費能力。
  • 排查消費者是否存在業務邏輯阻塞、異常重試等情況。
  • 必要時可重置消費位點，跳過已確認無法處理的消息，但請謹慎操作。

# 附錄

# 術語表

術語 說明
Cluster RocketMQ 集群，由 NameServer 和 Broker 組成。
NameServer 服務註冊與發現中心。
Broker 消息存儲和轉發服務節點。
Topic 消息主題，消息的分類標識。
MessageQueue 消息隊列，Topic 的分片。
Producer 生產者，負責發送消息。
Consumer 消費者，負責接收消息。
ConsumerGroup 消費者組，一組消費者的集合。
Tag 消息標籤，用於消息過濾。
Offset 消費位點，標識消費進度。
Raft 一種分布式一致性共識算法（Raft）。
License 許可證（License），產品授權憑證。
TPS 每秒事務處理量（Transactions Per Second）。
DLQ 死信隊列（Dead Letter Queue），用於存放無法被正常消費的消息。

# 配置快速參考

配置項 默認值/示例 說明
管控台端口 12305 瀏覽器訪問端口。
默認管理員賬號 admq 首次登錄後建議立即修改密碼。
NameServer 地址 127.0.0.1:9876 創建集群時填寫的 NameServer 地址。
消息默認保留時間 72 小時 超過保留時間的消息將被清理。
死信消息保留時間 3 天 建議及時處理死信消息。
單次消息查詢時間範圍 最近 2 小時 支持自定義擴展。
编辑页面 (opens new window)
#管控台用戶手冊

← 核心引擎使用者手冊→