遷移手冊

# 前言

本文檔為金蝶Apusic分散式訊息佇列for RocketMQ（Apusic Distributed Message Queue for RocketMQ，簡稱：ADMQ for RocketMQ）的遷移手冊，詳細介紹了如何將RocketMQ遷移到ADMQ for RocketMQ。

# 適用對象

本文檔適用於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. 出現異常及錯誤的日誌、截圖等詳細資訊

# 流程簡圖

遷移前狀態

遷移前狀態

搭建新RocketMQ服務

搭建新RocketMQ服務

關閉老Broker寫入權限

更換使用新的NameSrv位址

更換使用新的NameSrv位址

新Broker移除老NameSrv位址

新Broker移除老NameSrv位址

遷移後狀態

下線老RocketMQ服務

# 遷移概述

# 遷移原則

ADMQ for RocketMQ 完全相容 RocketMQ 的協定和用戶端，遷移過程遵循以下原則：

  1. 零程式碼改造：用戶端無需修改程式碼，僅需變更 NameServer 位址
  2. 配置相容：支援 RocketMQ 原生配置參數
  3. 資料可遷移：支援 Topic 配置和訊息資料遷移
  4. 平滑切換：支援雙寫和灰階切換，降低遷移風險

# 遷移範圍

遷移內容 是否支援 說明
應用程式碼 是 無需修改，僅需變更 NameServer 位址
用戶端配置 是 支援 RocketMQ 原生用戶端
Topic 定義 是 支援 Topic 建立和配置遷移
消費者組 是 支援消費者組配置遷移
使用者權限 是 支援 ACL 配置遷移
訊息資料 是 支援歷史訊息遷移
消費位點 是 支援消費進度遷移
訊息軌跡 是 支援訊息軌跡配置

# 遷移前檢查

# 版本相容性檢查

原 RocketMQ 版本 相容性 說明
4.9.x 完全相容 推薦遷移版本
5.0.x~5.3.x 完全相容 推薦遷移版本

# 用戶端相容性檢查

用戶端類型 相容版本 說明
Java 4.9.x - 5.3.x 完全相容
Go 2.x 完全相容
Python 0.4.x 完全相容
C/C++ 2.x 完全相容

# 遷移方案

# 方案一：雙寫遷移（推薦）

適用於不能停機的業務場景，透過雙寫保證資料一致性。

步驟：

  1. 部署 ADMQ for RocketMQ 叢集

    • 按照安裝手冊部署新叢集
    • 配置網路和防火牆

  2. 配置雙寫

    • 在應用中同時連接原 RocketMQ 和 ADMQ for RocketMQ
    • 發送訊息時同時發送到兩個叢集

  3. 同步歷史資料

    • 使用訊息回溯功能同步歷史訊息
    • 驗證資料一致性

  4. 切換消費者

    • 先切換部分消費者到 ADMQ for RocketMQ
    • 觀察業務是否正常

  5. 全量切換

    • 確認無誤後，切換所有消費者
    • 停止向原 RocketMQ 發送訊息

  6. 下線原叢集

    • 保留一段時間用於資料查詢
    • 確認無問題後下線

# 方案二：停服遷移

適用於可以短暫停機的業務場景，遷移速度快。

步驟：

  1. 停止生產者

    • 暫停業務系統向 RocketMQ 發送訊息

  2. 導出配置

    • 使用 mqadmin 導出 Topic、消費者組等配置

  3. 遷移配置到 ADMQ for RocketMQ

    • 在管控台或命令列建立對應的資源

  4. 遷移訊息資料

    • 使用訊息查詢和發送工具遷移訊息

  5. 切換 NameServer 位址

    • 修改應用配置，指向 ADMQ for RocketMQ

  6. 啟動生產者

    • 恢復業務系統訊息發送

# 配置遷移

# 導出原 RocketMQ 配置

# 使用導出命令，導出對應的配置和中繼資料
./bin/mqadmin exportConfigs -n {nameserver位址及埠號} -c {RocketMQ叢集名稱} -f {導出的中繼資料檔案的存放路徑}
./bin/mqadmin exportMetadata -n {nameserver位址及埠號} -c {RocketMQ叢集名稱} -f {導出的中繼資料檔案的存放路徑}
1
2
3

