遷移手冊

# 前言

本文檔為金蝶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)
#遷移手冊

← 維運手冊→