此 API 用于创建或更新快照存储仓库。
API #
PUT /_snapshot/{repository}
POST /_snapshot/{repository}
API 的作用 #
创建新的快照存储仓库或更新已存在的仓库配置。快照仓库是存储索引快照的位置，可以是：
- 共享文件系统：使用共享文件系统存储快照
- 云存储：使用 S3、Azure、GCS 等云存储服务
- 其他存储：通过插件支持 HDFS 等其他存储类型
如果仓库已存在，新的配置将替换现有配置。
API 的参数 #
路由参数 #
| 参数 | 类型 | 是否必需 | 描述 |
|---|---|---|---|
repository | string | 必需 | 仓库名称 |
查询字符串参数 #
| 参数 | 类型 | 是否必需 | 默认值 | 描述 |
|---|---|---|---|---|
master_timeout | time | 可选 | 30s | 等待主节点响应的超时时间 |
timeout | time | 可选 | 30s | 操作超时时间 |
verify | boolean | 可选 | true | 创建后是否验证仓库 |
请求体参数 #
| 参数 | 类型 | 是否必需 | 描述 |
|---|---|---|---|
type | string | 必需 | 仓库类型 可选值： fs, s3, hdfs, azure, gcs 等 |
settings | object | 必需 | 仓库特定配置 |
仓库类型和配置 #
文件系统仓库 (fs) #
| 参数 | 类型 | 是否必需 | 描述 |
|---|---|---|---|
location | string | 必需 | 共享文件系统的路径 |
compress | boolean | 可选 | 是否压缩快照文件，默认 true |
chunk_size | string | 可选 | 快照文件的块大小，默认 null |
max_restore_bytes_per_sec | string | 可选 | 恢复时的最大字节数/秒 |
max_snapshot_bytes_per_sec | string | 可选 | 创建快照时的最大字节数/秒 |
readonly | boolean | 可选 | 是否只读模式，默认 false |
S3 仓库 (s3) #
| 参数 | 类型 | 是否必需 | 描述 |
|---|---|---|---|
bucket | string | 必需 | S3 存储桶名称 |
region | string | 可选 | AWS 区域 |
endpoint | string | 可选 | S3 兼容服务的端点 |
access_key | string | 可选 | AWS 访问密钥 |
secret_key | string | 可选 | AWS 密钥 |
session_token | string | 可选 | AWS 会话令牌 |
请求示例 #
创建文件系统仓库 #
PUT /_snapshot/my-fs-repo
{
"type": "fs",
"settings": {
"location": "/mount/backups/my_backup"
}
}
创建带压缩的文件系统仓库 #
PUT /_snapshot/my-fs-repo-compressed
{
"type": "fs",
"settings": {
"location": "/mount/backups/my_backup",
"compress": true,
"chunk_size": "10m",
"max_restore_bytes_per_sec": "50mb",
"max_snapshot_bytes_per_sec": "100mb"
}
}
创建 S3 仓库 #
PUT /_snapshot/my-s3-repo
{
"type": "s3",
"settings": {
"bucket": "my-backup-bucket",
"region": "us-west-2",
"base_path": "easysearch"
}
}
创建 S3 兼容服务仓库 #
PUT /_snapshot/my-custom-s3-repo
{
"type": "s3",
"settings": {
"bucket": "my-backup-bucket",
"endpoint": "https://s3.example.com",
"access_key": "your-access-key",
"secret_key": "your-secret-key"
}
}
不验证仓库创建 #
PUT /_snapshot/my-repo?verify=false
{
"type": "fs",
"settings": {
"location": "/mount/backups/my_backup"
}
}
响应示例 #
成功响应 #
{
"acknowledged": true
}
错误响应 - 位置不存在 #
{
"error": {
"root_cause": [
{
"type": "repository_exception",
"reason": "[my-fs-repo] location [/mount/backups/my_backup] doesn't match any of the locations registered with the repository"
}
],
"type": "repository_exception",
"reason": "[my-fs-repo] failed to create repository"
},
"status": 500
}
使用场景 #
- 备份准备：在创建快照前先配置仓库
- 灾难恢复：配置远程存储用于灾难恢复
- 数据归档：配置长期存储用于数据归档
- 跨集群复制：使用共享存储实现跨集群数据复制
共享文件系统要求 #
使用文件系统仓库时，需要确保：
- 共享访问：所有节点都能访问同一位置
- 写入权限：所有节点都有写入权限
- 路径注册：路径已注册在
path.repo配置中 - 挂载点：文件系统已正确挂载
path.repo 配置 #
在 easysearch.yml 中配置：
path.repo: ["/mount/backups", "/mount/backup2"]
注意事项 #
- 此 API 支持 PUT 和 POST 方法
- 仓库创建后会默认验证（
verify=true） - 文件系统路径必须预先在
path.repo中注册 - 仓库配置更新后会完全替换现有配置
- 删除仓库不会删除存储的快照数据
最佳实践 #
- 验证配置：创建后验证仓库可访问
- 权限控制：限制仓库的访问权限
- 容量规划：确保存储空间充足
- 网络带宽：考虑恢复时的网络带宽
- 定期测试：定期测试恢复流程
