文档中心

云搜索服务

数据迁移

使用火山 TOS 跨云迁移数据

如果需要进行数据迁移的源集群在本地 IDC 环境或者在其他云厂商环境，则可以参考本文档将源集群的快照数据想办法存放到火山 TOS 中，然后在火山引擎 ES 集群中读取 TOS 快照数据并恢复索引。

数据迁移流程图

迁移其他云厂商的 Elasticsearch 集群数据，可以将快照存储到自己云的对象存储中，然后火山 TOS 通过配置迁移任务获取到快照数据。

迁移本地 IDC 环境内的 Elasticsearch 集群数据，可以直接将快照存储到火山引擎的 TOS。

注意事项

如果迁移本地 IDC 环境内的 Elasticsearch 集群数据，需要确保源 Elasticsearch 集群和目的火山 ES 集群分别与火山 TOS 网络互通。

如果迁移其他云厂商的 Elasticsearch 集群数据，需要确保源 Elasticsearch 集群中没有使用自研功能。

需要确保源集群和目的集群的版本是兼容的。目前火山引擎云搜索服务支持 6.7.1、6.8.23 和 7.10.2 三个版本的 ES 集群，版本兼容情况如下表所示。如需了解更多版本兼容情况，可参考开源文档 snapshot restore version compatibility。

如果需要迁移到火山引擎云搜索服务的 OpenSearch 2.9.0 版本实例，可以使用 Logstash 进行数据迁移。详细操作，请参见使用 Logstash 跨集群迁移数据。

快照版本
集群版本

6.x
7.x
6.x
✅
✅
7.x
❌
✅

场景一：迁移本地 IDC 环境 Elasticsearch 集群数据

准备工作

获取本地 IDC 的源 Elasticsearch 集群的访问用户、用户密码，以及访问地址。

获取目的火山 ES 集群的访问用户、用户密码，以及访问地址。相关文档，请参见查看实例详情。如果需要为火山 ES 集群开通公网访问，请参见配置实例公网访问。

获取火山账号的 AccessKey 和 SecretAccessKey。如何获取，请参见API访问密钥管理。

提前创建火山引擎 TOS Bucket，并获取相关信息。如何创建 Bucket，请参见创建存储桶。

存储桶名称：doc-test

所属地域：cn-beijing

S3 Endpoint：tos-s3-cn-beijing.volces.com

一、源集群中创建快照

安装 repository-s3 插件

火山引擎 TOS 兼容 AWS S3 协议。在本地 IDC 的源 Elasticsearch 集群中，您可以直接通过官方插件 repository-s3 进行数据备份。

可以先通过 _cat/plugins API 查看集群已安装的插件列表。

如果没有安装 repository-s3 插件，则需要在每个节点上手动安装，安装后重启集群。

执行以下命令，安装 repository-s3 插件。

如需了解 repository-s3 插件安装的更多信息，可参考开源文档 S3 Repository Plugin。

sudo bin/elasticsearch-plugin install repository-s3

注意

repository-s3 插件在创建快照存储库时，需要获取能够访问对应 S3 的 access_key 和secret_key 信息。但出于安全考虑，默认情况下集群不允许显示配置 access_key 和secret_key，因此您在使用时可能会出现 Setting [access_key] is insecure, but property [allow_insecure_settings] is not set 报错。

您可以选择如下任意一种方案来避免出现该报错：

方案 1 ：重启集群前，为每个节点的 config/jvm.options 文件中新增一行 es.allow_insecure_settings=true 配置，该配置可允许集群显示配置 access_key 和secret_key。

方案 2 ：在命令行中分别执行如下命令，来手动添加access_key 和 secret_key。

bin/elasticsearch-keystore add s3.client.default.access_key

bin/elasticsearch-keystore add s3.client.default.secret_key

若选择方案 2 手动添加了 access_key 和 secret_key，那么在创建快照存储库时，您无需再重复配置 access_key 和 secret_key。

创建快照存储库

在本地 IDC 的源 Elasticsearch 集群中，执行以下命令，创建一个快照存储库。

curl -X PUT http://${source_username}:${source_password}@${source_es_host}/_snapshot/${repo_name}?pretty -H 'Content-Type: application/json' -d'​
{​
  "type" : "s3",​
    "settings" : {​
      "bucket" : "${bucket_name}",​
      "path_style_access" : "false",​
      "endpoint" : "${tos_s3_endpoint}",​
      "protocol" : "http",​
      "client" : "default",​
      "base_path" : "${base_path}",​
      "region" : "${bucket_region}",​
      "access_key": "${your_access_key}",​
      "secret_key": "${your_secret_key}"​
    }​
}​
'​

