# 迁移其他RocketMQ的元数据到RocketMQ实例
本章节指导您迁移其他RocketMQ的元数据到云上RocketMQ实例。
主要提供以下两种迁移方法，请根据实际情况选择：
- [方法一]：通过**mqadmin**命令导出源实例的元数据，然后在云上RocketMQ实例中创建迁移任务。
- [方法二]：导出源实例的Topic和消费组列表（适用于不支持通过**mqadmin**命令导出元数据的场景），然后通过脚本将Topic和消费组列表导入到云上RocketMQ实例中。
迁移元数据导入Topic和消费组时，Topic和消费组会创建在所有代理上。因此，在4.8.0版本中，迁移能导入的Topic上限为单个代理的Topic上限。例如，rocketmq.4u8g.cluster\*2代理的实例，单个代理Topic上限为4000，则通过迁移整个实例最多能导入4000个Topic。
#### 操作视频
本视频演示华为云上RocketMQ实例之间的元数据迁移操作。
因产品功能演进，操作界面可能存在差异，相关视频仅供参考，具体以实际环境为准。
#### 前提条件
- 已购买RocketMQ实例。
- 准备一台Linux系统的主机，在主机中安装[Java Development Kit 1.8.111或以上版本](https://www.oracle.com/java/technologies/downloads/#java8)，并完成环境变量配置，具体操作可参见[快速连接RocketMQ并生产消费消息](https://support.huaweicloud.com/qs-hrm/hrm-qs-001.html)。
- 准备网络环境。
RocketMQ实例分内网地址以及公网地址两种网络连接方式。如果使用公网地址，则消息生产与消费客户端需要有公网访问权限，并配置如下安全组。
表1安全组规则（RocketMQ实例4.8.0版本）
| 方向 | 协议 | 端口 | 源地址 | 说明 |
|:---|:---|:---|:---|:---|
| 入方向 | TCP | 8200 | RocketMQ客户端所在的IP地址或地址段。 | 使用TCP协议，通过公网访问元数据节点的端口。 |
| 入方向 | TCP | 10101-10199 | RocketMQ客户端所在的IP地址或地址段。 | 使用TCP协议，通过公网访问业务节点的端口。 |
表2安全组规则（RocketMQ实例5.x版本）
| 方向 | 协议 | 端口 | 源地址 | 说明 |
|:---|:---|:---|:---|:---|
| 入方向 | TCP | 8200 | RocketMQ客户端所在的IP地址或地址段。 | 使用TCP协议，通过公网访问实例的端口。 |
| 入方向 | TCP | 8081 | RocketMQ客户端所在的IP地址或地址段。 | 使用gRPC协议，通过公网访问实例的端口。 |
| 入方向 | TCP | 10101 | RocketMQ客户端所在的IP地址或地址段。 | 使用TCP协议，通过公网访问业务节点的端口。 |
- 客户端所在服务器可以访问公网，用于下载RocketMQ软件包。
#### 方法一：通过mqadmin命令导出源实例的元数据，然后在华为云上RocketMQ实例中导入元数据
**获取自建RocketMQ或华为云上另一个RocketMQ实例的元数据**
1. 登录已准备的Linux系统主机，下载RocketMQ软件包。
```
wget https://archive.apache.org/dist/rocketmq/5.3.0/rocketmq-all-5.3.0-bin-release.zip
```
2. 解压软件包。
```
unzip rocketmq-all-5.3.0-bin-release.zip
```
3. （可选）如果RocketMQ实例开启了[ACL访问控制](https://support.huaweicloud.com/usermanual-hrm/hrm-ug-070.html)，执行**mqadmin** 命令时，需要鉴权。
切换到解压后的软件包目录下，在"conf/tools.yml"文件中，增加如下内容。
```
accessKey:*******
secretKey:*******
```
accessKey和secretKey表示在控制台"实例管理 \> 用户管理"页面，创建的用户名和密钥，具体可参见[创建用户](https://support.huaweicloud.com/usermanual-hrm/hrm-ug-035.html#hrm-ug-035__section491614421020)。
4. 进入解压后的软件包目录下，执行以下命令，查询集群名称。
- 未开启SSL的实例，执行以下命令。
```
sh ./bin/mqadmin clusterList -n {nameserver地址及端口号}
```
例如："nameserver地址及端口号"为"192.168.0.65:8100"。
```
sh ./bin/mqadmin clusterList -n 192.168.0.65:8100
```
- 已开启SSL的实例，执行以下命令。
```
JAVA_OPT=-Dtls.enable=true sh ./bin/mqadmin clusterList -n {nameserver地址及端口号}
```
例如："nameserver地址及端口号"为"192.168.0.65:8100"。
```
JAVA_OPT=-Dtls.enable=true sh ./bin/mqadmin clusterList -n 192.168.0.65:8100
```
5. 执行以下命令，导出元数据。
- 未开启SSL的实例，执行以下命令。
```
sh ./bin/mqadmin exportMetadata -n {nameserver地址及端口号} -c {RocketMQ集群名称} -f {导出的元数据文件的存放路径}
```
例如："nameserver地址及端口号"为"192.168.0.65:8100"，"RocketMQ集群名称"为"DmsCluster"，"导出的元数据文件的存放路径"为"/tmp/rocketmq/export"。
```
sh ./bin/mqadmin exportMetadata -n 192.168.0.65:8100 -c DmsCluster -f /tmp/rocketmq/export
```
- 已开启SSL的实例，执行以下命令。
```
JAVA_OPT=-Dtls.enable=true sh ./bin/mqadmin exportMetadata -n {nameserver地址及端口号} -c {RocketMQ集群名称} -f {导出的元数据文件的存放路径}
```
例如："nameserver地址及端口号"为"192.168.0.65:8100"，"RocketMQ集群名称"为"DmsCluster"，"导出的元数据文件的存放路径"为"/tmp/rocketmq/export"。
```
JAVA_OPT=-Dtls.enable=true sh ./bin/mqadmin exportMetadata -n 192.168.0.65:8100 -c DmsCluster -f /tmp/rocketmq/export
```
**在控制台迁移元数据**
1. 登录[RocketMQ实例控制台](https://console.huaweicloud.com/dms/?engine=reliability&locale=zh-cn#/queue/manager/instances)。
2. 单击RocketMQ实例的名称，进入实例概览页面。
3. 在左侧导航栏，选择"迁移上云 \> 元数据迁移"，进入迁移任务列表页面。
4. 单击"导入元数据"，弹出"导入元数据"对话框。
5. 参考[表3]，设置迁移任务的参数。
表3迁移任务参数说明
| 参数 | 说明 |
|:---|:---|
| 任务类型 | 选择"从RocketMQ导入"。 |
| 任务名称 | 您可以自定义迁移任务的名称，用于区分不同的迁移任务。 任务名称命名规则如下： - 长度为4\~64个字符。 - 只能由英文字符、数字、中划线、下划线组成，且开头须为英文字母。 |
| 是否同名覆盖 | - 如果开启同名覆盖，会对已有的同名元数据的配置进行修改。 例如：原实例Topic01的读队列个数为3，云上实例Topic01的读队列个数为2，开启同名覆盖后，云上实例Topic01的读队列个数变为3。 - 如果不开启同名覆盖，同名元数据的迁移将失败。 例如：原实例的Topic包含Topic01和Topic02，云上实例的Topic包含Topic01和Topic03，不开启同名覆盖，原实例Topic01的迁移将失败。 |
| 元数据 | 上传[元数据]。 |
6. 单击"确定"。
迁移完成后，在迁移任务列表页面查看"任务状态"。
- 当"任务状态"为"迁移完成"，表示所有元数据都已成功迁移。 迁移成功后，请参考[使用客户端连接RocketMQ（关闭SSL）](https://support.huaweicloud.com/usermanual-hrm/hrm-ug-039.html)或[使用客户端连接RocketMQ（开启SSL）](https://support.huaweicloud.com/usermanual-hrm/hrm-ug-040.html)生产和消费消息，以确保元数据可用。
- 当"任务状态"为"迁移失败"，表示元数据中部分或全部元数据迁移失败。单击迁移任务名称，进入迁移任务详情页，在"迁移结果"中查看迁移失败的Topic/消费组名称，以及失败原因及解决方法。解决问题后，再执行后面的步骤。
#### 方法二：导出源实例的Topic和消费组列表，然后通过脚本将Topic和消费组列表导入到华为云上RocketMQ实例中
**获取其他厂商、自建RocketMQ或华为云上另一个RocketMQ实例的元数据**
1. 登录其他厂商界面，导出源实例的Topic和消费组列表。
2. 将Topic和消费组列表分别放入"topics.txt"和"groups.txt"中，格式为每行一个Topic名称/消费组名称，例如：
```
topic-01
topic-02
...
topic-n
```
在"groups.txt"中不能存在空行（例如在消费组名称后多增加了一个换行符），否则导入云上RocketMQ实例时，会多创建名称为空的消费组。
**通过脚本将Topic和消费组列表导入到华为云上RocketMQ实例中**
1. 登录已准备的Linux系统主机，下载RocketMQ软件包。
```
wget https://archive.apache.org/dist/rocketmq/5.3.0/rocketmq-all-5.3.0-bin-release.zip
```
2. 解压软件包。
```
unzip rocketmq-all-5.3.0-bin-release.zip
```
3. （可选）如果RocketMQ实例开启了[ACL访问控制](https://support.huaweicloud.com/usermanual-hrm/hrm-ug-070.html)，执行**mqadmin** 命令时，需要鉴权。
切换到解压后的软件包目录下，在"conf/tools.yml"文件中，增加如下内容。
```
accessKey:*******
secretKey:*******
```
accessKey和secretKey表示在控制台"用户管理"页面，创建的用户名和密钥。
4. 进入解压后软件包的**bin**目录下，将"topics.txt"和"groups.txt"上传到此目录中。
5. 执行以下脚本，将Topic和消费组列表导入到云上RocketMQ实例中。
```
#!/bin/bash
# Read groups from groups.txt file
groups=()
while read -r group; do
groups+=("$group")
done < "groups.txt"
# Read topics from topic.txt file
topics=()
while read -r topic; do
topics+=("$topic")
done < "topics.txt"
# Add topics
for topic in "${topics[@]}"; do
echo "Adding topic: $topic"
sh mqadmin updateTopic -n -c DmsCluster -t "$topic"
done
# Add consumer groups
for group in "${groups[@]}"; do
echo "Adding consumer group: $group"
sh mqadmin updateSubGroup -n -c DmsCluster -g "$group"
done
```
其中"namesrvIp:8100"为云上RocketMQ实例的连接地址。
6. 登录[RocketMQ实例控制台](https://console.huaweicloud.com/dms/?engine=reliability&locale=zh-cn#/queue/manager/instances)。
7. 单击RocketMQ实例的名称，进入实例概览页面。
8. 查看Topic和消费组是否导入成功。
- 在左侧导航栏，单击"实例管理 \> Topic管理"，进入Topic列表页面，查看导入的Topic信息。
- 在左侧导航栏，单击"实例管理 \> 消费组管理"，进入消费组列表页面，查看导入的消费组信息。
导入成功后，请参考[使用客户端连接RocketMQ（关闭SSL）](https://support.huaweicloud.com/usermanual-hrm/hrm-ug-039.html)或[使用客户端连接RocketMQ（开启SSL）](https://support.huaweicloud.com/usermanual-hrm/hrm-ug-040.html)生产和消费消息，以确保元数据可用。
#### 相关文档
创建元数据迁移任务也可以通过调用API完成，具体请参见[新建元数据迁移任务](https://support.huaweicloud.com/api-hrm/CreateRocketMqMigrationTask.html)。