管控台使用者手冊

# 前言

本文档为金蝶 Apusic 分布式訊息佇列（Apusic Distributed Message Queue）统一管控台產品的使用者手册，详细介绍 ADMQ 產品管控台的功能使用、配置方法及管理操作等内容。

# 适用对象

本文档适用于 IT 資訊化业务负责人、研發经理、软件项目经理、软件架构师、維運工程师。

# 技术支援

ADMQ 產品提供全面的技术支援服務，您可以通过以下方式获得技术支援：

  • 网址：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. 出现異常及錯誤的日誌、截圖等详细資訊

# 版本变更說明

版本號 發布日期 修订内容 修订人
V2.0.6 2026-06-23 初始發布：统一管控台部署与維運手册，覆盖資源管理、叢集管理、設定中心、監控警報、通知中心、系統设置及常见问题 -

# 概览

# 概述

ADMQ Manager 是一款企業级统一訊息中介軟體管理平台，支援对 ADMQ 多种訊息内核的集中化管理。平台提供从資源纳管、叢集部署、配置管理、監控警報到通知推送的全链路維運能力，帮助企業实现訊息中介軟體的一站式管理。

# 核心功能

功能域 說明
資源管理 管理伺服器、License 授權、软件安裝包等基礎資源
叢集管理 訊息中介軟體叢集的部署、纳管、執行個體維運
設定中心 配置檔案範本管理与線上推送
維運管理 审计日誌追踪，记录資源与 API 操作
監控中心 采集目标管理、警報規則配置、系統元件健康监测
警報中心 警報总览、路由策略、抑制規則、靜默管理
通知中心 通知範本、訂閱关系、通知渠道（邮件/Webhook/站内訊息）
系統设置 使用者与角色的權限管理

# 管理主控台部署

# 安裝前准备

  • 获取安裝包：从 http://www.apusic.com/ 下載金蝶 Apusic 分布式訊息佇列安裝包，或从金蝶 Apusic 分布式訊息佇列產品光盘中获得相应的安裝包檔案。
  • 系統要求：Java 环境（管控台 JDK 17 以上，節點 JDK 1.8 及以上版本）、記憶體（16GB+）、硬盘空间（100GB+）、瀏覽器（IE8 及以上，FireFox、Chrome）

# 开始安裝

# 获取上傳產品包

ADMQ 管控台安裝包为 admq-manager 开头的壓縮包，例如 admq-manager-V2.0.6.20260602-x86_64.tar.gz

获取安裝包后，可将其上傳到伺服器的任意目錄下。

# 管理主控台安裝

解壓安裝包

mv admq-manager-V2.0.6.20260602-x86_64.tar.gz /opt/
cd /opt
tar -zxvf admq-manager-V2.0.6.20260602-x86_64.tar.gz
1
2
3

修改資料庫類型（可选）

默认使用 H2 資料庫，如果正式环境部署需要换成其他資料庫，例如 MySQL。

/opt/admq-manager-V2.0.6/config/application.properties 檔案中添加了多种資料庫配置，可以把使用的資料庫配置打开，注释掉其他不使用的資料庫設定項。

第1步：注释掉 H2 資料庫相关配置，打开 MySQL 的相关配置

修改資料庫配置

第2步：配置 MySQL 的位址、連接埠、資料庫名稱、使用者名、密碼，路徑如上图 config/other-config/db-mysql.properties MySQL 資料庫配置

第3步：管控台启动的时候会自动載入資料庫初始化脚本

其他資料庫参照此步骤即可

# 启动管理主控台服務

cd /opt/admq-manager-V2.0.6/
./bin/admq-service start
1
2

# 停止管理主控台服務

cd /opt/admq-manager-V2.0.6/
./bin/admq-service stop
1
2

# 驗證

第1步：在瀏覽器中键入 URL：http://ip:12305 或者 https://ip:12306

第2步：在登入界面輸入使用者名（admq），密碼（11111111）进行登入，首次登入需要修改密碼。

使用者名（admq）和密碼（11111111）为示例初始密碼，首次登入后必须修改。

image-20260828121405096

第3步：若登入成功，会跳轉到 ADMQ 管控台首页，则表示安裝成功。

ADMQ 管控台首页

# 安全注意事项

为确保 ADMQ 管控台安全运行，请遵循以下建議：

  • 修改默认密碼：首次登入后必须修改預設管理員密碼，避免使用弱密碼或长期沿用初始密碼。
  • 最小權限原則：为不同使用者分配角色时，仅授予完成工作所需的最小功能表与操作權限。
  • 網路安全：生產环境禁止将管控台連接埠直接暴露到公网，建議通过 VPN、跳板機或反向代理访问。
  • SSH 安全：添加伺服器时，建議使用专用維運账号并啟用金鑰認證；密碼欄位为可选，仅在需要連線探測或自動安裝代理时填寫。
  • 敏感資訊保護：License 檔案、授權中心位址、SMTP 密碼、Webhook Token 等属于敏感資訊，请妥善保管，避免在截圖或日誌中泄露。
  • 定期審計：定期查看操作审计日誌与使用者登入日誌，发现異常及时处理。

# 快速入门

平台的标准使用流程遵循"資源准备 → 叢集部署 → 叢集管理"的闭环：

┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│  1.上傳      │ →  │  2.添加      │ →  │  3.上傳       │ → │  4.建立     │
│   License   │    │   伺服器     │    │   軟體包      │    │   叢集      │
└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘
       ↑                                                  ↓
       └──────────────────────────────────────────────────┘
                        **第5步：叢集管理**
1
2
3
4
5
6
7

# 通过管控台部署訊息叢集

第1步：添加伺服器

点击【資源管理】-【伺服器管理】进入伺服器管理頁面，点击左上角**"新增"**按鈕，进入新增頁面。

伺服器管理頁面

填寫以下資訊：

欄位 必填 預設值 說明
可用區 是 第一个可用區 从已定义的可用區中选择，新增后不可修改
管理 IP 是 — 伺服器的管理網路 IP，用于 SSH 連接和平台通信
資料 IP 否 同管理 IP 資料面通信 IP，若与管理 IP 不同则单独填寫
SSH 連接埠 是 22 SSH 服務連接埠，范围 0-65535
账号 是 root SSH 登入账号
密碼 否 — SSH 登入密碼
SSH 是 支援 开关控制是否啟用 SSH 連接
程式目錄 是 /apusic/admq/program 訊息中介軟體程式安裝路徑
資料目錄 是 /apusic/admq/data 訊息中介軟體資料存储路徑
描述 否 — 伺服器備註資訊，最多 128 字符

儲存前建議操作：点击 連線探測 按鈕驗證 SSH 连通性。

第2步：添加 License

点击【資源管理】-【License 管理】进入 License 管理頁面，这里支援 3 种類型 License 管理：

以下授權内容均为示例，非真实授權資訊。

  • KBC 授權：一般为正式授權檔案，以 .lic 结尾，如 KBCLIC-260316-000118.lic，内容如下：

    示例 productId：1739014596951278592，非真实敏感資訊。

    {
"license":"SbP4b7L4ptmvy+h5LJUcxu+QvTwG2wOMIUxIhNEErT+1H6el5CtE3E...",
"productId":"1739014596951278592",
"secretKey":"SK-FBSZJJ",
"licenseEncodeType":"RAW",
"sign":"QgmsGjcHeAEVkK4055okxSq8dDgZ5otFsVld++0YkMqc3..."
}
    1
    2
    3
    4
    5
    6
    7

  • 授權中心授權：連接授權中心的配置，通常为 acls.properties 檔案，内容如下：

    示例内网位址：172.20.140.218:6869，非真实位址。

    apusic_acls_enable=true
apusic_acls_authUrls=172.20.140.218:6869
apusic_acls_tenant=public
apusic_acls_ns=KBCLIC-260528-000187
    1
    2
    3
    4

  • 传统授權：一般为臨時授權檔案，以 .xml 结尾，如 license.xml，内容如下：

    示例 License，非真实授權。

    <?xml version="1.0" encoding="UTF-8"?>
<license
    product="Apusic Distributed Message Queue"
    edition="Standard Edition"
    version="V2.0"
    licensee="臨時授權"
    datefrom="2025-12-19"
    expiration="2026-03-31"
    CPUs="1"
    license_ver="58"
   	signature="Yd1KqNVztF286tMp6zHFn65l6sBDo3ZQK1PC53kSmWRMR7t8oHmjlPd..."
/>
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13

下面以 KBC 授權为例，添加授權

  • 点击【新增】，右侧弹出新增頁面

  • 选择 KBC 類型授權

  • 填寫授權名稱

  • 貼上授權内容或者上傳授權檔案

  • 点击解析，若解析成果，则在下方区域展示正确的產品名稱、版本等

  • 点击確認，完成授權添加

    License 解析结果

第3步：上傳產品包

为保障运行一致性，需在軟體包管理功能中，上傳对应產品的產品包。若未上傳產品包，在后续接入时，将無法选择到对应的版本进行接入。

軟體包管理頁面

提示：若客戶網路安全要求，管控台上傳功能受限，也可以通过命令行上傳軟體包

cd /opt/admq-manager-V2.0.6
mkdir -p data/init/packages
# 拷贝安裝包至data/init/packages目錄
cp ADMQ-V2.0.6.tar.gz data/init/package
./bin/init packages
1
2
3
4
5

第4步：建立叢集

点击【資源管理】-【叢集清單】进入叢集管理頁面，点击左上角**"新增部署"**按鈕，进入新增頁面。

下面以部署 ADMQ for Kafka 为例，新增部署

  • 选择叢集類型，如 ADMQ Kafka
  • 填寫基本資訊，包含叢集名稱、部署模式、軟體包版本、描述
  • 填寫叢集配置，选择各元件部署的伺服器以及使用的授權
  • 確認部署資訊是否正确，点击**"开始部署"**，开启后台部署任务
  • 待部署任务全部成功执行，则表示叢集部署完成

后续使用请参考对应訊息引擎使用者手册

建立叢集頁面

第5步：叢集管理

针对訊息叢集的管理与維運，管控台提供了丰富的管理功能，请参考下文

# 功能使用

# 伺服器管理

功能定位：纳管實體機器/虛擬機器資源，维护伺服器代理，为叢集部署提供節點基礎。

# 功能入口

左侧功能表：資源管理 → 伺服器管理

伺服器管理清單

頁面包含三个页签：

页签 說明
伺服器管理 查看、添加、編輯、刪除伺服器，管理代理生命週期
可用區 定义逻辑区域（如机房、可用區），供伺服器归属使用
伺服器代理 管理代理安裝/卸載脚本範本

# 伺服器管理

# 伺服器清單

伺服器清單展示已纳管的所有伺服器，主要欄位如下：

欄位 說明
部署叢集 该伺服器已部署的叢集名稱
可用區 伺服器所属可用區
伺服器資訊 主機名 + SSH 連接資訊（账号@IP:連接埠），点击主機名可进入詳情页
代理狀態 伺服器代理（BBX）的运行狀態
CPU 使用率 即時 CPU 使用率
記憶體使用率 即時記憶體使用率
特徵碼 License 授權特徵碼，用于綁定授權许可
描述 伺服器的備註說明
建立時間 纳管時間

代理狀態說明：

狀態 含义
未安裝 伺服器尚未安裝代理
安裝中 代理正在安裝
未執行 初次安裝后未執行
執行中 代理正常运行，可进行远程操作
異常 代理运行異常，需检查或重装
# 添加伺服器

操作路徑： 点击清單左上角 新增 按鈕

填寫表單：

欄位 必填 預設值 說明
可用區 是 第一个可用區 从已定义的可用區中选择，新增后不可修改
管理 IP 是 — 伺服器的管理網路 IP，用于 SSH 連接和平台通信，新增后不可修改
資料 IP 否 同管理 IP 資料面通信 IP，若与管理 IP 不同则单独填寫，新增后不可修改
SSH 連接埠 是 22 SSH 服務連接埠，范围 0-65535
账号 是 root SSH 登入账号，仅限英文、数字、-、_
密碼 否 — SSH 登入密碼，用于連線探測和代理安裝
SSH 是 支援 开关控制是否啟用 SSH 連接；关闭后無法进行連線探測和自動安裝代理
程式目錄 是 /apusic/admq/program 訊息中介軟體程式安裝路徑
資料目錄 是 /apusic/admq/data 訊息中介軟體資料存储路徑
描述 否 — 伺服器備註資訊，最多 128 字符

儲存前建議操作： 点击 連線探測 按鈕驗證 SSH 连通性，确保填寫的 IP、連接埠、账号、密碼正确。

# 編輯伺服器

点击伺服器行末 編輯 按鈕，可修改以下欄位：

  • 可用區（不可修改）
  • 管理 IP（不可修改）
  • 資料 IP（不可修改）
  • 主機名（系統自动采集，不可修改）
  • SSH 連接埠、账号、密碼
  • SSH 开关狀態
  • 程式目錄（不可修改）
  • 資料目錄（不可修改）
  • 描述

不可修改的欄位在編輯时以停用狀態展示。

# 刪除伺服器

点击行末 更多 → 刪除，確認后即可刪除。刪除前请确保：

  • 该伺服器上没有正在运行的叢集執行個體
  • 不再需要该伺服器的監控和日誌資料
# 批次操作

清單支援批次選擇（勾選左侧核取方塊），顶部工具栏提供以下批量功能：

按鈕 功能 說明
新增 单条添加伺服器 弹出添加表單
匯入 批次匯入伺服器 按範本格式填寫后批次匯入
匯出 匯出伺服器清單 匯出当前清單資料为檔案
批量安裝命令 生成代理安裝命令 選中伺服器后生成批次安裝脚本
同步 HOSTS 同步 hosts 配置 将伺服器 hosts 資訊同步到各節點
获取特徵碼 获取 License 特徵碼 批量获取伺服器的授權特徵碼
下載範本 下載匯入範本 获取标准匯入範本檔案
# 代理管理

代理（BBX）是部署在伺服器上的轻量级代理程式，负责执行平台下发的指令、采集伺服器指標、提供远程終端能力。

代理相关操作（点击行末"更多"展開）：

操作 适用场景 說明
部署代理 伺服器未安裝代理 通过 SSH 自动在目标伺服器上安裝代理
手動安裝 自动部署失敗 查看手動安裝指引，自行在伺服器上执行安裝命令
代理詳情 查看代理資訊 查看代理版本、狀態、資源占用等详细資訊
初始化代理 代理配置異常 重置代理配置，復原初始狀態
远程終端 需要登入伺服器操作 代理狀態为"執行中"时可用，通过瀏覽器打开 Web Terminal
# 匯入/匯出

批次匯入流程：

  • 第1步：点击 下載範本 获取标准匯入範本
  • 第2步：按範本格式填寫伺服器資訊（可用區、IP、連接埠、账号、密碼、目錄等）
  • 第3步：点击 匯入 按鈕，选择填寫好的檔案上傳
  • 第4步：系統校验通过后批量建立伺服器记录

匯出： 点击 匯出 按鈕，将当前伺服器清單匯出为檔案儲存到本地。

# 可用區管理

可用區用于对伺服器进行逻辑分組，通常对应實體機器房、資料中心或網路区域。

# 添加可用區

点击 新增 按鈕，填寫：

欄位 必填 規則
编码 是 英文、数字、-、_、.，最多 64 字符，建立后不可修改
可用區 是 可用區顯示名稱，最多 64 字符
# 編輯可用區

点击 編輯 可修改可用區名稱；编码不可修改。

# 刪除可用區

点击 刪除 即可刪除。刪除前请確認：

  • 该可用區下没有關聯的伺服器
  • 该可用區没有被任何叢集配置引用

# 伺服器代理

该页签用于管理代理的安裝和卸載脚本範本。

# 代理安裝脚本

展示代理安裝脚本範本，管理員可根据实际环境调整：

  • 下載源位址
  • 安裝路徑
  • 启动参数
  • 依赖检查逻辑
# 代理卸載脚本

展示代理卸載脚本範本，用于从伺服器上完整清理代理程式。

脚本修改后儲存即生效，后续通过平台触发的安裝/卸載操作将使用最新脚本。

# License 管理

功能定位：管理平台授權许可，支援 KBC、授權中心、传统授權三种模式，实现 License 的录入、解析、下发和回收。

# 功能入口

左侧功能表：資源管理→ License 管理

License 管理頁面

頁面包含三个页签：

页签 說明
KBC 基于 KBC（Key-Based Certificate）的授權许可管理
授權中心 对接集中式授權中心进行统一授權管理
传统授權 基于序列号和 CDKey 的传统授權方式

# 授權清單

各页签清單展示已录入的 License 记录，不同授權模式的欄位有所差異。

# KBC 清單
欄位 說明
名稱 License 的名稱标识
使用節點 当前已下發授權的伺服器節點数量，点击数字可查看節點明细
產品名稱 授權对应的產品名稱
產品版本 授權对应的產品版本
授權单位 被授權的单位/组织名稱
開始時間 授權生效日期
結束時間 授權過期日期
# 授權中心清單
欄位 說明
名稱 License 的名稱标识
使用節點 当前已下發授權的伺服器節點数量，点击数字可查看節點明细
是否开启 授權中心 ACL 功能是否啟用
連接位址 授權中心認證服務位址
命名空间 授權中心命名空间
租用戶 授權中心租用戶标识
# 传统授權清單欄位
欄位 說明
名稱 License 的名稱标识
使用節點 当前已下發授權的伺服器節點数量，点击数字可查看節點明细
序列号 License 序列号
CDKey License CDKey
產品 授權產品名稱
版本 授權產品版本
授權对象 被授權的单位/个人
IP/MAC 授權綁定的 IP 或 MAC 位址
生效日期 授權生效日期
過期日期 授權過期日期

