管控台用户手册

# 前言

本文档为金蝶 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 地址或域名。

ADMQ 管控台登录页面

# 登录流程

  1. 打开浏览器，访问上述地址。
  2. 在登录页面输入用户名和密码。
  3. 单击登录按钮，验证通过后进入系统管理首页。
  4. 若密码错误超过限制次数，账号可能会被临时锁定，请联系管理员处理。

# 默认账号与密码修改

系统预置默认管理员账号为 admq。首次登录后，建议按以下步骤修改密码：

  1. 单击右上角用户头像，选择个人设置或修改密码。
  2. 输入原密码及新密码，确认新密码。
  3. 单击保存，完成密码修改。

建议密码长度不小于 8 位，同时包含大小写字母、数字及特殊字符，并定期更换。

# 权限与角色

ADMQ 管控台支持基于角色的访问控制，常见角色包括：

  • 系统管理员：拥有全部权限，包括集群接入、用户管理、License 管理等。
  • 运维人员：可管理集群、Topic、订阅组、消息查询及监控大盘等日常运维资源。
  • 只读用户：仅可查看资源与监控数据，无法执行创建、修改、删除等变更操作。

# 集群管理

# 查看集群列表

  1. 登录管控台，点击左侧菜单集群管理。
  2. 在集群列表中可以查看所有已创建的 RocketMQ 集群。
  3. 列表显示：集群名称、状态、Broker 数、版本、创建时间等信息。

集群列表页面

# 创建集群

  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. 在新建命名空间对话框，设置命名空间的相关属性配置。

    创建命名空间对话框

    • 命名空间名称：设置命名空间的名称（创建后不可修改），3-32 个字符，只能包含字母、数字及“_”和“-”。

    • 命名空间描述：命名空间的备注说明。

  4. 单击保存完成所在集群命名空间的创建。

后续步骤：接下来就可以在该命名空间中创建 Topic 进行消息的生产和消费。

# 修改命名空间

如果需要重新修改编辑，可以通过以下步骤操作：

  1. 在命名空间列表页，单击操作列的编辑，进入编辑页面。
  2. 修改说明，单击保存完成修改。

# 删除命名空间

如果想删掉创建的命名空间，可以通过以下步骤操作：

  1. 在命名空间列表页，单击操作列的删除。
  2. 在删除的确认弹框中，单击确认，即可删除命名空间。

当命名空间内有 Topic 时，该命名空间不可被删除。

# 主题管理

# 操作场景

Topic 是 ADMQ RocketMQ 中的核心概念。Topic 通常用来对系统生产的各类消息做一个集中的分类和管理。

在实际应用场景中，一个 Topic 往往代表着一个业务聚合，由开发者根据自身系统设计、数据架构设计来决定如何设计不同的 Topic。

# 创建 Topic

  1. 登录 ADMQ 控制台，单击目标集群的进入业务功能进入集群基本信息页面。

  2. 单击主题页签，选择命名空间后，单击新建进入创建 Topic 页面。

  3. 在新建 Topic 对话框中，填写以下信息。

    创建 Topic 对话框

    • Topic 名称：填写 Topic 名称（创建后不可修改），3-64 个字符，只能包含字母、数字、“-”及“_”。

    • 类型：选择消息类型，包括：普通、全局顺序、局部顺序。

    • 队列数：选择队列数量。多队列分区可以提高单 Topic 的生产消费性能，但是无法保证顺序性。

    • broker：选择创建主题的 broker 节点。

    • 描述：填写 Topic 的说明信息。

  4. 单击确认，在 Topic 列表中即可看见创建好的 Topic。

# 查看主题详情

  1. 在 Topic 列表中，单击目标 Topic 的名称，进入主题详情页面，可以查看主题的基本信息和队列的消费情况。

    主题详情页面

# 列表查询 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. 填写订阅组相关信息。

    创建订阅组对话框

    • 订阅组名称：填写订阅组名称（创建后不可修改），3-64 个字符，只能包含字母、数字、“-”及“_”。

    • broker：订阅组创建的 broker 节点。

    • 描述：填写订阅组说明。

    • 高级设置：

      • 开启消费：关闭后订阅组下的所有消费会暂停，重新开启可继续消费。
      • 开启广播模式：关闭后订阅组下的所有声明为广播模式的消费者会暂停，重新开启可继续消费。

  4. 单击提交，完成订阅组创建。

