前言

本文档为金蝶Apusic分布式消息队列for MQTT（Apusic Distributed Message Queue，简称：ADMQ for MQTT）的快速使用手册，提供产品介绍，安装部署产品的基本步骤及验证方式。

适用对象

本文档适用于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. 出现异常及错误的日志、截图等详细信息

快速入门

流程概览

第1步：创建认证器与授权源
            │
            ↓
第2步：创建用户 ──┐
                  ├──→ 第4步：配置 ACL 权限
第3步：创建主题 ──┘            │
                               ↓
        第5步：发送测试消息验证通路 ──→ 第6步：接入业务代码

---

第1步：创建认证器与授权源

MQTT 用户和 ACL 规则分别依赖认证器和授权源。首次使用 MQTT 集群时，需要先创建内置数据库认证器和授权源。

1. 进入 认证与授权 页面（左侧菜单：消息中间件 → ADMQ MQTT → 认证与授权）
2. 在 认证器 标签页点击 "新增" 按钮
3. 填写：
   • 名称：built_in_database
   • 认证方式：内置数据库
   • 描述：MQTT 内置数据库认证器
4. 点击 "确认"
5. 切换到 授权源 标签页，点击 "新增" 按钮
6. 填写：
   • 名称：built_in_database
   • 授权方式：内置数据库
   • 描述：MQTT 内置数据库授权源
7. 点击 "确认"

为什么先做这一步？ 后续创建的用户必须绑定到认证器，ACL 规则必须绑定到授权源；没有认证器和授权源，用户和权限页面将无法选择对应的来源。

---

第2步：创建用户

为"设备上报系统"创建专用的 MQTT 用户：

1. 进入 用户 页面（左侧菜单：消息中间件 → ADMQ MQTT → 用户）
2. 点击 "新增" 按钮
3. 填写：
   • 认证器：选择已创建的 built_in_database 认证器
   • 用户名：device-service
   • 密码：设置一个安全密码
   • 是否超级用户：否
   • 描述：设备上报系统服务账号
4. 点击 "确认"

普通业务账号建议不开启超级用户。超级用户会绕过所有 ACL 检查。

---

第3步：创建主题

主题是 MQTT 中消息的分类单元。为设备上报创建主题：

1. 进入 主题 页面（左侧菜单：消息中间件 → ADMQ MQTT → 主题）
2. 点击 "新增" 按钮
3. 填写：
   • Topic：sensor/+/temperature
   • 默认 QoS：1
   • 是否保留消息：否
   • 描述：设备温度上报主题
4. 点击 "确认"

主题通配符说明：+ 匹配单个层级，因此 sensor/+/temperature 可以匹配 sensor/living-room/temperature，但不能匹配 sensor/living-room/bedroom/temperature（后者需用 #）。

---

第4步：配置 ACL 权限

为用户分配发布/订阅主题的权限：

1. 进入 权限 页面（左侧菜单：消息中间件 → ADMQ MQTT → 权限）
2. 确保顶部已选择 built_in_database 授权源
3. 点击 "新增" 按钮
4. 填写：
   • 主体类型：用户名
   • 用户名：device-service
   • 权限：允许
   • 动作：全部（允许发布和订阅）
   • 主题：sensor/#
   • QoS：-1（不限制）
   • Retain：-1（不限制）
   • 描述：设备服务可读写 sensor 下所有主题
5. 点击 "确认"

生效说明：ACL 规则保存后会自动生效，无需再点击"同步到 MQTT"。

---

第5步：发送测试消息验证通路

在接入业务代码前，先用平台内置的发送功能验证消息通路是否正常：

1. 进入 主题 页面
2. 在 sensor/+/temperature 行点击 "发送消息"
3. 填写：
   • Payload：{"deviceId":"D001","temperature":24.5}
   • QoS：1
   • Retain：否
4. 点击 "确认发送"
5. 进入 保留消息 页面（若 Retain 为否则不会在此出现），或进入 客户端 页面查看是否有测试客户端在线

验证通过的标志：消息发送成功且无权限拒绝提示，说明用户认证和 ACL 配置已生效。

---

第6步：接入业务代码

平台侧的资源已准备就绪，接下来在您的应用程序中接入 MQTT 客户端：

连接参数：

参数	值	获取方式
Broker 地址	集群节点 IP	管理员提供
端口	1883（TCP）	监听器管理页面查看
用户名	device-service	第2步创建
密码	您设置的密码	第2步设置
ClientID	业务自定义	保证全局唯一

生产者示例（Java + Eclipse Paho）：

import org.eclipse.paho.client.mqttv3.MqttClient;
import org.eclipse.paho.client.mqttv3.MqttMessage;

MqttClient client = new MqttClient("tcp://localhost:1883", "publisher-001");
org.eclipse.paho.client.mqttv3.MqttConnectOptions options = new org.eclipse.paho.client.mqttv3.MqttConnectOptions();
options.setUserName("device-service");
options.setPassword("your-password".toCharArray());
client.connect(options);

MqttMessage message = new MqttMessage("{\"deviceId\":\"D001\",\"temperature\":24.5}".getBytes());
message.setQos(1);
client.publish("sensor/D001/temperature", message);

client.disconnect();
client.close();

消费者示例（Java + Eclipse Paho）：

MqttClient client = new MqttClient("tcp://localhost:1883", "subscriber-001");
org.eclipse.paho.client.mqttv3.MqttConnectOptions options = new org.eclipse.paho.client.mqttv3.MqttConnectOptions();
options.setUserName("device-service");
options.setPassword("your-password".toCharArray());
client.connect(options);

client.subscribe("sensor/+/temperature", 1);
client.setCallback(new org.eclipse.paho.client.mqttv3.MqttCallback() {
    public void messageArrived(String topic, MqttMessage message) {
        System.out.println("收到消息: " + topic + " -> " + new String(message.getPayload()));
    }
    public void connectionLost(Throwable cause) {}
    public void deliveryComplete(org.eclipse.paho.client.mqttv3.IMqttDeliveryToken token) {}
});

---

后续运维操作

业务接入后，日常可通过以下功能进行运维管理：

运维场景	操作路径	说明
查看在线客户端	客户端管理	查看客户端 ID、用户名、IP、连接时间
强制下线异常客户端	客户端行 → "断开连接"	立即断开指定连接
查看消息堆积	Topic 监控 / 监控大盘	关注流入/流出/丢弃数量
排查消费延迟	慢订阅管理	查看消息投递耗时较长的订阅
处理保留消息	保留消息管理	查看或删除不再需要的保留消息
查看系统告警	监控与统计 → 告警	查看 CPU/内存/连接数异常等告警
调整认证授权	认证与授权	修改认证器、授权源、ACL 规则

---

小结

完成上述 6 步后，您已经：

• ✅ 创建了 MQTT 内置数据库认证器和授权源
• ✅ 创建了专用的 MQTT 业务用户
• ✅ 创建了设备上报主题
• ✅ 配置了细粒度的 ACL 访问控制
• ✅ 验证了消息通路的正确性
• ✅ 将配置参数接入到业务代码中

这是使用 MQTT 的最小可用闭环。后续可根据业务需要，在此基础上扩展更多主题、用户、ACL 规则，或配置监听器、系统参数实现更丰富的功能。

各功能的详细说明请参阅同目录下的其他文档。