大网数据广告活动
数据库部署与 SQL 参考

跨集群数据迁移工具

· 52CE 我爱测

StarRocks 跨集群数据迁移工具由 StarRocks 社区提供。您可以使用该工具轻松地将数据从源集群迁移到目标集群。

跨集群数据迁移工具

StarRocks 跨集群数据迁移工具由 StarRocks 社区提供。您可以使用该工具轻松地将数据从源集群迁移到目标集群。

迁移路径 支持信息
从存算一体到存算一体 从 v3.1.8 和 v3.2.3 起
从存算一体到存算分离 从 v3.1.8 和 v3.2.3 起
从存算分离到存算分离 从 v4.1 起
从存算分离到存算一体 不支持

准备工作

在源集群上

无需在源集群上执行任何准备工作。

在目标集群上

数据迁移前,必须在目标集群上完成以下准备工作。

开放端口

如果您已启用防火墙,则必须开放以下端口:

组件 端口 默认值
FE query_port 9030
FE http_port 8030
FE rpc_port 9020
BE/CN be_http_port 8040
BE/CN be_port 9060

在源集群上

迁移期间,源集群的 Auto-Vacuum 机制可能会删除目标 CN 仍需读取的历史数据版本。为防止这种情况发生,您必须通过动态设置 FE 配置项 lake_autovacuum_grace_period_minutes 为一个较大的值来延长 Auto-Vacuum 宽限期:

ADMIN SET FRONTEND CONFIG("lake_autovacuum_grace_period_minutes"="10000000");

该设置会阻止源集群在迁移期间回收过期的对象存储文件,这将导致存储放大。建议尽量缩短迁移窗口,并在迁移完成后将该配置项重置为默认值 30:

ADMIN SET FRONTEND CONFIG("lake_autovacuum_grace_period_minutes"="30");

在目标集群上

数据迁移前,必须在目标集群上完成以下准备工作。

开放端口

如果您已启用防火墙,则必须开放以下端口:

组件 端口 默认值
FE query_port 9030
FE http_port 8030
FE rpc_port 9020

禁用 Compaction

迁移期间必须在目标集群上禁用 Compaction,以防止与传入的复制数据发生冲突。

  1. 动态禁用 Compaction:

    ADMIN SET FRONTEND CONFIG("lake_compaction_max_tasks"="0");
    
  2. 为防止集群重启后 Compaction 被重新启用,还需在 FE 配置文件 fe.conf 中添加以下配置:

    lake_compaction_max_tasks = 0
    

迁移完成后,请从 fe.conf 中删除上述配置以重新启用 Compaction,并执行以下语句动态启用 Compaction:

ADMIN SET FRONTEND CONFIG("lake_compaction_max_tasks"="-1");

在目标集群上创建源存储卷

迁移工具会识别每张源表使用的存储卷,并按照命名规范 src_<source_volume_name> 在目标集群上查找对应的存储卷。在启动迁移前,您必须预先创建这些存储卷。

这些存储卷仅在迁移期间使用,目的是让目标 CN 能够读取源集群的对象存储。迁移完成后,这些存储卷将不再需要,可以删除。

  1. 在源集群上,列出所有存储卷:

    SHOW STORAGE VOLUMES;
    
  2. 对于计划迁移的表所使用的每个存储卷,查看其配置信息:

    DESCRIBE STORAGE VOLUME <volume_name>;
    

    示例输出:

    +---------------------+------+-----------+-------------------------------+-----------------------------+
    | Name                | Type | IsDefault | Location                      | Params                      |
    +---------------------+------+-----------+-------------------------------+-----------------------------+
    | builtin_storage_vol | S3   | true      | s3://my-bucket                | {"aws.s3.region":"...",...} |
    +---------------------+------+-----------+-------------------------------+-----------------------------+
    
  3. 在目标集群上,使用相同的对象存储凭证创建一个镜像存储卷,但名称前缀为 src_:

    CREATE STORAGE VOLUME src_<source_volume_name>
    TYPE = S3
    LOCATIONS = ("<same_location_as_source>")
    PROPERTIES
    (
        "enabled" = "true",
        "aws.s3.region" = "<region>",
        "aws.s3.endpoint" = "<endpoint>",
        "aws.s3.use_aws_sdk_default_behavior" = "false",
        "aws.s3.use_instance_profile" = "false",
        "aws.s3.access_key" = "<access_key>",
        "aws.s3.secret_key" = "<secret_key>",
        "aws.s3.enable_partitioned_prefix" = "false"
    );
    
    • 无论源集群的设置如何,请将 aws.s3.enable_partitioned_prefix 设置为 false。迁移工具直接使用源分区的完整路径读取文件,因此不能对镜像存储卷应用分区前缀。
    • 对每个待迁移表所使用的唯一存储卷重复此步骤。例如,如果源集群使用 builtin_storage_volume,则在目标集群上创建 src_builtin_storage_volume。
    • 建议为源存储卷使用临时凭证(access key / secret key),迁移完成后可以将其吊销。