# 授權模式說明

模式 适用场景 授權内容
KBC 金蝶/Apusic 產品线的憑證式授權 上傳或貼上授權檔案内容，系統自动解析產品名稱、版本、授權单位、有效期等資訊
授權中心 对接集中式 ACL 授權中心 配置 acl.properties 内容，包括認證位址、租用戶、命名空间等
传统授權 基于序列号+CDKey 的经典授權方式 上傳或貼上传统授權檔案，系統自动解析序列号、CDKey、產品、版本、授權对象、IP/MAC 綁定等資訊

# 新增 License

操作路徑： 点击清單左上角 新增 按鈕

填寫表單：

欄位 必填 說明
類型 是 选择 KBC / 授權中心 / 传统授權，新增后不可修改
名稱 是 License 的名稱标识，新增后不可修改，最多 255 字符
# KBC 授權内容

第1步：在 授權内容 文本框中貼上授權檔案内容，或点击 上傳授權檔案 按鈕选择檔案上傳 第2步：点击 解析 按鈕，系統自动提取以下資訊：

欄位 說明
產品名稱 授權檔案中的產品名稱
產品版本 授權檔案中的產品版本
授權单位 被授權的单位名稱
開始時間 授權生效時間
結束時間 授權過期時間

解析后的欄位自动填充且不可手动編輯。若解析失敗，请检查授權檔案内容是否完整正确。

# 授權中心内容

第1步：在 授權内容 文本框中貼上 acl.properties 檔案内容，或点击 上傳檔案 按鈕选择檔案上傳 第2步：点击 解析 按鈕，系統自动提取以下資訊：

欄位 說明
apusic_acls_enable ACL 功能是否开启
apusic_acls_authUrls 授權中心認證位址
apusic_acls_tenant 租用戶标识
apusic_acls_ns 命名空间
# 传统授權内容

第1步：在 授權内容 文本框中貼上授權檔案内容，或点击 上傳授權檔案 按鈕选择檔案上傳 第2步：点击 解析 按鈕，系統自动提取以下資訊：

欄位 說明
序列号 License 序列号
CDKey License CDKey
產品 授權產品名稱
版本 授權產品版本
版本號 版本號
授權对象 被授權的单位/个人
IP/MAC 授權綁定的 IP 或 MAC 位址
生效日期 授權生效時間
過期日期 授權過期時間

# 編輯 License

点击 License 行末 編輯 按鈕，可修改授權内容。

  • 類型：不可修改
  • 名稱：不可修改
  • 授權内容：可重新貼上或上傳檔案并解析，解析成功後将更新所有自动填充欄位

不可修改的欄位在編輯时以停用狀態展示。

# 刪除 License

点击行末 刪除 按鈕，確認后即可刪除。刪除前请确保：

  • 该 License 未下發到任何伺服器節點（使用節點数为 0）
  • 不再需要该 License 的授權資訊

刪除后無法復原，请谨慎操作。

# 下发授權

将 License 下发到叢集節點，使授權在目标伺服器上生效。

操作路徑： 点击 License 行末 下发 按鈕

操作步骤：

第1步：选择叢集：在下拉框中选择目标叢集 第2步：选择節點（可选）：

  • 勾選具体節點，则只下发到選中的節點
  • 不勾選任何節點，则下发到该叢集的所有節點 第3步：点击 確認 完成下发

節點資訊展示：

欄位 說明
節點名稱 節點的主機名或 IP
節點 IP 伺服器的管理 IP
節點類型 節點在叢集中的角色/元件類型

下发到多个節點时，系統会逐个执行。若部分節點下發失敗，将提示失敗原因。

# 查看使用節點

点击 使用節點 列中的数字，可查看当前 License 已下發的節點清單。

彈窗展示以下資訊：

欄位 說明
叢集名稱 節點所属叢集
節點名稱 節點的主機名
節點 IP 伺服器的管理 IP
節點類型 節點在叢集中的角色/元件類型

# 軟體包管理

功能定位：上傳和管理訊息中介軟體的安裝包，为叢集部署和接管提供軟體包資源。

# 功能入口

左侧功能表：資源管理 → 軟體包管理

軟體包清單

# 軟體包清單

軟體包清單展示已上傳的所有安裝包，主要欄位如下：

欄位 說明
軟體類型 訊息中介軟體類型，如 ADMQ、Kafka、RabbitMQ 等
安裝包版本 軟體包的版本號
檔案路徑 軟體包在伺服器上的存储路徑，点击複製圖示可複製完整路徑
晶片架構 軟體包适用的 CPU 架构
檔案大小（MB） 軟體包檔案大小
狀態 軟體包的啟用/停用狀態
建立時間 軟體包上傳時間

狀態說明：

狀態 含义
啟用 軟體包可用，可用于叢集部署
停用 軟體包不可用

# 支援的軟體類型

平台支援上傳以下訊息中介軟體的安裝包：

軟體類型 說明
ADMQ 金蝶天燕訊息佇列（基于 Pulsar）
RocketMQ Apache RocketMQ
ActiveMQ Apache ActiveMQ
Kafka Apache Kafka
RabbitMQ RabbitMQ
EMQX EMQX MQTT 訊息伺服器

# 上傳軟體包

操作路徑： 点击清單左上角 上傳 按鈕

上傳軟體包支援两种方式：本地檔案上傳 和 HTTP 链接匯入。

# 选择軟體類型

在弹出的上傳側邊欄中，首先选择軟體類型：

類型 值
ADMQ admq
ActiveMQ open-activemq
RocketMQ open-rocket
Kafka open-kafka
RabbitMQ open-rabbitmq
EMQX open-emqx
# 本地檔案上傳

选择 本地檔案上傳 方式，将檔案拖拽到上傳区域或点击选择檔案。

各類型軟體包命名规范：

軟體類型 命名格式 示例
ADMQ {type}-V{版本號}-{晶片架構}.tar.gz admq-V1.0.0-x86.tar.gz
RocketMQ rocketmq-V{版本號}-{晶片架構}.tar.gz rocketmq-V1.0.0-x86.tar.gz
ActiveMQ ADMQ-V{版本號}-ActiveMQ-{建置日期}.tar.gz ADMQ-V1.0.0.0-ActiveMQ-20240101.tar.gz
Kafka ADMQ-V{版本號}-Kafka-{建置日期}.tar.gz ADMQ-V1.0.0.0-Kafka-20240101.tar.gz
RabbitMQ ADMQ-V{版本號}-RabbitMQ-{建置日期}.tar.gz ADMQ-V1.0.0.0-RabbitMQ-20240101.tar.gz
EMQX emqx-{版本號}-{作業系統}-{晶片架構}.tar.gz emqx-5.8.0-el8-amd64.tar.gz

支援的晶片架構：

架构 說明
all 通用架構
x86 x86 架构
x86_64 x86_64 架构
arm ARM 架构
arrch64 ARM64 架构
mips MIPS 架构
risc-v RISC-V 架构

注意：EMQX 仅支援 all（通用）架构。

上傳規則：

  • 每次只能上傳一个軟體包
  • 檔案扩展名必须为 .tar.gz
  • 軟體包名稱必须符合对应類型的命名规范，否则上傳将被拒绝

上傳过程中会顯示即時进度条和已上傳/总檔案大小。

# HTTP 链接匯入

选择 HTTP 链接匯入 方式，輸入軟體包的下載位址，点击 开始下載。

系統将在后台下載軟體包，下載过程中会輪詢顯示进度狀態：

狀態 說明
等待中... 下載任务已提交，等待开始
正在下載... 正在从远程位址下載檔案
正在处理... 下載完成，正在处理檔案
下載完成 軟體包已成功匯入
下載失敗 下載过程中发生錯誤

下載完成后，系統会自動重新整理清單。

# 刪除軟體包

点击軟體包行末 刪除 按鈕，在確認彈窗中確認后即可刪除。

刪除前请確認：

  • 该軟體包未被任何叢集部署任务引用
  • 该軟體包不再需要用于后续部署

刪除操作不可復原，请谨慎操作。

# 叢集清單

功能定位：查看和管理已部署/纳管的所有訊息中介軟體叢集，包括 ADMQ、RocketMQ、ActiveMQ、Kafka、RabbitMQ 五大類型。

# 功能入口

左侧功能表：資源管理 → 叢集清單

叢集清單

# 叢集清單

叢集清單展示平台纳管的所有訊息中介軟體叢集，支援表格檢視和卡片檢視两种展示方式，可通过右上角檢視切換按鈕进行切換。

# 清單欄位說明
欄位 說明
叢集名稱 叢集别名 + 叢集名稱（如 生產叢集 (prod-cluster)），点击可複製完整名稱
類型 訊息中介軟體類型，如 ADMQ、RocketMQ、ActiveMQ、Kafka、RabbitMQ；管控接入的叢集会标注"（管控接入）"
部署模式 叢集的部署架构模式
版本 叢集运行的訊息中介軟體版本號
运行狀態 叢集整体运行健康狀態
啟用狀態 叢集是否啟用平台监测等定时任务
計算節點 计算/代理節點的运行狀態摘要
儲存節點 存储/协调節點的运行狀態摘要（ADMQ 叢集顯示）
描述 叢集的備註說明
建立時間 叢集纳管或部署的時間
# 狀態說明

运行狀態：

狀態 含义
正常 叢集各元件运行正常
異常 叢集存在运行異常的元件，需检查

啟用狀態：

狀態 含义
已啟用 平台正在对叢集执行监测、采集等定时任务
已停用 已暫停叢集相关的监测等定时任务

部署模式說明：

模式 适用類型 說明
单机部署 全部 单節點部署，适用于開發測試环境
叢集部署 ADMQ、Kafka、RabbitMQ 多節點分散式部署，提供高可用性能力
负载部署 ActiveMQ 多節點負載平衡部署
主从部署 全部 主從架構部署，主節點故障时從節點可接管

# 叢集操作详解

# 顶部工具栏

清單上方提供以下快捷操作按鈕：

按鈕 功能 說明
新增部署 建立新叢集 进入叢集部署向导，按步骤完成新叢集的部署
快速部署 一键快速部署 基于预设範本快速建立标准叢集
管控接入 接入外部叢集 将已运行的外部叢集接入平台进行管控
扫描纳管 自动发现叢集 扫描網路中已部署的叢集并纳入管理
# 单行操作

每行叢集记录右侧提供以下操作按鈕：

操作 權限要求 說明
執行個體 cluster:node:query 查看叢集的節點/執行個體清單，进入節點管理頁面
配置 cluster:cluster:config 查看和修改叢集設定參數
命令行 — 打开 Web Terminal 連接到叢集（仅 ADMQ 叢集顯示）
进入业务功能 ADMIN 角色 切換到业务功能侧，以当前叢集为操作对象
更多 — 展開更多操作功能表，详见下文
# 更多操作功能表

点击行末 更多（...）圖示展開的操作功能表，根据叢集類型动态顯示：

ADMQ 叢集：

操作 權限要求 說明
依赖 cluster:cluster:dependency 管理叢集依赖檔案的上傳、下发和更新
插件 cluster:cluster:plugin 管理叢集插件的載入、卸載和替换
資源隔離 cluster:cluster:isolate 配置叢集的資源隔離策略
初始化 / 更新元資料 cluster:cluster:init 初始化或更新協調器中的叢集位址元資料
啟用 / 停用 cluster:cluster:enable/disable 啟用或暂停叢集监测定时任务
刪除 — 刪除叢集记录

RocketMQ 叢集：

操作 權限要求 說明
憑證 cluster:cluster:cert 管理叢集 TLS 憑證的上傳、下发和更新
刪除 — 刪除叢集记录

RabbitMQ 叢集：

操作 權限要求 說明
策略 cluster:cluster:mirror 配置镜像佇列策略
刪除 — 刪除叢集记录

ActiveMQ / Kafka 叢集：

操作 說明
刪除 刪除叢集记录
# 刪除叢集

点击 更多 → 刪除，確認后即可刪除叢集记录。

刪除流程：

  • 第1步：首次点击刪除，系統尝试正常刪除叢集
  • 第2步：若叢集存在異常导致無法正常刪除，会提示異常原因
  • 第3步：此时可选择 強制刪除，仅刪除平台中的叢集记录，不影响实际运行的叢集節點

刪除前请確認：

  • 不再需要该叢集的監控和配置資料
  • 若为部署型叢集，刪除记录不会自动清理伺服器上的进程和資料
# 檢視切換

清單支援两种檢視模式：

檢視 特点 适用场景
表格檢視 欄位完整，支援列排序和隱藏 需要查看详细欄位資訊
卡片檢視 資訊聚合展示，直观清晰 快速浏览叢集整體狀態

檢視模式会自动儲存到本地，下次进入頁面时復原上次选择的檢視。

# 搜尋

清單右上角提供搜尋框，支援按 叢集名稱 进行模糊搜尋，輸入关键词后按回车或点击搜尋按鈕即可过滤清單。

# 執行個體清單

功能定位：查看和管理已部署/纳管叢集的所有執行個體節點，支援 Kafka、RabbitMQ、ActiveMQ 三大類型。

# 功能入口

左侧功能表：維運管理 → 執行個體清單

執行個體清單

# 頁面概览

執行個體清單展示平台纳管的所有訊息中介軟體執行個體節點，通过顶部页签可切換 Kafka、RabbitMQ、ActiveMQ 三种類型。

# 清單欄位說明
欄位 說明
叢集/執行個體 叢集别名 + 執行個體名稱，标识執行個體所属叢集及其節點名稱
執行個體類型 執行個體所属元件類型，如 Broker、Proxy、Controller 等
可用區 執行個體部署所在的逻辑可用區
IP 執行個體所在伺服器的 IP 位址
授權 綁定的 License 授權名稱，未綁定时顯示 -
執行個體狀態 執行個體进程的运行狀態
叢集狀態 RabbitMQ 特有欄位，顯示執行個體是否已加入 RabbitMQ 叢集
启动時間 執行個體进程最近一次启动的時間
描述 執行個體的備註說明
建立時間 執行個體建立或纳管的時間
# 狀態說明

執行個體狀態：

狀態 含义
執行中 執行個體进程正常运行
已停止 執行個體进程已停止

叢集狀態（RabbitMQ）：

狀態 含义
主執行個體 该執行個體为 RabbitMQ 叢集的主節點（brokerId = 0）
已加入 從節點已成功加入 RabbitMQ 叢集
未加入 從節點尚未加入 RabbitMQ 叢集

# 顶部工具栏

清單上方提供以下功能：

功能 說明
叢集篩選 右上角下拉选择器，按叢集别名过滤執行個體清單
自動重新整理 选择重新整理頻率（5s / 30s / 1m / 5m），开启后按間隔自动輪詢執行個體狀態
手動重新整理 点击重新整理按鈕立即获取最新執行個體狀態
# 叢集篩選
  • 切換页签（Kafka / RabbitMQ / ActiveMQ）时，叢集下拉选项会自动更新为对应類型的叢集清單
  • 选择叢集后，清單仅展示该叢集下的執行個體
  • 清空选择后，展示当前類型下的全部執行個體
# 自動重新整理
  • 默认关闭，首次进入頁面时不会自動重新整理
  • 选择重新整理間隔后，系統按设定頻率自动輪詢執行個體狀態
  • 离开頁面或切換页签时，自動重新整理会自动停止
  • 手動重新整理会重置自動重新整理计时器

# 批次操作

清單支援批次選擇（勾選左侧核取方塊），選中執行個體后顶部工具栏顯示批次操作按鈕：

按鈕 權限要求 說明
启动 cluster:node:start 批次啟動選中的已停止執行個體
停止 cluster:node:stop 批次停止選中的執行中執行個體

批次操作規則：

  • 系統会自动按叢集对選中的執行個體进行分組
  • 不同叢集的執行個體会分别发送操作指令
  • 若任一叢集的操作失敗，后续叢集的操作将终止
  • 操作完成后自動重新整理清單，并清空選中狀態

# 单行操作

每行執行個體记录右侧提供以下操作按鈕：

操作 權限要求 說明
启动 / 停止 cluster:node:start / cluster:node:stop 启动或停止当前執行個體进程，根据執行個體当前狀態动态顯示按鈕文字
重新啟動 cluster:node:restart 重新啟動当前執行個體进程
編輯 — 打开編輯彈窗，修改執行個體配置資訊
加入叢集 cluster:node:deploy RabbitMQ 特有，将未加入叢集的從節點加入 RabbitMQ 叢集
日誌 cluster:node:query 进入執行個體日誌查看頁面
終端 — 打开 Web Terminal 連接到執行個體所在伺服器
# 启动 / 停止執行個體
  • 第1步：点击行末 启动 或 停止 按鈕
  • 第2步：彈窗確認操作目标執行個體
  • 第3步：確認后系統向執行個體发送启动/停止指令
  • 第4步：操作指令发送成功後会提示成功資訊

注意：管控接入類型的執行個體（registerType = 1）不支援启动/停止/重新啟動操作，对应按鈕会置灰停用。

# 重新啟動執行個體
  • 第1步：点击行末 重新啟動 按鈕
  • 第2步：彈窗確認操作目标執行個體
  • 第3步：確認后系統向執行個體发送重新啟動指令
# 編輯執行個體
  • 第1步：点击行末 編輯 按鈕
  • 第2步：在彈窗中修改執行個體配置
  • 第3步：点击確認儲存修改
# 加入叢集（RabbitMQ）

RabbitMQ 類型執行個體特有操作：

  • 仅对 從節點（brokerId ≠ 0）、未加入叢集（叢集狀態为"未加入"）且 執行個體狀態为執行中 的執行個體顯示
  • 点击后系統将该執行個體加入 RabbitMQ 叢集
  • 操作成功後会自動重新整理清單狀態
