云消息队列 RocketMQ 版：迁移上云操作

前提条件

• 创建消息队列RocketMQ版5.0系列实例

• 创建服务关联角色

  • 角色名称：AliyunServiceRoleForRMQMigration

  • 权限策略：AliyunServiceRolePolicyForRMQMigration

  • 权限说明：允许云消息队列 RocketMQ 版使用该角色获取访问专有网络VPC的权限。

注意事项

在迁移之前，请检查源集群是否存在定时消息。迁移任务完成后，所有生产和消费的路由将被切换到目标集群，可能会造成部分定时消息、失败重试消息无法消费的情况。建议迁移后源集群保留部分消费者进程，以便完成定时消息和失败重试消息的消费。

迁移操作流程

• 步骤一：迁移评估

  根据自建开源RocketMQ的版本、功能使用情况评估迁移上云的风险和兼容性，确认迁移任务的目标和范围。

• 步骤二：配置网络信息

  录入自建集群的网络及节点信息，云消息队列 RocketMQ 版会按照最小范围打通网络配置，为后期运行切流操作和切流检查提供权限。

• 步骤三：迁移元数据

  云消息队列 RocketMQ 版读取自建集群的Topic和Group元数据信息，并同步复制到目标云消息队列 RocketMQ 版实例上。

• 步骤四：更换接入点

  确认此次迁移范围内的所有生产者以及消费者，将源集群消息收发代码中的接入点修改为目标阿里云云消息队列 RocketMQ 版实例的接入点。

• 步骤五：迁移消息业务

  按照Topic粒度，分阶段执行切流操作。

步骤一：迁移评估

技术评估

• 自建集群约束：评估源自建RocketMQ集群是否符合如下约束，若其中有部分约束项不满足要求，请提交工单咨询解决方案。

  约束项	说明
  部署版本	支持Apache RocketMQ 5.x、 4.x服务端版本。
  网络要求	源集群需要部署在阿里云VPC网络环境中，若部署在线下IDC环境则需要支持VPC私网地址访问。
  支持地域	仅以下地域支持使用迁移上云功能：华东1（杭州）、华东2（上海）、华北2（北京）、华南1（深圳）和华北3（张家口）。
  功能约束	阿里云云消息队列 RocketMQ 版暂不支持ACL验证，自建RocketMQ集群若开启了ACL功能，则需要关闭，若未关闭则迁移后ACL功能也不会生效。
  参数约束	消息大小： 不超过4 MB。 消息保存时长： 最短24小时。 最长720小时。 定时消息最大延迟时间： 包年包月、按量付费标准版，Serverless标准版与专业版最大支持7天。 包年包月、按量付费专业版，铂金版最大支持40天。 更多参数约束，请参见配额与限制。

• SDK版本约束：迁移方案秉承最小变更原则，一般场景下支持客户端SDK版本直接升级，若是大版本变更一般涉及大量新功能特性变更和稳定性优化，建议您迁移的同时升级SDK版本。

  SDK类型	支持语言	SDK版本	是否需要升级
  Apache RocketMQ Remoting SDK 该类型SDK接入点配置格式如下： producer.setNamesrvAddr(“xxx:9876”); consumer.setNamesrvAddr(“xxx:9876”);	Java	5.x SDK	默认兼容，无需升级。
  	Java、C++、	4.x SDK	如果源集群使用了PullConsumer、DefaultLitePullConsumer、DefaultPullConsumer接口，需要升级到5.x系列SDK。更多信息，请参见SDK参考概述。
  Apache RocketMQ gRPC SDK 该类型SDK接入点配置格式如下： ClientConfiguration clientConfiguration = ClientConfiguration.newBuilder() .setEndpoints(192.168.XX.XX:9876) .setCredentialProvider(sessionCredentialsProvider) .build();	Java、C++、GO、C#	5.x SDK	默认兼容，无需升级。

迁移范围确认

云消息队列 RocketMQ 版支持Topic级别的迁移粒度，能达到分批次、可灰度、可回滚的效果，有效降低大面积变更的风险。

步骤二：配置网络信息

创建迁移任务并配置源自建集群的网络信息，用于云消息队列 RocketMQ 版迁移工具读取源自建集群的元数据信息，并实现后续迁移任务的控制。