迁移 Range 分布表

Range 分布表迁移仅支持从存算分离集群迁移到存算分离集群。迁移工具会根据源表定义自动创建缺失的目标表,请勿手动创建目标表。

请先记录以下 FE 配置的原值。对于每项动态配置,还需在每个适用 FE 的 fe.conf 中持久化相同设置,避免 FE 重启后迁移约束发生变化。

  1. 在源集群和目标集群上禁用 Tablet 合并,并保持 Range 分布启用:

    ADMIN SET FRONTEND CONFIG ("tablet_reshard_enable_tablet_merge" = "false");
    ADMIN SET FRONTEND CONFIG ("enable_range_distribution" = "true");
    
  2. enable_execute_script_on_frontend 是静态配置。请在源集群和目标集群的每个 FE 的 fe.conf 中将其设置为 true,并在迁移窗口开始前重启 FE。

    enable_execute_script_on_frontend = true
    
  3. 在目标集群上将目标大小设置为 0,关闭 Tablet 自动分裂和合并:

    ADMIN SET FRONTEND CONFIG ("tablet_reshard_target_size" = "0");
    

    请勿改用极大值。迁移工具根据源表定义创建目标表,源表上设置的表属性 tablet_reshard_target_size 会一并带到目标表。这些表会以表属性为准,极大值对其不起作用。设置为 0 则会关闭所有表的自动分裂和合并。迁移工具提交的分裂按精确边界执行,不依赖该配置。

  4. 启动工具前,分别在源集群和目标集群上执行以下查询:

    SELECT JOB_ID, DB_NAME, TABLE_NAME, JOB_TYPE, JOB_STATE
    FROM information_schema.tablet_reshard_jobs
    WHERE JOB_TYPE = 'MERGE_TABLET'
      AND JOB_STATE NOT IN ('FINISHED', 'ABORTED');
    

    只有该查询在两个集群上都没有返回相关行时,才能开始迁移。该条件会等待所有非终态合并作业排空,包括 PENDING、PREPARING、RUNNING、CLEANING 和 ABORTING。保持源集群自动分裂启用,使源拓扑可以继续演进。迁移期间不要在目标集群上执行可能改变拓扑的独立写入或预分裂操作。

工具通过仅在 Leader 上执行的 ADMIN EXECUTE ON FRONTEND 调用读取源集群和目标集群的实际拓扑。每个 Tablet 的完整 Range 值包含 lowerBound、lowerIncluded、upperBound 和 upperIncluded。空端点表示负无穷或正无穷。在有限的多列端点列表中,空单元格表示 SQL NULL,其余单元格均为规范字符串值。该表示方式保留两端的包含标志,并能区分字面字符串 NULL 与 SQL NULL。该桥接会保留完整表示以便后续扩展,但当前 FE 到 BE 的分裂链路仅接受左闭右开的 [lower, upper) 子区间。

ADMIN EXECUTE ON FRONTEND 不会转发到其他 FE。工具必须发现并直连每个集群的 Leader FE,迁移用户必须拥有 SYSTEM 级别的 OPERATE 权限。FE 脚本属于特权代码:请使用专用可信账号、妥善保护凭证,并将生成的脚本参数作为正确转义的 JSON 放入单个 SQL 字符串中。DDL 执行器必须完整发送 ADMIN 语句,不得按分号拆分。迁移后,请按下文说明恢复已记录的静态脚本执行配置。

对于每张 Range 分布表,工具会比较最新读取的源拓扑和目标拓扑。如果两者不一致,工具会停止为该表生成新的复制作业,但允许已排队、正在发送和已在目标集群运行的作业完成。这些作业及复制事务全部排空后,工具通过既有 DDL 队列提交精确边界 Tablet 分裂。只有再次读取拓扑并确认源、目标 Range 在结构上完全相等后,才会恢复复制。

Range 分布不会改变存算分离的版本同步语义。每次复制仍使用源物理分区的 visibleVersion,比较完整的元数据和文件集合,并跳过目标集群上已存在的文件。