# 查看日誌
  • 第1步：点击行末 日誌 按鈕
  • 第2步：頁面跳轉至執行個體日誌查看页，展示该執行個體的日誌檔案清單和内容

详见下文「執行個體日誌查看」章节。

# 終端
  • 第1步：点击行末 終端 按鈕
  • 第2步：在新視窗中打开 Web Terminal，連接到執行個體所在伺服器
  • 第3步：終端初始目錄为執行個體的程式目錄

# 執行個體日誌查看

从執行個體清單点击 日誌 按鈕进入，頁面分为左右两部分：左侧日誌檔案清單，右侧日誌内容查看区。

# 日誌檔案清單

展示執行個體程式目錄下 logs/ 檔案夹中的所有日誌檔案：

  • 檔案按修改時間倒序排列（最新的在前）
  • 顯示檔案名、檔案大小、修改時間
  • 支援按檔案名搜尋过滤
  • 点击重新整理按鈕重新获取檔案清單
  • 首次进入时自动選中第一个檔案
# 日誌内容查看

選中日誌檔案后，右侧展示日誌内容：

連接狀態：

狀態 說明
連接中... 正在与伺服器建立 SSE 連接获取日誌流
即時推送中 已建立連接，即時接收日誌更新
已中斷 連接已关闭，不再接收新日誌

工具栏功能：

按鈕 說明
搜尋日誌内容 輸入关键词，高亮匹配的行；顯示匹配数量，支援上下導航跳轉
中斷連接 中斷 SSE 連接，停止即時推送
建立連接 重新建立 SSE 連接，开始即時推送
清空 清空当前已載入的日誌内容
滾到底部 快速滚动到日誌末尾

日誌顯示特性：

  • 即時串流推送，最大保留 10000 行日誌
  • 自動滾底：連接狀態下有新日誌时自动滚动到底部
  • 使用者手動滾動后，自動滾底暂停，滾到底部后復原
  • 搜尋匹配的行以高亮背景顯示，当前匹配行以深色高亮
# 面包屑導航

頁面顶部提供面包屑導航，可快速返回執行個體清單：

執行個體清單 > 執行個體日誌
1

# 部署任务

功能定位：建立和管理訊息中介軟體叢集的自动化部署任务，支援 ADMQ、Kafka、RocketMQ、RabbitMQ、ActiveMQ、EMQX 六种叢集類型。

# 功能入口

左侧功能表：叢集管理 → 部署任务

部署任务清單

# 頁面概览

# 统计卡片

頁面顶部展示 5 张统计卡片，点击卡片可快速篩選对应狀態的任务：

卡片 說明
任务总数 全部部署任务数量
執行中 狀態为"執行中"或"復原中"的任务数量
成功 已成功完成的部署任务数量
失敗 部署失敗的任务数量
待執行 等待執行的部署任务数量
# 任务清單

部署任务清單展示所有已建立的部署任务，主要欄位如下：

欄位 說明
叢集名稱 部署目标叢集的名稱，点击可进入部署詳情页
叢集類型 訊息中介軟體類型，如 ADMQ、Kafka、RocketMQ 等
部署模式 单机部署 / 叢集部署
狀態 当前部署任务的执行狀態
失敗原因 部署失敗时的錯誤資訊，鼠标悬停可查看完整内容
重試次數 该任务已重試的次数
建立時間 任务建立時間
操作 詳情、重試、刪除

# 部署狀態說明

狀態 含义
待執行 任务已建立，等待调度执行
執行中 部署流程正在执行
成功 所有部署步骤均已完成
失敗 某个步骤执行失敗，部署中断
復原中 部署失敗后正在执行復原操作
已取消 任务已被取消

# 建立部署任务

平台提供两种建立部署任务的方式：快速部署（简化流程）和建立部署（向导式完整流程）。

# 方式一：快速部署

点击清單右上角 快速部署 按鈕，在弹出的側邊欄中填寫：

欄位 必填 說明
叢集類型 是 选择 Kafka、RabbitMQ、RocketMQ、ActiveMQ 或 EMQX
叢集名稱 是 叢集名稱，最多 64 字符
部署模式 是 单机部署 / 叢集部署
節點数 叢集模式时 各元件節點数量（如 ZK 節點数、Broker 節點数）
啟用 Exporter 否 是否啟用指標采集元件（Kafka 特有）

快速部署会自动分配伺服器、选择默认軟體包和設定範本，适合快速建立标准环境。

# 方式二：建立部署（向导式）

点击清單右上角 建立部署 按鈕，进入 4 步向导流程。

第1步：选择叢集類型

彈窗展示 6 种叢集類型卡片：

類型 特点
ADMQ 多租用戶
ADMQ Kafka 高吞吐
ADMQ RocketMQ 多功能
ADMQ RabbitMQ 轻量级
ADMQ ActiveMQ 传统
ADMQ EMQX 物联网

点击卡片进入对应類型的部署向导。

第2步：基本資訊

欄位 必填 說明
叢集名稱 是 叢集名稱，最多 64 字符
部署模式 是 单机部署 / 叢集部署
軟體包版本 是 从已上傳的軟體包中选择；若无可用軟體包，需先在「系統配置 > 軟體包管理」中上傳
描述 否 叢集備註資訊，最多 128 字符

第3步：叢集配置

区域 說明
默认配置 - 自訂設定项 修改各元件的默认連接埠、参数等配置；支援添加自訂設定项
全域環境變數 设置全局 JVM 参数、日誌設定等環境變數，所有節點默认继承

各叢集類型默认設定項：

叢集類型 默认設定項
Kafka Broker 連接埠、ZK 客戶端連接埠、ZK 通信連接埠、ZK 选举連接埠、Exporter 連接埠
RabbitMQ AMQP 連接埠、Management 連接埠、Erlang 分布式連接埠、Prometheus 指標連接埠
ActiveMQ OpenWire 連接埠、Management 連接埠、Prometheus 指標連接埠
EMQX MQTT TCP 連接埠、MQTT SSL 連接埠、WebSocket 連接埠、WebSocket SSL 連接埠、Dashboard 連接埠
ADMQ / RocketMQ 无预设默认設定項，可通过自訂設定添加

第4步：節點配置

按元件類型分組配置各節點：

欄位 必填 說明
伺服器 是 从已纳管的伺服器中选择
元件類型 是 该節點运行的元件角色（如 Broker、ZooKeeper 等）
設定範本 是 选择設定範本，支援多选
授權檔案 部分需要 Broker 等計算節點通常需要綁定 License

点击節點右侧 進階設定 按鈕，可进一步设置：

欄位 說明
部署目錄 可选，默认自动生成
資料目錄 可选，默认自动生成（部分組件類型支援）
環境變數 覆盖全域設定，仅作用于当前節點
連接埠覆寫 覆盖叢集默认連接埠配置（部分組件支援）

各叢集類型元件說明：

叢集類型 元件角色
ADMQ ZooKeeper（協調器）、Storage（存储）、Broker（计算）、单机程式
Kafka ZooKeeper（協調器）、Broker（计算）、Exporter（采集）
RocketMQ NameServer（協調器）、Broker（计算）
RabbitMQ RabbitMQ 節點
ActiveMQ Broker
EMQX EMQX 節點

ADMQ 叢集模式要求：必须至少包含 ZooKeeper、BookKeeper（Storage）、Broker 各一个節點。

第5步：確認部署

展示部署摘要資訊，包括叢集名稱、類型、部署模式、軟體包版本、節點数量及節點配置詳情。確認无误后点击 开始部署 提交任务。

部署开始后不可取消，请確認伺服器資源充足。

# 任务操作

# 查看詳情

点击清單中 叢集名稱 或行末 詳情 按鈕，进入部署詳情页。詳情页包含：

部署概览

資訊 說明
整體狀態 当前部署任务狀態標籤
目前步驟 正在执行的步骤名稱
失敗原因 失敗时的錯誤資訊
进度条 整體完成百分比
步驟統計 總步驟 / 已完成 / 待執行 / 失敗

部署步骤

以步驟條形式展示各步骤的执行狀態，点击步骤可查看该步骤的详细日誌。支援单步骤重試（仅失敗步驟可用）。

執行時間线

展示最近 5 个已啟動步骤的執行時間和狀態，以及总耗时。

部署執行中时，頁面每 10 秒自動重新整理。

# 重試部署

当部署任务狀態为 失敗 时，清單行末和詳情页均顯示 重試 按鈕。点击后確認，系統将从失敗的步骤继续执行。

重試部署会保留已成功完成的步骤结果，仅重新执行失敗及后续步骤。

# 刪除部署任务

点击行末 刪除 按鈕，確認后即可刪除。刪除后该部署任务记录将無法復原。

刪除部署任务不会影响已部署的叢集執行個體，仅刪除部署任务记录。

# 設定範本

功能定位：管理訊息中介軟體的配置檔案範本，支援 Properties/YAML/JSON/XML/INI/CONF 等多种格式。範本用于叢集部署时自动生成節點配置檔案，也可作为配置基线供線上設定引用。

# 功能入口

左侧功能表：設定中心 → 設定範本

設定範本清單

# 頁面概览

設定範本清單展示所有已建立的設定範本，主要欄位如下：

欄位 說明
範本名稱 範本的顯示名稱，点击可进入詳情页；若为默认範本，名稱旁会顯示「默认」標籤
叢集類型 该範本适用的訊息中介軟體類型（如 Kafka、RabbitMQ 等）
檔案名 配置檔案的实际檔案名，如 server.properties、rabbitmq.conf
檔案類型 配置檔案的格式類型，如 Properties、YAML、JSON 等
描述 範本的備註說明，支援行内快速編輯
類型 系統範本 / 使用者範本，系統範本不可修改和刪除
建立時間 範本建立時間
更新時間 範本最后修改時間

類型說明：

類型 含义
系統 平台内置的默认範本，不可編輯、不可刪除
使用者 使用者自行建立的範本，可編輯、可刪除

# 支援的檔案格式

平台支援以下配置檔案格式：

格式 說明 典型场景
Properties Java Properties 格式，键值对形式 Kafka server.properties
YAML YAML 格式，支援層級結構 各类中介軟體的 YAML 配置
JSON JSON 格式 结构化配置資料
XML XML 标记格式 ActiveMQ 等 XML 配置檔案
INI INI 分段配置格式 Windows 风格配置檔案
CONF Conf 通用配置格式 RabbitMQ rabbitmq.conf
其他 不属于以上類型的其他格式 自定义脚本或配置檔案

# 操作详解

# 新增範本

操作路徑： 点击清單左上角 新增範本 按鈕

填寫表單：

欄位 必填 預設值 說明
範本名稱 是 — 範本的顯示名稱
叢集類型 是 — 从下拉框选择适用的訊息中介軟體類型
檔案名 是 — 配置檔案的实际檔案名，如 server.properties
檔案類型 是 — 从下拉框选择配置檔案的格式類型
描述 否 — 範本的備註說明
设为默认範本 否 关闭 开启后，该叢集類型下新建部署时将默认使用此範本
範本内容 是 — 配置檔案的实际内容，支援 Jinja2 範本语法，編輯器提供搜尋/替换/换行符切換功能

範本内容編輯器功能：

功能 說明
搜尋 輸入关键词后按回车定位，支援上下切換匹配项
替换 替换当前匹配项或全部替换
换行符切換 支援 LF（Unix/macOS）、CRLF（Windows）、CR（Classic Mac）三种换行符

儲存前请確認範本内容语法正确。若使用 Jinja2 範本变量，请确保变量名与部署参数一致。

# 編輯範本

編輯基本資訊：

点击範本名稱进入詳情页，在「基本資訊」卡片中点击 編輯 按鈕，可修改：

  • 範本名稱
  • 檔案名
  • 檔案類型
  • 描述
  • 是否设为默认範本

系統範本不支援編輯基本資訊。

編輯範本内容：

在「範本内容」卡片中点击 編輯 按鈕，进入内容編輯模式。編輯完成后点击 儲存 即可生效。

系統範本不支援編輯範本内容。

# 複製範本

点击行末 更多 → 複製，系統将以当前範本为基礎建立一个新範本：

  • 範本名稱自动追加 _copy 后缀
  • 叢集類型、檔案名、檔案類型、描述、範本内容均複製自原範本
  • 默认範本标记不会複製（新範本默认非默认）

複製后可按需修改并儲存。

# 刪除範本

点击行末 更多 → 刪除，確認后即可刪除。

系統範本不可刪除。刪除前请確認该範本未被任何部署任务或線上設定引用。

# 设为默认範本

在新增或編輯範本时，开启「设为默认範本」开关即可。同一叢集類型下只能有一个默认範本，新设为默认时会自动取消该類型下其他範本的默认标记。

默认範本的作用：

  • 建立部署任务时，系統会自动选择该叢集類型的默认範本
  • 默认範本名稱旁会顯示蓝色「默认」標籤
# 行內編輯描述

在清單的「描述」列中，点击描述文本旁的 編輯圖示，可直接在行内修改描述内容，按回车或点击 確認圖示 儲存，点击 取消圖示 放弃修改。

系統範本的描述不支援行內編輯。

# 預覽範本

点击行末 預覽 按鈕，弹出預覽視窗，以语法高亮形式展示範本内容。預覽視窗提供 複製内容 按鈕，可将完整内容複製到剪贴板。

# 匯入範本

操作路徑： 点击清單左上角 匯入範本 按鈕

匯入流程分为三步：

第1步：上傳 ZIP 檔案

  • 点击或将 ZIP 檔案拖拽到上傳区域
  • 仅支援 ZIP 格式，檔案大小不超过 50MB
  • ZIP 内需包含範本檔案夹，每个檔案夹对应一个設定範本

第2步：預覽確認

系統解析 ZIP 檔案后展示匯入預覽清單，包含以下資訊：

狀態 含义
新增 该範本为新範本，将建立新记录
覆盖 同名範本已存在，将更新原有记录
非法 範本資料校验不通过，無法匯入
  • 默认自动勾選所有有效（非非法）条目
  • 可手动勾選/取消勾選需要匯入的条目
  • 非法条目不可勾選，并会顯示具体原因

第3步：匯入结果

確認匯入后，系統展示匯入结果统计：

结果 說明
成功 成功匯入的範本数量
失敗 匯入失敗的範本数量，会顯示具体原因
跳過 未勾選或未被处理的範本数量
# 匯出範本

单个匯出： 点击行末 更多 → 匯出，将当前範本打包为 ZIP 檔案下載。

批次匯出： 在清單中勾選多个範本（左侧核取方塊），点击顶部 批次匯出 按鈕，将選中的範本打包为一个 ZIP 檔案下載。

# 系統範本 vs 使用者範本

特性 系統範本 使用者範本
来源 平台内置，随版本發布 使用者自行建立
編輯 不支援 支援
刪除 不支援 支援
行內編輯描述 不支援 支援
设为默认 支援 支援
标识 清單中顯示红色「系統」標籤 清單中顯示绿色「使用者」標籤

系統範本作为平台初始配置参考，建議使用者基于系統範本複製后按需修改，形成自己的範本库。

# 線上設定

功能定位：将設定範本应用到具体叢集節點，实现配置檔案的線上編輯和批量推送。

# 功能入口

左侧功能表：設定中心 → 線上設定

線上設定清單

# 頁面概览

線上設定清單展示已建立的所有設定項，主要欄位如下：

欄位 說明
配置名稱 配置的顯示名稱，点击可进入詳情页
檔案名 配置檔案的实际檔案名，如 server.properties
檔案類型 配置檔案的格式類型，如 Properties、YAML、JSON 等
叢集 配置所属叢集的别名（括号内为叢集名稱）
節點 IP 配置将要推送到的目标伺服器 IP
目前版本 配置内容的目前版本號，格式为 v{N}
同步狀態 配置内容与伺服器的同步情况
更新時間 配置内容最后一次修改的時間

清單顶部提供篩選条件，支援按叢集、配置名稱、節點 IP、同步狀態进行过滤。

# 同步狀態說明

狀態 颜色 含义
未同步 灰色 配置内容已編輯但未推送到伺服器
同步中 蓝色 配置正在推送到伺服器的过程中
已同步 绿色 配置内容已成功推送到伺服器
同步失敗 红色 設定推送失敗，需检查伺服器連接或配置内容

同步失敗时，狀態標籤旁会顯示具体的失敗原因，便于排查问题。

# 操作详解

# 新增配置

操作路徑： 点击清單左上角 新增配置 按鈕

填寫表單：

欄位 必填 說明
叢集類型 是 选择目标叢集的訊息中介軟體類型（ADMQ、Kafka、RocketMQ 等）
目标叢集 是 选择已部署的具体叢集
目标節點 是 选择叢集中的目标伺服器節點
配置名稱 是 配置的顯示名稱
檔案名 是 配置檔案的实际檔案名，如 server.properties
檔案類型 是 Properties / YAML / JSON / XML / INI / Conf / 其他
配置路徑 是 檔案在伺服器上的存放路徑，选择節點后自动填充
配置内容 是 配置檔案的具体内容

选择節點后，配置路徑会自动填充为该節點的程式目錄下的 config/ 子目錄，可根据实际需要进行修改。

# 預覽配置

点击行末 預覽 按鈕，弹出配置内容預覽視窗。

  • 支援根据檔案類型进行语法高亮（Properties、YAML、JSON、XML 等）
  • 顯示行号，便于定位
  • 支援 複製内容 按鈕，一键複製全部配置文本到剪贴板
# 編輯配置

操作路徑： 点击行末 編輯 按鈕，或点击配置名稱进入詳情页后点击 編輯

編輯頁面分为两部分：

