---
title: "创建快照仓库"
date: 2026-01-21
lastmod: 2026-01-21
description: "介绍如何在 Easysearch 中创建或更新快照存储仓库。"
tags: ["快照", "备份", "仓库管理"]
summary: "此 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 必需 仓库类型"
---


此 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 | 必需 | 仓库类型<br>可选值：`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 会话令牌 |

## 请求示例

### 创建文件系统仓库

```json
PUT /_snapshot/my-fs-repo
{
  "type": "fs",
  "settings": {
    "location": "/mount/backups/my_backup"
  }
}
```

### 创建带压缩的文件系统仓库

```json
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 仓库

```json
PUT /_snapshot/my-s3-repo
{
  "type": "s3",
  "settings": {
    "bucket": "my-backup-bucket",
    "region": "us-west-2",
    "base_path": "easysearch"
  }
}
```

### 创建 S3 兼容服务仓库

```json
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"
  }
}
```

### 不验证仓库创建

```bash
PUT /_snapshot/my-repo?verify=false
{
  "type": "fs",
  "settings": {
    "location": "/mount/backups/my_backup"
  }
}
```

## 响应示例

### 成功响应

```json
{
  "acknowledged": true
}
```

### 错误响应 - 位置不存在

```json
{
  "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
}
```

## 使用场景

1. **备份准备**：在创建快照前先配置仓库
2. **灾难恢复**：配置远程存储用于灾难恢复
3. **数据归档**：配置长期存储用于数据归档
4. **跨集群复制**：使用共享存储实现跨集群数据复制

## 共享文件系统要求

使用文件系统仓库时，需要确保：

1. **共享访问**：所有节点都能访问同一位置
2. **写入权限**：所有节点都有写入权限
3. **路径注册**：路径已注册在 `path.repo` 配置中
4. **挂载点**：文件系统已正确挂载

### path.repo 配置

在 `easysearch.yml` 中配置：

```yaml
path.repo: ["/mount/backups", "/mount/backup2"]
```

## 注意事项

1. 此 API 支持 PUT 和 POST 方法
2. 仓库创建后会默认验证（`verify=true`）
3. 文件系统路径必须预先在 `path.repo` 中注册
4. 仓库配置更新后会完全替换现有配置
5. 删除仓库不会删除存储的快照数据

## 最佳实践

1. **验证配置**：创建后验证仓库可访问
2. **权限控制**：限制仓库的访问权限
3. **容量规划**：确保存储空间充足
4. **网络带宽**：考虑恢复时的网络带宽
5. **定期测试**：定期测试恢复流程

## 相关文档

- [查询所有快照仓库](./get-all-snapshot-repositories.md)
- [查询指定快照仓库](./get-specific-snapshot-repository.md)
- [删除快照仓库](./delete-snapshot-repository.md)
- [创建快照](./create-snapshot.md)
- [验证快照仓库](./verify-snapshot-repository.md)