可用于实现MySQL到openGauss的一键式迁移，集成全量迁移、增量迁移、反向迁移及数据校验功能，支持工具一键安装、任务设定与执行计划管理，实时展示迁移步骤状态、进度及异常原因。【此简介由AI生成】
MySQL一键式迁移
功能介绍
gs_rep_portal是一个用Java编写的，在linux系统上运行的，集成了全量迁移、增量迁移、反向迁移、数据校验的工具。gs_rep_portal支持以上工具的一键式安装上述工具，设定迁移任务，任务根据用户设定的执行计划顺序的调用相应工具完成每个迁移步骤，并能实时展示每个步骤的状态、进度、异常原因等。
注意事项
- portal在执行增量迁移、反向迁移、增量校验时需要使用curl工具。
- 同一个迁移计划的增量迁移和反向迁移不会同时开启，如果一个计划中包含了增量迁移和反向迁移，那么需要用户手动停止增量迁移，启动反向迁移。当用户启动反向迁移之后，无法再启动增量迁移。
- portal使用的workspace.id只能为小写字母与数字的组合。
- portal在启动多个计划时，需要保证MySQL数据库实例各不相同，openGauss端数据库各不相同，且同一个MySQL数据库实例和openGauss端数据库的增量迁移和反向迁移不能同时开启。
默认文件结构
使用默认配置安装的portal的文件结构如下。
portal/
config/
migrationConfig.properties
toolspath.properties
status
currentPlan
input
chameleon/
config-example.yml
datacheck/
application-source.yml
application-sink.yml
application.yml
log4j2.xml
log4j2source.xml
log4j2sink.xml
debezium/
connect-avro-standalone.properties
mysql-sink.properties
mysql-source.properties
opengauss-sink.properties
opengauss-source.properties
logs/
portal.log
pkg/
chameleon/
chameleon-7.0.0rc3-py3-none-any.whl
datacheck/
openGauss-DataCheck-7.0.0-RC3.tar.gz
debezium/
confluent-community-5.5.1-2.12.zip
openGauss-IncReplicateMysql2OpenGauss-7.0.0-RC3.tar.gz
openGauss-IncReplicateOpenGauss2Mysql-7.0.0-RC3.tar.gz
tmp/
tools/
chameleon/
datacheck/
debezium/
confluent-5.5.1/
plugin/
debezium-connector-mysql/
debezium-connector-opengauss/
portal.portId.lock
portalControl-7.0.0-RC3-exec.jar
gs_datacheck.sh
gs_mysync.sh
gs_rep_portal.sh
gs_replicate.sh
README.md
安装教程
portal的安装目录默认为/ops/portal，可根据实际需要更换。
源码安装：
1.通过git命令下载源代码，将源代码中的portal文件夹复制到/ops下。
git clone https://gitee.com/opengauss/openGauss-migration-portal.git
2.使用maven命令编译源代码获得portalControl-7.0.0-RC3-exec.jar，并将jar包放在/ops/portal下。
mvn clean package -Dmaven.test.skip=true
java版本：JDK17及以上
maven版本：3.8.1以上
3.使用一键式脚本启动portal时，请将/ops/portal/shell目录下中的.sh文件提取出来，放在/ops/portal/目录，也就是和jar包同一目录下。
安装包安装：
各系统版本和架构对应的下载链接如下：
1.下载gs_rep_portal安装包
wget -c https://opengauss.obs.cn-south-1.myhuaweicloud.com/latest/tools/centos7/PortalControl-7.0.0-RC3-x86_64.tar.gz
2.解压gs_rep_portal安装包
tar -zxvf PortalControl-7.0.0-RC3-x86_64.tar.gz
启动方式
使用一键式脚本gs_rep_portal启动portal，通过参数使用portal的各项功能。
sh gs_rep_portal.sh 参数 workspace.id &
这里的参数为数个单词之间加下划线，比如"start_mysql_full_migration"这种形式，分为安装指令，启动指令，停止指令，卸载指令等，会在下文介绍。
portal会在workspace文件夹下创造对应id的文件夹，并将执行任务时的参数和日志等信息存入该文件夹。如果不指定workspace.id，那么workspace.id默认值为1。
命令行输入以下指令可以查看帮助（包括使用方式和可用指令）：
sh gs_rep_portal.sh help &
参数优先级： workspace下设置的参数 > 公共空间参数。如果使用的workspace.id和之前存在的workspace.id相同的话将沿用之前的workspace里面的参数，如果不同的话，那么portal将从config文件夹中复制一份配置文件到id对应的workspace下面作为这个任务的配置文件。
建议每次运行迁移任务时使用不同的workspace.id。
安装迁移工具
迁移功能与对应的迁移工具如下表所示：
| 迁移功能 | 使用工具 |
|---|---|
| 全量迁移 | chameleon |
| 增量迁移 | confluent、debezium-connector-mysql |
| 反向迁移 | confluent、debezium-connector-opengauss |
| 数据校验（包括全量校验和增量校验） | confluent、datacheck |
各工具版本：
| 工具 | 版本 |
|---|---|
| chameleon | 7.0.0rc3 |
| confluent | 5.5.1 |
| datacheck | 7.0.0-RC3 |
| replicate-mysql2openGauss | 7.0.0-RC3 |
| replicate-openGauss2mysql | 7.0.0-RC3 |
使用以下指令可以安装所有迁移工具：
sh gs_rep_portal.sh install_mysql_all_migration_tools 1
准备动作
如果portal在安装时安装了全量迁移工具以外的其他工具，那么portal启动confluent（内置kafka）作为运行其他工具时的准备动作。安装之后将自动运行准备动作指令。
结束准备动作时的命令：
sh gs_rep_portal.sh stop_kafka a
启动准备动作时的命令：
sh gs_rep_portal.sh start_kafka a
离线安装特性说明
由于全量迁移工具chameleon是python语言编写，对于不同的安装环境，需要依赖环境中的mariadb-devel（或mysql-devel，mysql5-devel），python-devel，python3-devel软件。当环境中无上述软件，且安装环境无法联网时，可能会导致chameleon安装失败。
为了优化用户安装体验，并且在无法联网环境下也能安装成功，portal将chameleon所依赖的软件打包到了安装包中，用户在使用portal安装chameleon前，只需要给予portal安装用户sudo且不需要输入密码的权限。安装时，portal会自动在安装chameleon前，安装其所依赖的软件，然后自动安装chameleon。安装成功后，可以将portal安装用户的sudo权限取消，后续迁移无需用到sudo权限。
用户根据安装环境的系统及架构，从此文档上方提供的下载链接下载portal安装包，便可使用此特性进行安装。
当portal安装用户没有sudo权限时，使用portal安装chameleon时，会自动跳过安装其依赖的软件，直接安装chameleon，如果环境上已存在其所依赖的软件，仍然可以安装chameleon成功。因此，安装用户没有sudo权限时，并不会阻塞portal安装各迁移工具。
配置参数
用户可以在/ops/portal/config目录的migrationConfig.properties文件中修改迁移所用参数。
参数优先级：workspace下设置的参数 > 公共空间参数。如果使用的workspace.id和之前存在的workspace.id相同的话将沿用之前的workspace里面的参数，如果不同的话，那么portal将从config文件夹中复制一份配置文件到id对应的workspace下面作为这个任务的配置文件。
| 参数名称 | 参数说明 |
|---|---|
| mysql.user.name | mysql数据库用户名 |
| mysql.user.password | mysql数据库用户密码 |
| mysql.database.host | mysql数据库ip |
| mysql.database.port | mysql数据库端口 |
| mysql.database.name | mysql数据库名 |
| opengauss.user.name | openGauss数据库用户名 |
| opengauss.user.password | openGauss数据库用户密码 |
| opengauss.database.host | openGauss数据库ip |
| opengauss.database.port | openGauss数据库端口 |
| opengauss.database.name | openGauss数据库名 |
| opengauss.database.schema | openGauss数据库模式名 |
除了配置迁移所用基本参数外，用户还可在指定位置自行配置工具自身的所用参数。但是portal会默认修改工具自身的临时文件和日志位置，并分配部分工具自身所用的端口。用户可自行查看并修改工具的配置文件，默认工具配置文件位置如下表。
注意事项：
- zookeeper默认端口2181、kafka默认端口9092、schema-registry默认端口8081不会自动分配，其余工具均会自动分配端口。用户如果需要修改工具的端口，请不要修改IP。如果需要修改kafka的端口，要注意将kafka的文件中的参数listeners的值修改为PLAINTEXT://localhost:要配置的端口。
- 下表使用${config}代表/ops/portal/config目录，即公共空间配置的参数。如果想修改某个workspace的参数，比如workspace.id=2的计划的参数，请将/ops/portal/config替换为/ops/portal/workspace/2/config。
- 下表使用${confluent.path}代表/ops/portal/config目录的toolspath.properties文件里面confluent.path的值。
- 每次创建新的任务时，/ops/portal/config/debezium目录的connect-avro-standalone.properties文件会被自动复制成四份并修改端口。
| 工具名称 | 配置文件位置 |
| chameleon | ${config}/chameleon/config-example.yml |
| zookeeper | ${confluent.path}/etc/kafka/zookeeper.properties |
| kafka | ${confluent.path}/etc/kafka/server.properties |
| schema-registry | ${confluent.path}/etc/schema-registry/schema-registry.properties |
| connector-mysql | ${config}/debezium/connect-avro-standalone.properties |
| ${config}/debezium/mysql-source.properties | |
| ${config}/debezium/mysql-sink.properties | |
| connector-opengauss | ${config}/debezium/connect-avro-standalone.properties |
| ${config}/debezium/opengauss-source.properties | |
| ${config}/debezium/opengauss-sink.properties | |
| datacheck | ${config}/datacheck/application-source.yml |
| ${config}/datacheck/application-sink.yml | |
| ${config}/datacheck/application.yml |
执行迁移计划
portal支持启动多个任务执行不同的迁移计划，但是要求各迁移计划使用的MySQL实例和openGauss数据库互不相同。
启动迁移计划时需要添加参数，这样不同的迁移计划可以根据不同的workspace.id进行区分，如果不添加的话，workspace.id默认值为1。
启动workspace.id为2的全量迁移：
sh gs_rep_portal.sh start_mysql_full_migration 2 &
portal除了支持单项功能的启动与停止，也会提供一些组合的默认计划：
启动workspace.id为2的包括全量迁移和全量校验在内的迁移计划：
sh gs_rep_portal.sh start_plan1 2 &
计划列表
| 计划名称 | 包括指令 |
|---|---|
| plan1 | 全量迁移→全量校验 |
| plan2 | 全量迁移→全量校验→增量迁移→增量校验 |
| plan3 | 全量迁移→全量校验→增量迁移→增量校验→反向迁移 |
增量迁移和反向迁移
增量迁移功能是持续将MySQL端的数据修改同步到openGauss端的功能，而反向迁移功能是持续将openGauss端的数据修改同步到MySQL端的功能，所以二者均不会自动关闭。如果用户想要停止增量迁移功能，需要另开窗口输入指令停止增量迁移功能，反向迁移功能同理。
并且需要注意的是：增量迁移和反向迁移不能同时开启，如果一个计划中包含了增量迁移和反向迁移，那么需要用户手动停止增量迁移，启动反向迁移。用户在停止增量迁移之后到启动反向迁移之前，禁止向openGauss进行作业，否则会导致这之间的数据丢失。
以启动默认计划3为例：
1.在配置好配置文件后输入以下指令启动workspace.id为3的计划plan3：
sh gs_rep_portal.sh start_plan3 3 &
这时portal会自动执行全量迁移→全量校验→增量迁移→增量校验，然后一直处于增量迁移状态（此时增量迁移和增量校验同时运行）。
2.如果用户想要停止增量迁移功能，需要另开窗口输入以下指令停止增量迁移功能：
sh gs_rep_portal.sh stop_incremental_migration 3 &
输入指令后，这个进程会退出，而正在执行计划的workspace.id为3的portal主进程会接收到停止增量迁移的消息，从而停止增量迁移，等待下一步指令。
3.如果用户想要启动反向迁移功能，需要输入以下指令：
sh gs_rep_portal.sh run_reverse_migration 3 &
输入指令后，这个进程会退出，而正在执行计划的workspace.id为3的portal主进程会接收到启动反向迁移的消息，从而启动反向迁移，此时portal一直处于反向迁移状态。
如果想要停止整个迁移计划，请参考下方的“停止计划”小节。
以下为启动迁移计划的指令列表：
启动指令列表
| 指令名称 | 指令说明 |
|---|---|
| verify_pre_migration | 迁移前校验 |
| verify_reverse_migration | 反向迁移前校验 |
| start_mysql_full_migration | 开始mysql全量迁移 |
| start_mysql_incremental_migration | 开始mysql增量迁移 |
| start_mysql_reverse_migration | 开始mysql反向迁移 |
| start_mysql_full_migration_datacheck | 开始mysql全量校验 |
| start_mysql_incremental_migration_datacheck | 开始mysql增量校验 |
| start_plan1 | 开始默认计划plan1 |
| start_plan2 | 开始默认计划plan2 |
| start_plan3 | 开始默认计划plan3 |
| start_current_plan | 开始自定义计划 |
| show_plans | 显示默认计划 |
| show_information | 显示数据库相关信息，包括mysql和openGuass端的数据库名、用户名、密码、ip、端口等 |
| stop_plan | 停止计划 |
用户也可以在/ops/portal/config目录的currentPlan文件中自定义迁移计划，但自定义迁移计划需要遵守以下规则：
-
在currentPlan中每行填入一条启动单个迁移任务的指令，如start_mysql_full_migration，start_mysql_incremental_migration等。指令的顺序遵循：
- start_mysql_full_migration
- start_mysql_full_migration_datacheck
- start_mysql_incremental_migration
- start_mysql_incremental_migration_datacheck
- start_mysql_reverse_migration
如果顺序错误则portal报错。
-
增量校验的上一项一定是增量迁移，全量校验的上一项一定是全量迁移。
-
每个单项任务只能添加一次。
停止计划
举例：
在portal正在执行计划的状态下，另开一个窗口输入以下指令可以停止workspace.id为3的任务：
sh gs_rep_portal.sh stop_plan 3 &
输入指令后，这个进程会退出，而正在执行计划的workspace.id为3的portal主进程会接收到停止计划的消息，从而停止计划。
启动多个计划
portal支持同时启动多个计划，但是这些计划的mysql端应该为各不相同的实例，openGauss端应该为各不相同的数据库：
首先修改配置文件，详情见配置参数环节。
使用workspace.id为p1启动第一个迁移计划（这里以启动计划3为例）：
sh gs_rep_portal.sh start_plan3 p1 &
然后再次修改配置文件。
使用workspace.id为p2启动第一个迁移计划（这里以启动计划3为例）：
sh gs_rep_portal.sh start_plan3 p2 &
这样就启动了多个portal。
卸载迁移工具
使用以下指令可以卸载不同功能对应的迁移工具，举例：
sh gs_rep_portal.sh uninstall_mysql_all_migration_tools 1 &
在命令行运行这条命令可以卸载所有功能用到的迁移工具。
| 指令名称 | 指令说明 |
|---|---|
| uninstall_mysql_full_migration_tools | 卸载mysql全量迁移工具 |
| uninstall_mysql_incremental_migration_tools | 卸载mysql增量迁移工具 |
| uninstall_mysql_datacheck_tools | 卸载mysql数据校验工具 |
| uninstall_mysql_reverse_migration_tools | 卸载mysql反向迁移工具 |
| uninstall_mysql_all_migration_tools | 卸载mysql迁移工具 |
完整数据迁移流程
1.下载gs_rep_portal安装包
wget -c https://opengauss.obs.cn-south-1.myhuaweicloud.com/latest/tools/centos7/PortalControl-7.0.0-RC3-x86_64.tar.gz
2.解压gs_rep_portal安装包
tar -zxvf PortalControl-7.0.0-RC3-x86_64.tar.gz
3.在/ops/portal/config目录的toolspath.properties文件中修改安装路径，然后启动命令安装
sh gs_rep_portal.sh install_mysql_all_migration_tools 1 &
4.在/ops/portal/config目录的migrationConfig.properties文件中修改迁移参数，指定新的workspace.id为2启动迁移计划3
sh gs_rep_portal.sh start_plan3 2 &
5.程序将自动运行至增量迁移和增量校验同时开启中，让workspace.id为2的任务停止增量迁移，此时程序进入等待状态，之后可以启动反向迁移或停止计划
sh gs_rep_portal.sh stop_incremental_migration 2 &
6.启动反向迁移，此时程序进入反向迁移状态，之后可以停止计划
sh gs_rep_portal.sh run_reverse_migration 2 &
7.停止workspace.id为2的计划
sh gs_rep_portal.sh stop_plan 2 &
参与贡献
- Fork 本仓库
- 新建 Feat_xxx 分支
- 提交代码
- 新建 Pull Request
特技
- 使用 Readme_XXX.md 来支持不同的语言，例如 Readme_en.md, Readme_zh.md
- Gitee 官方博客 blog.gitee.com
- 你可以 https://gitee.com/explore 这个地址来了解 Gitee 上的优秀开源项目
- GVP 全称是 Gitee 最有价值开源项目，是综合评定出的优秀开源项目
- Gitee 官方提供的使用手册 https://gitee.com/help
- Gitee 封面人物是一档用来展示 Gitee 会员风采的栏目 https://gitee.com/gitee-stars/