基本資訊： 展示配置名稱、檔案名、檔案類型、所属叢集、節點 IP、配置路徑、同步狀態等唯讀資訊。

配置内容： 提供線上編輯器，支援：

  • 直接修改配置文本内容
  • 儲存：仅儲存修改，不推送至伺服器
  • 儲存并同步：儲存修改后立即推送到目标伺服器
  • 取消：放弃当前修改，復原原始内容

編輯儲存后，版本號会自动递增，同步狀態重置为"未同步"。

# 同步配置

操作路徑： 点击行末 更多 → 同步，或在詳情页点击 同步到伺服器

同步操作将目前版本的配置内容推送到目标伺服器的指定路徑：

  • 第1步：系統弹出確認对话框，顯示目标檔案名和伺服器 IP
  • 第2步：点击確認后开始同步
  • 第3步：同步完成后清單自動重新整理，顯示最新同步狀態

同步成功：狀態变为"已同步" 同步失敗：狀態变为"同步失敗"，并顯示失敗原因

# 查看历史

点击行末 历史 按鈕，弹出歷史版本視窗。

歷史版本清單展示该配置的所有变更记录：

欄位 說明
版本號 格式为 v{N}，从 1 开始递增
操作類型 建立 / 更新 / 同步 / 復原
操作人 执行该操作的使用者
操作時間 变更发生的具体時間
变更摘要 该版本变更内容的简要描述

歷史版本操作：

操作 說明
查看詳情 打开版本對比視窗，查看该版本与目前版本的差異
復原 将配置復原到该歷史版本，復原后会建立新的版本記錄

版本對比視窗：

  • 左右分栏展示两个版本的配置内容
  • 差異行以颜色标注：红色为刪除、绿色为新增
  • 支援 上一个差異 / 下一个差異 按鈕快速定位变更点
  • 支援将左侧版本復原为目前版本
# 刪除配置

操作路徑： 点击行末 更多 → 刪除

刪除前请確認：

  • 该配置不再需要维护
  • 刪除后伺服器上的配置檔案不会被自动清理，仅刪除平台中的管理记录

# 采集目标

功能定位：配置 Prometheus 監控的采集目标，管理各訊息中介軟體叢集的指標抓取端点，实现監控資料的统一采集。

# 功能入口

左侧功能表：監控中心 → 采集目标

采集目标清單

# 頁面概览

采集目标清單展示已設定的所有監控抓取端点，主要欄位如下：

欄位 說明
任务名 采集任务的标识名稱，未填寫时系統自动生成
目标位址 Prometheus 抓取的 HTTP 端点位址
叢集類型 对应的訊息中介軟體類型（如 ADMQ、Kafka、RabbitMQ 等）
描述 采集目标的備註說明
認證資訊 認證方式及简要配置資訊，鼠标悬停可查看詳情
添加時間 采集目标的建立時間
同步狀態 設定同步到 Prometheus 的狀態
抓取狀態 Prometheus 最近一次抓取的结果
上次抓取時間 Prometheus 最近一次执行抓取的時間
抓取耗时 最近一次抓取的耗时，单位秒
狀態 采集目标的啟用/关闭狀態，可通过开关切換
# 同步狀態說明
狀態 含义
未同步 配置尚未同步到 Prometheus，或同步后未生效
成功 配置已成功同步到 Prometheus
失敗 設定同步失敗，鼠标悬停可查看失敗原因
# 抓取狀態說明
狀態 含义
正常 Prometheus 抓取成功，目标端点可正常访问
異常 Prometheus 擷取失敗，目标端点不可达或返回錯誤
未知 尚未执行过抓取，或抓取狀態未知

# 認證方式說明

采集目标支援以下四种認證方式，根据目标端点的实际安全策略选择：

認證方式 适用场景 需填寫内容
无認證 目标端点无需認證即可访问 无需额外配置
Basic Auth 目标端点使用 HTTP Basic 認證 使用者名、密碼
Bearer Token 目标端点使用 Bearer Token 認證 Token 字符串
TLS 目标端点使用 mTLS 双向認證 CA 憑證、客戶端憑證、客戶端私钥、是否跳過憑證校验

TLS 認證注意事项：CA 憑證、客戶端憑證、客戶端私钥需以 Base64 编码形式填寫。若目标端点使用自簽名憑證，可开启"跳過憑證校验"开关。

# 操作详解

# 新增采集目标

操作路徑： 点击清單左上角 新增 按鈕

填寫表單：

欄位 必填 預設值 說明
服務類型 是 ADMQ（或第一个可用類型） 从已定义的叢集類型中选择，也可手动輸入
任务名 否 — 采集任务标识，只能包含字母、数字、下划线和横线，不填则自动生成
目标位址 是 — Prometheus 抓取的 HTTP 端点位址，如 http://192.168.1.1:8080/metrics（示例位址，非真实資料）
描述 否 — 采集目标備註資訊，最多 512 字符
標籤 否 cluster、ip 自定义 Key-Value 標籤，用于 Prometheus 警報和查詢分組；RabbitMQ 類型默认额外带 node 標籤
認證類型 否 无認證 根据目标端点的認證策略选择

標籤预设規則：

  • 預設標籤：cluster、ip
  • RabbitMQ 類型额外增加：node
  • 標籤以 Key-Value 形式填寫，最终序列化为 JSON 存储
# 編輯采集目标

点击行末 編輯 按鈕，可修改以下欄位：

  • 服務類型
  • 任务名
  • 目标位址
  • 描述
  • 標籤
  • 認證類型及認證配置

編輯后配置不会立即同步到 Prometheus，需手动执行"立即同步"操作。

# 立即同步

操作路徑： 点击清單左上角 立即同步 按鈕

将当前所有采集目标配置生成 Prometheus 抓取配置檔案，并同步到 Prometheus 服務。同步完成后清單中的"同步狀態"欄位会更新。

同步操作可能需要一定時間，请等待按鈕 loading 狀態结束后再查看结果。

# 匯入配置

操作路徑： 点击清單左上角 匯入配置 按鈕

支援从 ZIP 檔案批次匯入 Prometheus 抓取配置：

  • 第1步：点击彈窗中的上傳区域，选择 ZIP 格式檔案
  • 第2步：选择是否"匯入后立即同步"（默认开启）
  • 第3步：点击 匯入 按鈕执行匯入

匯入结果說明：

结果 含义
新增 配置檔案中存在但平台中不存在的采集目标，已建立
更新 配置檔案中存在且平台中已存在的采集目标，已更新
跳過 因校验失敗或其他原因未處理的采集目标

匯入完成后会展示每条记录的详细处理结果（成功/失敗及原因）。

# 匯出配置

操作路徑： 点击清單左上角 匯出配置 按鈕

匯出当前所有采集目标生成的 Prometheus 抓取配置檔案：

  • 配置預覽：左侧展示所有生成的配置檔案清單，右侧展示選中檔案的内容（YAML 格式）
  • 複製：複製当前選中檔案的内容到剪贴板
  • 下載 ZIP：将所有配置檔案打包为 ZIP 下載到本地
# 刪除采集目标

点击行末 刪除 按鈕，確認后即可刪除。刪除后：

  • 该采集目标不再参与 Prometheus 抓取
  • 已采集的历史監控資料不受影响
  • 刪除后需执行"立即同步"才能使配置变更生效
# 啟用/关闭采集目标

点击清單中 狀態 列的开关，可快速啟用或关闭采集目标：

  • 开启：Prometheus 会对该目标执行定期抓取
  • 关闭：Prometheus 不再对该目标执行抓取，但配置记录保留

狀態切換后需执行"立即同步"才能使配置变更生效。

# 警報規則

功能定位：基于 PromQL 定义監控警報規則，当指標满足阈值条件并持續指定時間后觸發警報，同步至 Prometheus 进行警報判定。

# 功能入口

左侧功能表：監控中心 → 警報規則

警報規則清單

# 頁面概览

警報規則清單展示已建立的所有警報規則，主要欄位如下：

欄位 說明
規則名稱 警報規則的名稱标识
指標名 監控指標名稱，使用自定义 PromQL 时该欄位为空
PromQL 警報判定使用的 PromQL 表达式
阈值 阈值類型 + 阈值数值，如 > 80；使用自定义 PromQL 时顯示为 -
持續時間 指標持續满足阈值条件的最短時間，如 5m 表示持續 5 分钟
嚴重級別 P0-緊急 / P1-嚴重 / P2-警告 / P3-提示
添加時間 規則建立時間
同步時間 最近一次同步到 Prometheus 的時間
同步狀態 規則同步到 Prometheus 的狀態
狀態 規則啟用/关闭开关

同步狀態說明：

狀態 含义
未同步 規則尚未同步到 Prometheus
成功 規則已成功同步并生效
失敗 同步过程中发生錯誤，可悬停查看失敗原因

清單操作栏：

按鈕 功能 說明
新增 建立警報規則 弹出建立表單
立即同步 手动触发同步 将所有啟用狀態的規則立即同步到 Prometheus
匯入規則 批次匯入規則 上傳 JSON 格式的規則配置檔案
匯出規則 匯出規則为 YAML 将当前所有規則匯出为 Prometheus 規則 YAML 檔案

清單支援按規則名稱搜尋、按狀態篩選，并支援分页浏览。

# 嚴重級別說明

警報規則按影响程度分为四个嚴重級別：

级别 标识 說明
P0 緊急 系統核心功能受损，需立即处理，如叢集完全不可用
P1 嚴重 关键功能異常，影响业务运行，如節點當機、資料丢失风险
P2 警告 潜在问题或性能下降，需关注并计划处理，如資源使用率偏高
P3 提示 一般性資訊提示，不影响业务，如配置建議、非关键指標波动

新建規則时默认嚴重級別为 P2-警告。

# 建立警報規則

操作路徑： 点击清單左上角 新增 按鈕

# 基礎配置
欄位 必填 預設值 說明
規則名稱 是 — 警報規則名稱，最多 100 字符
使用自定义 PromQL 表达式 否 关闭 开关控制是否使用自定义 PromQL；关闭时通过指標名 + 阈值方式配置
# 方式一：指標名 + 阈值（默认）

关闭"使用自定义 PromQL 表达式"开关时填寫：

欄位 必填 預設值 說明
指標名 否 — 監控指標名稱，如 admq_cluster_health
阈值類型 否 > 比较运算符：>、<、==、!=、>=、<=
阈值数值 否 — 觸發警報的阈值数值
# 方式二：自定义 PromQL 表达式

开启"使用自定义 PromQL 表达式"开关时填寫：

欄位 必填 說明
PromQL 表达式 否 輸入 PromQL 查詢表达式，支援语法高亮和自动补全

PromQL 編輯器提供以下能力：

  • 语法高亮：基于 CodeMirror 的 PromQL 语法着色
  • 自动补全：輸入时自动提示指標名、函数和標籤
  • 试运行：点击"试运行"按鈕可即时驗證表达式并查看查詢结果
# 通用配置
欄位 必填 預設值 說明
持續時間 否 5m 指標持續满足条件的最短時間，格式如 5m、1h
嚴重級別 否 P2 P0-緊急 / P1-嚴重 / P2-警告 / P3-提示
描述 否 — 警報規則的備註說明
# 進階設定（可选）

点击 進階設定 展開以下欄位：

欄位 必填 說明
綁定叢集 否 将規則關聯到指定叢集，下拉选择已註冊的叢集
中介軟體類型 否 ADMQ / Kafka / RocketMQ / RabbitMQ / MQTT / AMQ
优先级 否 数字越小优先级越高，用于多条規則冲突时的排序
標籤 否 键值对形式自訂標籤，会附加到警報事件中
注释 否 键值对形式自定义注释，可用于警報通知範本

標籤和注释以键值对形式配置，点击"添加標籤"/"添加注释"增加条目，点击行末刪除按鈕移除。

# 操作详解

# 立即同步

点击 立即同步 按鈕，平台将立即把所有狀態为"开启"的警報規則生成 YAML 規則檔案并部署到 Prometheus，同时触发 Prometheus 配置重载。

同步结果：

  • 同步成功：規則清單中同步狀態变为"成功"，同步時間更新
  • 同步失敗：同步狀態变为"失敗"，悬停狀態標籤可查看具体錯誤資訊

平台也会按默认週期（每 5 分钟）自动执行同步，无需手动操作。

# 匯入規則

操作路徑： 点击 匯入規則 按鈕

匯入流程：

第1步：上傳檔案

在彈窗中点击或拖拽上傳 JSON 格式的規則配置檔案（仅支援 .json 格式） 第2步：預覽確認

点击 預覽 按鈕，系統解析檔案并展示匯入預覽：

  • 新增：该規則在系統中不存在，将建立新记录
  • 覆盖：该規則已存在，将更新现有记录

第3步：確認匯入

核对預覽结果后点击 確認匯入，完成批次匯入

匯入完成后彈窗顯示结果摘要：共匯入 N 条，成功 N 条，失敗 N 条。

# 匯出規則

点击 匯出規則 按鈕，平台将当前所有警報規則打包为 Prometheus 規則 YAML 檔案并下載到本地，檔案名为 admq-monitor-rules-YYYY-MM-DD.yml。

匯出的 YAML 檔案可直接用于 Prometheus 規則配置。

# 編輯規則

点击規則行末 編輯 按鈕，在弹出的側邊欄表單中修改規則内容。

可修改的欄位与建立时一致，包括：

  • 規則名稱、描述
  • PromQL 表达式或指標名 + 阈值配置
  • 持續時間、嚴重級別
  • 進階設定（綁定叢集、中介軟體類型、优先级、標籤、注释）
  • 狀態（开启/关闭）

編輯后儲存，規則会自动标记为"未同步"狀態，等待下次同步后生效。

# 刪除規則

点击規則行末 刪除 按鈕，確認后即可刪除。刪除前请確認：

  • 该規則不再被任何警報策略引用
  • 刪除后对应的 Prometheus 規則将在下次同步时自动清理
# 啟用/关闭規則

点击規則行"狀態"列的开关，可快速啟用或关闭单条規則：

  • 开启：規則参与 Prometheus 警報判定
  • 关闭：規則不参与警報判定，同步时不会被部署到 Prometheus

# 系統元件

功能定位：監控平台自身依赖元件的健康狀態，包括管控服務節點、資料庫、Prometheus、Alertmanager 等。

# 功能入口

左侧功能表：監控中心 → 系統元件

系統元件監控

# 頁面概览

系統元件頁面以卡片形式展示两类元件的运行狀態：

区域 說明
管控服務 平台管控節點的运行狀態
依赖元件 平台依赖的外部元件（資料庫、Prometheus、Alertmanager）的运行狀態

頁面每 30 秒 自動重新整理一次，也可点击右上角 重新整理 按鈕手動重新整理。

# 管控服務

管控服務卡片展示平台各管控節點的狀態資訊。

# 展示欄位
欄位 說明
節點名稱 管控節點的名稱标识
狀態 節點的線上/離線狀態
節點位址 節點的 IP:連接埠
最后心跳 節點最后一次上报心跳的時間
# 狀態說明
狀態 含义 說明
線上 節點正常运行 節點在 90 秒内上报过心跳
離線 節點心跳逾時 節點超过 90 秒未上报心跳，或从未上报过心跳

# 依赖元件

依赖元件卡片展示平台运行所依赖的外部元件狀態。

# 元件清單
元件 說明 检查方式
資料庫 平台使用的資料庫服務 尝试建立資料庫連接，驗證連接有效性
普罗米修斯 (Prometheus) 指標采集与存储服務 访问 Prometheus 健康检查接口 (/-/healthy)
警報管理 (Alertmanager) 警報通知管理服務 访问 Alertmanager 健康检查接口 (/-/healthy)
# 展示欄位
欄位 說明
元件名稱 元件的中文名稱及英文标识
狀態 元件的線上/離線狀態
類型 元件的具体類型（如 MySQL、PostgreSQL 等）
位址 元件的連接位址或 URL
最后检查 最近一次健康检查的時間
錯誤資訊 狀態为離線时，展示具体的失敗原因
# 狀態說明
狀態 含义
線上 元件服務正常，健康检查通过
離線 元件服務異常，健康检查未通过，鼠标悬停可查看具体錯誤資訊
# 資料庫類型识别

平台支援的資料庫類型在元件卡片中展示如下：

類型标识 說明
MySQL MySQL 資料庫
PostgreSQL PostgreSQL 資料庫
H2 H2 記憶體資料庫
DM 达梦資料庫
KingBase 人大金仓資料庫
OSCAR 神通資料庫
HighGo 瀚高資料庫

# 警報总览

功能定位：警報中心的统一入口，集中展示当前所有警報的统计資訊、24 小时趋势和警報分組清單，帮助維運人员快速掌握系統警報全貌。

# 功能入口

左侧功能表：警報中心 → 警報总览

警報总览

# 頁面概览

警報总览頁面自上而下分为三个区域：统计卡片、趋势图、警報分組清單。

# 统计卡片

頁面顶部展示 8 张统计卡片，即時反映当前警報的整体态势：

卡片 說明
活跃警報 当前处于"警報中"狀態的警報总数，红色高亮
今日警報 今日（00:00 至今）产生的警報总数
已抑制 被抑制規則合并或靜默的警報数量
靜默中 当前处于靜默時段内的警報数量
P0-緊急 P0 级别警報数量
P1-嚴重 P1 级别警報数量
P2-警告 P2 级别警報数量
P3-提示 P3 级别警報数量

统计卡片資料随頁面載入自动获取，也可通过右上角 重新整理 按鈕手动更新。

# 24 小时警報趨勢图

统计卡片下方展示近 24 小时的警報数量折线图，横轴为時間（每小时一个資料点），纵轴为警報数量。

  • 鼠标悬停在資料点上可查看该时刻的具体警報数
  • 趋势图帮助识别警報高發時段，辅助判断是否存在週期性異常