在存算分离集群之间迁移并使用透明数据加密 (TDE) 时,新复制的私有独立物理文件会使用源加密元数据读取,然后按目标策略重新加密。若无法解封装源密钥层级,迁移会在目标端发布前失败。当源文件已加密或目标端启用 TDE 时,不支持新复制共享或打包的物理文件。目标端已存在的对象可以直接复用,并保留其目标端加密元数据。从存算一体源迁移到存算分离目标时,如果源 Rowset 或 DCG 文件已加密,迁移会以失败关闭方式停止;该路径不支持对这些文件解密并按目标策略重新加密。

此流程仅支持通过分裂收敛。如果收敛需要目标集群执行合并,流程将以失败关闭方式停止,包括源集群发生合并、目标集群存在独有边界、Range 交叉或目标拓扑比源拓扑更细的情况。Range Colocate 布局也不受支持。

迁移完成后,请先等待工具、复制作业和事务以及 Tablet Reshard 作业全部排空。对于源、目标集群的合并配置和目标 Tablet 大小等动态配置,请使用 ADMIN SET FRONTEND CONFIG 恢复,并在 fe.conf 中恢复其已记录的值。仅当迁移前已启用自动 Reshard 时才恢复该行为,否则保持禁用。对于静态配置 enable_execute_script_on_frontend,请在每个 FE 的 fe.conf 中恢复已记录的值并重启 FE。仅当其原值为 false,或您有意采用更严格的迁移后安全策略时,才禁用脚本执行。

为复制启用旧版兼容性

StarRocks 在新旧版本之间的行为可能存在差异,从而导致跨集群数据迁移过程中出现问题。因此,在数据迁移前,您必须在目标集群上启用旧版兼容性,并在数据迁移完成后将其禁用。

  1. 您可以使用以下语句检查是否已为复制启用旧版兼容性:

    ADMIN SHOW FRONTEND CONFIG LIKE 'enable_legacy_compatibility_for_replication';
    

    如果返回 true,则表示已为复制启用旧版兼容性。

  2. 动态启用复制旧版兼容性:

    ADMIN SET FRONTEND CONFIG("enable_legacy_compatibility_for_replication"="true");
    
  3. 为防止在数据迁移过程中集群重启导致旧版兼容性自动禁用,还需在 FE 配置文件 fe.conf 中添加以下配置项:

    enable_legacy_compatibility_for_replication = true
    

数据迁移完成后,您需要从配置文件中删除 enable_legacy_compatibility_for_replication = true,并使用以下语句动态禁用复制旧版兼容性:

ADMIN SET FRONTEND CONFIG("enable_legacy_compatibility_for_replication"="false");

配置数据迁移(可选)

您可以使用以下 FE 和 BE 参数配置数据迁移操作。在大多数情况下,默认配置即可满足需求。如果您希望使用默认配置,可以跳过此步骤。

请注意,增大以下配置项的值可以加速迁移,但也会增加源集群的负载压力。

FE 参数

以下 FE 参数为动态配置项。有关如何修改,请参阅配置 FE 动态参数。

参数 默认值 单位 描述
replication_max_parallel_table_count 100 - 允许并发的数据同步任务最大数量。StarRocks 为每张表创建一个同步任务。
replication_max_parallel_replica_count 10240 - 允许并发同步的 tablet 副本最大数量。
replication_max_parallel_data_size_mb 1048576 MB 允许并发同步的数据最大大小。
replication_transaction_timeout_sec 86400 秒 同步任务的超时时长。

BE 参数

以下 BE 参数为动态配置项。有关如何修改,请参阅配置 BE 动态参数。

参数 默认值 单位 描述
replication_threads 0 - 执行同步任务的线程数。0 表示将线程数设置为 BE 所在机器 CPU 核数的 4 倍。

步骤一:安装工具

建议将迁移工具安装在目标集群所在的服务器上。

  1. 启动终端,下载工具的二进制包。

    wget https://releases.starrocks.io/starrocks/starrocks-cluster-sync.tar.gz
    
  2. 解压安装包。

    tar -xvzf starrocks-cluster-sync.tar.gz
    

步骤二:配置工具

与迁移相关的配置

进入解压后的目录,修改配置文件 conf/sync.properties。

cd starrocks-cluster-sync
vi conf/sync.properties

文件内容如下:

# 如果为 true,所有表将只同步一次,程序完成后自动退出。
one_time_run_mode=false

source_fe_host=
source_fe_query_port=9030
source_cluster_user=root
source_cluster_password=
source_cluster_password_secret_key=

# 如果要在存算分离源集群之间迁移数据,可以留空或省略此项。
source_cluster_token=

target_fe_host=
target_fe_query_port=9030
target_cluster_user=root
target_cluster_password=
target_cluster_password_secret_key=

jdbc_connect_timeout_ms=30000
jdbc_socket_timeout_ms=60000

