客户在使用 TDMQ RocketMQ 版时，通常会面临着存量业务的切换，例如从自建的 RocketMQ 或者其他平台的托管版 RocketMQ 迁移到 TDMQ-RocketMQ 版上。当前自建的 RocketMQ 集群只支持 4.x 版本的集群，后续会根据客户需求支持更多版本。
在进行迁移时，客户一般有两种迁移方式：有感迁移和无感迁移。
有感迁移指客户先进行元数据的导入和导出，后续按照 数据流迁移指引，依次对消费者和生产者切换接入地址。但是这种迁移方式对于客户的在线业务有一定侵入性，在接入点的切换时，会对线上业务有影响，因此更加适合对业务连续性不高或者没有要求的迁移场景。
操作场景
目前，腾讯云 TDMQ RocketMQ 版支持客户在不中断业务的前提下，进行整个集群的迁移，且在整个迁移的各个阶段中，客户可以在控制台可视化查看迁移任务的进度，并且支持任务的暂停和回滚。
该任务指导您将开源的 RocketMQ 集群的无感迁移至腾讯云消息队列 RocketMQ 版。
迁移步骤
前提条件
CAM 权限配置
无感迁移涉及到的云 API 如下：
接口名称 | 接口说明 |
ChangeMigratingTopicToNextStage | 修改迁移中的 Topic 状态进入下一步 |
DescribeMigratingTopicList | 查询 Topic 迁移状态列表 |
DescribeMigratingTopicStats | 查询迁移主题的实时数据 |
DescribeSmoothMigrationTaskList | 查询平滑迁移任务列表 |
DescribeSourceClusterGroupList | 平滑迁移过程获取源集群 Group 列表 |
DoHealthCheckOnMigratingTopic | 检查迁移中的主题是否处于正常状态，只有处于正常状态的主题，才可以进入下一个迁移阶段 |
ImportSourceClusterConsumerGroups | 导入消费者组列表 |
ImportSourceClusterTopics | 导入 Topic 列表 |
RollbackMigratingTopicStage | 回滚正在迁移的主题至前一个阶段 |
DeleteSmoothMigrationTask | 删除平滑迁移任务，只有被取消的任务才可删除 |
DescribeMigratingGroupStats | 查看迁移消费组的实时信息 |
RemoveMigratingTopic | 从迁移列表中移除主题，仅当主题处于初始状态时有效 |
创建任务
在正式开始迁移前，您需要在迁移上云页面选择新建集群无感迁移类型的任务，按照如下指引填写任务的相关信息。在创建任务前，建议您评估好源集群当前的流量情况，选择合适的腾讯云 RocketMQ 集群进行购买，避免出现迁移到云上后，因为云上的集群规格过小导致出现限流情况。
任务名称：迁移任务的名称，按照实际业务情况命名即可。
源集群类型：支持自建的 4.x 和 5.x 集群，请保证填写的集群类型和实际自建的版本一致，避免后续推进任务时报错。
源集群名称：用户自建的集群名称，按照实际业务情况命名即可。
目标集群类型：目前支持 RocketMQ 4.x 专享和通用集群和 RocketMQ 5.x 集群。
目标集群地域：根据实际业务需要选择，仅展示存在目标集群的地域。
目标集群：可以根据实际需要选择 RocketMQ 4.x 通用集群和专享集群或者 RocketMQ 5.x 集群，注意保证目标集群的规格能够完全承载源集群的流量。
说明：
由于适配迁移上云的集群需要单独安装迁移组件，因此需要单独购买支持无感迁移的 4.x 专享集群。您也可以在购买专享集群时就打开迁移上云组件 的开关，如下图所示。RocketMQ 4.x 通用集群和 5.x 全系列不受迁移组件的影响，可以直接使用您之前购买的对应集群。
信息填写完成后，单击创建任务后，正式进入任务第一步。
在任务详情页，您可以随时查看已经创建好的任务的进度和当前的架构示意图等。
步骤1：连接源集群
在这一步，您需要确认网络连接类型，填写源集群的相关信息：
网络连接类型：腾讯云上的 RocketMQ 集群连接源集群时使用的网络连接类型。根据实际情况可以选择公网和 VPC 网络，后续步骤中会对网络连接进行校验。如您选择的是 VPC 网络，需要再次选择具体的 VPC 和子网。
说明：
如您选择的是使用公网，为了保证迁移能够顺利进行，您需要允许腾讯云访问您对应网络内的资源。您可以在下表中选择您的地域，将对应地域的腾讯云的 IP 地址加入到您自建集群的公网白名单内。
源集群所在地域 | 需要放通的公网 IP 网段 |
北京 | 152.136.0.0/16 81.70.0.0/16 |
上海 | 121.4.0.0/16 106.54.0.0/16 49.234.0.0/16 49.235.0.0/16 175.24.0.0/16 |
广州 | 119.29.0.0/16 106.52.0.0/16 106.53.0.0/16 106.55.0.0/16 118.89.0.0/16 81.71.0.0/16 42.194.0.0/16 |
南京 | 119.45.0.0/16 129.211.0.0/16 146.56.0.0/16 175.25.0.0/16 |
中国香港 | 119.28.0.0/16 101.32.0.0/16 |
新加坡 | 43.134.0.0/16 101.32.0.0/16 |
硅谷 | 170.106.0.0/16 49.51.0.0/16 |
弗吉尼亚 | 43.130.0.0/16 170.103.0.0/16 |
上海金融 | 212.129.0.0/16 |
NameServer 地址：根据上一步填写的网络连接类型，填写源集群的 NameServer 地址，格式为 IP + 端口，多个地址用分号隔开。
NameServer 地址类型：仅在使用 VPC 网络访问源集群时需要填写。根据不同客户的使用习惯，NameServer 地址可能为腾讯云上的 CVM 地址或是 CLB 地址，请如实填写。此处仅用于区分网络打通场景，对后续的操作没有影响。
源集群是否开启 ACL：请如实填写，如果您的源集群开启了 Admin API 的 ACL 管理，为了保证迁移顺利，您需要填写源集群的 accessKey 和 secretKey（此处为调用 Admin API 的 ak 和 sk，而非收发消息使用的 ak sk，这里需要注意区分）。
注意：
根据不同客户的迁移场景，存在多个源集群迁移到同一个腾讯云 RocketMQ 集群（目标集群）的场景，这种场景下需要注意以下问题：
1. 同一个目标集群仅能同时在一个迁移任务中，因此如果出现上述情况，请多个源集群分批次迁移。
2. 多个迁移任务时，不同的源集群（假设分别为源集群 A 和 B）可能 ACL 的开启情况不一样。假设第一次迁移任务时迁移源集群 A，在创建任务阶段，源集群 A 的 ACL 开关填写为开启，则实际目标集群的 ACL 开关也已经开启。在进行第二次迁移任务，即迁移源集群 B 时，页面会默认连接源集群 B 时也需要 ACL信息，如果实际源集群 B 没有使用 ACL，则在后续切流过程中，需要将源集群 B 的客户端都补充 AK/SK 的相关配置。
3. 如果在上述迁移场景中，源集群 A 在首次迁移任务时未开启 ACL 开关，则默认也不会对源集群 B 的客户端进行 AK/SK 的校验。
以上信息填写完成后，可以单击页面底部的完成网络配置按钮，TDMQ RocketMQ 的迁移组件会连接源集群，如果连接成功后，可以单击进入下一步。如果连接出现错误，会在页面提示错误的原因，常见的错误原因和解决办法有：
错误原因 | 解决方案 |
连接 NameServer 出错 | 确认填写的 NameServer 地址是否正确； 如您使用的是公网连接，请确认 NameServer 的公网白名单是否添加了腾讯云的 IP 白名单，或者白名单的配置是否正确； 如您使用的是公网连接，请确认目标集群，即您购买的腾讯云 RocketMQ 集群开启了公网连接 |
鉴权错误 | 确认源集群是否开启权限管控，如已开启，请确认填写的 accessSecret 和 accessKey 是否正确 |
步骤2：导入元数据
在成功连接到源集群的 NameServer 后，您可以开始将源集群的元数据同步到目标集群。
迁移工具会自动扫描出源集群的相关元数据，即 Topic 和 Group 等。如下图所示，您可以在页面上确认 Topic 和 Group 的相关信息，确认无误后，您可以单击 操作 列的 确认并导入 按钮进行确认；您也可以通过单击列表前的 
迁移元数据时的注意事项：
如您在当前列表没有找到源集群上创建的 Topic 或者 Group，您可以单击右上角的刷新按钮进行刷新。
如果刷新后还是没有源集群的部分 Topic 和 Group信息，您可以单击新建按钮进行新建 Topic 或者 Group 操作。
Topic 的队列数默认和源集群内的队列数保持一致，出于稳定性考虑，如您源集群的 Topic 的队列数不满足 TDMQ RocketMQ 的队列数范围（如超出16个队列或者小于3个队列的情况），RocketMQ 会对队列数进行微调，页面会进行提示。
迁移的 Group 默认均为 TCP 协议，如需创建支持 HTTP 协议的Group您可以在目标集群页单独创建。
对于目标集群为 4.x 专享集群的情况，如果源集群使用了命名空间的，迁移工具会默认截取 Topic 或者 Group 命名中 “%” 符号前的字段作为命名空间的名称；如果您的源集群没有启用命名空间，则迁移工具会默认将 Topic 和 Group 都导入到一个默认名的 Default 的命名空间内。
导入元数据阶段，您也可以添加集群用于收发消息的角色和AK/SK，如果角色过多，您可以点击右上角的 
导入元数据后，如果您需要创建新的 Topic / Group，或者对 Topic / Group 进行操作，请前往目标集群，即 RocketMQ 控制台的对应集群进行创建。
说明：
步骤3：修改源集群接入点
在确认需要迁移的元数据都完成导入后，您需要根据页面的指引，修改所有客户端的接入点地址。
客户端修改接入点后，迁移工具会将流量转发到源集群上，实际各个客户端连接的还是源集群，故本步骤不会产生风险。在单击进入下一步前，请确保所有的客户端（包括消费者和生产者）的接入点均切换完成，否则在进入下一步进行 Topic 的灰度迁移时，未切换接入点的客户端将连接不到目标集群，因此无法进行灰度迁移。
在 接入点修改详情 列表页展示的源集群和目标集群下各个 Group 下连接的客户端个数对比，您可以以此来快速定位还未完成修改的消费者客户端。如下图所示，列表页会展示源集群和目标集群不一致的 Group 并自动展开两边的 Client 客户端列表进行对比，在 “备注” 列，您可以快速定位到原因。
如果确认所有客户端的接入点均已修改完成，则可以继续单击 下一步，正式进入切流阶段。在进入切流阶段前，如果出现有客户端接入点未修改完成的情况，页面也会提醒，如没有出现弹窗，则可以认为所有的消费者客户端接入点均切换完成。
步骤4：灰度迁移消息
在灰度迁移阶段，迁移工具将按 Topic 粒度进行逐个迁移，按照 “初始状态（读写源集群） > 开启双读（写源集群双读） > 双读双写 > 切流中（写目标集群双读） > 切流完成（读写目标集群）” 的顺序进行迁移，迁移过程中，每个状态均可以回滚到上一个状态：
初始状态：读写源集群状态，是迁移的起始状态，读写流量经过迁移组件代理转发，依旧访问源集群，因此对业务侧无侵入。
开启双读：消息生产者客户端写源集群，同时消息消费者同时读取来自源集群和目标集群的流量。
双读双写：消息生产者客户端发送的消息随机到源集群或者目标集群，您可以在监控页面查看不同集群的流量；同时消息消费者同时读取来自源集群和目标集群的流量。
切流中：消息生产者客户端写目标集群，同时消息消费者同时读取来自源集群和目标集群的流量。您需要在此阶段验证新的消息收发链路无异常，并等待源集群存量消息消费完成。
切流完成：在上一步确认新的消息收发链路符合预期后，在源集群已经消费所有消息并无堆积情况下，进入读写目标集群状态，全部读写流量只访问目标新集群。
如上图所示，您可以通过查看是否就绪列的内容，查看 Topic 是否具备迁移条件；迁移工具会间隔一段时间进行批量扫描，您也可以通过操作列的健康检查 按钮进行单个 Topic 的实时检查。达到 “已就绪” 状态的 Topic 可以进入下一阶段，在切流过程中，您也可以单击回滚进行单个 Topic 或者批量的状态回滚。
在 Topic 切流的过程中，您可以通过迁移监控Tab查看整个集群或者单个 Topic 的流量和运行状态。仅处于“初始状态”的 Topic 支持移出迁移任务。
在切流过程中，您可以自由查看目标集群和源集群的 Group（消费者组）和客户端数量的对比，如上图所示，同时会提示源集群有哪些 Group 未完成切换。
在切流过程中，您也可以通过监控页签查看源集群和目标集群的流量变化，在监控数据会使用不同的图例展示出来。
步骤5：完成迁移
在所有 Topic 均到 “切流完成” 状态后，您可以进入下一步，即完成整个迁移过程。迁移完成后，即所有的 Topic 和客户端均完成迁移，所有的消息流量均在 TDMQ RocketMQ 上运行。您可以通过查看目标集群和源集群的监控，后续可以逐步下线源集群。
