--- title: "创建快照" date: 2026-01-31 lastmod: 2026-01-31 description: "创建索引快照" tags: ["快照", "创建", "备份"] summary: "在指定的快照仓库中创建快照，备份索引数据。 API 格式 # POST /_snapshot/{repository}/{snapshot} PUT /_snapshot/{repository}/{snapshot} API 作用 # 该 API 用于创建快照备份： 备份一个或多个索引到指定的快照仓库 支持选择性备份（指定索引列表） 可选包含集群全局状态 支持增量快照 API 参数 # 路径参数 # 参数 类型 是否必填 默认值 描述 {repository} String 是 - 快照仓库名称 {snapshot} String 是 - 快照名称 查询参数 # 参数 类型 是否必填 默认值 描述 master_timeout Time 否 30s 连接主节点的超时时间 wait_for_completion Boolean 否 false 是否等待快照完成后再返回响应 请求体参数 # 参数 类型 是否必填 默认值 描述 indices Array 否 ["_all"] 要包含在快照中的索引列表。支持多索引语法和别名。空数组或 ["*_all"] 表示备份所有打开的索引 ignore_unavailable Boolean 否 false 是否忽略不可用的索引（未找到或已关闭） include_global_state Boolean 否 true 是否在快照中包含集群全局状态元数据 partial Boolean 否 false 是否允许部分快照（当某些索引的分片不可用时） settings Object 否 {} 仓库特定的设置（如压缩、块大小等） metadata Object 否 null 附加到快照的用户自定义元数据（最大 1024 字节） 请求示例 # 创建所有索引的快照 # POST /_snapshot/my_backup/snapshot_1 { "indices": "*", "include_global_state": true } 创建指定索引的快照 # POST /_snapshot/my_backup/daily_backup { "indices": ["index1", "index2", "logs-*"], "ignore_unavailable": true, "include_global_state": false, "metadata": { "created_by": "admin", "description": "Daily backup" } } 等待快照完成 # POST /_snapshot/my_backup/full_backup?" --- 在指定的快照仓库中创建快照，备份索引数据。 ## API 格式 ``` POST /_snapshot/{repository}/{snapshot} PUT /_snapshot/{repository}/{snapshot} ``` ## API 作用 该 API 用于创建快照备份： - 备份一个或多个索引到指定的快照仓库 - 支持选择性备份（指定索引列表） - 可选包含集群全局状态 - 支持增量快照 ## API 参数 ### 路径参数 | 参数 | 类型 | 是否必填 | 默认值 | 描述 | |------|------|----------|--------|------| | `{repository}` | String | **是** | - | 快照仓库名称 | | `{snapshot}` | String | **是** | - | 快照名称 | ### 查询参数 | 参数 | 类型 | 是否必填 | 默认值 | 描述 | |------|------|----------|--------|------| | `master_timeout` | Time | 否 | `30s` | 连接主节点的超时时间 | | `wait_for_completion` | Boolean | 否 | `false` | 是否等待快照完成后再返回响应 | ### 请求体参数 | 参数 | 类型 | 是否必填 | 默认值 | 描述 | |------|------|----------|--------|------| | `indices` | Array | 否 | `["_all"]` | 要包含在快照中的索引列表。支持多索引语法和别名。空数组或 `["*_all"]` 表示备份所有打开的索引 | | `ignore_unavailable` | Boolean | 否 | `false` | 是否忽略不可用的索引（未找到或已关闭） | | `include_global_state` | Boolean | 否 | `true` | 是否在快照中包含集群全局状态元数据 | | `partial` | Boolean | 否 | `false` | 是否允许部分快照（当某些索引的分片不可用时） | | `settings` | Object | 否 | `{}` | 仓库特定的设置（如压缩、块大小等） | | `metadata` | Object | 否 | `null` | 附加到快照的用户自定义元数据（最大 1024 字节） | ## 请求示例 ### 创建所有索引的快照 ```json POST /_snapshot/my_backup/snapshot_1 { "indices": "*", "include_global_state": true } ``` ### 创建指定索引的快照 ```json POST /_snapshot/my_backup/daily_backup { "indices": ["index1", "index2", "logs-*"], "ignore_unavailable": true, "include_global_state": false, "metadata": { "created_by": "admin", "description": "Daily backup" } } ``` ### 等待快照完成 ```json POST /_snapshot/my_backup/full_backup?wait_for_completion=true { "indices": ["*"], "include_global_state": true } ``` ### 创建部分快照 ```json POST /_snapshot/my_backup/partial_snapshot { "indices": ["index1", "index2"], "partial": true } ``` ## 响应示例 ### wait_for_completion=false（默认） ``` 202 Accepted ``` ```json { "accepted": true } ``` ### wait_for_completion=true（成功） ``` 200 OK ``` ```json { "snapshot": { "snapshot": "snapshot_1", "uuid": "K8i7oP2rR4aK9sD5fG1hJ3mN6pQ", "version_id": 811419996, "version": "8.11.4", "indices": ["index1", "index2"], "data_streams": [], "state": "SUCCESS", "start_time": "2026-02-04T12:00:00.000Z", "start_time_in_millis": 1738644000000, "end_time": "2026-02-04T12:05:00.000Z", "end_time_in_millis": 1738644300000, "duration_in_millis": 300000, "include_global_state": true, "metadata": { "created_by": "admin" }, "total_shards": 10, "successful_shards": 10, "failed_shards": 0, "failures": [] } } ``` ### wait_for_completion=true（部分失败） ``` 200 OK ``` ```json { "snapshot": { "snapshot": "snapshot_1", "uuid": "K8i7oP2rR4aK9sD5fG1hJ3mN6pQ", "version_id": 811419996, "version": "8.11.4", "indices": ["index1", "index2"], "data_streams": [], "state": "PARTIAL", "reason": "some shards failed to snapshot", "start_time": "2026-02-04T12:00:00.000Z", "start_time_in_millis": 1738644000000, "end_time": "2026-02-04T12:05:00.000Z", "end_time_in_millis": 1738644300000, "duration_in_millis": 300000, "include_global_state": true, "total_shards": 10, "successful_shards": 8, "failed_shards": 2, "failures": [ { "shard": 0, "index": "index1", "node": "node-1", "reason": "failed to snapshot shard", "status": "503" } ] } } ``` ## 响应状态码 | 状态码 | 描述 | |--------|------| | 202 Accepted | 快照操作已启动但未完成（wait_for_completion=false） | | 200 OK | 快照完成成功或部分成功（wait_for_completion=true） | | 500 Internal Server Error | 快照完全失败 | ## 响应字段说明 ### 快照对象字段 | 字段 | 类型 | 描述 | |------|------|------| | `snapshot` | String | 快照名称 | | `uuid` | String | 快照的唯一标识符 | | `version_id` | Integer | 创建快照的 Easysearch 版本号 | | `version` | String | 创建快照的 Easysearch 版本字符串 | | `indices` | String[] | 快照中包含的索引列表 | | `data_streams` | String[] | 快照中包含的数据流列表 | | `state` | String | 快照状态（SUCCESS、PARTIAL、FAILED） | | `reason` | String/null | 失败或部分失败的原因 | | `start_time` | String | 快照开始时间（ISO 格式） | | `start_time_in_millis` | Long | 开始时间（毫秒时间戳） | | `end_time` | String | 快照结束时间（ISO 格式） | | `end_time_in_millis` | Long | 结束时间（毫秒时间戳） | | `duration_in_millis` | Long | 快照总耗时（毫秒） | | `include_global_state` | Boolean | 是否包含集群全局状态 | | `metadata` | Object | 附加的用户自定义元数据 | | `total_shards` | Integer | 快照的总分片数 | | `successful_shards` | Integer | 成功的分片数 | | `failed_shards` | Integer | 失败的分片数 | | `failures` | Array | 分片失败详情数组 | ## 命名规范 ### 仓库名称 - 必须是非空字符串 - 小写 - 不能包含空格 - 不能包含逗号、井号 - 不能以下划线开头 ### 快照名称 - 必须是非空字符串 - 小写 - 不能包含空格 - 不能包含逗号、井号 - 不能以下划线开头 ## 使用场景 1. **定期备份**：按计划创建定期快照 2. **全量备份**：备份所有索引和集群状态 3. **选择性备份**：仅备份重要索引 4. **迁移准备**：在数据迁移前创建快照 ## 注意事项 1. **元数据大小**：用户元数据限制为 1024 字节 2. **并发限制**：同一索引的并发快照会冲突 3. **默认索引**：未指定索引时备份所有打开的索引 4. **增量快照**：只备份自上次快照以来的变更 5. **部分快照**：使用 `partial=true` 允许部分分片失败时仍创建快照 ## 快照状态说明 | 状态 | 描述 | |------|------| | `SUCCESS` | 所有分片快照成功 | | `PARTIAL` | 部分分片快照失败 | | `FAILED` | 快照完全失败 | | `IN_PROGRESS` | 快照正在进行中 | ## 相关操作 - **GET /_snapshot/{repository}/{snapshot}**：查询快照信息 - **DELETE /_snapshot/{repository}/{snapshot}**：删除快照 - **POST /_snapshot/{repository}/{snapshot}/_restore**：恢复快照 - **GET /_snapshot/{repository}**：查询仓库信息 ## 实现文件 - **REST 处理器**：`RestCreateSnapshotAction.java` - **请求类**：`CreateSnapshotRequest.java` - **响应类**：`CreateSnapshotResponse.java` - **Transport Action**：`TransportCreateSnapshotAction.java` - **快照信息**：`SnapshotInfo.java`