# 以逗号分隔的数据库名或表名列表,格式为 <db_name> 或 <db_name.table_name>
# 示例:db1,db2.tbl2,db3
# 生效顺序:1. include 2. exclude
include_data_list=
exclude_data_list=

# 如无特殊需求,请保持以下配置的默认值。
target_cluster_storage_volume=
# 此配置项仅用于存算分离集群之间的迁移。
target_cluster_use_builtin_storage_volume_only=false
target_cluster_replication_num=-1
target_cluster_max_disk_used_percent=80
# 为与源集群保持一致,请使用 null。
target_cluster_enable_persistent_index=

max_replication_data_size_per_job_in_gb=1024

meta_job_interval_seconds=180
meta_job_threads=4
ddl_job_interval_seconds=10
ddl_job_batch_size=10

# table config
ddl_job_allow_drop_target_only=false
ddl_job_allow_drop_schema_change_table=true
ddl_job_allow_drop_inconsistent_partition=true
ddl_job_allow_drop_inconsistent_time_partition = true
ddl_job_allow_drop_partition_target_only=true
# index config
enable_bitmap_index_sync=false
ddl_job_allow_drop_inconsistent_bitmap_index=true
ddl_job_allow_drop_bitmap_index_target_only=true
# MV config
enable_materialized_view_sync=false
ddl_job_allow_drop_inconsistent_materialized_view=true
ddl_job_allow_drop_materialized_view_target_only=false
# View config
enable_view_sync=false
ddl_job_allow_drop_inconsistent_view=true
ddl_job_allow_drop_view_target_only=false

replication_job_interval_seconds=10
replication_job_batch_size=10
report_interval_seconds=300

enable_table_property_sync=false

# privilege config
enable_privilege_sync=false
ddl_job_allow_drop_user_target_only=false
ddl_job_allow_drop_role_target_only=false
ddl_job_allow_drop_inconsistent_user=true
ddl_job_allow_revoke_grant_target_only=false
privilege_sync_exclude_users=
privilege_sync_exclude_roles=

各参数说明如下:

参数 描述
one_time_run_mode 是否启用一次性同步模式。启用后,迁移工具只执行全量同步而不进行增量同步。
source_fe_host 源集群 FE 的 IP 地址或 FQDN(全限定域名)。
source_fe_query_port 源集群 FE 的查询端口(query_port)。
source_cluster_user 登录源集群使用的用户名。该用户必须被授予 SYSTEM 级别的 OPERATE 权限。
source_cluster_password 登录源集群使用的用户密码。
source_cluster_password_secret_key 用于加密源集群登录用户密码的密钥。默认值为空字符串,表示登录密码不加密。如需加密 source_cluster_password,可以通过 SQL 语句 SELECT TO_BASE64(AES_ENCRYPT('<source_cluster_password>','<source_cluster_password_ secret_key>')) 获取加密后的 source_cluster_password 字符串。
source_cluster_token 源集群的 Token。有关如何获取集群 Token,请参阅下方的获取集群 Token。
注意
在存算分离集群之间迁移时不需要集群 Token,因为文件直接从对象存储读取。如果要在存算分离源集群之间迁移数据,可以留空或省略此项。
target_fe_host 目标集群 FE 的 IP 地址或 FQDN(全限定域名)。
target_fe_query_port 目标集群 FE 的查询端口(query_port)。
target_cluster_user 登录目标集群使用的用户名。该用户必须被授予 SYSTEM 级别的 OPERATE 权限。
target_cluster_password 登录目标集群使用的用户密码。
target_cluster_password_secret_key 用于加密目标集群登录用户密码的密钥。默认值为空字符串,表示登录密码不加密。如需加密 target_cluster_password,可以通过 SQL 语句 SELECT TO_BASE64(AES_ENCRYPT('<target_cluster_password>','<target_cluster_password_ secret_key>')) 获取加密后的 target_cluster_password 字符串。
jdbc_connect_timeout_ms FE 查询的 JDBC 连接超时时间,单位为毫秒。默认值:30000。
jdbc_socket_timeout_ms FE 查询的 JDBC socket 超时时间,单位为毫秒。默认值:60000。
include_data_list 需要迁移的数据库和表,多个对象之间用逗号(,)分隔。例如:db1, db2.tbl2, db3。此项优先于 exclude_data_list 生效。如果要迁移集群中的所有数据库和表,则无需配置此项。
exclude_data_list 不需要迁移的数据库和表,多个对象之间用逗号(,)分隔。例如:db1, db2.tbl2, db3。include_data_list 优先于此项生效。如果要迁移集群中的所有数据库和表,则无需配置此项。
target_cluster_storage_volume 目标集群为存算分离集群时,用于存储目标集群中表的存储卷。如果要使用默认存储卷,无需指定此项。
target_cluster_use_builtin_storage_volume_only 是否在目标集群中使用 builtin_storage_volume 进行迁移。该项仅用于存算分离集群之间的迁移。当此项设置为 true 时,目标集群中创建的表将统一使用 builtin_storage_volume,而不是沿用源集群的 storage_volume 配置。当源集群有多个自定义存储卷,但您希望在目标集群中将所有表统一到一个存储卷下时,此项非常有用。
target_cluster_replication_num 在目标集群中创建表时指定的副本数。如果要使用与源集群相同的副本数,无需指定此项。
target_cluster_max_disk_used_percent 目标集群为存算一体时,目标集群 BE 节点的磁盘使用率阈值。当目标集群任意 BE 的磁盘使用率超过该阈值时,迁移将终止。默认值为 80,即 80%。
meta_job_interval_seconds 迁移工具从源集群和目标集群获取元数据的时间间隔,单位为秒。可以使用此项的默认值。
meta_job_threads 迁移工具从源集群和目标集群获取元数据所使用的线程数。可以使用此项的默认值。
ddl_job_interval_seconds 迁移工具在目标集群上执行 DDL 语句的时间间隔,单位为秒。可以使用此项的默认值。
ddl_job_batch_size 在目标集群上执行 DDL 语句的批量大小。可以使用此项的默认值。
ddl_job_allow_drop_target_only 是否允许迁移工具删除仅存在于目标集群而不存在于源集群的数据库或表。默认值为 false,表示不删除。可以使用此项的默认值。
ddl_job_allow_drop_schema_change_table 是否允许迁移工具删除源集群和目标集群之间 Schema 不一致的表。默认值为 true,表示将被删除。可以使用此项的默认值。迁移工具将在迁移期间自动同步被删除的表。
ddl_job_allow_drop_inconsistent_partition 是否允许迁移工具删除源集群和目标集群之间数据分布不一致的分区。默认值为 true,表示将被删除。可以使用此项的默认值。迁移工具将在迁移期间自动同步被删除的分区。
ddl_job_allow_drop_partition_target_only 是否允许迁移工具删除在源集群中已删除的分区,以保持源集群和目标集群之间的分区一致性。默认值为 true,表示将被删除。可以使用此项的默认值。
replication_job_interval_seconds 迁移工具触发数据同步任务的时间间隔,单位为秒。可以使用此项的默认值。
replication_job_batch_size 迁移工具触发数据同步任务的批量大小。可以使用此项的默认值。
max_replication_data_size_per_job_in_gb 迁移工具触发数据同步任务的数据大小阈值,单位为 GB。如果待迁移分区的大小超过该值,将触发多个数据同步任务。默认值为 1024。可以使用此项的默认值。
report_interval_seconds 迁移工具打印进度信息的时间间隔,单位为秒。默认值:300。可以使用此项的默认值。
target_cluster_enable_persistent_index 是否在目标集群中启用持久化索引。如果未指定此项,目标集群将与源集群保持一致。
注意
在两个存算分离集群之间迁移数据时,工具会自动将主键表 CREATE TABLE 语句中的 persistent_index_type = LOCAL 转换为 CLOUD_NATIVE,无需手动操作。
ddl_job_allow_drop_inconsistent_time_partition 是否允许迁移工具删除源集群和目标集群之间时间不一致的分区。默认值为 true,表示将被删除。可以使用此项的默认值。迁移工具将在迁移期间自动同步被删除的分区。
enable_bitmap_index_sync 是否启用 Bitmap 索引的同步。
ddl_job_allow_drop_inconsistent_bitmap_index 是否允许迁移工具删除源集群和目标集群之间不一致的 Bitmap 索引。默认值为 true,表示将被删除。可以使用此项的默认值。迁移工具将在迁移期间自动同步被删除的索引。
ddl_job_allow_drop_bitmap_index_target_only 是否允许迁移工具删除在源集群中已删除的 Bitmap 索引,以保持源集群和目标集群之间的索引一致性。默认值为 true,表示将被删除。可以使用此项的默认值。
enable_materialized_view_sync 是否启用物化视图的同步。
ddl_job_allow_drop_inconsistent_materialized_view 是否允许迁移工具删除源集群和目标集群之间不一致的物化视图。默认值为 true,表示将被删除。可以使用此项的默认值。迁移工具将在迁移期间自动同步被删除的物化视图。
ddl_job_allow_drop_materialized_view_target_only 是否允许迁移工具删除在源集群中已删除的物化视图,以保持源集群和目标集群之间的物化视图一致性。默认值为 true,表示将被删除。可以使用此项的默认值。
enable_view_sync 是否启用视图的同步。
ddl_job_allow_drop_inconsistent_view 是否允许迁移工具删除源集群和目标集群之间不一致的视图。默认值为 true,表示将被删除。可以使用此项的默认值。迁移工具将在迁移期间自动同步被删除的视图。
ddl_job_allow_drop_view_target_only 是否允许迁移工具删除在源集群中已删除的视图,以保持源集群和目标集群之间的视图一致性。默认值为 true,表示将被删除。可以使用此项的默认值。
enable_table_property_sync 是否启用表属性的同步。
enable_privilege_sync 是否启用用户、角色及其权限的同步。默认值为 false,表示不同步账户元数据。
ddl_job_allow_drop_user_target_only 是否允许迁移工具删除仅存在于目标集群而不存在于源集群的用户。默认值为 false,表示不会被删除。
ddl_job_allow_drop_role_target_only 是否允许迁移工具删除仅存在于目标集群而不存在于源集群的角色。默认值为 false,表示不会被删除。
ddl_job_allow_drop_inconsistent_user 是否允许迁移工具重建(即删除后重新创建)源集群和目标集群之间定义不一致的用户。默认值为 true。仅当该用户的权限在同一轮次中被成功读取时才会重建,以便重建后立即重新授予其权限。
ddl_job_allow_revoke_grant_target_only 是否允许迁移工具回收仅在目标集群中授予而在源集群中未授予的权限。默认值为 false,表示不会被回收。
privilege_sync_exclude_users 迁移工具不修改的用户,多个用户之间以英文逗号(,)分隔。用户可以指定为用户名(jack),也可以指定为完整的用户标识('jack'@'%')。root 和 target_cluster_user 中指定的用户始终被排除。
privilege_sync_exclude_roles 迁移工具不修改的角色,多个角色之间以英文逗号(,)分隔。