注意事项

• 云消息队列 RocketMQ 版迁移工具按照最小范围粒度仅访问源自建集群如下信息：

  • Topic元数据配置信息

  • Group元数据配置信息

  • Topic动态路由注册信息

  • 消费者连接信息及消费堆积信息

  不会访问源集群其他信息，也不会对源自建集群的配置信息做任何写操作，因此不会对源自建集群的运行造成影响。

• 网络信息配置完成后请务必仔细检查，确认无误后再进行下一步操作，一旦进入下一步则无法回退修改网络配置信息，只能重新创建任务。

操作步骤

1. 登录云消息队列 RocketMQ 版控制台。

2. 在顶部菜单栏选择源集群和目标云消息队列 RocketMQ 版实例所属地域，然后在左侧导航栏选择RocketMQ Copilot > 迁移上云。

3. 在迁移上云页面单击创建任务。

4. 在弹出的创建迁移任务面板配置相关参数，然后单击确定。

   具体参数说明，请参见源集群网络配置参数。

5. 在迁移上云配置向导的网络信息配置页面中填写源自建RocketMQ集群的网络信息，然后单击配置网络信息。

   具体参数说明，请参见源集群网络配置参数。

6. 等待后台配置，直到页面显示配置完成，然后单击下一步。

参数配置说明

步骤三：迁移元数据

网络打通后，需要根据迁移范围选择指定的Topic和Group，完成元数据迁移操作。

注意事项

• 迁移元数据时，云消息队列 RocketMQ 版迁移工具会动态读取源自建集群的Topic和Group信息并在列表中全部展示，只需要操作本次任务范围内相关的Topic和Group即可。

• 该操作步骤无法回退，请确保本次任务范围内的Topic和Group都迁移完成后再进入下一步，否则后续需要手动补充Topic。

操作步骤

1. 在迁移上云任务的元数据迁移配置向导页面，单击Topic元数据页签。

2. 在Topic列表中选中需要迁移的Topic，在消息类型下拉框中选择对应的Topic的类型，然后在其操作列单击确认并导入。

   您也可以选择多个Topic，直接单击批量导入。

   重要

   开源Apache RocketMQ 4.x版本没有消息类型的概念，阿里云云消息队列 RocketMQ 版会对Topic的消息类型和Message的类型进行一致性校验，因此在元数据迁移时，您需要根据实际业务场景手动录入Topic的消息类型。

   如果消息类型选择错误，会导致迁移后消息收发失败。如果您不确定Topic的消息类型或存在Topic混用的情况，可以提交工单咨询。

3. 单击Group元数据页签，在Group列表中选中需要迁移的Group，在消费顺序类型下拉框中选择消息消费的投递顺序，然后在其操作列单击确认并导入。

   您也可以选择多个Group，直接单击批量导入。

   重要

   开源Apache RocketMQ 4.x系列SDK的消息消费顺序在客户端中配置，阿里云云消息队列 RocketMQ 版5.x版本实例在服务端中控制Group的消费顺序，因此在元数据迁移时，您需要根据实际业务场景手动录入Group的消费顺序类型。

   如果消费顺序的类型选择错误，会导致迁移后消息的消费顺序出现异常。如果您不确定Group的消费顺序，可以提交工单咨询。

4. 确认本次迁移任务内所有需要迁移的Topic和Group已经全部导入后，单击导入完成，进入下一步。

步骤四：更换接入点

Topic和Group元数据迁移完成后，开始进入线上业务迁移阶段，您需要协调此次迁移涉及的生产者应用、消费者应用连接到目标集群，即将生产者和消费者应用的接入点修改为云消息队列 RocketMQ 版5.x实例的接入点。

注意事项

• 接入点更换后修改重启生产者和消费者应用，此步骤虽然将消息收发应用接入到目标云消息队列 RocketMQ 版实例，但迁移工具后台仍将消息收发的Topic路由连接至源自建集群，因此消息收发链路在该步骤不会产生变化和影响。各消息收发应用间可自由安排切换顺序。

• 请确保此次迁移涉及的所有生产者应用和消费者应用均已完成接入点更换，不能有遗漏。

  • 如果部分生产者应用未更换接入点，则会导致部分消息发送失败。

  • 如果部分消费者应用未更换接入点，则会导致消息堆积部分消息消费不到。