参数位置	参数说明
请求 URL	source_username：源 Elasticsearch 集群的访问用户。 source_password：源 Elasticsearch 集群的访问用户密码。 source_es_host：源 Elasticsearch 集群的访问地址。 repo_name：自定义设置新建快照存储库的名称，例如 doc-repo。
TOS 配置	bucket：火山引擎 TOS Bucket 的名称。 endpoint：火山引擎 TOS Bucket 的 S3 Endpoint，例如 tos-s3-cn-beijing.volces.com。 base_path：目标端 TOS 桶内存放快照文件的路径，不能以 / 开头和结尾。建议 base_path 和 repo_name 设置为相同值，方便管理。 region：火山引擎 TOS Bucket 的所属地域的 Region ID，例如 cn-beijing。 access_key：火山引擎账号的 AccessKey。如何获取，请参见 API访问密钥管理。 secret_key：火山引擎账号的 SecretAccessKey。说明若您在安装 repository-s3 插件时，已通过 bin/elasticsearch-keystore add 命令手动添加了access_key 和 secret_key，那么在创建快照存储库时，无需再重复配置 access_key 和 secret_key。

创建索引快照

在本地 IDC 的源 Elasticsearch 集群中，执行以下命令，创建索引快照。快照数据存储到新建的快照存储库。

curl -X POST http://${source_username}:${source_password}@${source_es_host}/_snapshot/${repo_name}/${snapshot_name}?wait_for_completion=true' \​
-H 'Content-Type: application/json' \​
-d '{​
  "indices": "${index_name}",​
  "ignore_unavailable": false,​
  "include_global_state": false​
}'​

参数位置	参数说明
请求 URL	source_username：源 Elasticsearch 集群的访问用户。 source_password：源 Elasticsearch 集群的访问用户密码。 source_es_host：源 Elasticsearch 集群的访问地址。 repo_name：新建的快照存储库的名称，比如“doc-repo”。 snapshot_name：自定义设置快照名称，比如“doc-snapshot”。 wait_for_completion=true：当系统有快照正处于IN_PROGRESS（正在运行中）状态，默认情况无法继续创建快照。如果您仍然想要继续创建快照，则可以在请求中添加该参数并设置为true。
快照配置	indices：快照中需要包含或删除的索引列表，默认包含所有索引。多个索引使用英文逗号（,）分隔。在索引名称前添加减号（-），表示删除索引。通配符（）用于替代索引名称的部分内容，如 myindex，用以匹配符合该表达式的索引。 ignore_unavailable：当indices列表中的索引不存在，是否忽略而不导致快照失败。 true：表示忽略，当索引不存在时仍继续快照。 false：默认值，表示不忽略，索引不存在时导致快照失败。 include_global_state：是否在快照中包含集群状态。 true：默认值，表示包含集群状态。 false：表示不包含集群状态。

查看快照进度

源 Elasticsearch 集群执行创建快照的命令后，您可以通过以下命令查看快照的创建进度。通过返回值的end_time确定快照是否创建完成。

curl -X GET http://${source_username}:${source_password}@${source_es_host}/_snapshot/${repo_name}/${snapshot_name}?pretty​

二、TOS 快照恢复到火山 ES 集群

创建快照存储库

在火山 ES 集群中，使用相同 TOS Bucket 创建一个快照存储库。

curl -X PUT http://${target_username}:${target_password}@${target_es_host}/_snapshot/${repo_name}?pretty -H 'Content-Type: application/json' -d'​
{​
  "type" : "s3",​
    "settings" : {​
      "bucket" : "${your_bucket_name}",​
      "path_style_access" : "false",​
      "endpoint" : "${tos_s3_endpoint}",​
      "protocol" : "http",​
      "client" : "default",​
      "base_path" : "${your_base_path}",​
      "region" : "${your_bucket_region}",​
      "access_key": "${your_access_key}",​
      "secret_key": "${your_secret_key}"​
    }​
}​
'​