# 在 ADMQ for RocketMQ 中建立配置

# 使用管控台匯入中繼資料

  1. 登入管控台
  2. 進入「中繼資料匯入」頁面
  3. 建立中繼資料匯入任務，匯入對應的中繼資料

# 資料遷移

# 使用訊息回溯遷移

RocketMQ 支援按時間回溯消費訊息，可用於資料遷移。

// 從原叢集消費歷史訊息並發送到新叢集
DefaultLitePullConsumer consumer = new DefaultLitePullConsumer("migrate-group");
consumer.setNamesrvAddr("old-rocketmq:9876");
consumer.subscribe("test-topic", "*");
consumer.setConsumeFromWhere(ConsumeFromWhere.CONSUME_FROM_FIRST_OFFSET);
consumer.start();

DefaultMQProducer producer = new DefaultMQProducer("migrate-group");
producer.setNamesrvAddr("admq-rocketmq:9876");
producer.start();

while (true) {
    List<MessageExt> msgs = consumer.poll();
    for (MessageExt msg : msgs) {
        Message newMsg = new Message(msg.getTopic(), msg.getTags(), msg.getKeys(), msg.getBody());
        producer.send(newMsg);
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# 使用 mqadmin 導出匯入

# 導出訊息（按時間範圍）
bin/mqadmin printMsg -n localhost:9876 -t test-topic -s "2026-01-01#00:00:00:000" -e "2026-01-02#00:00:00:000" > messages.txt

# 使用指令碼解析並發送到新叢集
# 需要自行編寫指令碼解析訊息內容並發送
1
2
3
4
5

# 用戶端遷移

# NameServer 位址變更

僅需修改應用設定檔中的 NameServer 位址：

# 原配置
rocketmq.namesrv.addr=old-rocketmq:9876

# 新配置
rocketmq.namesrv.addr=admq-rocketmq:9876
1
2
3
4
5

# 常見用戶端配置

# Java (Spring Boot)

rocketmq:
  name-server: admq-rocketmq:9876
  producer:
    group: test-group
  consumer:
    group: test-group
1
2
3
4
5
6

# Go

producer, err := golang.NewProducer(
    golang.WithEndpoints("admq-rocketmq:9876"),
    golang.WithConsumerGroup("test-group"),
)
1
2
3
4

# 遷移驗證

# 功能驗證

驗證項 驗證方法
連線測試 使用用戶端連線 ADMQ for RocketMQ，確認能正常建立連線
訊息發送 發送測試訊息，確認能成功到達 Broker
訊息消費 啟動消費者，確認能正常接收和處理訊息
順序訊息 發送順序訊息，確認消費順序正確
延時訊息 發送延時訊息，確認按時投遞
事務訊息 發送事務訊息，確認事務一致性

# 效能驗證

驗證項 驗證方法
吞吐量 對比原叢集和新叢集的訊息發送速率
延遲 測量訊息從發送到消費的延遲
並發 測試多生產者、多消費者並發場景
穩定性 長時間運行測試，觀察是否有異常

# 資料一致性驗證

# 對比原叢集和新叢集的 Topic 訊息數
bin/mqadmin topicStatus -n old-rocketmq:9876 -t test-topic
bin/mqadmin topicStatus -n admq-rocketmq:9876 -t test-topic

# 對比消費者進度
bin/mqadmin consumerProgress -n old-rocketmq:9876 -g test-group
bin/mqadmin consumerProgress -n admq-rocketmq:9876 -g test-group
1
2
3
4
5
6
7

# 回滾方案

如果遷移過程中出現問題，需要回滾到原 RocketMQ 叢集：

  1. 停止向 ADMQ for RocketMQ 發送訊息
  2. 切換 NameServer 位址回原 RocketMQ
  3. 同步 ADMQ for RocketMQ 中的新訊息回原叢集（如有需要）
  4. 恢復業務系統
编辑页面 (opens new window)
#遷移手冊

← 維運手冊→