# 过期缓存清理

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节点上的该指标总和将趋于稳定（不再增长）。

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://documentation.alluxio.io/ee-ai-cn/ai-3.6/cache/stale-cache-cleaning.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.