---
title: "恢复快照"
date: 2026-01-19
lastmod: 2026-01-19
description: "介绍如何在 Easysearch 中从快照恢复数据到集群。"
tags: ["快照", "恢复", "数据恢复"]
summary: "此 API 用于从快照恢复数据到集群。
API #  POST /_snapshot/{repository}/{snapshot}/_restore API 的作用 #  从指定的快照中恢复数据到集群。恢复操作可以：
 恢复全部索引：恢复快照中的所有索引 恢复部分索引：只恢复指定的索引 重命名索引：恢复时重命名索引 修改设置：恢复时修改索引设置 全局状态：恢复全局集群状态  API 的参数 #  路由参数 #     参数 类型 是否必需 描述     repository string 必需 快照仓库名称   snapshot string 必需 快照名称    查询字符串参数 #     参数 类型 是否必需 默认值 描述     master_timeout time 可选 30s 等待主节点响应的超时时间   wait_for_completion boolean 可选 false 是否等待恢复操作完成    请求体参数 #     参数 类型 是否必需 默认值 描述     indices array 可选 [] 要恢复的索引列表"
---


此 API 用于从快照恢复数据到集群。

## API

```
POST /_snapshot/{repository}/{snapshot}/_restore
```

## API 的作用

从指定的快照中恢复数据到集群。恢复操作可以：

- **恢复全部索引**：恢复快照中的所有索引
- **恢复部分索引**：只恢复指定的索引
- **重命名索引**：恢复时重命名索引
- **修改设置**：恢复时修改索引设置
- **全局状态**：恢复全局集群状态

## API 的参数

### 路由参数

| 参数 | 类型 | 是否必需 | 描述 |
|------|------|----------|------|
| `repository` | string | 必需 | 快照仓库名称 |
| `snapshot` | string | 必需 | 快照名称 |

### 查询字符串参数

| 参数 | 类型 | 是否必需 | 默认值 | 描述 |
|------|------|----------|--------|------|
| `master_timeout` | time | 可选 | 30s | 等待主节点响应的超时时间 |
| `wait_for_completion` | boolean | 可选 | false | 是否等待恢复操作完成 |

### 请求体参数

| 参数 | 类型 | 是否必需 | 默认值 | 描述 |
|------|------|----------|--------|------|
| `indices` | array | 可选 | [] | 要恢复的索引列表<br>支持多索引语法<br>`+test*`：包含匹配的索引<br>`-test42`：排除指定索引 |
| `partial` | boolean | 可选 | false | 是否允许部分恢复<br>即使某些分片失败也继续 |
| `include_global_state` | boolean | 可选 | false | 是否恢复全局集群状态<br>包括模板、持久化设置等 |
| `include_aliases` | boolean | 可选 | true | 是否恢复索引别名 |
| `rename_pattern` | string | 可选 | null | 恢复时的重命名模式<br>正则表达式模式 |
| `rename_replacement` | string | 可选 | null | 重命名替换模式 |
| `index_settings` | object | 可选 | {} | 所有被恢复索引的设置 |
| `ignore_index_settings` | array | 可选 | [] | 恢复时要忽略的索引设置 |
| `storage_type` | string | 可选 | local | 存储类型<br>可选值：`local`, `remote_snapshot` |

## 请求示例

### 恢复所有索引

```bash
POST /_snapshot/my-repo/snapshot1/_restore
```

### 恢复指定索引

```json
POST /_snapshot/my-repo/snapshot1/_restore
{
  "indices": ["index1", "index2", "index3"]
}
```

### 使用通配符恢复索引

```json
POST /_snapshot/my-repo/snapshot1/_restore
{
  "indices": "logs-*",
  "ignore_unavailable": true
}
```

### 恢复时重命名索引

```json
POST /_snapshot/my-repo/snapshot1/_restore
{
  "indices": "old_index_*",
  "rename_pattern": "old_index_(.+)",
  "rename_replacement": "restored_index_$1"
}
```

### 恢复并包含全局状态

```json
POST /_snapshot/my-repo/snapshot1/_restore
{
  "indices": "*",
  "include_global_state": true
}
```

### 恢复并修改索引设置

```json
POST /_snapshot/my-repo/snapshot1/_restore
{
  "indices": ["index1", "index2"],
  "index_settings": {
    "index.number_of_replicas": 2,
    "index.refresh_interval": "5s"
  }
}
```

### 忽略某些索引设置

```json
POST /_snapshot/my-repo/snapshot1/_restore
{
  "indices": ["index1"],
  "ignore_index_settings": ["index.lifecycle.name", "index.routing.allocation.include._tier_preference"]
}
```

### 等待恢复完成

```bash
POST /_snapshot/my-repo/snapshot1/_restore?wait_for_completion=true
```

## 响应示例

### 成功响应

```json
{
  "accepted": true
}
```

### 等待完成的响应

```json
{
  "snapshot": {
    "snapshot": "snapshot1",
    "repository": "my-repo",
    "indices": ["index1", "index2", "index3"]
  },
  "shards": {
    "total": 9,
    "successful": 9,
    "failed": 0
  }
}
```

### 错误响应 - 索引已存在

```json
{
  "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` 可以在恢复时重命名索引：

```json
{
  "rename_pattern": "old_(.+)",
  "rename_replacement": "new_$1"
}
```

**示例**：
- `old_index1` → `new_index1`
- `old_index2` → `new_index2`

## 恢复冲突处理

如果索引已存在，恢复会失败。可以：

1. **删除现有索引**：先删除现有索引再恢复
2. **使用不同名称**：通过重命名使用新名称
3. **部分恢复**：使用 `partial=true` 允许部分失败

## 使用场景

1. **灾难恢复**：从备份中恢复整个集群
2. **数据迁移**：将数据从一个集群迁移到另一个
3. **环境复制**：复制生产数据到测试环境
4. **版本回滚**：将索引回滚到之前的状态

## 注意事项

1. 此 API 只支持 POST 方法
2. 恢复的索引不能已存在（除非关闭）
3. 恢复全局状态可能覆盖现有配置
4. 大索引恢复可能需要较长时间
5. 恢复操作会占用网络和磁盘资源

## 最佳实践

1. **先测试**：在测试环境先验证恢复流程
2. **监控进度**：使用恢复状态 API 监控进度
3. **分批恢复**：大量索引可以分批恢复
4. **带宽管理**：设置合理的带宽限制
5. **验证数据**：恢复后验证数据完整性

## 相关文档

- [创建快照](./create-snapshot.md)
- [删除快照](./delete-snapshot.md)
- [查询快照信息](./get-snapshot-info.md)