# 警報分組清單

趋势图下方为警報分組卡片清單，按警報分組規則聚合展示。每张卡片展示以下資訊：

欄位 說明
级别標籤 该分組警報的级别（P0-P3），以彩色標籤展示
警報条数 该分組内包含的警報数量
摘要 警報摘要資訊，鼠标悬停可查看完整内容
中介軟體 产生警報的訊息中介軟體類型
最近触发時間 该分組最近一次警報觸發時間

卡片操作： 点击任意分組卡片，可进入该分組的警報詳情页，查看分組内的具体警報清單。

分页： 清單底部提供分页控件，默认每页 12 张卡片，支援切換每页顯示数量。

# 篩選功能

警報分組清單上方提供多维度篩選条件，帮助快速定位关注的警報：

篩選条件 說明 操作方式
狀態 警報中 / 已復原 / 已抑制 下拉选择，默认"警報中"
级别 P0-緊急 / P1-嚴重 / P2-警告 / P3-提示 下拉选择，可多选
关键词 按警報摘要、標籤等内容模糊搜尋 輸入框輸入，停止輸入 400ms 后自动触发搜尋
時間范围 警報觸發時間的起止范围 日期時間选择器，精確到分鐘

篩選操作：

  • 各篩選条件变更后自动触发查詢（关键词搜尋有 400ms 防抖）
  • 点击 查詢 按鈕可手动触发重新整理
  • 点击篩選条件右侧的 清除 圖示可清空对应条件

# 警報級別說明

平台将警報划分为 4 个级别，用于区分警報的緊急程度和處理優先級：

级别 標籤颜色 說明 典型场景
P0-緊急 红色 系統核心功能受损，需立即处理 叢集宕机、核心服務不可用、資料丢失风险
P1-嚴重 橙红色 重要功能異常，影响业务运行 節點故障、性能嚴重下降、关键資源耗尽
P2-警告 黄色 潜在风险或轻度異常，需关注 資源使用率偏高、配置異常、非核心功能異常
P3-提示 绿色 資訊性通知，供参考 常规狀態变化、计划内事件提醒

警報級別由警報規則配置时指定，不同级别的警報可配置不同的通知策略和升级机制。

# 自動重新整理

頁面右上角提供自動重新整理頻率设置：

选项 說明
关闭 不自動重新整理，需手动点击重新整理按鈕
30s 每 30 秒自動重新整理一次
1m 每 1 分钟自動重新整理一次
5m 每 5 分钟自動重新整理一次
15m 每 15 分钟自動重新整理一次
30m 每 30 分钟自動重新整理一次
1h 每 1 小时自動重新整理一次

建議在大屏監控场景选择较短的重新整理間隔（如 30s 或 1m），日常維運可选择 5m 或更长間隔以减少请求负载。

# 路由策略

功能定位：配置警報通知的路由規則，决定不同警報由谁接收。当警報觸發时，系統按优先级从高到低依次匹配路由策略，命中后将警報发送给对应的接收器。

# 功能入口

左侧功能表：警報中心 → 路由策略

路由策略

# 頁面概览

頁面采用左右分栏布局：

  • 左侧：路由策略卡片清單，按优先级升序排列
  • 右侧：選中策略的詳情編輯面板
# 左侧卡片清單

每张路由卡片展示以下資訊：

欄位 說明
策略名稱 路由策略的唯一标识名稱
优先级 数值越小优先级越高，决定匹配顺序
比對條件標籤 该路由的匹配標籤条件（如 severity=critical）
重复間隔 警報未復原时重复发送通知的間隔時間

卡片按优先级从小到大排列，优先级为 0 的預設路由始终位于清單最下方，以绿色底色标识。

# 右侧詳情面板

選中左侧任意卡片后，右侧面板展示该策略的完整配置，分为三个区域：

区域 說明
策略詳情 策略名稱、优先级、父層路由、接收器、分組欄位、比對後繼續等基礎配置
比對條件 警報標籤匹配規則，支援多条条件组合
通知策略 等待時間、間隔時間、重复間隔等通知聚合参数

# 建立路由策略

操作路徑： 点击左侧清單上方 新建策略 按鈕

填寫表單：

# 策略詳情
欄位 必填 預設值 說明
策略名稱 是 — 路由策略的唯一标识名稱，最多 100 字符
优先级 是 当前最大优先级 + 1 数值越小优先级越高，范围 1-9999
父層路由 否 — 选择已存在的路由作为父级，不選则为頂層路由
接收器 是 admq-manager Alertmanager 中已定义的 receiver 名稱，决定警報通知發送给谁
分組欄位 否 — 多个欄位用逗号分隔；有值时必须包含 cluster,alertname,severity
比對後繼續 否 关闭 开启后，当前路由匹配成功仍继续向下匹配其他路由
# 比對條件

点击 添加条件 可新增匹配規則，多条条件之间为 AND 关系（需同时满足）。每条条件包含：

欄位 說明
欄位名 警報標籤的欄位名稱，如 severity、cluster、alertname 等
运算符 =（等于）、!=（不等于）、=~（正規表達式比對）、!~（正規表達式不比對）
值 匹配的目标值

示例：

欄位名 运算符 值 含义
severity = critical 嚴重級別警報
cluster =~ prod-.* 叢集名稱以 prod- 开头
alertname != NodeDown 排除節點當機警報
# 通知策略
欄位 必填 預設值 說明
等待時間（秒） 否 30 初次警報等待時間，聚合组内其他警報后一起发送
間隔時間（秒） 否 300 同一分組内，新旧警報至少間隔多久发送
重复間隔（秒） 否 14400 警報未復原时，重复发送的間隔時間

填寫完成后，点击右下角 儲存 按鈕即可建立。

# 編輯路由策略

在左侧清單中点击任意非預設路由卡片，右侧面板載入该策略的当前配置，修改后点击 儲存 即可生效。

預設路由（Default）的策略名稱、优先级、父層路由、接收器、比對條件等欄位不可編輯，仅通知策略参数（等待時間、間隔時間、重复間隔）可修改。

# 刪除路由策略

在右侧詳情面板点击 刪除 按鈕，確認后即可刪除该路由策略。

預設路由不可刪除。

刪除前请確認：

  • 该路由策略不再被其他路由作为父级引用
  • 刪除后不会导致警報无人接收（建議确保有最後手段路由覆盖）

# 路由匹配規則說明

警報觸發时，系統按以下規則进行路由匹配：

  • 第1步：按优先级排序：优先级数值越小，匹配顺序越靠前
  • 第2步：逐条匹配：从高优先级到低优先级依次检查每条路由的比對條件
  • 第3步：AND 逻辑：同一路由内的多条比對條件需同时满足才算命中
  • 第4步：比對後繼續：若开启"比對後繼續"，命中后仍继续向下匹配其他路由；否则命中即停止
  • 第5步：默认兜底：若所有自定义路由均未命中，警報进入預設路由（Default）
# 父層路由与子路由
  • 支援配置父層路由，形成層級結構
  • 子路由继承父路由的上下文，可用于更细粒度的警報分發
  • 不配置父層路由则为頂層路由，直接参与根級匹配

# 預設路由說明

系統内置一条 Default 路由，作为所有警報的最后兜底：

  • 不可刪除：刪除操作将被拒绝
  • 不可修改基礎配置：策略名稱固定为 Default，优先级固定为 0，接收器固定为 admq-manager
  • 可修改通知策略：等待時間、間隔時間、重复間隔可根据需要调整
  • 无比對條件：預設路由不设任何比對條件，确保所有未命中的警報都能被接收

建議保持預設路由的接收器配置为有效值，避免警報丢失。

# 抑制規則

功能定位：配置警報间的抑制关系，避免同类或關聯警報产生警報風暴，减少無效通知。

# 功能入口

左侧功能表：警報中心 → 抑制規則

# 抑制規則原理說明

当系統中同时存在多条警報时，某些警報之间存在因果關係或包含關係。例如，一台伺服器宕机会导致该伺服器上的所有服務執行個體产生警報。如果不加处理，使用者会收到大量重复或關聯的警報通知。

抑制規則的作用就是：当满足特定条件的"來源警報"存在时，自动抑制（靜默）满足另一组条件的"目標警報"，使其不触发通知。

抑制邏輯：

概念 說明
來源警報（sourceMatch） 触发抑制的前提条件。当存在满足此条件的警報时，才考虑抑制其他警報
目標警報（targetMatch） 被抑制的警報條件。满足此条件的警報将被靜默
等同標籤（equalLabels） 來源警報与目標警報之间必须具有相同值的標籤。用于限定"同一对象"的抑制范围

工作流程：

  • 第1步：系統收到一条新警報
  • 第2步：检查是否存在已触发的"來源警報"，且该來源警報满足 sourceMatch 条件
  • 第3步：检查新警報是否满足 targetMatch 条件
  • 第4步：检查來源警報与新警報在 equalLabels 指定的標籤上是否具有相同的值
  • 第5步：以上条件全部满足时，新警報被抑制，不发送通知

# 頁面概览

抑制規則頁面采用卡片式布局，每张卡片展示一条規則的完整資訊。

卡片展示欄位：

欄位 說明
規則名稱 抑制規則的名稱标识
狀態开关 开启/关闭，控制規則是否生效
源警報條件 当警報满足以下条件（標籤鍵值對匹配）
等同標籤 來源警報与目標警報必须具有相同值的標籤名
目標警報条件 则抑制以下警報（標籤鍵值對匹配）
描述 規則的備註說明（鼠标悬停可查看完整内容）

頁面操作：

操作 說明
規則名稱搜尋 在顶部搜尋框輸入規則名稱，500ms 后自动触发搜尋
狀態篩選 按"开启"或"关闭"篩選規則
新建抑制規則 点击"新建抑制規則"按鈕建立新規則
編輯 点击卡片底部"編輯"按鈕修改規則
刪除 点击卡片底部"刪除"按鈕刪除規則
狀態切換 点击卡片右上角开关快速啟用/停用規則

# 建立抑制規則

# 操作路徑

点击頁面左上角 新建抑制規則 按鈕，弹出右侧側邊欄表單。

# 填寫表單
欄位 必填 說明
規則名稱 是 抑制規則的名稱，最多 100 字符
描述 否 規則的備註說明
來源警報比對條件 否 定义触发抑制的源警報條件，支援添加多条標籤鍵值對匹配
等同標籤 否 來源警報与目標警報必须具有相同值的標籤名清單，可多选或手动輸入
目標警報比對條件 否 定义被抑制的目標警報条件，支援添加多条標籤鍵值對匹配
狀態 是 开启/关闭，默认开启
# 來源警報比對條件 / 目標警報比對條件

每条比對條件由標籤名和標籤值组成：

  • 標籤名：支援下拉选择已有標籤，也可手动輸入。须符合 Prometheus 標籤命名规范
  • 標籤值：选择標籤名后，系統自动載入该標籤的歷史值供选择，也可手动輸入
  • 可添加多条条件，条件之间为与关系（同时满足）
  • 不填寫任何条件时，表示匹配任意警報

示例：

來源警報比對條件：severity = critical, alertname = NodeDown
等同標籤：cluster, instance
目標警報比對條件：severity = warning
1
2
3

含义：当存在 severity=critical 且 alertname=NodeDown 的警報时，抑制同一 cluster 和 instance 下所有 severity=warning 的警報。

# 編輯抑制規則

点击卡片底部 編輯 按鈕，在右侧側邊欄中修改規則内容。可修改所有欄位。

# 刪除抑制規則

点击卡片底部 刪除 按鈕，確認后即可刪除。刪除后该規則立即失效，已被抑制的警報不再受该規則影响。

# 標籤命名规范

所有標籤名须符合 Prometheus 规范，格式为：[a-zA-Z_][a-zA-Z0-9_]*

規則說明：

要求 說明
首字符 必须是英文字母（a-z, A-Z）或下划线（_）
后续字符 可以是英文字母、数字（0-9）或下划线
不允許 数字开头、包含空格、包含连字符（-）、包含特殊符号

有效示例：

  • cluster
  • instance
  • severity
  • job_name
  • _internal

無效示例：

標籤名 無效原因
1cluster 以数字开头
cluster-name 包含连字符
instance ip 包含空格
alert.name 包含句点

儲存时系統会自动校验標籤名格式，不符合规范的標籤名将提示錯誤。

# 靜默管理

功能定位：臨時屏蔽警報通知，避免在計畫內維護、已知故障等场景下产生警報噪音。支援一次性靜默和週期性靜默两种模式。

# 功能入口

左侧功能表：警報中心 → 靜默管理

頁面包含三个页签：

页签 說明
生效中 查看当前处于生效或待生效狀態的靜默規則
週期性規則 查看和管理每日週期性靜默規則
已過期 查看已失效的一次性靜默規則

# 生效中

# 頁面概览

展示当前处于 生效中 或 待生效 狀態的一次性靜默規則，以卡片形式呈现。每个卡片包含以下資訊：

欄位 說明
狀態 生效中（绿色）或 待生效（橙色）
比對條件 该規則匹配的警報標籤，如 severity=critical
生效時間 規則的開始時間和結束時間
建立人 建立该靜默規則的使用者
建立時間 規則的建立時間
靜默原因 建立时填寫的備註說明
# 搜尋与篩選

清單顶部提供以下篩選条件：

篩選条件 說明
建立人 按建立人账号模糊搜尋
狀態 按 待生效 / 生效中 / 已過期 篩選
# 刪除規則

点击卡片底部 刪除 按鈕，確認后即可刪除该靜默規則。刪除后，匹配该規則的警報将復原正常通知。

# 週期性規則

# 頁面概览

展示所有每日週期性靜默規則。週期性規則会在每天指定的時段内自动生效，无需手动重复建立。

每个卡片展示的資訊与「生效中」页签类似，额外包含：

欄位 說明
每日生效時間 如 每天 09:00 ~ 18:00
生效星期 規則在哪些星期几生效，如 周一、周二、周三；不填则每天生效
規則結束日期 規則的有效截止日期，不填则永久生效
# 刪除規則

点击卡片底部 刪除 按鈕，確認后即可刪除该週期性規則。刪除后，当天及后续日期将不再自动靜默。

# 已過期

# 頁面概览

展示所有已過期的一次性靜默規則，仅用于历史追溯和审计。過期規則不可復原，只能查看和刪除。

建立靜默規則

# 操作路徑

点击清單左上角 新建靜默規則 按鈕，弹出建立側邊欄。

# 填寫表單

第1步：选择規則類型

類型 說明 适用场景
一次性 在指定的起止時間段内生效，過期后自动失效 臨時維護時段、已知故障处理
每日週期性 每天在固定時段内重复生效 固定维护时段、夜间低优先级警報屏蔽

第2步：配置比對條件

比對條件用于指定该靜默規則作用于哪些警報。至少需添加一条比對條件。

每条比對條件包含：

欄位 必填 說明
標籤名 是 警報標籤的名稱，如 severity、instance、job 等；支援从已有標籤中选择，也可手动輸入
標籤值 是 標籤对应的值，如 critical、localhost:9090 等；支援从已有值中选择，也可手动輸入

比對邏輯： 警報的所有標籤必须同时满足配置的比對條件，才会被靜默。条件之间为 AND 关系。

例如：配置 severity=critical 且 instance=192.168.1.10（示例 IP）时，只有同时满足这两个標籤的警報才会被靜默。

第3步：配置時間規則

一次性靜默：

欄位 必填 說明
開始時間 是 規則开始生效的日期和時間
結束時間 是 規則失效的日期和時間，必须晚于開始時間

每日週期性靜默：

欄位 必填 預設值 說明
每日開始時間 是 — 每天开始靜默的時間，格式 HH:mm
每日結束時間 是 — 每天结束靜默的時間，格式 HH:mm；若結束時間早于開始時間，则表示跨天（次日）
生效星期 否 每天 选择規則在哪些星期几生效；不選则每天生效
規則結束日期 否 永久 規則的有效截止日期；不選则永久生效

跨天說明：若每日開始時間设为 22:00，結束時間设为 06:00，则表示每天 22:00 至次日 06:00 期间警報被靜默。

第4步：填寫靜默原因

欄位 必填 說明
靜默原因 是 填寫建立该靜默規則的原因，用于审计追溯，如 "周末資料庫維護時段"
# 4.3 儲存規則

点击 儲存 按鈕提交。建立成功後，規則将立即按配置生效。

# 一次性靜默 vs 週期性靜默

對比项 一次性靜默 週期性靜默
生效方式 在指定的起止時間段内生效一次 每天在固定時段内自动重复生效
過期后 自动移至「已過期」页签 持續生效，直到达到结束日期或被刪除
适用场景 臨時维护、一次性故障处理 固定維護時段、週期性低优先级警報屏蔽
時間精度 精確到分鐘（日期+時間） 精確到分鐘（仅時間，按天重复）
星期限制 不支援 支援指定生效星期
结束日期 由結束時間决定 可单独设置規則結束日期，不填则永久

# 通知範本管理

功能定位：管理警報和事件通知的内容範本，定义不同事件類型下的通知标题和内容格式，支援通过变量动态填充实际資料。

# 功能入口

左侧功能表：通知中心 → 通知範本

通知範本管理

# 頁面概览

範本清單展示已設定的所有通知範本，主要欄位如下：

欄位 說明
範本名稱 範本的顯示名稱，用于标识和区分不同範本
事件類型 範本綁定的事件類型，如"警報通知"、"叢集部署成功"等
标题範本 通知标题的範本内容，支援变量替换
内容範本 通知正文的範本内容，支援变量替换
狀態 啟用（绿色）或停用（灰色），仅啟用的範本会参与通知匹配
建立時間 範本的建立時間