参数位置	参数说明
请求 URL	target_username：目的火山 ES 集群的访问用户。 target_password：目的火山 ES 集群的访问用户密码。 target_es_host：目的火山 ES 集群的访问地址。 repo_name：自定义设置新建快照存储库的名称，比如“doc-repo”。
TOS 配置	bucket：火山引擎 TOS Bucket 的名称。 endpoint：火山引擎 TOS Bucket 的 S3 Endpoint，比如“tos-s3-cn-beijing.volces.com”。 base_path：目标端 TOS 桶内存放快照文件的路径，不能以/开头和结尾。建议base_path和repo_name设置为相同值，方便管理。 region：火山引擎 TOS Bucket 的所属地域的 Region ID，比如“cn-beijing”。 access_key：火山引擎账号的 AccessKey。如何获取，请参见API访问密钥管理。 secret_key：火山引擎账号的 SecretAccessKey。

从 TOS 快照恢复索引

在火山 ES 集群中，可以从 TOS Bucket 中读取快照数据，然后恢复索引。快照恢复索引时，可以修改索引名称，也可以不修改索引名称，请按需查看对应的命令行。

恢复索引时，保留索引原名。对于系统索引（.开头），恢复为以source_system_index_开头的索引。

curl -X POST http://${target_username}:${target_password}@${target_es_host}/_snapshot/${repo_name}/${snapshot_name}/_restore?wait_for_completion=true' \
-H 'Content-Type: application/json' \
-d '{
"ignore_unavailable": false,
"rename_pattern": "(\\..+)",
"rename_replacement": "source_system_index_$1"
}'

恢复索引时，修改索引名称。以下示例表示将快照中的索引统一恢复为restored_开头的索引。

curl -X POST http://${target_username}:${target_password}@${target_es_host}/_snapshot/${repo_name}/${snapshot_name}/_restore?wait_for_completion=true' \
-H 'Content-Type: application/json' \
-d '{
"ignore_unavailable": false,
"rename_pattern": "(.+)",
"rename_replacement": "restored_$1"
}'

恢复索引的命令行涉及到以下参数，请根据真实情况填写。恢复索引还支持其他更多参数，如需了解，可参见开源文档Restore a snapshot。

参数位置	参数说明
请求 URL	target_username：目的火山 ES 集群的访问用户。 target_password：目的火山 ES 集群的访问用户密码。 target_es_host：目的火山 ES 集群的访问地址。 repo_name：快照存储库的名称，比如“doc-repo”。 snapshot_name：需要恢复的快照名称，即在源 Elasticsearch 集群中创建的快照，比如“doc-snapshot”。
恢复索引配置	ignore_unavailable：是否忽略索引不存在，而不导致恢复快照失败。该示例中未设置具体的索引列表，表示恢复快照中的全部索引。 true：表示忽略，当索引不存在时仍继续恢复快照。 false：默认值，表示不忽略，索引不存在时导致恢复快照失败。 rename_pattern：索引名称的正则表达式过滤条件，将符合过滤条件的索引进行重命名。 rename_replacement：为匹配到的索引填写重命名规则。示例值restored_$1表示在需要恢复的索引名称前面添加restored_前缀。

查看恢复进度

目的火山 ES 集群执行从 TOS 快照恢复索引的命令后，您可以通过以下命令查看恢复进度。

curl http://${target_username}:${target_password}@${target_es_host}/_cat/recovery/${index_name}​

您还可以通过对比查看源 Elasticsearch 集群和目的火山 ES 集群对应索引settings、mapping是否一致，以及通过 _cat/indices API 对比文档数量是否一致，一致则表示同步完成。

场景二：迁移其他云厂商 Elasticsearch 集群数据

准备工作

获取目的火山 ES 集群的访问用户、用户密码，以及访问地址。相关文档，请参见查看实例详情。如果需要为火山 ES 集群开通公网访问，请参见配置实例公网访问。

获取火山账号的 AccessKey 和 SecretAccessKey。如何获取，请参见API访问密钥管理。

配置 TOS 迁移任务时，需要配置其他云厂商对象存储相关信息。请先获取其他云厂商账号的 AccessKey 和 SecretAccessKey 信息、对象存储桶名称和访问地址。

提前创建火山引擎 TOS Bucket，并获取相关信息。如何创建 Bucket，请参见创建存储桶。

存储桶名称：doc-test

所属地域：cn-beijing

S3 Endpoint：tos-s3-cn-beijing.volces.com

一、源集群创建快照

如果需要迁移其他云厂商的 Elasticsearch 集群数据，可以先将快照存储到自己云的对象存储中。

请根据自己所属云，查看对应的文档，此处提供以下三种云环境创建快照的文档链接。

阿里云 Elasticsearch 集群创建快照：手动备份

腾讯云 Elasticsearch 集群创建快照：使用 COS 进行备份及恢复

华为云 Elasticsearch 集群创建快照：手动创建快照