获取集群 Token

在存算分离集群之间迁移时不需要集群 Token。如果要在存算分离源集群之间迁移数据,可以跳过此步骤。

集群 Token 存储在 FE 元数据中。登录 FE 节点所在的服务器,运行以下命令:

cat fe/meta/image/VERSION | grep token

输出:

token=wwwwwwww-xxxx-yyyy-zzzz-uuuuuuuuuu

映射存储卷

迁移工具在目标集群上创建表时,按以下优先顺序确定表的存储卷:

  1. 如果 target_cluster_use_builtin_storage_volume_only 设置为 true,则所有表使用 builtin_storage_volume。
  2. 如果 target_cluster_storage_volume 设置为特定存储卷,则所有表使用该指定存储卷。
  3. 否则,默认情况下保留源表的存储卷属性。来自不同源存储卷的表将在目标集群上对应存储卷下创建,前提是这些存储卷在目标集群上存在。

因此,如果您希望保留源集群中每张表的存储卷属性,可以在目标集群中预先创建相同的存储卷。迁移完成后,目标集群中的每张表将继承其在源集群中的存储卷属性。

请注意,带有 src_ 前缀的存储卷用途不同:它们仅在迁移期间使用,目的是让目标 CN 能够读取源集群的对象存储。迁移完成后,src_<name> 存储卷将不再需要,可以删除。

网络相关配置(可选)

数据迁移期间,迁移工具需要访问源集群和目标集群的所有 FE 节点,目标集群需要访问源集群的所有 BE 和 CN 节点。

您可以通过在对应集群上执行以下语句来获取这些节点的网络地址:

-- 获取集群中 FE 节点的网络地址。
SHOW FRONTENDS;
-- 获取集群中 BE 节点的网络地址。
SHOW BACKENDS;
-- 获取集群中 CN 节点的网络地址。
SHOW COMPUTE NODES;

如果这些节点使用了无法从集群外部访问的私有地址(例如 Kubernetes 集群内的内部网络地址),则需要将这些私有地址映射为可从外部访问的地址。

进入工具的解压目录,修改配置文件 conf/hosts.properties。

cd starrocks-cluster-sync
vi conf/hosts.properties

文件的默认内容如下,描述了如何配置网络地址映射:

# <SOURCE/TARGET>_<host>=<mappedHost>[;<srcPort>:<dstPort>[,<srcPort>:<dstPort>...]]

<host> 必须与 SHOW FRONTENDS、SHOW BACKENDS 或 SHOW COMPUTE NODES 返回结果中 IP 列显示的地址一致。

