---
title: "清理快照仓库"
date: 2026-03-25
lastmod: 2026-03-25
description: "清理快照仓库中的过期数据"
tags: ["快照", "仓库", "清理"]
summary: "从快照仓库中删除过期的数据，释放存储空间。
API 格式 #  POST /_snapshot/{repository}/_cleanup API 作用 #  该 API 用于清理快照仓库中的孤立数据：
 删除不再被仓库元数据引用的快照 blob 文件 清理过期的索引生成文件 删除孤儿索引的 blob 容器 移除不再需要的旧分片生成文件  API 参数 #  路径参数 #     参数 类型 是否必填 默认值 描述     {repository} String 是 - 要清理的仓库名称    查询参数 #     参数 类型 是否必填 默认值 描述     timeout Time 否 30s 操作的超时时间   master_timeout Time 否 30s 连接主节点的超时时间    请求示例 #  清理指定仓库 #  POST /_snapshot/my_backup_repo/_cleanup 设置超时时间 #  POST /_snapshot/my_backup_repo/_cleanup?"
---


从快照仓库中删除过期的数据，释放存储空间。

## API 格式

```
POST /_snapshot/{repository}/_cleanup
```

## API 作用

该 API 用于清理快照仓库中的孤立数据：
- 删除不再被仓库元数据引用的快照 blob 文件
- 清理过期的索引生成文件
- 删除孤儿索引的 blob 容器
- 移除不再需要的旧分片生成文件

## API 参数

### 路径参数

| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
|------|------|----------|--------|------|
| `{repository}` | String | **是** | - | 要清理的仓库名称 |

### 查询参数

| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
|------|------|----------|--------|------|
| `timeout` | Time | 否 | `30s` | 操作的超时时间 |
| `master_timeout` | Time | 否 | `30s` | 连接主节点的超时时间 |

## 请求示例

### 清理指定仓库

```
POST /_snapshot/my_backup_repo/_cleanup
```

### 设置超时时间

```
POST /_snapshot/my_backup_repo/_cleanup?timeout=5m
```

## 响应示例

### 成功响应

```json
{
  "results": {
    "deleted_blobs": 42,
    "deleted_bytes": 1048576
  }
}
```

## 响应字段说明

| 字段 | 类型 | 描述 |
|------|------|------|
| `deleted_blobs` | Long | 删除的 blob 文件数量 |
| `deleted_bytes` | Long | 删除的数据总字节数 |

## 清理过程

### 1. 安全检查
- 验证同一仓库上没有其他清理操作正在运行
- 确保没有快照创建或删除操作正在进行
- 验证仓库支持清理操作（必须是 `BlobStoreRepository`）

### 2. 识别过期数据
清理过程会识别并删除：
- **过期快照 blob**：仓库元数据中未引用的快照文件（`.dat`）
- **过期根 blob**：已过时的索引生成文件
- **孤儿索引**：元数据中不存在的索引的 blob 容器
- **旧分片生成**：不再需要的分片生成文件

### 3. 执行流程
1. 检查仓库状态并验证没有冲突操作
2. 在集群状态中记录清理操作
3. 列出仓库中的所有 blob
4. 与当前仓库元数据比较以识别过期数据
5. 写入新的索引生成文件以防止并发操作
6. 删除所有已识别的过期 blob
7. 更新集群状态标记清理完成

## 使用场景

1. **存储优化**：释放失败或中止操作留下的孤立数据占用的空间
2. **定期维护**：定期清理以保持仓库存储效率
3. **故障恢复**：清理因网络故障或节点失败产生的孤儿数据

## 注意事项

1. **只读仓库**：只读仓库不能执行清理操作，会抛出异常
2. **主节点执行**：操作仅在主节点上执行
3. **支持类型**：只有 `BlobStoreRepository` 实现支持清理
4. **幂等性**：API 是幂等的，对同一仓库状态多次运行会产生相同结果
5. **主节点故障转移**：主节点故障转移时，任何进行中的清理操作会从集群状态中安全移除

## 相关操作

- **PUT /_snapshot/{repository}**：创建快照仓库
- **GET /_snapshot/{repository}**：查询快照仓库
- **DELETE /_snapshot/{repository}**：删除快照仓库
- **POST /_snapshot/{repository}/{snapshot}**：创建快照

## 实现细节

- **REST 处理器**：`RestCleanupRepositoryAction.java`
- **Transport Action**：`TransportCleanupRepositoryAction.java`
- **请求类**：`CleanupRepositoryRequest.java`
- **响应类**：`CleanupRepositoryResponse.java`
- **结果类**：`RepositoryCleanupResult.java`