二、配置 TOS 迁移任务

在火山引擎 TOS 中，您可以通过配置迁移任务将其他云厂商对象存储中的数据迁移到火山对象存储 TOS。

配置迁移任务的具体操作，请参见创建迁移任务-使用公共网络

三、TOS 快照恢复到火山 ES 集群

创建快照存储库

在火山 ES 集群中，使用火山 TOS Bucket 创建一个快照存储库。

curl -X PUT http://${target_username}:${target_password}@${target_es_host}/_snapshot/${repo_name}?pretty -H 'Content-Type: application/json' -d'​
{​
  "type" : "s3",​
    "settings" : {​
      "bucket" : "${your_bucket_name}",​
      "path_style_access" : "false",​
      "endpoint" : "${tos_s3_endpoint}",​
      "protocol" : "http",​
      "client" : "default",​
      "base_path" : "${your_base_path}",​
      "region" : "${your_bucket_region}",​
      "access_key": "${your_access_key}",​
      "secret_key": "${your_secret_key}"​
    }​
}​
'​

参数位置	参数说明
请求 URL	target_username：目的火山 ES 集群的访问用户。 target_password：目的火山 ES 集群的访问用户密码。 target_es_host：目的火山 ES 集群的访问地址。 repo_name：自定义设置新建快照存储库的名称，比如“doc-repo”。
TOS 配置	bucket：火山引擎 TOS Bucket 的名称。 endpoint：火山引擎 TOS Bucket 的 S3 Endpoint，比如“tos-s3-cn-beijing.volces.com”。 base_path：目标端 TOS 桶内存放快照文件的路径，不能以/开头和结尾。建议base_path和repo_name设置为相同值，方便管理。 region：火山引擎 TOS Bucket 的所属地域的 Region ID，比如“cn-beijing”。 access_key：火山引擎账号的 AccessKey。如何获取，请参见API访问密钥管理。 secret_key：火山引擎账号的 SecretAccessKey。

从 TOS 快照恢复索引

恢复索引时，保留索引原名。对于系统索引（.开头），恢复为以source_system_index_开头的索引。

curl -X POST http://${target_username}:${target_password}@${target_es_host}/_snapshot/${repo_name}/${snapshot_name}/_restore?wait_for_completion=true' \
-H 'Content-Type: application/json' \
-d '{
"ignore_unavailable": false,
"rename_pattern": "(\\..+)",
"rename_replacement": "source_system_index_$1"
}'

恢复索引时，修改索引名称。以下示例表示将快照中的索引统一恢复为restored_开头的索引。

curl -X POST http://${target_username}:${target_password}@${target_es_host}/_snapshot/${repo_name}/${snapshot_name}/_restore?wait_for_completion=true' \
-H 'Content-Type: application/json' \
-d '{
"ignore_unavailable": false,
"rename_pattern": "(.+)",
"rename_replacement": "restored_$1"
}'

恢复索引的命令行涉及到以下参数，请根据真实情况填写。恢复索引还支持其他更多参数，如需了解，可参见开源文档Restore a snapshot。

参数位置	参数说明
请求 URL	target_username：目的火山 ES 集群的访问用户。 target_password：目的火山 ES 集群的访问用户密码。 target_es_host：目的火山 ES 集群的访问地址。 repo_name：快照存储库的名称，比如“doc-repo”。 snapshot_name：需要恢复的快照名称，即从其他云厂商迁移到火山 TOS Bucket 中的快照数据，比如“doc-snapshot”。
恢复索引配置	ignore_unavailable：是否忽略索引不存在，而不导致恢复快照失败。该示例中未设置具体的索引列表，表示恢复快照中的全部索引。 true：表示忽略，当索引不存在时仍继续恢复快照。 false：默认值，表示不忽略，索引不存在时导致恢复快照失败。 rename_pattern：索引名称的正则表达式过滤条件，将符合过滤条件的索引进行重命名。 rename_replacement：为匹配到的索引填写重命名规则。示例值restored_$1表示在需要恢复的索引名称前面添加restored_前缀。

查看恢复进度

目的火山 ES 集群执行从 TOS 快照恢复索引的命令后，您可以通过以下命令查看恢复进度。

curl http://${target_username}:${target_password}@${target_es_host}/_cat/recovery/${index_name}​

最近更新时间：2026.03.03 17:07:08

这个页面对您有帮助吗？

有用

无用

快照版本	集群版本
快照版本		6.x	7.x
6.x	✅	✅
7.x	❌	✅