迁移手册

# 前言

本文档为金蝶Apusic分布式消息队列for MQTT（Apusic Distributed Message Queue，简称：ADMQ for MQTT）的迁移手册，详细介绍了如何将现有MQTT Broker迁移到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. 出现异常及错误的日志、截图等详细信息

# 迁移概述

# 迁移原则

ADMQ for MQTT 完全兼容 MQTT 3.1、3.1.1、5.0 协议，迁移过程遵循以下原则：

  1. 零代码改造：客户端无需修改代码，仅需变更连接地址
  2. 配置兼容：支持标准 MQTT 客户端和配置参数
  3. 数据可迁移：支持用户、ACL 规则、保留消息等配置迁移
  4. 平滑切换：支持双写和灰度切换，降低迁移风险

# 迁移范围

迁移内容 是否支持 说明
应用代码 是 无需修改，仅需变更 Broker 地址
客户端配置 是 支持标准 MQTT 客户端
用户账号 是 支持内置数据库用户迁移
ACL 规则 是 支持 ACL 权限规则迁移
保留消息 是 支持保留消息迁移
监听器配置 是 支持 TCP/SSL/WebSocket 监听器配置
系统配置 部分 部分高级配置可能需要手动调整

# 迁移前检查

# 协议兼容性检查

原 MQTT Broker 兼容性 说明
EMQX 完全兼容 推荐迁移版本
Mosquitto 完全兼容 基础 MQTT 功能
HiveMQ 完全兼容 企业级 MQTT 功能
RabbitMQ MQTT Plugin 完全兼容 基础 MQTT 功能

# 客户端兼容性检查

客户端类型 兼容版本 说明
Eclipse Paho 1.2.x+ 完全兼容
MQTT.js 4.x+ 完全兼容
EMQX Client 5.x+ 完全兼容
其他标准 MQTT 客户端 - 完全兼容

# 迁移方案

# 方案一：双写迁移（推荐）

适用于不能停机的业务场景，通过双写保证数据一致性。

步骤：

  1. 部署 ADMQ for MQTT 集群

    • 按照安装手册部署新集群
    • 配置网络和防火墙

  2. 配置双写

    • 在应用中同时连接原 MQTT Broker 和 ADMQ for MQTT
    • 发布消息时同时发送到两个集群

  3. 同步配置

    • 在 ADMQ for MQTT 中创建用户、ACL 规则
    • 配置监听器、系统参数

  4. 切换订阅者

    • 先切换部分订阅者到 ADMQ for MQTT
    • 观察业务是否正常

  5. 全量切换

    • 确认无误后，切换所有订阅者
    • 停止向原 MQTT Broker 发送消息

  6. 下线原集群

    • 保留一段时间用于数据查询
    • 确认无问题后下线

# 方案二：停服迁移

适用于可以短暂停机的业务场景，迁移速度快。

步骤：

  1. 停止业务系统

    • 暂停所有 MQTT 客户端连接

  2. 导出原 Broker 配置

    • 导出用户、ACL 规则、保留消息等

  3. 迁移配置到 ADMQ for MQTT

    • 在管控台或命令行创建对应的资源

  4. 切换连接地址

    • 修改应用配置，指向 ADMQ for MQTT

  5. 启动业务系统

    • 恢复 MQTT 客户端连接

# 方案三：灰度迁移

适用于大规模系统，逐步迁移不同业务模块。

步骤：

  1. 按业务模块划分迁移批次
  2. 每批次按双写迁移方案执行
  3. 验证通过后迁移下一批次
  4. 全部完成后下线原集群

# 配置迁移

# 用户迁移

# 导出原 Broker 用户

# EMQX 示例
emqx ctl admins list
# 或使用 Dashboard 导出
1
2
3

# 在 ADMQ for MQTT 中创建用户

  1. 登录管控台
  2. 进入「用户」页面
  3. 创建内置数据库认证器（如未创建）
  4. 批量导入或逐个创建用户
  5. 点击「同步到 MQTT」

# ACL 规则迁移

# 导出原 Broker ACL 规则

# EMQX 示例
cat etc/acl.conf
1
2

# 在 ADMQ for MQTT 中创建 ACL 规则

  1. 登录管控台
  2. 进入「认证与授权」-「权限」页面
  3. 选择 built_in_database 授权源
  4. 逐个创建 ACL 规则
  5. 点击「同步到 MQTT」

