# TTL （有效时间）规则

## 概览和使用场景

Alluxio 支持为不同目录中的缓存定义 TTL（有效时间）规则。当文件缓存时间超过其 TTL 后，Alluxio 将自动删除该缓存。TTL 基于缓存加载到 Alluxio 中的时间。因此，文件的不同部分或不同副本可能会在不同时间被驱逐出 Alluxio。

TTL 规则仅指定缓存的最长有效时间，并不能阻止由于其他原因（如 Worker 的缓存容量已满）而导致的缓存驱逐。有关何时以及如何触发缓存驱逐的详细信息，请参阅[缓存驱逐](/ee-da-cn/cache/eviction.md)。

TTL 功能可以用于自动释放缓存，无需人工干预。例如，如果某些缓存仅在一天内有用，则可以将 TTL 设置为 24 小时。TTL 功能还可以用于限制缓存中敏感数据的有效时间，从而控制风险并满足合规要求。

要启用此功能，请按以下配置进行设置：

```properties
alluxio.ttl.policy.enabled=true
alluxio.ttl.eviction.check.interval=1h
```

TTL 规则存储在 ETCD 中。Alluxio Worker 会定期轮询 ETCD，确保遵循已定义的 TTL 规则。Worker 会每隔 1 小时（由 `alluxio.ttl.eviction.check.interval`控制） 扫描其所有缓存，并删除所有 TTL 已过期的缓存。

## 基础操作

有关命令的完整说明，请参阅 [CLI 参考资源](/ee-da-cn/reference/user-cli.md#ttl)。

### 添加 TTL

您可以为 Alluxio 命名空间中的目录设置新的 TTL 规则。

```console
$ bin/alluxio ttl add --path /s3/data/ --time 1h
Added alluxioPath=/s3/data/ and time=1h
```

我们不建议将TTL 时长定义为小于 `alluxio.ttl.eviction.check.interval` ，否则将打印警告信息。不过，TTL 规则仍可添加成功。您可以选择删除该规则或将其更新为更合理的 TTL 规则。

```console
$ bin/alluxio ttl add --path /s3/small_interval/ --time 5s
Warning: You are setting TTL policy to 5s. This TTL is too small. Note that expired cache are scanned and evicted every 1h. Please consider making this TTL larger with `bin/alluxio ttl update` command.
Added alluxioPath=/s3/small_interval/ and time=5s
```

Alluxio 也支持嵌套 TTL 规则。对于一个文件，如果有多个 TTL 规则适用，则规定最具体的规则将生效。例如，如果定义了多个嵌套 TTL 规则，文件 `/s3/data/team1/temporary/checkpoint` 的 TTL 将为 1 小时。

```console
$ bin/alluxio ttl add --path /s3/data/ --time 10h
Added alluxioPath=/s3/data/ and time=10h

$ bin/alluxio ttl add --path /s3/data/team1 --time 5h
Added alluxioPath=/s3/data/team1 and time=5h

$ bin/alluxio ttl add --path /s3/data/team1/temporary --time 1h
Added alluxioPath=/s3/data/team1/temporary and time=1h
```

TTL 定义的目录层级没有限制，父级 TTL 规则的子规则数量也没有限制。但是，我们不建议定义超过 100 个 TTL 规则或超过 3 层的嵌套 TTL 规则，因为这些规则需要集群管理员手动管理，规则数越多，管理越困难。

### 更新 TTL 规则

您可以在添加 TTL 规则后对其进行更新：

```console
$ bin/alluxio ttl update --path /s3/test_folder/ --time 30min
Updated alluxioPath=/s3/test_folder/ and time=30min

$ bin/alluxio ttl update --path /s3/test_folder/ --time 5s
Warning: You are setting TTL policy to 5s. This TTL is too small. Note that expired cache are scanned and evicted every 1h. Please consider making this TTL larger with `bin/alluxio ttl update` command.
Updated alluxioPath=/s3/test_folder/ and time=5s
```

### 删除 TTL 规则

该命令用于从 ETCD 中删除 TTL 策略。下面是一些示例：

```console
$ bin/alluxio ttl remove --path /s3/test_folder
Removed TTL policy for alluxioPath=/s3/test_folder/
```

### 列出所有 TTL 规则

该命令将列出所有有效的 TTL 策略：

```console
$ bin/alluxio ttl list
Listing all TTL policies
The ttl policy table is empty.

$ bin/alluxio ttl list
Listing all TTL policies
/s3/test.csv/     TTL: 1 hour
/s3/test_2.csv/   TTL: 30 seconds
```

### 强制触发 TTL 扫描

您可以使用下列命令让所有 Worker 立即触发一轮缓存 TTL 扫描。如果某个 Worker 已在进行常规扫描，那么该 Worker 将被跳过，不对其重新扫描。

```console
$ bin/alluxio ttl trigger
Force triggering all workers to scan their cache with TTL rules.
Successfully scheduled on-demand TTL evictions.

# If two workers are already in the middle of a regular scan
$ bin/alluxio ttl trigger
Force triggering all workers to scan their cache with TTL rules.
2 workers are already scanning
Successfully scheduled on-demand TTL evictions.
```

由于每次完整缓存 TTL 扫描都会产生系统开销，因此我们不建议过多使用该命令。相反，应依赖每个 worker 的常规 TTL 扫描来删除过期的缓存。只有当常规扫描无法被正确触发，或者需要快速从缓存中恢复部分空间时，才使用该命令。

## 进阶配置和操作

### 配置 TTL 扫描间隔

每次 TTL 扫描的默认时间间隔为 1 小时。由于每次扫描都会产生系统开销，我们建议您在生产环境中设置较大的间隔时间，例如：

```properties
alluxio.ttl.eviction.check.interval=24h
```

### 可观察性

Alluxio 提供了指标 `alluxio_eviction_by_ttl_bytes` 来反映不同规则上驱逐的缓存数据量：

```console
$ curl "http://localhost:30000/metrics/"
(snip)
# HELP alluxio_eviction_by_ttl_bytes_total Total number of bytes evicted from Alluxio workers by TTL policy.
# TYPE alluxio_eviction_by_ttl_bytes_total counter
alluxio_eviction_by_ttl_bytes_total{policy_path="s3://test-bucket/"} 4194304.0
(snip)
```


---

# 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-da-cn/cache/eviction/ttl.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.