# 查看消费者详情

  1. 单击订阅组列表，展示订阅组的列表，显示客户端协议（目前仅支持 TCP 协议）、在线生产者数、在线消费者数、广播消费。

    订阅组列表页面

  2. 单击订阅组的名称，进入订阅组详情页面，可以看到订阅组的基本信息和连接的客户端信息。

    • 订阅关系：订阅组和主题的订阅关系。
    • 生产者客户端：展示生产者客户端信息。
    • 消费者客户端：展示消费者客户端信息。

    订阅组详情页面

# 重置消费位点

  1. 在订阅组列表中，单击目标订阅组操作列的重置消费位点。

  2. 在弹窗中，可以选择从最新位点开始或者按从指定时间点开始设定 Topic 的消费位移 offset（即指定该订阅下的消费者从哪里开始消费消息）。

  3. 单击提交，完成设置。

    重置消费位点弹窗

# 订阅组同步

在订阅组列表中，左上角单击同步，同步自动创建的订阅组和通过命令创建的订阅组（如果不手动主动同步，一般 5 分钟定时任务同步）。

订阅组同步按钮

# 编辑订阅组

  1. 在订阅组列表中，单击目标订阅组操作列的编辑。

  2. 在弹窗中，对订阅组信息和是否开启广播消费进行编辑。

  3. 单击提交，完成修改。

    编辑订阅组弹窗

# 删除订阅组

删除 Group 后，由该 Group 标识的消费者将立即停止接收消息，该 Group 下的所有配置将会被清空，且无法恢复，请您谨慎执行该操作。

  1. 在 Group 列表中，找到需要删除的订阅组，单击操作列的删除。
  2. 在弹出的提示框中，单击提交，完成删除。

# 消息查询

# 查询消息

# 进入查询页面

  1. 登录 ADMQ RocketMQ 控制台，在左侧导航栏单击消息查询。

  2. 在消息查询页面，选择好命名空间后根据页面提示输入查询条件。

    • 时间范围：选择需要查询的时间范围，一般默认 2 小时，也可以自定义时间范围。
    • 命名空间：选择需要查询的 Topic 所在的命名空间。
    • 主题：选择需要查询的 Topic。
    • 查询方式：消息查询功能支持三种查询方式。

    消息查询条件区域

# 按主题查询

选择按主题查询，直接展示该主题的相关消息信息，适用于查看某段时间内 Topic 的全部消息。

# 按消息 ID 查询

选择按消息 ID 查询，该方式属于精确查询，速度快、精确匹配，适用于已记录消息 ID 的场景。

# 按消息 Key 查询

选择按消息 Key 查询，该方式属于模糊查询，适用于您没有记录消息 ID 但是设置了消息 Key 的场景。

# 消息详情

  1. 单击查询，下方列表会展示所有查询到的结果并分页展示。

    消息查询结果列表

    消息查询结果详情

  2. 找到您希望查看内容或参数的消息，单击操作列的查看详情，即可查看消息的基本信息、内容（消息体）以及参数。

    消息详情页面

# 死信队列

# 操作场景

死信队列是一种特殊的消息队列，用于集中处理无法被正常消费的消息的队列。当消息在达到一定重试次数后仍未能被正常消费，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 精确定位到任意一条消息。

  3. 单击查询，下方列表会展示所有查询到的结果并分页展示。

    死信消息查询结果

  4. 找到您希望查看内容或参数的消息，单击操作列的查看详情，即可查看消息的基本信息、内容（消息体）以及参数。

    死信消息详情页面

  5. 单击操作列的重新发送，将会对死信消息重新发送。

# 集群通道

# 跨集群数据复制和同步

通过 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. 单击新建任务创建对应的导入任务，导入对应的数据文件。

    创建元数据导入任务

  3. 点击提交导入，创建对应的元数据导入任务。

# 查看任务状态

任务创建成功后，进入任务列表查看任务进度。如果数据过多时，任务需要加载一段时间。

元数据导入任务状态

# 监控大盘

# 监控说明

ADMQ RocketMQ 管控台的监控大盘从 Broker 与 NameServer 采集运行时指标，提供集群、节点、主题、消费者四个维度的监控视图，帮助用户掌握消息收发速率、吞吐量、磁盘使用、消费延迟等关键运行状态。

监控大盘概览

# 时间范围选择

页面顶部提供时间范围选择器，支持快捷选项（最近 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)
#管控台用户手册

← 消息引擎用户手册→