迁移手册

# 前言

本文档为金蝶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)
#迁移手册

← 运维手册→