清單支援按事件類型下拉篩選和按範本名稱关键词搜尋。

# 範本变量說明

通知範本支援使用 ${变量名} 语法插入动态变量，系統在发送通知时会自动将变量替换为实际值。

# 通用变量

以下变量在大多数事件類型中均可使用：

变量 說明 示例
${clusterName} 叢集名稱 kafka-prod
${time} 事件发生時間 2025-06-08T14:30:00
${eventType} 事件類型编码 ALERT_FIRING
# 警報事件变量（ALERT_FIRING / ALERT_RESOLVED）
变量 說明 示例
${alertId} 警報記錄 ID 12345
${fingerprint} 警報指纹 cpu_usage_high_xxx
${alertStatus} 警報狀態 触发中 / 已復原
${isRecover} 是否復原 false / true
${severity} 警報級別 CRITICAL
${cluster} 警報所属叢集 kafka-prod
${middleware} 中介軟體類型 KAFKA
${resourceType} 資源類型 topic
${resourceName} 資源名稱 order-topic
${summary} 警報摘要 CPU 使用率超过 80%
${description} 警報詳情 節點 192.168.1.10 CPU 使用率持續 5 分钟超过阈值（示例 IP）
${values} 警報指標值（JSON） {"cpu_usage": 85.2}
${resolvedAt} 復原時間（仅復原事件） 2025-06-08T15:00:00
# 資源操作事件变量（Kafka Topic/Group 相关）
变量 說明 示例
${topicName} Topic 名稱 order-topic
${namespace} 命名空间 default
${clusterName} 叢集名稱 kafka-prod
# License 事件变量
变量 說明 示例
${licenseName} License 名稱 ADMQ-Enterprise
${licenseUnit} License 授權单位 CPU
${productName} 產品名稱 ADMQ Manager
${endTime} 過期時間 2025-12-31
${status} 狀態描述 即将過期
${days} 剩余天数 30
${time} 当前時間 2025-06-08T14:30:00
# 扩展变量

事件發布时可以通过 extensions 传递任意自定义欄位，这些欄位同样可以在範本中使用。例如：

  • ${originInfo.ip} — 支援多级嵌套访问
  • ${errorReason} — 錯誤原因
  • ${taskId} — 任务 ID
  • ${serverIp} / ${nodeIp} — 伺服器/節點 IP

注意：若範本中使用了某个变量但该事件实际未提供该变量值，则变量占位符将保持原样輸出（如 ${clusterName}）。

# 建立/編輯範本

# 操作路徑

点击清單左上角 新增 按鈕建立範本，或点击行末 編輯 按鈕修改已有範本。

# 表單欄位
欄位 必填 預設值 說明
範本名稱 是 — 範本的顯示名稱
事件類型 是 — 从下拉清單中选择綁定的事件類型，每个事件類型通常只对应一个範本
通知渠道 否 站内訊息 选择该範本适用的通知渠道，可多选（站内訊息、邮件、Webhook）
标题範本 是 — 通知标题範本，支援 ${变量名} 语法
内容範本 是 — 通知正文範本，支援 ${变量名} 语法
狀態 否 啟用 开关控制範本是否生效
# 标题範本示例
【${eventType}】${clusterName} 发生警報
1
# 内容範本示例
叢集：${clusterName}
時間：${time}
事件：${title}
詳情：${content}
1
2
3
4

# 刪除範本

点击行末 刪除 按鈕，確認后即可刪除。

刪除範本后，对应事件類型将不再发送通知。如需暂停通知，建議将範本狀態改为"停用"而非直接刪除。

# 匯入/匯出

通知資料支援以 JSON 格式匯入和匯出，匯出檔案同时包含範本配置、訂閱配置和渠道配置三部分。

# 匯出資料

点击 匯出資料 按鈕，系統将当前所有通知配置匯出为 JSON 檔案，檔案名格式为 notification-data-YYYY-MM-DD.json。

# 匯入資料

操作步骤：

  • 第1步：点击 匯入資料 按鈕，选择要匯入的 JSON 檔案
  • 第2步：系統解析后弹出預覽視窗，展示即将匯入的範本清單及处理狀態
  • 第3步：預覽視窗中每条資料的狀態說明：
狀態 含义
新增（绿色） 该事件類型尚无範本，将新建
覆盖（橙色） 该事件類型已有範本，将覆盖更新
  • 第4步：確認无误后点击 確認匯入，系統执行匯入并返回结果统计
# JSON 檔案结构
{
  "templates": [
    {
      "name": "警報通知範本",
      "eventType": "ALERT_FIRING",
      "channels": "[\"SITE_MESSAGE\", \"EMAIL\"]",
      "titleTemplate": "【警報】${clusterName} 发生異常",
      "contentTemplate": "時間：${time}\\n詳情：${content}",
      "status": 1
    }
  ],
  "subscriptions": [
    {
      "type": 1,
      "targetId": "1",
      "eventType": "ALERT_FIRING",
      "channels": "[\"SITE_MESSAGE\"]",
      "status": 1
    }
  ],
  "channels": [
    {
      "name": "邮件通知",
      "code": "EMAIL_001",
      "channelType": "EMAIL",
      "config": "{\"smtpHost\":\"smtp.example.com\",...}",

> 示例域名/邮箱，非真实資料。
      "status": 1
    }
  ]
}
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
27
28
29
30
31
32

注意：匯入操作会同时覆盖通知範本、訂閱配置和渠道配置。建議在匯入前先匯出備份当前配置。

# 通知訂閱管理

功能定位：配置通知事件的接收对象，定义"谁（使用者/資源/角色）在什么事件发生时通过什么渠道接收通知"。

# 功能入口

左侧功能表：通知中心 → 通知訂閱管理

通知訂閱管理

# 頁面概览

訂閱清單展示所有已設定的通知訂閱，主要欄位如下：

欄位 說明
訂閱類型 訂閱对象的類型：使用者 / 資源 / 角色 / 系統默认
目标ID 具体訂閱目标的标识，如使用者名、叢集名、角色名或 DEFAULT
事件類型 触发通知的具体事件，如叢集警報、部署完成等
通知渠道 通知发送的渠道，如站内訊息、邮件、Webhook；未設定时默认使用站内訊息
狀態 啟用（绿色）或停用（灰色），停用后该訂閱不再触发通知
建立時間 訂閱配置建立時間

清單顶部支援按以下条件篩選：

篩選条件 說明
事件類型 从系統预定义的事件類型中选择
訂閱類型 使用者 / 資源 / 角色 / 系統默认
狀態 啟用 / 停用

# 訂閱類型說明

平台支援四种訂閱類型，用于指定通知的接收对象：

類型 值 說明 目标选择
使用者 1 指定具体使用者接收通知 从系統使用者清單中选择
資源 2 指定叢集資源接收通知 从已纳管的叢集清單中选择
角色 3 指定角色下所有使用者接收通知 从系統角色清單中选择
系統默认 4 系統级默认訂閱，不綁定具体对象 固定为 DEFAULT

同一事件類型下，不同類型訂閱可共存。例如：可以既为使用者 A 訂閱"叢集警報"事件，又为角色"維運人员"訂閱同一事件。

# 建立訂閱

操作路徑： 点击清單左上角 新增訂閱 按鈕

填寫表單：

欄位 必填 預設值 說明
訂閱類型 是 使用者 选择后下方"目标"下拉框会联动載入对应选项
目标 是 — 根据訂閱類型联动顯示：使用者清單 / 叢集清單 / 角色清單 / DEFAULT
事件類型 是 — 从系統预定义的事件類型中选择，支援搜尋
通知渠道 否 站内訊息 从已啟用的渠道配置中选择；未选择时默认使用站内訊息
狀態 是 啟用 开关控制，停用后该訂閱不再生效

表單填寫注意事项：

  • 第1步：选择訂閱類型后，系統会自动載入对应的目标选项，请等待載入完成后再选择目标
  • 第2步：目标下拉框支援搜尋，可直接輸入关键词快速定位
  • 第3步：通知渠道需先在"通知渠道配置"中建立并啟用，否则下拉框为空
  • 第4步：点击 儲存 按鈕完成建立

# 編輯訂閱

点击行末 編輯 按鈕，可修改以下欄位：

  • 訂閱類型（可修改，修改后目标会重置）
  • 目标
  • 事件類型
  • 通知渠道
  • 狀態

編輯时訂閱類型可变更，但变更后需重新选择目标。

# 刪除訂閱

点击行末 刪除 按鈕，確認后即可刪除。刪除后该訂閱立即停止生效，已产生的历史通知不受影响。

# 通知渠道管理

功能定位：配置通知的投递方式，支援站内訊息、邮件、Webhook 三种渠道類型，供通知範本和訂閱規則调用。

# 功能入口

左侧功能表：通知中心 → 通知渠道管理

通知渠道管理

# 頁面概览

渠道清單展示已設定的所有通知渠道，主要欄位如下：

欄位 說明
名稱 渠道執行個體的顯示名稱，如"企業邮件网关"
编码 渠道唯一标识，建立后不可修改
渠道類型 站内訊息 / 邮件 / Webhook
狀態 啟用（绿色）/ 停用（灰色），停用的渠道不会被调用
建立時間 渠道建立時間

# 渠道類型說明

平台支援以下三种通知渠道類型：

類型 說明 适用场景
站内訊息 将通知投递到平台的訊息中心，使用者登入后在站内訊息清單中查看 平台内部使用者即时提醒
邮件 通过 SMTP 伺服器发送邮件到使用者綁定的邮箱 重要警報、日报等需要持久化留存的场景
Webhook 将通知内容以 HTTP 请求方式推送到外部系統 对接企業微信、钉钉、飞书等第三方协作平台

# 新增渠道配置

点击清單左上角 新增渠道配置 按鈕，按以下步骤填寫：

# 1. 基礎資訊
欄位 必填 說明
名稱 是 渠道顯示名稱，如"企業邮件网关"，最多 64 字符
编码 是 唯一标识编码，建立后不可修改，仅限英文、数字、-、_
渠道類型 是 三选一：站内訊息 / 邮件 / Webhook，建立后不可修改
狀態 是 开关控制，默认啟用
# 2. 邮件渠道配置

选择渠道類型为 邮件 时，需填寫 SMTP 参数：

欄位 必填 預設值 說明
SMTP 伺服器 是 — SMTP 伺服器位址，如 smtp.example.com（示例域名）
SMTP 連接埠 是 — SMTP 服務連接埠，常见值：25、465、587
使用者名 是 — SMTP 認證账号，如 noreply@example.com（示例邮箱）
密碼 是 — SMTP 認證密碼
发件人位址 是 — 邮件 From 欄位位址
使用 SSL 否 关闭 开启后使用 SSL 加密連接（連接埠通常为 465）
# 3. Webhook 渠道配置

选择渠道類型为 Webhook 时，需填寫以下参数：

欄位 必填 預設值 說明
Webhook URL 是 — 接收通知的外部接口位址，如 https://hooks.example.com/xxx（示例 URL）
请求方法 是 POST POST 或 GET
Headers 否 — 自定义请求头，JSON 格式，如 {"Authorization": "Bearer xxx"}
Payload 格式 是 标准格式 详见下表

Payload 格式选项：

格式 說明
标准格式 通用 JSON 结构，欄位为 content
钉钉 钉钉机器人 markdown 訊息格式
飞书 飞书机器人交互卡片格式
企業微信 企業微信机器人 markdown 訊息格式
云之家 云之家訊息推送格式
自定义 完全自定义 Payload 範本，支援变量替换

选择内置格式（标准/钉钉/飞书/企業微信/云之家）后，可点击 查看範本 預覽该格式的 JSON 结构，或点击 基于此建立自定义 将内置範本載入到自定义編輯器中修改。

选择 自定义 格式时，需在文本框中编写 Payload 範本，支援以下变量：

变量 說明
${userId} 接收使用者 ID
${title} 訊息标题
${content} 訊息内容
${eventType} 事件類型
${clusterName} 叢集名稱
${topicName} 主題名稱
${fingerprint} 警報指纹
${alertStatus} 警報狀態
${isRecover} 是否復原
${originInfo.xxx} event.context 中的任意欄位，支援多级嵌套

自定义範本编写完成后，建議点击 測試渲染 按鈕，使用模拟資料預覽渲染结果，確認格式正确后再儲存。

# 4. 站内訊息渠道配置

选择渠道類型为 站内訊息 时，无需额外設定參數。儲存后系統会自动将通知投递到平台訊息中心。

# 編輯渠道配置

点击渠道行末 編輯 按鈕，可修改以下欄位：

  • 名稱
  • 狀態
  • 各類型对应的設定參數（SMTP 参数、Webhook URL、Payload 範本等）

编码和渠道類型在編輯时不可修改，以停用狀態展示。

# 刪除渠道配置

点击行末 刪除 按鈕，確認后即可刪除。

刪除前请確認该渠道未被任何通知範本或訂閱規則引用，否则可能导致通知发送失敗。

# 測試功能

配置完成后，建議先进行測試驗證再正式啟用。

操作路徑： 点击渠道行末 測試 按鈕

測試步骤：

  • 第1步：在弹出的"測試发送"視窗中，选择一位測試使用者
  • 第2步：点击 确定，系統将向该使用者发送一条測試通知
  • 第3步：根据渠道類型，測試使用者可在以下位置查看：
    • 站内訊息：平台右上角訊息铃铛 → 站内訊息清單
    • 邮件：使用者綁定的邮箱收件箱
    • Webhook：外部系統接收到的 HTTP 请求

# 使用者管理

功能定位：管理平台使用者账号，包括建立使用者、分配角色、管理令牌及密碼等操作。

# 功能入口

左侧功能表：系統设置 → 使用者管理

使用者管理

# 頁面概览

使用者清單展示平台中已建立的所有使用者账号，主要欄位如下：

欄位 說明
使用者名 使用者登入账号，建立后不可修改
使用者類型 管理員 / 普通使用者
使用者邮箱 使用者綁定的邮箱位址
使用者描述 使用者的備註說明
建立時間 使用者账号的建立時間

清單支援按使用者名搜尋，右上角搜尋框輸入使用者名关键词后按回车或点击搜尋按鈕即可篩選。

# 添加使用者

操作路徑： 点击清單左上角 新增 按鈕

填寫表單：

欄位 必填 預設值 說明
使用者名稱 是 — 4-100 个字符，仅限字母、数字、-、_
使用者類型 是 普通使用者 管理員 / 普通使用者
使用者密碼 是 — 8-16 个字符，字母/数字/特殊符号至少包含 2 种
確認密碼 是 — 须与上方密碼一致
使用者邮箱 是 — 有效的邮箱位址格式
手机号码 否 — 有效的 11 位手机号码
描述 否 — 使用者備註資訊，最多 128 字符

填寫完成后点击 儲存 即可建立使用者。

# 操作详解

# 編輯使用者

点击使用者行末 編輯 按鈕，可修改以下欄位：

  • 使用者名稱（不可修改）
  • 外部使用者（不可修改）
  • 使用者類型（当前登入使用者自己的账号不可修改類型）
  • 使用者邮箱
  • 手机号码
  • 描述

不可修改的欄位在編輯时以停用狀態展示。

# 分配角色

点击行末 分配角色 按鈕，打开角色分配彈窗：

  • 左侧为可选角色清單，右侧为已选角色
  • 勾選角色后点击中间箭头进行添加或移除
  • 内置角色（超級管理員、系統管理員、密钥管理員、安全审计员、MQ 管理員）不可在此分配
  • 当前登入使用者自己的账号不可分配角色

点击 儲存 后角色綁定即时生效。

# 修改密碼

点击行末 更多 → 修改密碼，可修改该使用者的登入密碼：

欄位 必填 說明
当前密碼 是 輸入该使用者的当前密碼进行驗證
新密碼 是 8-16 个字符，字母/数字/特殊符号至少包含 2 种；须与旧密碼至少有两个字符不同且无包含關係
確認密碼 是 须与新密碼一致
# 重置密碼

点击行末 更多 → 重置密碼，管理員可将使用者密碼重置为系統默认密碼。

重置密碼操作无需驗證当前密碼，仅管理員角色可见。

# 令牌管理

点击行末 令牌 按鈕，进入该使用者的令牌管理頁面。

令牌清單欄位：

欄位 說明
叢集名稱 令牌所属叢集
令牌名稱 令牌的顯示名稱
令牌 令牌的密钥字符串，点击複製按鈕可複製
建立時間 令牌的建立時間

令牌操作：

操作 說明
新增令牌 选择所属叢集，填寫令牌名稱和明文密碼（部分叢集類型需填寫），建立新的访问令牌
權限 查看该令牌在各命名空间下的訊息發布/消費權限，以及主題權限和訂閱组權限
修改密碼 修改令牌的明文密碼（内置角色令牌不可修改）
刪除 刪除该令牌，刪除后無法復原
# 刪除使用者

点击行末 更多 → 刪除，確認后即可刪除该使用者。

注意：当前登入使用者不能刪除自己。

# 角色管理

功能定位：管理平台角色及其功能表權限，控制不同使用者可访问的功能范围。

# 功能入口

左侧功能表：系統设置 → 角色管理

角色管理

# 頁面概览

角色清單展示平台中所有角色，主要欄位如下：

欄位 說明
角色名稱 角色的顯示名稱
使用者数量（位） 已綁定该角色的使用者数量，点击数字可查看具体使用者清單
描述 角色的備註說明
建立時間 角色的建立時間

清單支援按角色名稱搜尋，支援分页展示。

# 系統预设角色

预设角色不可刪除、不可編輯名稱，權限由系統自动分配。

角色名稱 說明
MQ 管理員 拥有訊息中介軟體相关的管理權限（叢集、Topic、訂閱等）

