# 缓存驱逐

数据通过三种方式离开 Alluxio 缓存：

1. **自动驱逐** — Worker 在缓存空间不足时驱逐数据，顺序由配置的策略决定（默认 LRU）
2. **TTL 过期** — 后台扫描移除生命周期已到期的数据，与访问频率或优先级无关
3. **手动驱逐** — `job free` 按需显式清除某个路径的缓存

## 自动驱逐

当 Worker 需要为新数据腾出空间时，会运行驱逐器来选择并移除缓存中的页。提供三种策略：

| 策略        | 驱逐对象        |
| --------- | ----------- |
| `LRU`（默认） | 最长时间未被访问的数据 |
| `LFU`     | 访问次数最少的数据   |
| `FIFO`    | 最早写入的数据     |

要更改驱逐策略，在所有 Worker 的 `alluxio-site.properties` 中设置：

```properties
# 使用 LFU 替代默认的 LRU
alluxio.worker.page.store.evictor.type=LFU
```

### 异步驱逐

默认情况下，驱逐在写入期间同步执行，可能增加延迟。异步驱逐在后台运行，在缓存填满之前提前保持余量：

```properties
alluxio.worker.page.store.async.eviction.enabled=true
# 缓存使用率超过此阈值时开始驱逐（默认：0.9）
alluxio.worker.page.store.async.eviction.high.watermark=0.85
# 缓存使用率降至此阈值时停止驱逐（默认：0.8）
alluxio.worker.page.store.async.eviction.low.watermark=0.75
# 检查缓存使用情况的间隔（默认：1min）
alluxio.worker.page.store.async.eviction.check.interval=30s
```

{% hint style="info" %}
基于 TTL 的驱逐和 Cache Priority 也会影响被驱逐的内容和时机。详见[缓存策略](/ee-ai-cn/cache/managing-data-in-the-cache.md)。
{% endhint %}

## 手动驱逐：`free` 作业

使用 `job free` 显式清除某个路径的缓存数据——不会影响底层 UFS 的数据。常见使用场景：

* **模型版本更新**：在加载新版本前（或后）释放旧版本
* **作业完成后清理**：批处理作业完成后释放空间
* **强制重新缓存**：释放后重新加载，以拾取对 immutable 策略路径的 UFS 变更

### 提交与监控

{% tabs %}
{% tab title="Kubernetes (Operator)" %}

```shell
# Submit (returns immediately)
kubectl exec -n <NAMESPACE> alluxio-cluster-coordinator-0 -- \
  alluxio job free --path <ufs-or-alluxio-path> --submit

# Monitor progress
kubectl exec -n <NAMESPACE> alluxio-cluster-coordinator-0 -- \
  alluxio job free --path <ufs-or-alluxio-path> --progress
```

{% endtab %}

{% tab title="Docker / Bare-Metal" %}

```shell
# Submit (returns immediately)
bin/alluxio job free --path <ufs-or-alluxio-path> --submit

# Monitor progress
bin/alluxio job free --path <ufs-or-alluxio-path> --progress
```

{% endtab %}
{% endtabs %}

进度输出示例：

```console
Progress for Free path file '<path>':
    Job Id: b21ce9fb-f332-4d39-8bb4-554f9a4fa601
    Job Submitted: Fri Feb 02 21:28:56 CST 2024
    Job path: <path>
    Job State: SUCCEEDED, finished at Fri Feb 02 21:29:01 CST 2024
    Free Info:  totalFile:4 totalByte:3072.00KB
    Free Files Failed: 0
    Free Bytes Failed: 0B
    Free Files Succeeded: 4
    Free Bytes Succeeded: 3072.00KB
```

### 停止正在运行的 Free 作业

{% tabs %}
{% tab title="Kubernetes (Operator)" %}

```shell
kubectl exec -n <NAMESPACE> alluxio-cluster-coordinator-0 -- \
  alluxio job free --path <ufs-or-alluxio-path> --stop
```

{% endtab %}

{% tab title="Docker / Bare-Metal" %}

```shell
bin/alluxio job free --path <ufs-or-alluxio-path> --stop
```

{% endtab %}
{% endtabs %}

停止操作会将部分已释放的数据残留在缓存中。作业可通过再次使用 `--submit` 提交来恢复。

### 版本更新模式

将已固定的数据集替换为新版本：

{% tabs %}
{% tab title="Kubernetes (Operator)" %}

```shell
# 1. Remove priority pin from old version
kubectl exec -n <NAMESPACE> alluxio-cluster-coordinator-0 -- \
  alluxio priority remove --path <old-version-path>

# 2. Free old version from cache
kubectl exec -n <NAMESPACE> alluxio-cluster-coordinator-0 -- \
  alluxio job free --path <old-version-path> --submit

# 3. Load and pin new version
kubectl exec -n <NAMESPACE> alluxio-cluster-coordinator-0 -- \
  alluxio job load --path <new-version-path> --submit --verify
kubectl exec -n <NAMESPACE> alluxio-cluster-coordinator-0 -- \
  alluxio priority add --path <new-version-path> --priority high
```

{% endtab %}

{% tab title="Docker / Bare-Metal" %}

```shell
# 1. Remove priority pin from old version
bin/alluxio priority remove --path <old-version-path>

# 2. Free old version from cache
bin/alluxio job free --path <old-version-path> --submit

# 3. Load and pin new version
bin/alluxio job load --path <new-version-path> --submit --verify
bin/alluxio priority add --path <new-version-path> --priority high
```

{% endtab %}
{% endtabs %}

有关 `job free` 标志的完整列表，请参阅 [`job free` CLI 参考](/ee-ai-cn/reference/user-cli.md#job-free)。

您也可以通过 [REST API](https://documentation.alluxio.io/ee-ai-cn/cache/pages/YtiFc3YLKKtj3ToJvtWI#释放缓存) 以编程方式触发和管理 free 作业。

## 过时缓存清理

集群拓扑变更可能导致数据缓存在 Worker 上，但根据一致性哈希环，该 Worker 已不再"拥有"这些数据。这些过时数据占用空间但不会被提供给客户端。

**发生时机：**

* 添加或移除 Worker（归属权重新分配）
* 文件的副本因子降低
* Worker 暂时下线后其数据迁移，该 Worker 重新加入后

### 触发过时清理

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

这将向每个 Worker 提交一个异步作业。Worker 扫描本地存储，根据当前哈希环验证归属权，并删除不再属于自己的数据。可通过 `alluxio_cleared_stale_cached_data` Prometheus 指标或 Worker 日志监控进度。

更多详情请参阅 [REST API 参考](/ee-ai-cn/reference/rest-api.md)。

{% hint style="warning" %}
过时清理产生的大量文件删除操作可能造成元数据 I/O 压力，延长 Worker Pod 的终止时间。在大型集群上请选择维护窗口期执行。
{% endhint %}


---

# 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/cache/removing-data-from-the-cache.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.