接入点修改示例

• Apache RocketMQ Remoting协议SDK

  • 变更前：

    producer.setNamesrvAddr(“192.168.XX.XX:9876”);
      
    consumer.setNamesrvAddr(“192.168.XX.XX:9876”);

  • 变更后：

    producer.setNamesrvAddr(“rmq-cn-pe334******-vpc.cn-hangzhou.rmq.aliyuncs.com:8080”);
      
    consumer.setNamesrvAddr(“rmq-cn-pe334******-vpc.cn-hangzhou.rmq.aliyuncs.com:8080”);

• Apache RocketMQ gRPC协议SDK

  • 变更前：

    ClientConfiguration clientConfiguration = ClientConfiguration.newBuilder()
                .setEndpoints(192.168.XX.XX:9876)
                .setCredentialProvider(sessionCredentialsProvider)
                .build();

  • 变更后：

    ClientConfiguration clientConfiguration = ClientConfiguration.newBuilder()
                .setEndpoints(rmq-cn-pe334******-vpc.cn-hangzhou.rmq.aliyuncs.com:8080)
                .setCredentialProvider(sessionCredentialsProvider)
                .build();

操作步骤

步骤五：迁移消息业务

迁移消息业务需要按照Topic粒度对每个Topic进行切流操作，将消息读写流量分阶段切换到目标集群上。

注意事项

• 执行切流操作时，每切换一次Topic状态，请及时观察消息收发是否符合预期，若无异常再执行下一步切换操作，若消息收发出现异常可直接回滚操作，待异常原因排查后继续进行切流操作。

• 请确保此次迁移任务范围内的Topic均完成切流操作，且切流后消息收发平稳无异常再选择完成迁移任务，迁移任务一旦完成则无法修改。

切流状态说明

切流操作

1. 在迁移上云任务的消息迁移配置向导页面，在Topic列表中选择待迁移消息业务的Topic，确认其检查状态。

   • 若检查状态为检查通过，则直接执行下一步骤。

   • 若检查状态不是检查通过，请根据检查结果排查异常，然后在其操作列单击重新校验，直到检查通过。然后继续执行下一步骤。

     各切流状态所执行的检查项，请参见检查项说明。

   • 若检查状态不是检查通过，且您确认检查结果不会有实际影响，您可以直接在指定Topic的操作列单击忽略检查，然后执行下一步骤。

2. 在待切换Topic的操作列单击确认切流。

3. 在弹出的提示对话框中仔细阅读提示信息，然后单击确定。

   切流过程一共分为4个阶段，您需要重复执行切流操作4次，直到该Topic的切流阶段变为读写目标集群。

   各切流阶段的Topic读写流量情况，请参见切流阶段状态。

4. 确认本次迁移任务涉及的所有Topic均完成切流操作，然后单击页面下方的迁移完成。

相关操作说明

执行切流操作时，消息迁移页面的其他操作说明如下：

• 回滚

  • 回滚到上一个状态：若迁移过程中出现非预期结果，可将指定Topic的切流状态回滚到上一个运行正常的状态，待排查异常原因后再确定后续操作。

  • 回滚到初始状态：该方式可直接将切流状态强制回滚到初始状态，即还未开始切流的路由状态，一般用于异常情况紧急止血。

    说明

    该方式状态变化跨度较大，之前迁移过程中产生的未消费消息可能会造成延时或无法处理的情况。

• 补充创建

  若元数据迁移时有遗漏的Topic未进行迁移，在切流任务中可补充创建对应的Topic，即在云消息队列 RocketMQ 版5.x实例上手动创建一个和源集群Topic名称相同的Topic。

• 批量切流/批量回滚

  批量执行切流或回滚操作。

  说明

  批量切流和批量回滚仅支持操作切流阶段相同的Topic。

切流阶段检查项

相关文档

• 开源Apache RocketMQ和云消息队列 RocketMQ 版的差异以及迁移上云的方案原理和迁移优势，请参见迁移上云概述。

• 迁移任务完成后，您可以通过云消息队列 RocketMQ 版仪表盘的指标观察实例的运行状态和业务数据是否正常，若出现异常您可以随时进行回滚操作。