系統预设角色的權限在应用启动时自动初始化，如需调整请联系MQ管理員在「功能表權限」頁面修改。

# 操作详解

# 新增角色

操作路徑： 点击清單左上角 新增 按鈕

填寫表單：

欄位 必填 規則
角色名稱 是 中文、英文、数字、- 和 _ 组成，最多 20 字符，不可重复
描述 否 角色備註資訊，最多 128 字符

填寫完成后点击 儲存 即可建立。新增的角色類型为「自定义」，可自由編輯和刪除。

# 編輯角色

点击角色行末 編輯 按鈕，可修改角色的描述資訊。角色名稱在建立后不可修改。

系統预设角色不支援編輯。

# 分配功能表權限

点击角色行末 功能表權限 按鈕，进入權限分配頁面。

頁面布局：

  • 左侧：一级功能表清單，带核取方塊可全选/取消该功能表下所有權限
  • 右侧：二级功能表及具体功能權限清單，每个權限项通过开关控制是否啟用

操作步骤：

  • 第1步：在左侧勾選需要授權的一级功能表
  • 第2步：在右侧通过开关勾選具体的功能權限
  • 第3步：点击頁面底部 确定 儲存

系統预设角色进入功能表權限頁面时仅支援查看，不可修改。頁面底部顯示 返回 按鈕。

# 查看角色下的使用者

点击 使用者数量 列的数字，弹出側邊欄展示已綁定该角色的使用者清單。

使用者清單欄位：

欄位 說明
使用者名 使用者登入名
使用者邮箱 使用者邮箱位址
使用者描述 使用者備註資訊
建立時間 使用者建立時間

移除使用者： 点击行末 移除 按鈕，可将使用者从当前角色解绑。当前登入使用者不可移除自身。

# 刪除角色

点击行末 刪除 按鈕，確認后即可刪除。刪除前请确保：

  • 该角色不是系統预设角色
  • 该角色下没有關聯的使用者（如有使用者需先解绑）
# 批次刪除

清單支援批次選擇（勾選左侧核取方塊），選中后点击顶部工具栏 刪除 按鈕，可批次刪除多个自定义角色。

系統预设角色的核取方塊处于停用狀態，無法被選中。

# 常见问题

# 概览与首页

Q1：首页"我的叢集"区域顯示"暂无叢集，请先建立叢集"怎么办？

请按照頁面下方"业务流程指引"的顺序操作：

  • 先上傳 License 啟動平台授權
  • 上傳对应訊息中介軟體的軟體包
  • 添加伺服器資源
  • 进入"部署管理"建立叢集

建立完成后，叢集卡片将自动顯示在首页。

Q2：叢集狀態顯示"異常"如何处理？

点击该叢集卡片进入业务功能侧，查看叢集詳情頁面的節點狀態，定位異常節點后检查：

  • 伺服器代理（BBX）是否正常运行
  • 伺服器網路是否连通
  • 叢集服務进程是否存活

Q3：自動重新整理会影响頁面操作吗？

不会。自動重新整理仅在后台靜默更新資料，不会打断您当前正在进行的表單填寫、彈窗操作等交互。若需要稳定的資料檢視，建議将自動重新整理设为"不自動重新整理"。

Q4：为什么有些叢集卡片是灰色的？

灰色卡片表示该叢集已被"停用"。被停用的叢集無法接收新的生產流量，但仍可进入查看历史資料和配置。如需復原，请前往"叢集管理"頁面啟用该叢集。

# 伺服器管理

Q1：添加伺服器时連線探測失敗怎么办？

请依次检查：

  • 管理 IP 是否可达，網路是否连通
  • SSH 連接埠是否正确，防火牆是否放行
  • 账号密碼是否正确，账号是否有登入權限
  • 伺服器是否开启了密碼登入（部分环境默认关闭，需开启 PasswordAuthentication yes）

Q2：代理狀態一直顯示"未安裝"？

  • 確認伺服器 SSH 資訊填寫正确且 SSH 开关为"支援"
  • 尝试点击 部署代理 进行自動安裝
  • 若自動安裝失敗，点击 手動安裝 查看手動安裝指引

Q3：可以修改伺服器的管理 IP 吗？

不可以。管理 IP 是伺服器的唯一标识，新增时确定后不可修改。如需更换 IP，请刪除后重新添加。

Q4：資料 IP 和 管理 IP 有什么区别？

  • 管理 IP：用于平台与伺服器之间的管理通信（SSH、代理心跳）
  • 資料 IP：用于訊息中介軟體叢集節點之间的資料通信

在大多数场景下两者相同；若管理网与資料网分离，则分别填寫。

Q5：刪除伺服器会影响已部署的叢集吗？

会。刪除伺服器将解除平台对该節點的管理，若该伺服器上运行着叢集執行個體，可能导致叢集異常。刪除前请先将叢集執行個體遷移或下线。

# License管理

Q1：新增 License 时解析失敗怎么办？

请依次检查：

  • 授權檔案内容是否完整，是否包含必要欄位（如產品版本資訊）
  • 檔案格式是否正确，KBC 和传统授權需为文本格式
  • 授權中心模式需确保内容为 acl.properties 格式
  • 尝试重新上傳檔案或手动貼上内容后再解析

Q2：可以修改 License 的名稱吗？

不可以。名稱是 License 的唯一标识，新增时确定后不可修改。如需更换名稱，请刪除后重新添加。

Q3：下发授權后節點未生效怎么办？

  • 確認目标節點的代理狀態为"執行中"
  • 检查節點与平台之间的網路连通性
  • 查看節點日誌排查授權应用失敗的原因
  • 尝试重新下发授權

Q4：三种授權模式可以互相切換吗？

不可以。License 的類型在新增时确定后不可修改。如需使用其他授權模式，请新增对应的 License 记录。

Q5：刪除 License 会影响已下發的節點吗？

会。刪除 License 将解除平台对该授權的管理，已下發到節點的授權可能被回收或失效。刪除前请先将授權从所有節點上回收或确保不再需要使用。

Q6：授權中心模式和 KBC/传统授權有什么区别？

  • 授權中心：采用集中式認證，節點通过連接授權中心服務进行線上驗證，适合大规模部署和动态授權管理
  • KBC/传统授權：采用本地憑證/檔案授權，授權資訊直接下发到節點本地，适合離線环境或固定授權

# 軟體包管理

Q1：上傳时提示"軟體包名稱不合法"怎么办？

请检查軟體包名稱是否符合对应類型的命名规范：

  • 確認檔案扩展名为 .tar.gz
  • 確認名稱格式与所选軟體類型匹配（参考上文命名规范表）
  • 確認版本號、晶片架構等欄位填寫正确

Q2：上傳过程中断怎么办？

  • 本地檔案上傳：重新整理頁面后重新上傳
  • HTTP 链接匯入：若下載失敗，检查链接位址是否可访问，確認后重新提交

Q3：可以上傳多个相同類型的軟體包吗？

可以。平台支援同一類型、不同版本的多个軟體包共存，部署时可根据需要选择具体版本。

Q4：刪除軟體包会影响已部署的叢集吗？

不会直接影响已运行的叢集。但刪除后，基于该軟體包的新部署任务将無法执行。如需重新部署，需重新上傳对应版本的軟體包。

Q5：EMQX 軟體包的命名规范与其他類型不同？

是的。EMQX 使用官方原生命名格式 emqx-{版本號}-{作業系統}-{晶片架構}.tar.gz，与其他類型使用 ADMQ-V... 前缀的格式不同，请按提示要求填寫。

# 叢集清單

Q1：管控接入和扫描纳管有什么区别？

  • 管控接入：适用于已知的外部叢集，需要填寫叢集連接資訊（如位址、認證資訊）后接入平台
  • 扫描纳管：适用于網路中已部署但未知的叢集，平台自动扫描并发现可纳管的叢集

Q2：叢集运行狀態顯示"異常"怎么办？

  • 点击 執行個體 按鈕进入節點清單，查看具体哪个節點異常
  • 检查異常節點的进程是否正常运行
  • 检查伺服器網路连通性和資源使用情况
  • 必要时重新啟動異常節點或联系管理員排查

Q3：停用叢集会影响訊息收发吗？

不会。停用叢集仅暂停平台对该叢集的监测、采集等定时任务，不会停止叢集本身的运行，也不影响业务訊息的正常收发。仅在叢集異常时操作有效，可避免持續采集叢集資訊引发大量报错。

Q4：为什么有些操作按鈕是灰色的？

管控接入類型的叢集（标注"管控接入"）不支援部分維運操作，如執行個體查看、依赖管理、插件管理、資源隔離、初始化、啟用/停用等。这些操作在管控接入叢集上会被停用。

Q5：如何快速切換到某个叢集的业务功能？

ADMIN 角色的使用者可在叢集清單中点击 进入业务功能 按鈕，系統会自动切換到业务功能侧，并以该叢集为当前操作对象，直接跳轉到資源概览页。

Q6：卡片檢視中为什么看不到"儲存節點"？

卡片檢視对資訊进行了聚合展示，計算節點和儲存節點的详细狀態需切換到表格檢視查看，或点击 執行個體 按鈕进入節點管理頁面。

# 執行個體清單

Q1：为什么有些操作按鈕是灰色的？

管控接入類型的執行個體（registerType = 1）不支援启动、停止、重新啟動等維運操作，对应按鈕会置灰停用。只有平台部署的執行個體才支援完整的生命週期操作。

Q2：執行個體狀態顯示"已停止"怎么办？

  • 检查執行個體所在伺服器的資源使用情况（CPU、記憶體、磁碟）
  • 检查伺服器代理（BBX）是否正常运行
  • 尝试点击 启动 按鈕启动執行個體
  • 若啟動失敗，查看執行個體日誌排查具体原因
  • 必要时联系管理員排查

Q3：RabbitMQ 執行個體的"加入叢集"按鈕什么时候顯示？

同时满足以下条件时顯示：

  • 執行個體为從節點（brokerId ≠ 0）
  • 執行個體尚未加入叢集（叢集狀態为"未加入"）
  • 執行個體狀態为執行中

主節點（brokerId = 0）无需加入叢集操作。

Q4：批次操作可以跨叢集吗？

可以選中不同叢集的執行個體进行批次操作。系統会自动按叢集分組，分别发送指令。但需注意：若任一叢集的操作失敗，后续叢集的操作将终止。

Q5：自動重新整理会影响性能吗？

自動重新整理会按设定間隔向伺服器輪詢執行個體狀態。建議：

  • 執行個體数量较多时，避免使用 5s 的高频重新整理
  • 不需要即時監控时，关闭自動重新整理
  • 手動重新整理可以满足大部分日常維運场景

Q6：日誌查看頁面为什么顯示"暂无日誌檔案"？

可能原因：

  • 執行個體的程式目錄配置不正确，导致無法定位到 logs 目錄
  • 執行個體尚未产生日誌檔案
  • 伺服器代理（BBX）連接異常，無法读取檔案清單

请检查執行個體的程式路徑配置，并確認代理狀態正常。

Q7：Web Terminal 連接失敗怎么办？

  • 確認執行個體所在伺服器的代理（BBX）狀態为"執行中"
  • 检查伺服器防火牆是否放行了 Terminal 所需的連接埠
  • 尝试重新打开終端頁面
  • 若问题持續，联系管理員排查代理和網路连通性

# 部署任务

Q1：建立部署时提示"暂无軟體包"怎么办？

请前往 系統配置 > 軟體包管理 上傳对应叢集類型的軟體包，上傳完成后再返回建立部署。

Q2：節點配置时無法选择伺服器？

请確認：

  • 已在 資源管理 > 伺服器管理 中纳管伺服器
  • 伺服器代理狀態为"執行中"
  • 该伺服器未被其他叢集執行個體占用

Q3：部署失敗后如何排查问题？

  • 进入部署詳情页，查看 失敗原因
  • 点击失敗的步骤，查看步驟日誌中的 ERROR 级别记录
  • 展開日誌詳情，查看完整的錯誤堆栈和上下文資訊
  • 修复问题后点击 重試 继续部署

Q4：快速部署和建立部署有什么区别？

對比项 快速部署 建立部署
操作流程 简化，填寫少量欄位即可 向导式 4 步完整流程
伺服器选择 系統自动分配 手动选择
配置调整 使用預設值 支援详细配置自定义
适用场景 快速建立标准环境 生產环境精细化部署

Q5：部署任务可以取消吗？

部署任务一旦开始执行即不可取消。如确需中断，需等待目前步驟执行完毕后，在伺服器层面手动干预。

Q6：为什么有些步骤可以单独重試，有些不行？

仅狀態为 失敗 且标记为可重試的步骤支援单独重試。部分步骤因存在强依赖关系（如前置步骤未成功则后续步骤無法执行），不支援单独重試，需使用整体 重試部署 功能。

# 設定範本

Q1：如何基于现有範本快速建立新範本？

点击目标範本行末 更多 → 複製，系統会自动建立一个副本，名稱追加 _copy 后缀。进入詳情页修改内容后儲存即可。

Q2：默认範本有什么作用？

默认範本在建立部署任务时会被自动選中。每个叢集類型只能有一个默认範本，新设为默认时会自动取消同類型下其他範本的默认标记。

Q3：系統範本可以修改吗？

不可以。系統範本为平台内置，不可編輯、不可刪除。如需调整，请先複製系統範本生成使用者範本，再对使用者範本进行修改。

Q4：匯入 ZIP 檔案的格式要求是什么？

ZIP 檔案内需包含範本檔案夹，每个檔案夹对应一个設定範本，檔案夹内应包含範本元資料檔案和配置内容檔案。具体格式可参考匯出的範本 ZIP 檔案结构。

Q5：範本内容中的 Jinja2 语法有什么作用？

Jinja2 範本语法用于在部署时动态替换变量。例如 会在部署时根据实际参数替换为具体的 Broker ID。使用範本变量可以实现一套範本适配不同部署场景。

Q6：可以修改範本的叢集類型吗？

不可以。叢集類型在建立範本时确定，建立后不可修改。如需更换叢集類型，请複製範本后重新选择。

Q7：刪除範本会影响已部署的叢集吗？

不会直接影响已部署叢集的运行。但刪除后，基于该範本的線上設定可能無法正常同步或復原。刪除前请確認该範本不再被引用。

# 線上設定

Q1：新增配置时"目标叢集"下拉框为空怎么办？

请確認：

  • 已选择叢集類型
  • 该叢集類型下已有成功部署的叢集
  • 当前使用者有该叢集的查看權限

Q2：同步狀態顯示"同步失敗"，如何排查？

请依次检查：

  • 目标伺服器是否線上，網路是否可达
  • 伺服器代理（BBX）是否正常运行
  • 配置路徑是否有写入權限
  • 配置内容是否包含非法字符或格式錯誤

Q3：編輯儲存后同步狀態为什么变成"未同步"？

这是正常行为。每次編輯儲存后，平台中的配置内容已更新，但尚未推送到伺服器，因此狀態重置为"未同步"。需要手动执行"同步"操作将新内容推送到伺服器。

Q4：復原配置会自动同步到伺服器吗？

復原操作默认仅復原平台中的配置内容，不会自动同步到伺服器。復原后狀態为"未同步"，需要手动执行同步操作。如需復原后立即同步，可在復原时选择自动同步选项。

Q5：可以修改配置的目标節點吗？

不可以。配置与目标節點的綁定关系在建立时确定，不可修改。如需将相同配置应用到其他節點，请新建一条線上設定记录。

Q6：配置路徑可以手动修改吗？

可以。新增配置时路徑会根据節點程式目錄自动填充，但支援手动修改为其他合法路徑。请确保路徑在目标伺服器上存在且有写入權限。

# 采集目标

Q1：新增采集目标后为什么抓取狀態顯示"未知"？

Prometheus 抓取有週期性，新增目标后需要等待 Prometheus 下一次抓取週期执行后才会更新抓取狀態。也可点击"立即同步"加速配置生效。

Q2：同步狀態顯示"失敗"怎么办？

请依次检查：

  • Prometheus 服務是否正常运行
  • 平台与 Prometheus 之间的網路是否连通
  • 鼠标悬停同步狀態，查看具体的失敗原因提示
  • 检查 Prometheus 設定目錄的写入權限

Q3：抓取狀態顯示"異常"怎么办？

请依次检查：

  • 目标位址是否可达，網路是否连通
  • 目标端点的 /metrics 接口是否正常工作（可用瀏覽器或 curl 直接访问驗證）
  • 認證資訊是否填寫正确（Basic Auth 的使用者名密碼、Bearer Token、TLS 憑證等）
  • 目标端点是否开启了访问限制（如 IP 白名单、防火牆等）

Q4：Basic Auth 和 Bearer Token 有什么区别？

  • Basic Auth：HTTP 标准認證方式，通过使用者名和密碼进行認證，适用于大多数支援 HTTP Basic 認證的端点
  • Bearer Token：通过 Token 字符串进行認證，适用于需要传递 API Token 的端点

根据目标端点的实际認證要求选择对应方式。

Q5：匯入配置时支援什么格式？

仅支援 ZIP 格式檔案。ZIP 包内需包含符合 Prometheus 抓取配置规范的 YAML 檔案，系統会自动解析并转换为平台采集目标记录。

Q6：关闭采集目标后历史資料会丢失吗？

不会。关闭只是停止新的抓取，已采集到 Prometheus 中的历史監控資料仍然保留，可在 Grafana 或警報模块中正常查詢。

# 警報規則

Q1：同步狀態一直顯示"未同步"怎么办？

  • 確認規則狀態为"开启"，只有开启狀態的規則才会被同步
  • 点击 立即同步 手动触发同步
  • 检查 Prometheus 服務是否正常运行，網路是否可达
  • 悬停同步狀態標籤查看具体錯誤資訊