以下示例执行了以下操作:

  1. 将源集群的私有网络地址 192.1.1.1 和 192.1.1.2 分别映射到 10.1.1.1 和 10.1.1.2。
  2. 将 10.1.1.1 上源集群的 FE 端口 8030 和 9030 分别映射到 38030 和 39030。
  3. 将目标集群的私有网络地址 fe-0.starrocks.svc.cluster.local 映射到 10.1.2.1 并重映射端口 9030。
# <SOURCE/TARGET>_<host>=<mappedHost>[;<srcPort>:<dstPort>[,<srcPort>:<dstPort>...]]
SOURCE_192.1.1.1=10.1.1.1;8030:38030,9030:39030
SOURCE_192.1.1.2=10.1.1.2
TARGET_fe-0.starrocks.svc.cluster.local=10.1.2.1;9030:19030

数据迁移期间,迁移工具需要访问源集群和目标集群的所有 FE 节点。

与从存算一体集群迁移不同,您无需配置从目标集群到源集群 CN 节点的网络访问,因为数据直接在对象存储系统之间传输。

您可以通过在对应集群上执行以下语句来获取 FE 网络地址:

-- FE 节点
SHOW FRONTENDS;

如果 FE 节点使用了无法从集群外部访问的私有地址(例如 Kubernetes 集群内的内部网络地址),则需要将这些私有地址映射为可从外部访问的地址。

进入工具的解压目录,修改配置文件 conf/hosts.properties。

cd starrocks-cluster-sync
vi conf/hosts.properties

文件的默认内容如下,描述了如何配置网络地址映射:

# <SOURCE/TARGET>_<host>=<mappedHost>[;<srcPort>:<dstPort>[,<srcPort>:<dstPort>...]]

<host> 必须与 SHOW FRONTENDS 返回结果中 IP 列显示的地址一致。

以下示例将目标集群的 Kubernetes 内部 FQDN 映射到可访问的 IP:

TARGET_frontend-0.frontend.mynamespace.svc.cluster.local=10.1.2.1;9030:19030

用户、角色和权限同步(可选)

默认情况下,迁移工具不同步账户元数据。如果将 enable_privilege_sync 设置为 true,迁移工具还会将源集群的用户、角色及其权限同步到目标集群。

迁移工具每次获取元数据时,都会读取源集群和目标集群的用户、角色及其权限,进行比对,并执行使目标集群与源集群保持一致所需的 DDL 语句。用户定义通过 SHOW CREATE USER 获取,该语句返回的密码为密文,因此迁移过程中不会处理明文密码。

以下对象始终不会被迁移工具修改:

  • root 以及 target_cluster_user 中指定的用户。覆盖目标集群 root 的密码会导致目标集群的运维人员无法登录,删除迁移工具连接所使用的账号会中断工具自身的连接。

  • 不可变的内置角色 root、db_admin、cluster_admin、user_admin 和 security_admin。public 是内置角色但可以修改,因此其权限会被同步,而角色本身不会被改动。

  • privilege_sync_exclude_users 中指定的用户和 privilege_sync_exclude_roles 中指定的角色。

  • 两个集群的 FE 都必须支持 SHOW CREATE USER。如果任一集群的 FE 不支持该语句,迁移工具将跳过用户及其权限,仅同步角色和角色权限。

  • 权限同步的进度会以 Sync privilege progress 为前缀打印到日志文件 log/sync.INFO.log 中,其中列出角色、角色权限、用户和用户权限四个部分各自的状态。

  • 在一次性同步模式(one_time_run_mode=true)下,只有权限也同步一致后,迁移工具才会成功退出。如果任一集群不支持 SHOW CREATE USER,或者权限在连续三次比对后仍不一致,迁移工具将以失败状态退出。

步骤三:启动迁移工具

配置完成后,启动迁移工具以开始数据迁移过程。

./bin/start.sh
  • 如果您要从存算一体集群迁移数据,请确保源集群和目标集群的 BE 节点能够通过网络正常通信。
  • 运行期间,迁移工具会定期检查目标集群的数据是否落后于源集群。如果存在落后,则发起数据迁移任务。
  • 如果源集群持续有新数据写入,数据同步将一直持续,直到目标集群的数据与源集群一致。
  • 迁移期间可以查询目标集群中的表,但请勿向表中写入新数据,否则可能导致目标集群与源集群的数据不一致。目前,迁移工具不会禁止在迁移期间向目标集群写入数据。
  • 请注意,数据迁移不会自动终止。您需要手动检查并确认迁移完成后,再停止迁移工具。

查看迁移进度

查看迁移工具日志

您可以通过迁移工具日志 log/sync.INFO.log 查看迁移进度。

示例 1:查看任务进度。