# 监听器迁移

# 导出原 Broker 监听器配置

# EMQX 示例
cat etc/emqx.conf | grep listener
1
2

# 在 ADMQ for MQTT 中创建监听器

  1. 进入「监听器」页面
  2. 创建 TCP、SSL、WebSocket、WebSocket Secure 监听器
  3. SSL/WSS 类型需上传证书文件

# 保留消息迁移

# 使用客户端脚本迁移

对于小规模数据，可以编写客户端脚本迁移保留消息：

import paho.mqtt.client as mqtt

# 连接原 Broker
src_client = mqtt.Client(client_id="migrate-src")
src_client.connect("old-mqtt-broker", 1883, 60)

# 连接 ADMQ for MQTT
dst_client = mqtt.Client(client_id="migrate-dst")
dst_client.connect("admq-mqtt", 1883, 60)

# 订阅所有主题，接收保留消息
def on_message(client, userdata, msg):
    if msg.retain:
        # 转发到 ADMQ for MQTT
        dst_client.publish(msg.topic, msg.payload, qos=msg.qos, retain=True)
        print(f"Migrated retained message: {msg.topic}")

src_client.on_message = on_message
src_client.subscribe("#", qos=1)
src_client.loop_forever()
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

# 客户端迁移

# 连接地址变更

仅需修改应用配置文件中的 Broker 地址：

# 原配置
mqtt.broker=old-mqtt-broker
mqtt.port=1883

# 新配置
mqtt.broker=admq-mqtt
mqtt.port=1883
1
2
3
4
5
6
7

# SSL/TLS 配置变更

如果启用了 SSL，需要更新证书：

# 原配置
mqtt.ssl.ca-file=/path/to/old-ca.pem

# 新配置
mqtt.ssl.ca-file=/path/to/admq-ca.pem
1
2
3
4
5

# 常见客户端配置

# Java (Spring Boot)

spring:
  mqtt:
    host: admq-mqtt
    port: 1883
    username: device-service
    password: your-password
    client-id: spring-client-001
1
2
3
4
5
6
7

# Python

client = mqtt.Client(client_id="app-001")
client.username_pw_set("device-service", "your-password")
client.connect("admq-mqtt", 1883, 60)
1
2
3

# JavaScript

const client = mqtt.connect('mqtt://admq-mqtt:1883', {
    clientId: 'web-client-001',
    username: 'device-service',
    password: 'your-password'
});
1
2
3
4
5

# 迁移验证

# 功能验证

验证项 验证方法
连接测试 使用客户端连接 ADMQ for MQTT，确认能正常建立连接
消息发布 发送测试消息，确认能成功到达 Broker
消息订阅 启动订阅者，确认能正常接收消息
QoS 1/2 测试 QoS 1/2 消息投递和确认
保留消息 发送保留消息，确认新订阅者能立即收到
遗嘱消息 模拟异常断开，确认遗嘱消息被发布
ACL 权限 测试允许/拒绝规则是否生效
集群功能 验证节点故障时是否能自动切换

# 性能验证

验证项 验证方法
并发连接 测试大量客户端并发连接
消息吞吐 测试消息发布/订阅速率
延迟 测量消息从发布到接收的延迟
稳定性 长时间运行测试，观察是否有异常

# 回滚方案

如果迁移过程中出现问题，需要回滚到原 MQTT Broker：

  1. 停止向 ADMQ for MQTT 发送消息
  2. 切换连接地址回原 MQTT Broker
  3. 同步 ADMQ for MQTT 中的新消息回原集群（如有需要）
  4. 恢复业务系统

# 回滚检查清单

  • [ ] 原 MQTT Broker 仍在运行
  • [ ] 原集群数据未被删除
  • [ ] 应用配置可快速切换
  • [ ] 业务系统支持快速回滚

# 迁移最佳实践

  1. 充分测试：在测试环境完成完整迁移流程验证
  2. 备份数据：迁移前备份原集群配置和数据
  3. 监控迁移过程：实时监控迁移过程中的各项指标
  4. 制定回滚计划：确保在出现问题时能快速回滚
  5. 选择低峰期：在业务低峰期执行迁移操作
  6. 逐步切换：先切换非核心业务，验证无误后再切换核心业务
  7. 保留原集群：迁移完成后保留原集群一段时间，以备查询
编辑页面 (opens new window)
#迁移手册

← 运维手册→