管控台用户手册

# 前言

本文档为金蝶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)
#管控台用户手册

← 消息引擎用户手册→