Q2：PromQL 表达式如何驗證？

  • 在建立/編輯規則的 PromQL 編輯器中輸入表达式
  • 点击編輯器下方的 试运行 按鈕
  • 系統会即时执行查詢并返回结果，顯示匹配序列数和当前值
  • 若表达式有误，试运行会返回錯誤提示

Q3：使用自定义 PromQL 和指標名 + 阈值有什么区别？

  • 指標名 + 阈值：适合简单的阈值警報场景，平台自动组装为完整 PromQL 表达式
  • 自定义 PromQL：适合复杂警報场景，如多指標组合、聚合运算、正規表達式比對等，需自行编写完整表达式

Q4：匯入規則时提示"檔案内容不是有效的 JSON 格式"？

  • 请確認上傳的檔案为标准的 JSON 格式
  • 检查檔案编码是否为 UTF-8
  • 可使用 JSON 格式化工具校验檔案内容

Q5：持續時間格式有什么要求？

  • 使用 Prometheus 标准時間格式，如 5m（5 分钟）、1h（1 小时）、30s（30 秒）
  • 表示指標持續满足阈值条件的最短時間，达到该時間后才觸發警報

Q6：標籤和注释有什么作用？

  • 標籤（Labels）：附加到警報事件中的元資料，可用于警報路由、分組、靜默等策略
  • 注释（Annotations）：警報的附加說明資訊，可在警報通知範本中引用，如警報摘要、详细描述等

# 系統元件

Q1：管控節點顯示"離線"，但实际服務还在运行？

管控節點狀態依赖心跳上報机制。若節點顯示離線，请检查：

  • 该節點所在伺服器的系統時間是否与其他節點一致（時間偏差会导致心跳逾時判断異常）
  • 節點间的網路是否连通
  • 管控服務进程是否正常运行

Q2：Prometheus 或 Alertmanager 顯示"離線"，如何排查？

  • 检查对应服務的进程是否正常运行
  • 检查平台配置中 Prometheus/Alertmanager 的位址配置是否正确（admq.monitor.prometheus-url、admq.alert.alertmanager.url）
  • 若啟用了認證，检查使用者名和密碼配置是否正确
  • 检查網路防火牆是否放行了对应連接埠

Q3：資料庫顯示"離線"，平台頁面还能正常访问？

資料庫健康检查与頁面访问使用的連接池是同一資料源。若資料庫顯示離線：

  • 可能是瞬时網路抖动，等待 30 秒自動重新整理后再次观察
  • 若持續離線，请检查資料庫服務是否正常运行
  • 检查資料庫連接配置（spring.datasource.url）是否正确

Q4：頁面資料为空，没有展示任何元件？

  • 检查管控節點表（admq_manager_node）中是否有節點记录
  • 检查平台監控模块是否正常运行
  • 尝试点击 重新整理 按鈕手动获取最新狀態

Q5：健康检查的重新整理頻率可以调整吗？

頁面展示每 30 秒自動重新整理一次，该頻率由后端定时任务控制，暂不支援通过界面调整。如需修改，请联系管理員调整后端配置。

# 警報总览

Q1："活跃警報"和"今日警報"有什么区别？

  • 活跃警報：当前仍处于"警報中"狀態的警報总数，即问题尚未解决
  • 今日警報：今日（从 00:00 开始）产生的所有警報，包含已復原和已抑制的

Q2："已抑制"和"靜默中"有什么区别？

  • 已抑制：警報被抑制規則（Inhibit Rule）合并处理，例如当父警報觸發时，子警報被抑制不再重复通知
  • 靜默中：警報处于靜默時段（Silence）内，该时段内匹配的警報不会产生通知，但警報本身仍被记录

Q3：为什么有些警報分組顯示"无摘要"？

警報摘要来源于警報規則中配置的摘要範本。若規則未設定摘要，或警報資料缺少对应標籤，则顯示"无摘要"。建議检查警報規則的配置是否完整。

Q4：如何查看某个分組内的具体警報？

点击该分組卡片即可进入分組詳情页，頁面会展示该分組下的所有警報清單，包括每条警報的详细資訊、狀態变化历史等。

Q5：篩選条件设置后没有返回预期结果？

请检查：

  • 時間范围是否覆盖了警報的触发時間
  • 狀態篩選是否匹配（例如已復原的警報不会出现在"警報中"篩選结果中）
  • 关键词是否拼写正确，关键词搜尋范围包括警報摘要和標籤内容
  • 点击 查詢 按鈕確認篩選条件已生效

Q6：统计卡片的数字和趋势图为什么不一致？

统计卡片展示的是当前即時資料（活跃警報、今日警報等），而趋势图展示的是近 24 小时的历史資料分布。趋势图的資料点统计的是该小时内产生的警報总数，与"活跃警報"的即時计数口径不同。

# 路由策略

Q1：警報没有按预期路由到指定接收器？

请依次检查：

  • 路由策略的比對條件是否正确，欄位名和值是否与警報標籤一致
  • 优先级设置是否合理，高优先级的路由是否提前拦截了该警報
  • "比對後繼續"是否开启，未开启时命中即停止，后续路由不再检查
  • 接收器名稱是否在 Alertmanager 中已正确定义

Q2：优先级如何设置比较合理？

  • 建議将最精确、最具体的匹配規則设为较高优先级（数值较小）
  • 通用兜底規則设为较低优先级（数值较大）
  • 預設路由优先级为 0，始终最后匹配

Q3：分組欄位必须包含 cluster,alertname,severity 吗？

分組欄位为空时不做强制要求；一旦填寫了分組欄位，则必须包含 cluster、alertname、severity 这三个基礎欄位，以确保警報分組的唯一性和一致性。

Q4：可以建立多少条路由策略？

系統未对路由策略数量做硬性限制，但建議根据实际警報分类需求合理规划，避免路由規則过于复杂导致维护困难。

Q5：修改路由策略后多久生效？

儲存后立即生效，后续触发的警報将按最新路由規則进行匹配和分发。

# 抑制規則

Q1：來源警報或目標警報不填寫条件会怎样？

不填寫任何比對條件时，表示匹配任意警報。例如：

  • 來源警報不填条件 + 目標警報填寫条件 = 只要系統中有任意警報存在，就抑制满足目标条件的警報
  • 建議谨慎使用空条件，避免过度抑制导致漏报

Q2：等同標籤（equalLabels）的作用是什么？

等同標籤用于限定"同一对象"的抑制范围。例如：

  • 设置 equalLabels = ["cluster", "instance"] 时，只有当來源警報和目標警報的 cluster 值相同 且 instance 值也相同时，才会触发抑制
  • 不设置等同標籤时，只要存在满足 sourceMatch 的警報，就会抑制所有满足 targetMatch 的警報（全局抑制）

Q3：多条抑制規則之间是什么关系？

多条抑制規則之间为独立生效关系。一条警報只要被任意一条規則抑制，就不会发送通知。規則按优先级排序评估。

Q4：狀態开关的作用是什么？

  • 开启：規則生效，满足条件时正常执行抑制
  • 关闭：規則不生效，不影响任何警報

可通过卡片右上角的开关快速切換狀態，无需編輯規則。

Q5：为什么儲存时提示"標籤名不符合 Prometheus 规范"？

请检查來源警報比對條件、目標警報比對條件中的標籤名，以及等同標籤中的標籤名，确保：

  • 不以数字开头
  • 只包含英文字母、数字和下划线
  • 不包含空格、连字符、句点等特殊字符

Q6：抑制規則会影响警報的历史记录吗？

不会。抑制規則仅影响警報的通知发送，被抑制的警報仍会在警報清單中展示，只是不会触发通知渠道（如邮件、短信、Webhook 等）。

# 靜默管理

Q1：靜默期间警報还会记录吗？

会。靜默規則仅屏蔽警報通知（如邮件、短信、Webhook 等），警報本身仍会被系統记录和统计。靜默结束后，您可以在警報歷史中查看靜默期间产生的警報。

Q2：多个靜默規則同时匹配一条警報会怎样？

只要警報匹配任意一条处于生效狀態的靜默規則，该警報的通知就会被屏蔽。多条規則之间为 OR 关系。

Q3：週期性規則的「生效星期」不填代表什么？

不填表示该規則在每周的每一天都生效，即全年无休地按配置的時段靜默。

Q4：可以編輯已建立的靜默規則吗？

目前版本暂不支援編輯，如需调整規則内容，请刪除后重新建立。

Q5：刪除週期性規則会影响当天已生效的靜默吗？

刪除操作立即生效。刪除后，当天剩余時段内匹配该規則的警報将復原正常通知。

Q6：为什么「已過期」页签里没有週期性規則？

週期性規則不会出现在「已過期」页签中。只有当週期性規則被手动刪除，或达到其设置的規則結束日期后，才会停止生效并从「週期性規則」页签中消失。

Q7：跨天的時間如何理解？

当每日結束時間早于開始時間时，表示靜默時段跨天。例如開始時間 22:00、結束時間 06:00，表示每天 22:00 到次日 06:00 期间警報被靜默。

# 通知範本

Q1：範本建立后为什么没有收到通知？

请依次检查：

  • 範本狀態是否为"啟用"
  • 範本綁定的事件類型是否正确
  • 通知渠道是否已設定并啟用（如邮件 SMTP、Webhook URL 等）
  • 当前使用者是否已訂閱对应事件類型（在"通知訂閱"頁面配置）

Q2：一个事件類型可以配置多个範本吗？

不建議。系統按事件類型匹配範本时，取第一个啟用的範本生效。若需调整通知内容，建議編輯现有範本而非新建。

Q3：範本变量写错了会怎样？

若使用了不存在的变量（如 ${wrongVar}），该占位符将保持原样輸出在通知内容中。建議建立範本后通过实际事件触发驗證效果。

Q4：通知渠道顯示为空怎么办？

通知渠道清單来源于"通知渠道管理"頁面中已啟用的渠道配置。若下拉清單为空，请先到 通知中心 → 通知渠道 中建立并啟用至少一个渠道。

Q5：匯入 JSON 檔案时提示"檔案解析失敗"？

请检查：

  • 檔案格式是否为标准 JSON
  • 檔案编码是否为 UTF-8
  • 是否包含必需的 templates 欄位
  • 字符串中的特殊字符是否正确转义

Q6：匯出檔案可以跨环境匯入吗？

可以。匯出的 JSON 檔案是平台无关的配置資料，可在不同环境之间遷移。但匯入后请检查渠道配置（如 SMTP 伺服器、Webhook URL）是否需要根据目标环境调整。

# 通知訂閱

Q1：为什么通知渠道下拉框为空？

请检查：

  • 是否已在"通知渠道配置"中建立了渠道（如邮件、Webhook）
  • 渠道配置的狀態是否为"啟用"
  • 渠道配置是否已完成参数填寫并通过測試

Q2：訂閱狀態为"啟用"但没有收到通知？

请依次检查：

  • 对应事件是否真实发生（可在"事件管理"中查看事件记录）
  • 通知規則是否配置了该事件類型（訂閱与規則需同时配置才能触发通知）
  • 通知範本是否存在且狀態为啟用
  • 如果是邮件/Webhook 渠道，检查渠道配置是否正确

Q3：同一使用者被多次訂閱同一事件会重复通知吗？

不会。平台会对同一事件、同一接收人去重，确保使用者只收到一次通知。

Q4："系統默认"訂閱和普通訂閱有什么区别？

  • 系統默认：作为兜底策略，当事件没有匹配到具体使用者/資源/角色訂閱时，按系統默认配置发送通知
  • 使用者/資源/角色：精准訂閱，优先级高于系統默认，事件发生时优先匹配精准訂閱

Q5：可以批量建立訂閱吗？

当前頁面暂不支援批量建立，需逐条添加。如需为多个使用者訂閱同一事件，建議通过"角色"類型訂閱，将使用者加入对应角色即可。

# 通知渠道

Q1：邮件測試发送失敗怎么办？

请依次检查：

  • SMTP 伺服器位址和連接埠是否正确
  • 使用者名和密碼是否正确，账号是否有发信權限
  • 发件人位址格式是否合法
  • 若使用 SSL，確認伺服器支援 SSL 且連接埠正确（通常为 465）
  • 检查 SMTP 伺服器是否对发件 IP 有白名单限制

Q2：Webhook 測試发送失敗怎么办？

请依次检查：

  • Webhook URL 是否可达，網路是否连通
  • 请求方法是否与接收方要求一致（通常为 POST）
  • Headers 中是否包含必要的認證資訊
  • Payload 格式是否符合接收方的接口规范
  • 使用 測試渲染 功能確認範本渲染结果正确**

Q3：可以修改渠道的编码吗？

不可以。编码是渠道的唯一标识，建立时确定后不可修改。如需更换编码，请刪除后重新建立。

Q4：Payload 自定义範本中的变量如何获取 event.context 中的欄位？

event.context 中的欄位可直接通过 ${欄位名} 引用，支援多级嵌套。例如：

  • 一级欄位：${clusterName}、${topicName}
  • 多级嵌套：${originInfo.ip}、${originInfo.port}

Q5：刪除渠道会影响已設定的通知範本吗？

会。若通知範本中引用了该渠道，刪除后该範本对应渠道的发送将失敗。建議先检查"通知範本管理"中各範本的渠道配置，確認无引用后再刪除。

Q6：站内訊息的保留期限是多久？

默认保留 30 天，超期的站内訊息将自动清理。管理員可通过全域設定项 notification.retention.days 调整保留天数。

# 使用者管理

Q1：使用者名稱建立后可以修改吗？

不可以。使用者名稱是账号的唯一标识，建立时确定后不可修改。如需更换，请刪除后重新建立。

Q2：为什么無法刪除某个使用者？

请確認：

  • 当前登入使用者不能刪除自己的账号
  • 该使用者没有正在使用的資源或令牌（如有，建議先清理相关資源）

Q3：管理員和普通使用者有什么区别？

  • 管理員：拥有平台管理權限，可执行使用者管理、角色分配、密碼重置等操作
  • 普通使用者：仅拥有被分配角色对应的操作權限，無法管理其他使用者

Q4：为什么分配角色时看不到内置角色？

内置角色（超級管理員、系統管理員、密钥管理員、安全审计员、MQ 管理員）由系統统一管理，不在使用者级别的角色分配范围内。如需调整内置角色綁定，请联系超級管理員。

Q5：重置密碼和修改密碼有什么区别？

操作 适用场景 是否需要当前密碼
修改密碼 使用者主动更换密碼 需要輸入当前密碼驗證
重置密碼 管理員帮助使用者復原密碼 不需要，直接重置为默认密碼

Q6：令牌的作用是什么？

令牌用于使用者在特定叢集下的資源访问認證。每个令牌關聯一个叢集，可用于訊息發布/消費等操作。令牌頁面可查看和管理该使用者在所有叢集下的访问令牌。

# 角色管理

Q1：系統预设角色可以刪除吗？

不可以。系統预设角色（超級管理員、MQ 管理員、系統管理員、安全保密员、安全审计员、普通使用者）是平台运行所需的基礎角色，不可刪除、不可修改名稱。

Q2：为什么有些角色没有「編輯」和「刪除」按鈕？

只有「自定义」角色支援編輯和刪除。系統预设角色的操作列仅顯示「功能表權限」按鈕，且进入后只能查看權限不能修改。

Q3：角色名稱可以修改吗？

自定义角色在建立后，角色名稱不可修改，仅支援修改描述資訊。如需更换名稱，建議刪除后重新建立。

Q4：刪除角色时提示"角色下存在使用者"怎么办？

需先将该角色下的所有使用者解绑（移除使用者或为使用者分配其他角色），然后再执行刪除。

Q5：普通使用者角色有什么權限？

普通使用者角色默认不綁定任何功能表權限。管理員可根据实际需要，通过「功能表權限」功能为其分配特定的功能访问權限。

Q6：功能表權限修改后何时生效？

儲存后立即生效。已登入的使用者需重新登入或重新整理頁面后，新的權限配置才会生效。

# 附录

# A. 术语表

术语 說明
ADMQ 基于 Apache Pulsar 的企業级訊息佇列
PromQL Prometheus 查詢语言，用于时序資料查詢
Jinja2 Python 範本引擎语法，用于設定範本变量替换
Alertmanager Prometheus 生态的警報管理元件
Scrape Prometheus 主动拉取監控指標資料的行为
Payload Webhook 通知的訊息体内容
RBAC 基于角色的访问控制（Role-Based Access Control）
ACL 访问控制清單（Access Control List）
BBX 伺服器代理程式，负责执行平台指令、采集指標、提供远程終端

# B. 快捷键

快捷键 功能
Enter 搜尋框中按 Enter 触发搜尋
Ctrl + 点击 多选表格行（部分頁面支援）

# C. 部署模式速查表

模式 适用類型 說明
单机部署 全部 单節點部署，适用于開發測試环境
叢集部署 ADMQ、Kafka、RabbitMQ 多節點分散式部署，提供高可用性能力
负载部署 ActiveMQ 多節點負載平衡部署
主从部署 全部 主從架構部署，主節點故障时從節點可接管

# D. 警報嚴重級別速查表

级别 标识 說明 典型场景
P0-緊急 红色 系統核心功能受损，需立即处理 叢集宕机、核心服務不可用、資料丢失风险
P1-嚴重 橙红色 重要功能異常，影响业务运行 節點故障、性能嚴重下降、关键資源耗尽
P2-警告 黄色 潜在风险或轻度異常，需关注 資源使用率偏高、配置異常、非核心功能異常
P3-提示 绿色 資訊性通知，供参考 常规狀態变化、计划内事件提醒
编辑页面 (opens new window)
#统一管控台使用者手册

← 发版说明→