此 API 用于从快照恢复数据到集群。
API #
POST /_snapshot/{repository}/{snapshot}/_restore
API 的作用 #
从指定的快照中恢复数据到集群。恢复操作可以：
- 恢复全部索引：恢复快照中的所有索引
- 恢复部分索引：只恢复指定的索引
- 重命名索引：恢复时重命名索引
- 修改设置：恢复时修改索引设置
- 全局状态：恢复全局集群状态
API 的参数 #
路由参数 #
| 参数 | 类型 | 是否必需 | 描述 |
|---|---|---|---|
repository | string | 必需 | 快照仓库名称 |
snapshot | string | 必需 | 快照名称 |
查询字符串参数 #
| 参数 | 类型 | 是否必需 | 默认值 | 描述 |
|---|---|---|---|---|
master_timeout | time | 可选 | 30s | 等待主节点响应的超时时间 |
wait_for_completion | boolean | 可选 | false | 是否等待恢复操作完成 |
请求体参数 #
| 参数 | 类型 | 是否必需 | 默认值 | 描述 |
|---|---|---|---|---|
indices | array | 可选 | [] | 要恢复的索引列表 支持多索引语法 +test*：包含匹配的索引-test42：排除指定索引 |
partial | boolean | 可选 | false | 是否允许部分恢复 即使某些分片失败也继续 |
include_global_state | boolean | 可选 | false | 是否恢复全局集群状态 包括模板、持久化设置等 |
include_aliases | boolean | 可选 | true | 是否恢复索引别名 |
rename_pattern | string | 可选 | null | 恢复时的重命名模式 正则表达式模式 |
rename_replacement | string | 可选 | null | 重命名替换模式 |
index_settings | object | 可选 | {} | 所有被恢复索引的设置 |
ignore_index_settings | array | 可选 | [] | 恢复时要忽略的索引设置 |
storage_type | string | 可选 | local | 存储类型 可选值： local, remote_snapshot |
请求示例 #
恢复所有索引 #
POST /_snapshot/my-repo/snapshot1/_restore
恢复指定索引 #
POST /_snapshot/my-repo/snapshot1/_restore
{
"indices": ["index1", "index2", "index3"]
}
使用通配符恢复索引 #
POST /_snapshot/my-repo/snapshot1/_restore
{
"indices": "logs-*",
"ignore_unavailable": true
}
恢复时重命名索引 #
POST /_snapshot/my-repo/snapshot1/_restore
{
"indices": "old_index_*",
"rename_pattern": "old_index_(.+)",
"rename_replacement": "restored_index_$1"
}
恢复并包含全局状态 #
POST /_snapshot/my-repo/snapshot1/_restore
{
"indices": "*",
"include_global_state": true
}
恢复并修改索引设置 #
POST /_snapshot/my-repo/snapshot1/_restore
{
"indices": ["index1", "index2"],
"index_settings": {
"index.number_of_replicas": 2,
"index.refresh_interval": "5s"
}
}
忽略某些索引设置 #
POST /_snapshot/my-repo/snapshot1/_restore
{
"indices": ["index1"],
"ignore_index_settings": ["index.lifecycle.name", "index.routing.allocation.include._tier_preference"]
}
等待恢复完成 #
POST /_snapshot/my-repo/snapshot1/_restore?wait_for_completion=true
响应示例 #
成功响应 #
{
"accepted": true
}
等待完成的响应 #
{
"snapshot": {
"snapshot": "snapshot1",
"repository": "my-repo",
"indices": ["index1", "index2", "index3"]
},
"shards": {
"total": 9,
"successful": 9,
"failed": 0
}
}
错误响应 - 索引已存在 #
{
"error": {
"root_cause": [
{
"type": "snapshot_restore_exception",
"reason": "[my-repo:snapshot1] cannot restore index [index1] because it's open"
}
],
"type": "snapshot_restore_exception",
"reason": "[my-repo:snapshot1] cannot restore index [index1] because it's open"
},
"status": 500
}
索引重命名说明 #
使用 rename_pattern 和 rename_replacement 可以在恢复时重命名索引：
{
"rename_pattern": "old_(.+)",
"rename_replacement": "new_$1"
}
示例：
old_index1→new_index1old_index2→new_index2
恢复冲突处理 #
如果索引已存在，恢复会失败。可以：
- 删除现有索引：先删除现有索引再恢复
- 使用不同名称：通过重命名使用新名称
- 部分恢复：使用
partial=true允许部分失败
使用场景 #
- 灾难恢复：从备份中恢复整个集群
- 数据迁移：将数据从一个集群迁移到另一个
- 环境复制：复制生产数据到测试环境
- 版本回滚：将索引回滚到之前的状态
注意事项 #
- 此 API 只支持 POST 方法
- 恢复的索引不能已存在（除非关闭）
- 恢复全局状态可能覆盖现有配置
- 大索引恢复可能需要较长时间
- 恢复操作会占用网络和磁盘资源
最佳实践 #
- 先测试：在测试环境先验证恢复流程
- 监控进度：使用恢复状态 API 监控进度
- 分批恢复：大量索引可以分批恢复
- 带宽管理：设置合理的带宽限制
- 验证数据：恢复后验证数据完整性