[图示请参阅官方原文]

重要指标说明如下:

  • Sync job progress:数据迁移进度。迁移工具定期检查目标集群的数据是否落后于源集群,因此进度 100% 仅表示当前检查间隔内数据同步已完成。如果源集群持续有新数据写入,下一个检查间隔内进度可能会下降。
  • total:本次迁移操作中所有类型作业的总数。
  • ddlPending:待执行的 DDL 作业数量。
  • jobPending:待执行的数据同步作业数量。
  • sent:已从源集群发送但尚未开始的数据同步作业数量。理论上该值不应过大,如果该值持续增大,请联系我们的工程师。
  • running:当前正在运行的数据同步作业数量。
  • finished:已完成的数据同步作业数量。
  • failed:失败的数据同步作业数量。失败的数据同步作业将被重新发送,因此在大多数情况下可以忽略此指标。如果该值明显偏大,请联系我们的工程师。
  • unknown:状态未知的作业数量。理论上该值始终应为 0。如果该值不为 0,请联系我们的工程师。

示例 2:查看表迁移进度。

[图示请参阅官方原文]

  • Sync table progress:表迁移进度,即本次迁移任务中已迁移的表数量与需要迁移的表总数之比。
  • finishedTableRatio:至少有一次成功同步任务执行的表的比例。
  • expiredTableRatio:数据已过期的表的比例。
  • total table:本次数据迁移中涉及的表总数。
  • finished table:至少有一次成功同步任务执行的表的数量。
  • unfinished table:尚未执行任何同步任务的表的数量。
  • expired table:数据已过期的表的数量。

查看迁移事务状态

迁移工具为每张表开启一个事务。您可以通过查看对应事务的状态来了解该表的迁移状态。

SHOW PROC "/transactions/<db_name>/running";

<db_name> 是表所在数据库的名称。

查看分区数据版本

您可以通过比较源集群和目标集群中对应分区的数据版本来查看该分区的迁移状态。

SHOW PARTITIONS FROM <table_name>;

<table_name> 是该分区所属表的名称。

查看数据量

您可以通过比较源集群和目标集群的数据量来查看迁移状态。

SHOW DATA;

查看表行数

您可以通过比较源集群和目标集群中各表的行数来查看每张表的迁移状态。

SELECT 
  TABLE_NAME, 
  TABLE_ROWS 
FROM INFORMATION_SCHEMA.TABLES 
WHERE TABLE_TYPE = 'BASE TABLE' 
ORDER BY TABLE_NAME;

迁移后

当 Sync job progress 稳定保持在 100% 且业务已准备好切换时,按以下步骤完成切换:

  1. 停止向源集群写入数据。

  2. 验证停止写入后 Sync job progress 达到并保持在 100%。

  3. 停止迁移工具。

  4. 将您的应用程序指向目标集群地址。

  5. 如果您在存算分离集群之间迁移了数据,请在源集群上恢复 Auto-Vacuum 设置:

    ADMIN SET FRONTEND CONFIG("lake_autovacuum_grace_period_minutes"="30");
    
  6. 如果您在存算分离集群之间迁移了数据,请在目标集群上重新启用 Compaction。从 fe.conf 中删除 lake_compaction_max_tasks = 0 并执行:

    ADMIN SET FRONTEND CONFIG("lake_compaction_max_tasks"="-1");
    
  7. 在目标集群上禁用复制旧版兼容性。从 fe.conf 中删除 enable_legacy_compatibility_for_replication = true 并执行:

    ADMIN SET FRONTEND CONFIG("enable_legacy_compatibility_for_replication"="false");
    

限制

目前支持同步的对象列表如下(未列出的对象表示不支持同步):

  • 数据库
  • 内部表及其数据
  • 物化视图的 Schema 及其构建语句(物化视图中的数据不会被同步。如果物化视图的基表未同步到目标集群,物化视图的后台刷新任务将报错。)
  • 逻辑视图
  • 用户、角色及其权限(默认不同步,通过 enable_privilege_sync 开启)

对于存算分离集群之间的迁移:

  • 目标集群必须运行 v4.1 或更高版本。
  • 不支持从存算分离集群迁移到存算一体目标集群。
  • 源集群表使用的每个存储卷都必须在目标集群上预先创建对应的 src_<volume_name> 存储卷。

本文来自 StarRocks 文档贡献者,按 Apache 2.0 整理版式与相对链接,保留正文与代码。图示请参阅原文。作者与贡献记录。

资料来源与适用范围

资料来源
StarRocks 文档贡献者
适用范围
main 文档快照(2026-11-16)
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-16
授权说明
Apache 2.0

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。