# 过期缓存清理

Alluxio 客户端使用一致性哈希来确定访问或写入文件的对应worker节点。这确保了每个文件通常只缓存于其指定的worker上。但在某些情况下，worker节点中缓存的数据可能不再属于它。为释放内存并保持缓存的最佳利用率，Alluxio 提供**清理worker节点上过期缓存数据**的操作机制。

该操作会触发worker 节点扫描其本地缓存，验证其中的数据是否仍应由其缓存，并删除那些已不属于它的数据。

## 出现过期数据的情况

以下情况可能导致某个worker 节点上存在过期数据：

1. **副本数减少**\
   如果某个文件的副本数从 3 个减少为 2个，第三个worker节点仍会保留冗余副本，但事实上已不再需要。
2. **动态哈希环成员变更**\
   在使用动态哈希环时，如果某个worker节点暂时下线，其职责会由其他worker 接管。当该worker重新上线时，原先接管其职责的节点可能仍保留过期数据。
3. **集群扩容**\
   增加新的worker节点会改变缓存文件的归属权。原先缓存于旧节点上的数据，可能现在由新增的节点负责。

要清理这类过期数据可手动触发“清理过期缓存”操作。

## 清理过期缓存和 Free Job 的区别

“清理过期缓存”和“Free Job”是 Alluxio 的两种缓存清理机制。两者用途类似，容易混淆。以下表格对比了二者的不同点：

| 方面      | 清理过期缓存                 | Free Job                  |
| ------- | ---------------------- | ------------------------- |
| 主要用例    | 清理因集群变更导致的过期或错误缓存数据    | 释放应用程序不再需要的缓存数据           |
| 清理的缓存类型 | 错误或无效的缓存               | 有效但不再需要的缓存                |
| 清理目标    | 删除不应存放在当前worker节点的缓存文件 | 根据指定目录或索引文件清理worker节点上的文件 |
| 接口      | RESTful API            | RESTful API 和 CLI         |
| 输入参数    | 无                      | 需要目录路径或索引文件作为输入           |
| 调度机制    | 立即在所有worker 节点上执行      | 依赖任务系统进行调度                |

## 使用方式

此功能当前仅可**通过 RESTful API** 访问。

### 提交任务

以下 API 将异步触发在所有worker节点上执行“清理过期缓存”任务：

```shell
curl -X POST <coordinator-host>:<coordinator-api-port>/api/v1/cache -d '{"op":"clear-stale"}' -H "Content-Type: application/json"
```

此命令会向所有worker节点提交一个后台任务。多次提交该请求不会导致重复执行。

**示例响应:**

```json
{
  "errors": {
    "worker1-host": "Connection refused",
    "worker2-host": "Timeout"
  }
}
```

> 如果 `errors` 字段为空，说明任务已成功提交至所有worker节点。否则，`errors` 字段会列出提交失败的worker节点及错误信息。出现错误可能是由于网络连接失败，或先前提交的任务尚未完成运行。

### 停止任务

如需取消正在运行的任务，可发送如下 DELETE 请求：

```shell
curl -X DELETE <coordinator-host>:<coordinator-api-port>/api/v1/cache -d '{"op":"clear-stale"}' -H "Content-Type: application/json"
```

该请求将停止所有worker节点上的后台任务。如果没有正在运行的任务，命令也会成功执行，不会报错。

## 任务进度监控

目前无 **RPC 接口直接追踪过期缓存清理任务**的进度，但可以通过以下方式进行间接监控：

### 通过日志

当某个worker节点完成任务时，会输出以下日志：

```
2025-04-21T19:51:22,889 INFO  AsyncJobWorker - Clear stale cached files finished. 104857600 bytes released
```

该日志表明任务完成，并显示清理掉的缓存数据量。

### 通过 Prometheus 指标

Alluxio 提供如下指标来追踪清理过期缓存的情况：

```
alluxio_cleared_stale_cached_data
```

该指标统计的是每个worker节点通过“清理过期缓存”操作所释放的总字节数。

当任务完成时，所有worker节点上的该指标总和将趋于稳定（不再增长）。

可利用该指标来监控和预警整个集群中的缓存清理趋势。