> For the complete documentation index, see [llms.txt](https://documentation.alluxio.io/ee-ai-cn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.alluxio.io/ee-ai-cn/reference/rest-api.md).

# REST API

Rest API 设计用于作业、配置和集群管理。

### 分布式加载

提前将UFS数据加载到worker中缓存，避免冷读对用户产生性能影响。

#### 提交或恢复加载作业

| **方法** | **路径**       | **参数** | **请求体类型**                      |
| ------ | ------------ | ------ | ------------------------------ |
| POST   | /api/v1/load | 无      | Content-Type: application/json |

**参数**

| **名称**        | **类型** | **必填** | **描述**                                                                                                                                                                          | **示例**                                                                                     |
| ------------- | ------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `path`        | string | 否      | 要加载的单个 ufs 目录或文件，等价于 CLI 的 `--path`；该路径同时作为作业标识，供后续进度查询/停止使用                                                                                                                    | '{"path": "s3://bucket/dir/"}'                                                             |
| `index`       | string | 否      | ufs 上的索引文件路径（必须已挂载）                                                                                                                                                             | '{"index": s3://bucket/key}'                                                               |
| `paths`       | string | 否      | 要加载的 ufs 路径列表。目录路径必须以 `/` 结尾；不带 `/` 的路径按单个文件处理，目录漏写 `/` 时什么都不会加载。文件路径末尾可加空格和 `{range=...}`，只加载这些字节区间，见[缓存加载](https://documentation.alluxio.io/ee-ai-cn/cache/cache-loading.md)。 | '{"paths": \["s3://bucket/dir1/", "s3://bucket/key2", "s3://bucket/key3 {range=0-4MiB}"]}' |
| `alias`       | string | 否      | 和paths组合使用，供后续状态查询                                                                                                                                                              | '{"paths": \["s3://bucket/key1", "s3://bucket/key2"], "alias": "database1"}'               |
| `isOverWrite` | bool   | 否      | 终止同一目标的现有作业并按新参数提交全新作业，等价于 CLI 的 `--overwrite`                                                                                                                                  | '{"path": "s3://bucket/dir/", "isOverWrite": true}'                                        |
| `options`     | object | 否      | 配置加载作业的选项                                                                                                                                                                       | '{"index": s3://bucket/key, "options":{"batchSize":10}}'                                   |

其中，`path`、`index`和`paths`三选一. `paths`可以指定`alias`，否则内部随机生成alias返回用户。

可以使用 `options` 来配置加载作业的选项。可选字段有：

| **名称**             | **类型** | **必填** | **描述**                                                                                                     |
| ------------------ | ------ | ------ | ---------------------------------------------------------------------------------------------------------- |
| `batchSize`        | int    | 否      | worker从 ufs 加载数据的批处理大小                                                                                     |
| `replicas`         | int    | 否      | 加载文件副本数，默认值config中设置对应路径副本或1                                                                               |
| `skipIfExists`     | bool   | 否      | 如果文件已存在，则跳过加载过程.                                                                                           |
| `loadPolicy`       | enum   | 否      | 目前仅支持 IF\_CHANGED。如果文件已更改，则更新文件。                                                                           |
| `loadMetadataOnly` | bool   | 否      | 仅加载文件元数据。                                                                                                  |
| `verify`           | bool   | 否      | 加载完成后重新校验每个文件，补加载未完全缓存的文件，等价于 CLI 的 `--verify`。                                                            |
| `fileFilterRegex`  | string | 否      | 仅加载路径匹配该正则表达式的文件。                                                                                          |
| `preScanFile`      | bool   | 否      | 另做一次列举，统计目标的文件数与字节数，供进度显示总量。在作业第一次被调度时启动。                                                                  |
| `skipQuotaCheck`   | bool   | 否      | 跳过 `alluxio.dora.load.job.must.check.quota` 要求的配额检查，等价于 CLI 的 `--skip-quota-check`。                        |
| `indexServiceMode` | enum   | 否      | `withLoad`：在加载数据的同时为加载目录树中的每个目录重建 listing 索引；`indexOnly`：只重建 listing 索引，不加载任何数据或元数据；不传则为普通加载。未知取值返回 `400`。 |

**示例**

一个 JSON 请求负载示例如下：

```json
{
  "paths": [
    "s3://my-bucket/dir/to/path"
  ],
  "options": {
    "batchSize": 1,
    "replicas": 1,
    "loadMetadataOnly": true,
    "loadPolicy": "IF_CHANGED",
    "indexServiceMode": "withLoad"
  }
}
```

正常返回示例：json格式

```
{
  "target":"job-95e8a01f-d519-4c1a-8311-26714f4db623",
  "id":"1cf35e69-b6e6-4807-8aae-588e0e994277"
}
```

**错误码**

| **http状态码** | **错误码**               | **描述**                                                                                                                                                |
| ----------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| 200         | OK                    | 操作成功                                                                                                                                                  |
| 400         | Bad Request           | 请求没有正文或缺少必需字段；或在 `alluxio.dora.load.job.must.check.quota` 为 `true` 且未设置 `skipQuotaCheck` 时使用了 `paths`：路径列表没有加载路径或索引文件可用来查找配额，请改用 `index` 索引文件，或跳过配额检查 |
| 409         | Conflict              | 已存在相同目标与类型的作业，且它保持原有参数——运行中的继续运行，已停止的会被恢复；响应中返回该作业的 ID。若要替换它，请传 `isOverWrite`。                                                                        |
| 500         | Internal Server Error | 意外错误                                                                                                                                                  |

#### 获取加载作业进度

| **方法** | **路径**       | **参数** | **请求体类型** |
| ------ | ------------ | ------ | --------- |
| GET    | /api/v1/load | 有      | 无         |

**参数：**

| **名称**       | **类型** | **必填** | **描述**                                                 | **示例**                                                                           |
| ------------ | ------ | ------ | ------------------------------------------------------ | -------------------------------------------------------------------------------- |
| `target`     | string | 是      | 提交job时返回字段信息                                           | target=job-95e8a01f-d519-4c1a-8311-26714f4db623                                  |
| `fileList`   | bool   | 否      | 获取加载文件列表                                               | target=job-95e8a01f-d519-4c1a-8311-26714f4db623\&fileList=true                   |
| `fileStatus` | string | 否      | 文件列表类型\[TOTAL\|FAILURE]，不区分大小写。省略时默认为 TOTAL，其他取值返回 400 | target=job-95e8a01f-d519-4c1a-8311-26714f4db623\&fileList=true\&fileStatus=TOTAL |

注：3.7查询参数依然兼容, 例如:`alias`,`index`

路由不接受的查询参数（例如拼错的 `targe=`）会返回 `400` 并给出参数名；以前这类参数会被忽略，请求可能变成列出全部作业。对 load 和 free 作业，`target` 末尾多一个 `/` 也能查到提交时不带 `/` 的作业。

带 `fileList=true` 时，若作业不存在，或列表从未生成（例如没有失败文件的作业的 FAILURE 列表）或已过期，返回 404。列表超过 `alluxio.job.retention.time`（7d）且所属作业不再处于等待、运行或停止状态时会被删除。

**示例** 获取任务执行状态正常返回示例：json格式

```
{
    "id": "043cc6c2-b456-4d57-a807-a8c86256d8f2",
    "startTime": "2026-01-16T16:35:35.32+08:00",
    "endTime": "2026-01-16T16:35:42.149+08:00",
    "jobState": "SUCCEEDED",
    "timeElapsedMilliseconds": 6829,
    "paths": [
        "s3://test/index"
    ],
    "alias": "job-e7cc61f3-fdd5-45fe-a11b-e8f92f0c6d05",
    "batchSize": 200,
    "loadedBytes": 127,
    "totalBytes": 127,
    "loadedNonEmptyFiles": 1,
    "scannedFiles": 1,
    "replicas": "ALL"
}
```

获取任务列表正常返回示例：json格式

```
[
    {
        "path": "s3://test/index",
        "size": 0,
        "mTime": 0
    },
    {
        "path": "s3://test/index-copy",
        "size": 0,
        "mTime": 0
    }
]
```

**错误码**

| **http状态码** | **错误码**               | **描述** |
| ----------- | --------------------- | ------ |
| 200         | OK                    | 操作成功   |
| 404         | Not Found             | 任务不存在  |
| 500         | Internal Server Error | 意外错误   |

#### 停止加载作业

| **方法** | **路径**       | **参数** | **请求体类型**                      |
| ------ | ------------ | ------ | ------------------------------ |
| DELETE | /api/v1/load | 无      | Content-Type: application/json |

**参数：**

| **名称**   | **类型** | **必填** | **描述**       | **示例**                                                |
| -------- | ------ | ------ | ------------ | ----------------------------------------------------- |
| `target` | string | 是      | 提交job时返回字段信息 | {"target":"job-95e8a01f-d519-4c1a-8311-26714f4db623"} |

注：3.7停止参数依然兼容， 例如:`alias`,`index`

**错误码**

| **http状态码** | **错误码**     | **描述**        |
| ----------- | ----------- | ------------- |
| 200         | OK          | 操作成功          |
| 400         | Bad Request | 请求没有正文或缺少必需字段 |
| 404         | Not Found   | 加载作业不存在       |
| 410         | Gone        | 加载作业已完成       |

#### 列举加载作业列表

| **方法** | **路径**       | **参数** | **请求体类型** |
| ------ | ------------ | ------ | --------- |
| GET    | /api/v1/load | 有      | 无         |

**参数：**

| **名称**           | **类型** | **必填** | **描述**                                                                                                                                                                                 |
| ---------------- | ------ | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `state`          | string | 否      | 一个作业状态，或用逗号分隔的多个状态：WAITING、RUNNING、VERIFYING、STOPPED、SUCCEEDED、FAILED；或 `ALL`。不区分大小写。默认 `ALL`。同一请求中 WAITING、RUNNING、VERIFYING 不能与 STOPPED、SUCCEEDED、FAILED 混用                          |
| `endedAfter`     | string | 否      | 只列出在这个时间及之后结束的作业。时间用 RFC 3339 格式，例如 `2026-11-02T08:00:00Z` 或 `2026-11-02T16:00:00+08:00`；不带时区偏移的时间按 coordinator 所在时区解释。要求 `state` 只含 STOPPED、SUCCEEDED、FAILED。没有记录结束时间的 STOPPED 作业不会列出 |
| `lastKey`        | string | 否      | 上一页响应中的 `nextKey`。见[分页列举作业](#fen-ye-lie-ju-zuo-ye)                                                                                                                                     |
| `count`          | int    | 否      | 每页最多返回的作业数，1 到 10000。默认 1000                                                                                                                                                           |
| `failureSamples` | int    | 否      | 为每个列出的作业附带最多这么多个失败文件，0 到 100。默认 0，不附带。见[列举结果中的失败样本](#lie-ju-jie-guo-zhong-de-shi-bai-yang-ben)                                                                                         |

注：不带参数时列出所有状态的前 1000 个作业。响应中的 `isTruncated` 表示后面是否还有作业。

**错误码**

| **http状态码** | **错误码**     | **描述**                                                                                                                                                      |
| ----------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 200         | OK          | 操作成功                                                                                                                                                        |
| 400         | Bad Request | `state` 不认识或状态组合不允许；`endedAfter` 无法解析，或没有配合只含已结束状态的 `state`；`count` 或 `failureSamples` 超出范围；带了路由不接受的查询参数；或 `lastKey` 无法使用（见[分页列举作业](#fen-ye-lie-ju-zuo-ye)） |
| 404         | Not Found   | `lastKey` 是一个已不存在的作业的 id                                                                                                                                    |

**响应**

| **字段**        | **描述**                                                                                                          |
| ------------- | --------------------------------------------------------------------------------------------------------------- |
| `results`     | 这一页的作业                                                                                                          |
| `isTruncated` | `true` 表示这一页之后还有符合条件的作业，`false` 表示这是最后一页。每个响应都有这个字段                                                             |
| `nextKey`     | 只在 `isTruncated` 为 `true` 时出现。作为 `lastKey` 传入即可取下一页                                                             |
| `filter`      | coordinator 实际使用的过滤条件：`type`、`state`（不按状态过滤时为 `["ALL"]`）、`endedAfter`（只在请求带了它时出现，按 coordinator 所在时区显示）和 `count` |

`GET /api/v1/load?count=2` 的响应示例（json 格式）：

```
{
    "results": [
        {
            "id": "53b3123d-a042-4eb1-90e5-73798b963b04",
            "startTime": "2026-01-17T08:22:52.787+08:00",
            "endTime": "2026-01-17T08:22:57.289+08:00",
            "jobState": "SUCCEEDED",
            "timeElapsedMilliseconds": 4502,
            "paths": [
                "s3://tidas-alluxio-test/index"
            ],
            "alias": "job-1cfb048e-7ca7-48d3-8dd3-aa2ed8472176",
            "batchSize": 200,
            "loadedBytes": 127,
            "totalBytes": 127,
            "loadedNonEmptyFiles": 1,
            "scannedFiles": 1,
            "replicas": "ALL"
        },
        {
            "id": "89e288cf-480a-40df-a45b-91c3e08cb138",
            "startTime": "2026-01-17T08:22:54.117+08:00",
            "endTime": "1970-01-01T08:00:00+08:00",
            "jobState": "RUNNING",
            "runningStage": "LOADING",
            "paths": [
                "s3://tidas-alluxio-test/index"
            ],
            "alias": "job-9869111f-99f3-4ee4-9dbe-6c0204b96aec",
            "batchSize": 200,
            "replicas": "ALL"
        }
    ],
    "isTruncated": true,
    "nextKey": "jc1.bG9hZApzMzovL3RpZGFzLWFsbHV4aW8tdGVzdC9pbmRleA",
    "filter": {
        "type": "load",
        "state": ["ALL"],
        "count": 2
    }
}
```

#### 分页列举作业

一次列举最多返回 `count` 个作业：不传 `count` 时为 1000 个，最大 10000。`count` 超过上限返回 400，不会悄悄少返回。`/api/v1/load`、`/api/v1/free`、`/api/v1/copy`、`/api/v1/oci-preload` 和 [`/api/v1/jobs`](#lie-ju-suo-you-lei-xing-de-zuo-ye) 都按下面的步骤翻页：

1. 第一次请求不带 `lastKey`。
2. 如果 `isTruncated` 为 `true`，把 `nextKey` 原样作为 `lastKey`，再发一次同样的请求。下一页紧接着这一页开始，不会重复这一页的作业。
3. `isTruncated` 为 `false` 时，说明已经列完。

请按 `isTruncated` 判断，不要按这一页的作业数判断：最后一页也可能正好装满。响应里没有 `isTruncated`，说明 coordinator 早于这个字段；对这样的 coordinator，作业数少于 `count` 的那一页是最后一页。

```shell
curl -s 'http://coordinator:19999/api/v1/load?state=FAILED&endedAfter=2026-11-02T00:00:00Z&count=100'
curl -s 'http://coordinator:19999/api/v1/load?state=FAILED&endedAfter=2026-11-02T00:00:00Z&count=100&lastKey=<nextKey>'
```

`lastKey` 仍然兼容以前的写法：

* 在单一作业类型的路由上，填上一页最后一个作业的路径。
* 单 coordinator 部署（RocksDB 作业存储）上，也可以填上一页最后一个作业的 `id`。该作业已不存在时返回 404；属于其他类型，或 coordinator 无法从作业存储中读回该作业时返回 400。多 coordinator 部署（etcd 作业存储）不支持 id，返回 400。

限制：

* 作业存储不变时，作业的顺序是稳定的，但顺序本身没有约定，不要依赖它。
* 列举不是快照。翻页期间有作业提交、改变状态，或被保留期清理删除时，这个作业可能出现在两页里，也可能一页都不出现。
* `nextKey` 和作业路径在作业被保留期清理删除后仍然可用；作业 id 不行：请求会返回 404（`/api/v1/jobs?type=all` 上为 400），客户端需要不带 `lastKey` 从头列举。
* 以 `jc1.` 开头、但不是 coordinator 给出的 `lastKey`，返回 400。
* coordinator 无法从作业存储读回的作业仍会列出，内容取自存储的记录：只有 `id`、`jobState`、`endTime`、`errorMessage`、该类型有记录时的 `startTime`，以及提交时的路径，没有该类型的进度字段。客户端不要假设每个作业都带有路由的全部字段。

#### 列举结果中的失败样本

带 `failureSamples=N` 时，每个列出的作业多一个 `failureSamples` 数组，最多 N 个失败文件，这样不必逐个作业拉取失败文件列表就能看到失败原因。不带这个参数或 `failureSamples=0` 时，没有这个字段。

```shell
curl -s 'http://coordinator:19999/api/v1/load?state=FAILED&endedAfter=2026-11-02T00:00:00Z&failureSamples=3'
```

```
"failureSamples": [
    {
        "file": "s3://bucket/data/part-0001",
        "reason": "WORKER_FAILED",
        "message": "<error message>"
    }
]
```

| **字段**    | **描述**                                          |
| --------- | ----------------------------------------------- |
| `file`    | 失败的文件。不针对单个文件的失败为 `null`，例如 free 时联系不上某个 worker |
| `reason`  | 失败类别，取值随作业类型不同，见下文                              |
| `message` | 错误信息，最长 1024 个字符，超出部分截断                         |

* N 最大 100，且 `count` × N 最大 10000。超出返回 400，错误信息中给出当前 `count` 下允许的最大 N。
* N 是上限。作业记录的失败少于 N 时返回的样本也少；没有可取的样本时为 `[]`。任何作业类型或状态都不会让请求失败。
* load、copy、free 作业只在以 `FAILED` 结束时记录失败文件；其他状态的作业为 `[]`。
* load：最新的失败排在前面，每个文件一个样本。load 作业只保留最新的 1000 条失败记录，大文件每个失败的分段各占一条，所以少数几个失败的大文件就可能让可取的不同文件少于 N 个。`reason` 是调度器记录的原因，例如 `WORKER_FAILED`；具体原因（例如读取被拒绝）在 `message` 中。
* copy：失败文件中的任意一部分，不保证是最新的。`reason` 是错误码名称，例如 `INTERNAL`。
* free：整个 worker 的失败（`WORKER_FAILED`）或一批路径的失败（`BATCH_FAILED`）排在前面，`file` 为 `null`；之后是失败的文件（`FREE_FAILED`，`message` 中带 worker）。其余是任意一部分。
* OCI preload 作业的失败只记在内存中、不持久化，所以样本总是 `[]`。move 作业也为 `[]`。
* 样本取自作业存储的记录：RocksDB 与 etcd 作业存储上相同，coordinator 重启后也相同，且不为每个作业增加额外的读取。
* 这个参数只用于列举。带 `id`、`target` 或 `fileList` 的请求同时带 `failureSamples` 时返回 400。

#### 列举所有类型的作业

| **方法** | **路径**       | **参数** | **请求体类型** |
| ------ | ------------ | ------ | --------- |
| GET    | /api/v1/jobs | 有      | 无         |

在一个分页列表中列出各种类型的作业。提供这个路由的 coordinator 会在 [`/api/v1/cluster-info`](#huo-qu-ji-qun-xin-xi) 的 `features` 中列出 `job-list-all`。

**参数：**

| **名称**                                        | **类型** | **必填** | **描述**                                                                                                                                      |
| --------------------------------------------- | ------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`                                        | string | 否      | `load`、`free`、`copy`、`move`、`oci-preload`、`write-cache-decommission` 或 `all`。不区分大小写，`-` 也可写作 `_`。默认 `all`                                   |
| `state`、`endedAfter`、`count`、`failureSamples` |        | 否      | 与[列举加载作业列表](#lie-ju-jia-zai-zuo-ye-lie-biao)相同                                                                                              |
| `lastKey`                                     | string | 否      | 上一页的 `nextKey`；RocksDB 作业存储上也可以填上一页最后一个作业的 id。`type` 为 `all` 时，作业路径或找不到对应作业的 id 返回 400：不同类型的作业可能有相同的路径。指定单一 `type` 时，`lastKey` 的规则与该类型的路由相同 |

`results` 中每个作业都带 `jobType`（拼写与 `type` 参数相同），以及该类型在自己路由（`/api/v1/load`、`/api/v1/free`、`/api/v1/copy`、`/api/v1/oci-preload`）上显示的字段。move 作业显示所有作业共有的字段，以及与 copy 作业相同形式的 `path`：`{"source": ..., "destination": ...}`；`write-cache-decommission` 作业显示共有字段和 `path`。`isTruncated`、`nextKey`、`filter` 与单一类型的路由相同，`filter.type` 为列举的类型或 `all`。

`GET /api/v1/jobs?state=SUCCEEDED` 的响应示例（json 格式）：

```
{
    "results": [
        {
            "jobType": "load",
            "id": "53b3123d-a042-4eb1-90e5-73798b963b04",
            "startTime": "2026-01-17T08:22:52.787+08:00",
            "endTime": "2026-01-17T08:22:57.289+08:00",
            "jobState": "SUCCEEDED",
            "timeElapsedMilliseconds": 4502,
            "paths": ["s3://tidas-alluxio-test/index"],
            "alias": "job-1cfb048e-7ca7-48d3-8dd3-aa2ed8472176"
        },
        {
            "jobType": "free",
            "id": "1498117f-bf66-4198-967d-1186588c56d1",
            "startTime": "2026-01-17T22:13:35.198+08:00",
            "endTime": "2026-01-17T22:13:40.385+08:00",
            "jobState": "SUCCEEDED",
            "timeElapsedMilliseconds": 5187,
            "paths": ["s3://test/rest1/test/"],
            "alias": "job-312c44ac-156c-4e5a-b142-e540067ad086"
        }
    ],
    "isTruncated": false,
    "filter": {
        "type": "all",
        "state": ["SUCCEEDED"],
        "count": 1000
    }
}
```

**错误码**

| **http状态码** | **错误码**     | **描述**                                                                                                            |
| ----------- | ----------- | ----------------------------------------------------------------------------------------------------------------- |
| 200         | OK          | 操作成功                                                                                                              |
| 400         | Bad Request | `type` 不认识；`type=all` 时 `lastKey` 既不是 `nextKey` 也不是已存储作业的 id；或[列举加载作业列表](#lie-ju-jia-zai-zuo-ye-lie-biao)中列出的任一原因 |
| 404         | Not Found   | 指定单一 `type` 时，`lastKey` 是一个已不存在的作业的 id                                                                            |

### 释放缓存

将worker缓存数据清理，释放缓存存储空间

#### 提交或恢复释放作业

| **方法** | **路径**       | **参数** | **请求体类型**                      |
| ------ | ------------ | ------ | ------------------------------ |
| POST   | /api/v1/free | 无      | Content-Type: application/json |

**参数**

| **名称**        | **类型** | **必填** | **描述**                                                            | **示例**                                                                       |
| ------------- | ------ | ------ | ----------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `index`       | string | 否      | ufs 上的索引文件路径（必须已挂载）                                               | '{"index": s3://bucket/key}'                                                 |
| `paths`       | string | 否      | 要释放的 ufs 路径列表。目录路径必须以 `/` 结尾；不带 `/` 的路径按单个文件处理，目录漏写 `/` 时什么都不会释放。 | '{"paths": \["s3://bucket/dir1/", "s3://bucket/key2"]}'                      |
| `alias`       | string | 否      | 和paths组合使用，供后续状态查询                                                | '{"paths": \["s3://bucket/key1", "s3://bucket/key2"], "alias": "database1"}' |
| `isOverWrite` | bool   | 否      | 终止同一目标的现有作业并按新参数提交全新作业，等价于 CLI 的 `--overwrite`                    | '{"index": "s3://bucket/key", "isOverWrite": true}'                          |
| `options`     | object | 否      | 配置加载作业的选项                                                         | '{"index": s3://bucket/key, "options":{"batchSize":10}}'                     |

其中，index和paths二选一。paths可以指定alias，否则内部随机生成alias返回用户。

可以使用 `options` JSON 来配置释放作业的选项。所有选项都是可选的。可能的配置有：

| **名称**         | **类型** | **必填** | **描述**                                                                                      |
| -------------- | ------ | ------ | ------------------------------------------------------------------------------------------- |
| `batchSize`    | int    | 否      | 每轮调度分发给每个 worker 的索引条目数；不限制释放速率                                                             |
| `rateLimit`    | long   | 否      | 每个 worker 每秒释放文件数上限，全部运行中的 free 作业共享；0 表示不限速，不设置则使用 `alluxio.job.free.rate.limit`（默认 20000） |
| `replicas`     | int    | 否      | 释放文件副本的数量，仅在释放文件的时候有效                                                                       |
| `indexService` | bool   | 否      | 释放目录缓存                                                                                      |

**示例**

一个 JSON 请求负载示例如下：

```json
{
    "paths": [
        "s3://tidas-alluxio-test/index",
        "s3://tidas-alluxio-test/index-copy"
    ],
    "options": {
        "batchSize": "30"
    }
}
```

正常返回示例：json格式

```
{
    "target": "job-0aafec67-53b4-488c-b988-73493b2b9ebe",
    "id": "bc0c3296-ea1f-484b-b371-300bf4d54ca6"
}
```

**错误码**

| **http状态码** | **错误码**               | **描述**                                                                         |
| ----------- | --------------------- | ------------------------------------------------------------------------------ |
| 200         | OK                    | 操作成功                                                                           |
| 400         | Bad Request           | 请求没有正文或缺少必需字段                                                                  |
| 409         | Conflict              | 已存在相同目标与类型的作业，且它保持原有参数——运行中的继续运行，已停止的会被恢复；响应中返回该作业的 ID。若要替换它，请传 `isOverWrite`。 |
| 500         | Internal Server Error | 意外错误                                                                           |

#### 获取释放作业的进度

| **方法** | **路径**       | **参数** | **请求体类型** |
| ------ | ------------ | ------ | --------- |
| GET    | /api/v1/free | 有      | 无         |

**参数：**

| **名称**   | **类型** | **必填** | **描述**       | **示例**                                          |
| -------- | ------ | ------ | ------------ | ----------------------------------------------- |
| `target` | string | 是      | 提交job时返回字段信息 | target=job-95e8a01f-d519-4c1a-8311-26714f4db623 |

注：3.7查询参数依然兼容， 例如:`alias`,`index`

路由不接受的查询参数（例如拼错的 `targe=`）会返回 `400` 并给出参数名；以前这类参数会被忽略，请求可能变成列出全部作业。对 load 和 free 作业，`target` 末尾多一个 `/` 也能查到提交时不带 `/` 的作业。

**示例** 获取任务执行状态正常返回示例：json格式

````
```json
{
"id": "17bb4213-891b-4c3f-bc32-8d314051514b",
"startTime": "2026-01-17T21:59:11.831+08:00",
"endTime": "2026-01-17T21:59:16.104+08:00",
"jobState": "SUCCEEDED",
"timeElapsedMilliseconds": 4273,
"paths": [
    "s3://test/"
],
"alias": "job-95adb50b-4722-4a79-bd58-872cfeca48cb",
"freedBytes": 409600,
"totalBytes": 409600,
"freedFiles": 100,
"totalFiles": 100
````

} \`\`\`

**错误码**

| **http状态码** | **错误码**   | **描述** |
| ----------- | --------- | ------ |
| 200         | OK        | 操作成功   |
| 404         | Not Found | 任务不存在  |

#### 停止释放作业

| **方法** | **路径**       | **参数** | **请求体类型**                      |
| ------ | ------------ | ------ | ------------------------------ |
| DELETE | /api/v1/free | 无      | Content-Type: application/json |

**参数：**

| **名称**   | **类型** | **必填** | **描述**       | **示例**                                                |
| -------- | ------ | ------ | ------------ | ----------------------------------------------------- |
| `target` | string | 是      | 提交job时返回字段信息 | {"target":"job-95e8a01f-d519-4c1a-8311-26714f4db623"} |

注：3.7停止参数依然兼容， 例如:`alias`,`index`

**错误码**

| **http状态码** | **错误码**     | **描述**        |
| ----------- | ----------- | ------------- |
| 200         | OK          | 操作成功          |
| 400         | Bad Request | 请求没有正文或缺少必需字段 |
| 404         | Not Found   | 加载作业不存在       |
| 410         | Gone        | 加载作业已完成       |

#### 列出所有释放作业

| **方法** | **路径**       | **参数** | **请求体类型** |
| ------ | ------------ | ------ | --------- |
| GET    | /api/v1/free | 有      | 无         |

**参数：** `state`、`endedAfter`、`lastKey`、`count`、`failureSamples`，与[列举加载作业列表](#lie-ju-jia-zai-zuo-ye-lie-biao)相同；见[分页列举作业](#fen-ye-lie-ju-zuo-ye)。

**错误码：** 与[列举加载作业列表](#lie-ju-jia-zai-zuo-ye-lie-biao)相同。

**响应** 一个正常列举的响应：json格式

```
{
    "results": [
        {
            "id": "1498117f-bf66-4198-967d-1186588c56d1",
            "startTime": "2026-01-17T22:13:35.198+08:00",
            "endTime": "2026-01-17T22:13:40.385+08:00",
            "jobState": "SUCCEEDED",
            "timeElapsedMilliseconds": 5187,
            "paths": [
                "s3://test/rest1/test/"
            ],
            "alias": "job-312c44ac-156c-4e5a-b142-e540067ad086"
        },
        {
            "id": "3baf5ab6-c303-4a59-8678-f297870847f4",
            "startTime": "2026-01-17T22:13:26.177+08:00",
            "endTime": "2026-01-17T22:13:30.38+08:00",
            "jobState": "SUCCEEDED",
            "timeElapsedMilliseconds": 4203,
            "paths": [
                "s3://test/rest/test/"
            ],
            "alias": "job-749f2cbf-32cb-44d5-aa4f-4a4e6b94689b"
        }
    ],
    "isTruncated": false,
    "filter": {
        "type": "free",
        "state": ["ALL"],
        "count": 1000
    }
}
```

### 重新平衡

#### 列出所有重新平衡作业

**方法：** `GET`

**路径：** `/api/v1/rebalance`

**参数：** `state`、`lastKey`、`count`，与[列举加载作业列表](#lie-ju-jia-zai-zuo-ye-lie-biao)相同；见[分页列举作业](#fen-ye-lie-ju-zuo-ye)

**响应：**

* `200 - OK`：操作成功

  ```json
  {
    "results": [
      {...}
    ]
  }
  ```

  有关作业描述的更多信息，请参阅 **“获取重新平衡作业的进度”**
* `500 - Internal Server Error`：意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 获取重新平衡作业的进度

**方法：** `GET`

**路径：** `/api/v1/rebalance`

**参数：**

最多需要一个参数。

| **名称**   | **描述**                                                                                  |
| -------- | --------------------------------------------------------------------------------------- |
| `id`     | POST 返回的作业 ID                                                                           |
| `target` | 重新平衡作业的目标工作节点，可以是工作节点 ID（例如 worker-54b88939-de49-46ef-acab-fe489f46d1a0）或 ALL（表示所有工作节点） |

**响应：**

* `200 - OK`：操作成功（空值将被省略）

  ```json
  {
     "succeededWorkers":2,
     "bytesPreserved":4,
     "filesLoaded":0,
     "filesPreserved":1,
     "filesFailed":0,
     "totalWorkers":2,
     "bytesPruned":226,
     "filesPruned":5,
     "bytesLoaded":0,
     "timeElapsedMilliseconds":4536,
     "runningWorkers":0,
     "startTime":"2024-12-19T23:15:07.043+08:00",
     "id":"8de63d3a-63c8-4f08-bbc1-c87e3c0fb6d9",
     "state":"SUCCEEDED",
     "failedWorkers":0
  }
  ```
* `404 - Not Found`：未找到作业

  ```json
  {
    "status": "No job found..."
  }
  ```
* `500 - Internal Server Error`：意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 提交或恢复重新平衡作业

**方法：** `POST`

**路径：** `/api/v1/rebalance`

**参数：** 无

**请求体：** `Content-Type: application/json`

必需字段

| **名称**   | **描述**                                                                                      |
| -------- | ------------------------------------------------------------------------------------------- |
| `target` | 重新平衡作业的目标工作节点，可以是工作节点 ID（例如 `worker-54b88939-de49-46ef-acab-fe489f46d1a0`）或 `ALL`（表示所有工作节点） |

可以使用 `options` JSON 来配置加载作业的选项。所有选项都是可选的。可能的配置有：

| **名称**           | **描述**                              |
| ---------------- | ----------------------------------- |
| `loadBatchSize`  | 加载阶段的批处理大小，与加载作业中的 batchSize 选项相同   |
| `loadBandwidth`  | 每个工作节点每秒的加载带宽（字节）。例如：10485746000... |
| `pruneBandwidth` | 每个工作节点每秒的修剪带宽（字节）。例如：10485746000... |
| `skipPrune`      | 如果重新平衡应仅加载数据并跳过修剪不属于该工作节点的数据        |

一个 JSON 请求负载示例如下：

```json
{
  "target": "ALL",
  "options": {
    "loadBatchSize": 1000,
    "loadBandwidth": 10485746000,
    "pruneBandwidth": 10485746000,
    "skipPrune": false,
  }
}
```

**响应：**

* `200 - OK`：操作成功

  ```json
  {
    "id": "54b88939-de49-46ef-acab-fe489f46d1a0"
  }
  ```
* `400 - Bad Request`：请求没有正文或缺少必需字段

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `409 - Conflict`：使用相同路径恢复加载作业并返回先前的作业 ID

  ```json
  {
    "id": "54b88939-de49-46ef-acab-fe489f46d1a0"
  }
  ```
* `500 - Internal Server Error`：意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 停止重新平衡作业

**方法：** `DELETE`

**路径：** `/api/v1/rebalance`

**参数：** 无

**请求体：** `Content-Type: application/json`

最多需要一个参数。

| **名称**   | **描述**                                                                                      |
| -------- | ------------------------------------------------------------------------------------------- |
| `id`     | POST 返回的作业 ID                                                                               |
| `target` | 重新平衡作业的目标工作节点，可以是工作节点 ID（例如 `worker-54b88939-de49-46ef-acab-fe489f46d1a0`）或 `ALL`（表示所有工作节点） |

**响应：**

* `200 - OK`：操作成功

  ```json
  {
    "status": "ok"
  }
  ```
* `400 - Bad Request`：请求没有正文或缺少必需字段

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `410 - Gone`：作业不存在或已完成

  ```json
  {
    "status": "The job doesn't exist or has already finished"
  }
  ```
* `500 - Internal Server Error`：意外错误

  ```json
  {
    "status": "string"
  }
  ```

### Rebalance V2

Rebalance V2 端点取代了用于即时重新平衡作业的 V1 [`/api/v1/rebalance`](#chong-xin-ping-heng) 端点，并驱动版本化一致性哈希环。有关运维流程，请参阅[缓存重平衡](https://documentation.alluxio.io/ee-ai-cn/cache/cache-rebalancing.md)。

所有端点都要求 `alluxio.coordinator.job.meta.store.type = ETCD`。当未启用基于 etcd 的作业元数据存储时，下面的每个端点都会返回 `501`：

| 状态码                     | 响应体                                                                               |
| ----------------------- | --------------------------------------------------------------------------------- |
| `501 - Not Implemented` | `{ "status": "Etcd-based job metastore is not enabled for the coordinator ..." }` |

为简洁起见，下面每个端点的响应表中均省略了 `501` 错误响应。

#### 提交重新平衡作业

**方法：** `POST`

**路径：** `/api/v1/rebalance-v2`

**参数：**

所有字段均为可选；默认值取自协调器配置。

| 名称                          | 描述                                                                               |
| --------------------------- | -------------------------------------------------------------------------------- |
| `skipExistingFiles`         | 若为 `true`，跳过目标工作节点上已存在的文件。默认 `false`。                                            |
| `maxParallelWorkerSessions` | 每个工作节点的最大并发工作节点间会话数。必须在 `(0, 1000]` 范围内。默认 `10`。                                 |
| `maxParallelFilesPerWorker` | 每个会话内的最大并发文件传输数。必须为正整数。默认 `4`。                                                   |
| `loadSource`                | 接收方读取重新平衡文件数据的来源：`PEER`（从对等工作节点拉取页面）或 `UFS`（直接从 UFS 读取）。默认 `PEER`。参见下文 **数据来源**。 |

系统会施加一个组合的单工作节点并发上限：`maxParallelWorkerSessions × maxParallelFilesPerWorker × 2 ≤ 2048`。

**请求体：** `Content-Type: application/json`

```json
{
  "skipExistingFiles": false,
  "maxParallelWorkerSessions": 10,
  "maxParallelFilesPerWorker": 4,
  "loadSource": "PEER"
}
```

**响应：**

| 状态码                           | 响应体                                                                             | 描述                                                                                                                                             |
| ----------------------------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `200 - OK`                    | `{ "jobId": "<uuid>", "status": "RUNNING", "message": "" }`                     | 操作成功。即使部分工作节点未能收到派发，`status` 仍为 `RUNNING`；此时 `message` 为 `Some workers failed to receive dispatch: [<workerIds>]`。                             |
| `400 - Bad Request`           | `{ "status": "..." }`                                                           | 参数错误：`maxParallelWorkerSessions` 为 `<= 0` 或 `> 1000`；`maxParallelFilesPerWorker` 非正整数；组合的单工作节点并发上限超过 2048；或 `loadSource` 不是 `PEER` / `UFS` 之一。 |
| `400 - Bad Request`           | `{ "status": "Another rebalance job is already running with jobId <id>. ..." }` | 单作业约束：已有另一个重新平衡作业正在运行。                                                                                                                         |
| `400 - Bad Request`           | `{ "status": "Job not run as no changes in cluster member are detected" }`      | 当前哈希环与暂存哈希环完全相同（没有加入或离开的工作节点）。                                                                                                                 |
| `500 - Internal Server Error` | `{ "status": "<exception>" }`                                                   | 意外的服务器错误。                                                                                                                                      |

**数据来源。** `loadSource` 决定每个接收工作节点从何处读取重新平衡文件的字节数据。两种取值下的文件列表、元数据发现和作业编排完全相同——仅数据来源不同。

* `PEER`（默认）：接收方通过工作节点间数据通路从对等工作节点拉取已缓存的页面。
* `UFS`：接收方直接从 UFS 读取文件数据。当列表中的某个文件无法从 UFS 加载时，它会被**跳过**（而非失败），并在 verbose 模式的 `unitsSkippedPerPeer` 直方图中给出跳过原因：`not_found_in_ufs`（UFS 已挂载但文件不再存在）或 `ufs_not_mounted`（该文件的 UFS 未挂载到接收方）。

{% hint style="warning" %}
使用 `loadSource=UFS` 时，已有工作节点继续提供其此前缓存的版本，而新加入的工作节点从 UFS 加载当前版本。对于在 UFS 中发生变更的文件，这可能导致环上各副本不一致。仅在 UFS 文件不可变，或已配置缓存过滤 / 过时策略时才启用此选项。
{% endhint %}

#### 获取重新平衡作业状态

**方法：** `GET`

**路径：** `/api/v1/rebalance-v2`

**参数：**

| 名称        | 描述                                                                                                                                    |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `jobId`   | \[必需] POST 返回的作业 ID。                                                                                                                  |
| `verbose` | \[可选] 若为 `true`，每个工作节点条目将包含完整的按对等节点细分（计数器、字节总量、跳过原因直方图、近似唯一文件估计）。若为 `false` 或缺省，每个工作节点条目仅携带 `workerId`、`workerRole` 和 `errorMessage`。 |

当作业处于非终止状态时，协调器会轮询每个涉及的工作节点，将其重新归类为 `inProgress` / `succeeded` / `failed`，重新计算聚合总量，并重写 etcd 记录（在终止转换时将其移入 finished 前缀）。回显的 `plan` 反映提交的请求，包括目标哈希环成员和所用参数。

**响应：**

| 状态码                           | 响应体                                                | 描述                                                                                    |
| ----------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `200 - OK`                    | 见下方示例。                                             | 操作成功。`status` 为 `STARTED`、`RUNNING`、`SUCCEEDED`、`FAILED` 之一。每个工作节点条目的形态取决于 `verbose`。 |
| `400 - Bad Request`           | `{ "status": "Required parameters not provided" }` | 缺少 `jobId` 查询参数。                                                                      |
| `404 - Not Found`             | `{ "status": "No job found for the ID: <jobId>" }` | 在运行中或已完成的 etcd 前缀中均未找到给定 `jobId` 的作业。                                                 |
| `500 - Internal Server Error` | `{ "status": "..." }`                              | 意外的服务器错误。                                                                             |

一个成功响应体的示例：

```json
{
  "jobId": "54b88939-de49-46ef-acab-fe489f46d1a0",
  "status": "RUNNING",
  "createdAt": 1700000000000,
  "plan": {
    "targetHashRing": ["worker-a", "worker-b", "worker-c", "worker-d"],
    "addedWorkers": ["worker-d"],
    "removedWorkers": [],
    "skipExistingFiles": false,
    "maxParallelWorkerSessions": 10,
    "maxParallelFilesPerWorker": 4,
    "loadSource": "UFS"
  },
  "progress": {
    "totalUnitsDiscovered": 4,
    "totalUnitsRebalanced": 3,
    "totalUnitsFailed": 1,
    "totalBytesRebalanced": 3072,
    "totalUnitsSkipped": 0
  },
  "workersInProgress": [{
    "workerId": "worker-d",
    "workerRole": "ADDED",
    "errorMessage": ""
  }],
  "workersSucceeded": [],
  "workersFailed": []
}
```

使用 `verbose=true` 时，每个工作节点条目还会额外携带按对等节点的细分，例如 `unitsSkippedPerPeer`（在 `loadSource=UFS` 下可能包含上述 `not_found_in_ufs` 和 `ufs_not_mounted` 原因）：

```json
{
  "workerId": "worker-d",
  "workerRole": "ADDED",
  "errorMessage": "",
  "lastUpdateTimestampMs": 1700000001234,
  "unitsDiscoveredPerPeer": { "worker-a": 2, "worker-b": 1 },
  "unitsRebalancedPerPeer": { "worker-a": 2, "worker-b": 0 },
  "unitsFailedPerPeer":     { "worker-a": 0, "worker-b": 0 },
  "bytesRebalancedPerPeer": { "worker-a": 2048, "worker-b": 0 },
  "unitsSkippedPerPeer": {
    "worker-b": { "not_found_in_ufs": 1 }
  },
  "approximateUniqueFilesDiscovered": 3,
  "approximateUniqueFilesRebalanced": 2
}
```

#### 停止正在运行的重新平衡作业

**方法：** `DELETE`

**路径：** `/api/v1/rebalance-v2`

**参数：**

| 名称      | 描述                   |
| ------- | -------------------- |
| `jobId` | \[必需] POST 返回的作业 ID。 |

**请求体：** `Content-Type: application/json`

```json
{
  "jobId": "54b88939-de49-46ef-acab-fe489f46d1a0"
}
```

协调器会将停止信号广播给每个涉及的工作节点；工作节点会协作式终止，下一次 GET 将反映它们的终止状态。

**响应：**

| 状态码                           | 响应体                                                                                                                             | 描述                                |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
| `200 - OK`                    | `{ "jobId": "54b88939-...", "message": "Stop signal sent to workers. It may take some time for the job to be fully stopped." }` | 停止信号已派发给所有涉及的工作节点。                |
| `400 - Bad Request`           | `{ "status": "Only running job can be stopped. Job <jobId> is in status <status>" }`                                            | 作业的持久化状态不是 `STARTED` 或 `RUNNING`。 |
| `404 - Not Found`             | `{ "status": "No job found for the ID: <jobId>" }`                                                                              | 未找到给定 `jobId` 的作业。                |
| `500 - Internal Server Error` | `{ "status": "Failed to stop rebalance job <jobId> on worker <workerId>: <exception>" }`                                        | 至少有一个涉及的工作节点的停止 RPC 失败。           |

### 成员管理

`/membership` 端点管理集群成员关系和版本化一致性哈希环；它们取代了已弃用的 `/nodes` 端点（参见[节点管理](#jie-dian-guan-li)）。有关运维流程，请参阅[缓存重平衡](https://documentation.alluxio.io/ee-ai-cn/cache/cache-rebalancing.md)。

对版本化哈希环进行操作的端点（`GET /membership`、`GET /membership/staging`、`GET /membership/history`、`PUT /membership`、`PATCH /membership/staging`）要求已启用该功能（`alluxio.user.consistent.hash.ring.versioning.enabled=true`）；否则它们返回 `400` 并带有错误码 `VERSIONING_NOT_ENABLED`。`GET /membership/all`、`GET /membership/{workerId}` 和 `DELETE /membership/{workerId}` 不要求启用该功能。

除非另有说明，错误响应共享同一个 JSON 结构（`context` 对象为空时省略）：

```json
{
  "error": "WORKER_NOT_FOUND",
  "message": "human-readable detail",
  "context": { "workers": ["worker-id-1"] }
}
```

列表端点返回的 `fingerprint` 字段是对成员身份集合计算的 sha256（`sha256:<hex>`）；它是乐观并发令牌，在 `operation=commit` 时作为 `expectedFingerprint` 回传。该字段始终存在（哈希环未初始化时返回空集合对应的值）。

#### 初始化或修复哈希环

**方法：** `PUT`

**路径：** `/api/v1/membership`

**请求体：** `Content-Type: application/json`

```json
{
  "workerIds": ["worker-id-1", "worker-id-2"]
}
```

| 字段          | 类型        | 必填 | 描述                           |
| ----------- | --------- | -- | ---------------------------- |
| `workerIds` | string\[] | 是  | 用于初始化哈希环的、已注册的工作节点 ID 的非空列表。 |

无状态的 operator 可以安全地反复 PUT 此端点：

* **未初始化的哈希环** → 完成初始化 → `200`，`result=SUCCESS`。
* **已完全初始化的哈希环** → 若当前工作节点与输入匹配，返回 `200`，`result=ALREADY_INITIALIZED`（健康的哈希环永不会被覆盖）；若集合不同则返回 `409`。
* **部分初始化的哈希环**（例如引导过程中崩溃）→ 依请求修复 → `200`，`result=REPAIRED`。

该写入受准备请求时观察到的哈希环字段修订版本保护，因此并发修改会以 `409 CAS_CONFLICT` 形式暴露，而不会覆盖数据。该事务保护的键集合固定，与工作节点数量无关，因此初始化大型集群不受 etcd 单事务操作数上限的限制。

**响应：**

```json
{
  "result": "SUCCESS",
  "currentMembers": ["worker-id-1", "worker-id-2"]
}
```

| 字段               | 类型        | 描述                                                                               |
| ---------------- | --------- | -------------------------------------------------------------------------------- |
| `result`         | string    | `SUCCESS`（全新初始化）、`ALREADY_INITIALIZED`（在相同哈希环上的幂等空操作）、`REPAIRED`（修复了部分初始化的哈希环）之一 |
| `currentMembers` | string\[] | 哈希环被初始化/修复所用的工作节点 ID；当 `ALREADY_INITIALIZED` 时为现有的已提交成员                          |

| 状态码                           | 响应体（`error` 代码）            | 描述                                               |
| ----------------------------- | -------------------------- | ------------------------------------------------ |
| `400 - Bad Request`           | `VERSIONING_NOT_ENABLED`   | 未启用版本化哈希环                                        |
| `400 - Bad Request`           | `INVALID_ARGUMENT`         | 缺少请求体、`workerIds` 缺失/为空，或某个工作节点 ID 格式非法          |
| `400 - Bad Request`           | `WORKER_NOT_FOUND`         | 一个或多个请求的工作节点未注册（相关 ID 见 `context.workers`）       |
| `409 - Conflict`              | `RING_ALREADY_INITIALIZED` | 哈希环已用不同的工作节点集合初始化（现有集合见 `context.actualMembers`） |
| `409 - Conflict`              | `CAS_CONFLICT`             | 哈希环被并发修改；请重试                                     |
| `500 - Internal Server Error` | `INTERNAL`                 | 意外的服务器错误                                         |

#### 列出已提交成员

**方法：** `GET`

**路径：** `/api/v1/membership`

**参数：** 无

**响应：**

```json
{
  "initialized": true,
  "members": [
    {
      "workerId": "worker-00000000-0000-0000-0000-000000000001",
      "address": "worker-host-1:29999",
      "status": "ONLINE",
      "capacityBytes": 107374182400,
      "usedBytes": 53687091200,
      "nodeLabel": "zone-a"
    }
  ],
  "fingerprint": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
}
```

| 字段            | 类型        | 描述                               |
| ------------- | --------- | -------------------------------- |
| `initialized` | boolean   | 哈希环是否已初始化                        |
| `members`     | object\[] | 以工作节点详情对象表示的已提交成员（字段见下）。若未初始化则为空 |
| `fingerprint` | string    | 已提交成员集合的内容寻址指纹；始终存在              |

工作节点详情对象字段：

| 字段              | 类型     | 描述                                                        |
| --------------- | ------ | --------------------------------------------------------- |
| `workerId`      | string | 工作节点的唯一标识                                                 |
| `address`       | string | 工作节点的 `host:rpcPort`                                      |
| `status`        | string | 工作节点当前存活时为 `ONLINE`，否则为 `OFFLINE`（对于没有注册记录的成员为 `UNKNOWN`） |
| `capacityBytes` | number | 总存储容量（字节）                                                 |
| `usedBytes`     | number | 已用存储（字节）                                                  |
| `nodeLabel`     | string | 分配给工作节点的节点标签                                              |

| 状态码                           | 响应体（`error` 代码）          | 描述            |
| ----------------------------- | ------------------------ | ------------- |
| `400 - Bad Request`           | `VERSIONING_NOT_ENABLED` | 未启用版本化哈希环     |
| `500 - Internal Server Error` | `INTERNAL`               | 检索成员状态时发生意外错误 |

#### 列出所有已注册成员

**方法：** `GET`

**路径：** `/api/v1/membership/all`

**参数：** 无

返回工作节点详情对象数组（字段同 **列出已提交成员**）。仅当启用版本化哈希环时才包含 `inCurrent` 和 `inStaging`，否则省略。

**响应：**

```json
[
  {
    "workerId": "worker-00000000-0000-0000-0000-000000000001",
    "address": "worker-host-1:29999",
    "status": "ONLINE",
    "capacityBytes": 107374182400,
    "usedBytes": 53687091200,
    "nodeLabel": "zone-a",
    "inCurrent": true,
    "inStaging": false
  }
]
```

| 字段          | 类型      | 描述                             |
| ----------- | ------- | ------------------------------ |
| `inCurrent` | boolean | 工作节点是否在当前（已提交）哈希环中（版本化功能禁用时省略） |
| `inStaging` | boolean | 工作节点是否在暂存哈希环中（版本化功能禁用时省略）      |

| 状态码                           | 响应体（`error` 代码） | 描述              |
| ----------------------------- | --------------- | --------------- |
| `500 - Internal Server Error` | `INTERNAL`      | 检索工作节点列表时发生意外错误 |

#### 获取工作节点详情

**方法：** `GET`

**路径：** `/api/v1/membership/{workerId}`

**路径参数：**

| 名称         | 描述                           |
| ---------- | ---------------------------- |
| `workerId` | 工作节点 ID，匹配模式 `worker-[\w-]+` |

字段说明见 **列出已提交成员**。仅当启用版本化功能时才包含 `inCurrent` 和 `inStaging`。

**响应：**

```json
{
  "workerId": "worker-00000000-0000-0000-0000-000000000001",
  "address": "worker-host-1:29999",
  "status": "ONLINE",
  "capacityBytes": 107374182400,
  "usedBytes": 53687091200,
  "nodeLabel": "zone-a",
  "inCurrent": true,
  "inStaging": false
}
```

| 状态码                           | 响应体（`error` 代码）    | 描述                         |
| ----------------------------- | ------------------ | -------------------------- |
| `400 - Bad Request`           | `INVALID_ARGUMENT` | 提供的 `workerId` 不是有效的工作节点标识 |
| `404 - Not Found`             | `WORKER_NOT_FOUND` | 不存在给定 ID 的已注册工作节点          |
| `500 - Internal Server Error` | `INTERNAL`         | 意外的服务器错误                   |

#### 列出暂存成员

**方法：** `GET`

**路径：** `/api/v1/membership/staging`

**参数：** 无

**响应：**

```json
{
  "initialized": true,
  "members": [ { "workerId": "worker-...-000000000001", "address": "worker-host-1:29999", "status": "ONLINE", "capacityBytes": 107374182400, "usedBytes": 53687091200, "nodeLabel": "zone-a" } ],
  "diff": {
    "joining": ["worker-00000000-0000-0000-0000-000000000003"],
    "leaving": []
  },
  "fingerprint": "sha256:..."
}
```

当暂存哈希环尚未初始化时，`initialized` 为 `false`，`members` 为空，`diff` 省略，`fingerprint` 为空集合对应的值。

| 字段             | 类型        | 描述                                        |
| -------------- | --------- | ----------------------------------------- |
| `initialized`  | boolean   | 是否存在暂存哈希环                                 |
| `members`      | object\[] | 以工作节点详情对象表示的暂存成员。若未初始化则为空                 |
| `diff.joining` | string\[] | 存在于暂存环但不在当前环中的工作节点（提交时将被加入）               |
| `diff.leaving` | string\[] | 存在于当前环但不在暂存环中的工作节点（提交时将被移除）               |
| `fingerprint`  | string    | 暂存成员集合的指纹；提交时回传的 `expectedFingerprint` 令牌 |

| 状态码                           | 响应体（`error` 代码）          | 描述        |
| ----------------------------- | ------------------------ | --------- |
| `400 - Bad Request`           | `VERSIONING_NOT_ENABLED` | 未启用版本化哈希环 |
| `500 - Internal Server Error` | `INTERNAL`               | 意外的服务器错误  |

#### 更新暂存环

修改暂存哈希环。支持三种操作：`add` 和 `remove`（原子、幂等的批量编辑）以及 `commit`（将暂存环提升为当前环，由指纹保护）。

**方法：** `PATCH`

**路径：** `/api/v1/membership/staging`

**请求体：** `Content-Type: application/json`

```json
{
  "operation": "add",
  "workerIds": ["worker-00000000-0000-0000-0000-000000000003"]
}
```

```json
{
  "operation": "commit",
  "expectedFingerprint": "sha256:..."
}
```

| 字段                    | 类型        | 必填  | 描述                                                                                                 |
| --------------------- | --------- | --- | -------------------------------------------------------------------------------------------------- |
| `operation`           | string    | 是   | `add`、`remove`、`commit` 之一                                                                         |
| `workerIds`           | string\[] | 视情况 | `add` 和 `remove` 时必需。`add` 时每个必须已注册。已在暂存中（`add`）或已不存在（`remove`）的工作节点将被幂等吸收。在单个原子事务中应用。`commit` 时忽略 |
| `expectedFingerprint` | string    | 视情况 | `commit` 时必需。取自先前 `GET /membership/staging` 读取的 `fingerprint`；若暂存环自那以后发生变化，则拒绝提交                   |

**响应：**

```json
{
  "status": "SUCCESS",
  "staging": [
    "worker-00000000-0000-0000-0000-000000000001",
    "worker-00000000-0000-0000-0000-000000000002"
  ],
  "fingerprint": "sha256:..."
}
```

| 字段            | 类型        | 描述                                                                         |
| ------------- | --------- | -------------------------------------------------------------------------- |
| `status`      | string    | `add` / `remove` 为 `SUCCESS`；`commit` 为 `SUCCESS` 或 `NOTHING_TO_COMMIT` 之一 |
| `staging`     | string\[] | 操作后暂存环中工作节点 ID 的更新列表                                                       |
| `fingerprint` | string    | 操作后暂存环的指纹                                                                  |

| 状态码                           | 响应体（`error` 代码）          | 描述                                                                    |
| ----------------------------- | ------------------------ | --------------------------------------------------------------------- |
| `400 - Bad Request`           | `VERSIONING_NOT_ENABLED` | 未启用版本化哈希环                                                             |
| `400 - Bad Request`           | `INVALID_ARGUMENT`       | 缺少请求体、`operation` 缺失/非法、`add`/`remove` 缺少 `workerIds`，或某个工作节点 ID 格式非法 |
| `400 - Bad Request`           | `MISSING_FINGERPRINT`    | `commit` 操作缺少 `expectedFingerprint`                                   |
| `400 - Bad Request`           | `WORKER_NOT_FOUND`       | `add` 引用了未注册的工作节点，或 `commit` 时发现某个暂存工作节点的注册记录已被并发清除                   |
| `409 - Conflict`              | `FINGERPRINT_MISMATCH`   | `commit` 时的 `expectedFingerprint` 与当前暂存环不匹配                           |
| `409 - Conflict`              | `CAS_CONFLICT`           | 暂存环被并发修改；请重试                                                          |
| `503 - Service Unavailable`   | `ETCD_UNAVAILABLE`       | 无法连接 etcd                                                             |
| `500 - Internal Server Error` | `INTERNAL`               | 意外的服务器错误                                                              |

#### 获取哈希环变更历史

**方法：** `GET`

**路径：** `/api/v1/membership/history`

**参数：** 无

返回历史条目数组（每一项为一个过去的哈希环版本及其生效截止时间戳），若无历史则返回空数组。

**响应：**

```json
[
  {
    "effectiveUntil": 1748822400000,
    "members": ["worker-00000000-0000-0000-0000-000000000001"]
  },
  {
    "effectiveUntil": 1748908800000,
    "members": [
      "worker-00000000-0000-0000-0000-000000000001",
      "worker-00000000-0000-0000-0000-000000000002"
    ]
  }
]
```

| 字段               | 类型        | 描述                       |
| ---------------- | --------- | ------------------------ |
| `effectiveUntil` | number    | 此哈希环版本被取代时的 Unix 时间戳（毫秒） |
| `members`        | string\[] | 在此期间构成哈希环的工作节点 ID        |

| 状态码                           | 响应体（`error` 代码）          | 描述        |
| ----------------------------- | ------------------------ | --------- |
| `400 - Bad Request`           | `VERSIONING_NOT_ENABLED` | 未启用版本化哈希环 |
| `500 - Internal Server Error` | `INTERNAL`               | 意外的服务器错误  |

#### 永久清除工作节点

从成员存储中清除某个工作节点的注册记录（永久删除该工作节点在 etcd 中的条目）。

**前置条件。** 仅当以下两者同时成立时，工作节点才可被清除：

1. 工作节点处于 `OFFLINE` 状态——仍在心跳的工作节点不能被清除；请先停止该工作节点进程。
2. 当启用版本化哈希环时，哈希环必须已初始化，且该工作节点必须处于未绑定状态——**不**被当前或暂存成员列表引用。

前置条件不满足会导致 `409 Conflict`。该端点是幂等的：清除一个没有注册记录的工作节点会返回 `200 OK`，因此 operator 的对账循环可以安全重试。

**方法：** `DELETE`

**路径：** `/api/v1/membership/{workerId}`

**路径参数：**

| 名称         | 描述                           |
| ---------- | ---------------------------- |
| `workerId` | 工作节点 ID，匹配模式 `worker-[\w-]+` |

**响应：**

```json
{
  "status": "ok"
}
```

| 状态码                           | 响应体（`error` 代码）          | 描述                              |
| ----------------------------- | ------------------------ | ------------------------------- |
| `400 - Bad Request`           | `INVALID_ARGUMENT`       | 路径参数 `workerId` 不是可解析的工作节点标识    |
| `409 - Conflict`              | `WORKER_STILL_LIVE`      | 工作节点不处于 `OFFLINE` 状态（仍在心跳 / 在线） |
| `409 - Conflict`              | `WORKER_IN_CURRENT_RING` | 已启用版本化功能且该工作节点仍被当前哈希环引用         |
| `409 - Conflict`              | `WORKER_IN_STAGING_RING` | 已启用版本化功能且该工作节点仍被暂存哈希环引用         |
| `409 - Conflict`              | `RING_NOT_INITIALIZED`   | 已启用版本化功能但 etcd 中缺少当前/暂存成员列表     |
| `503 - Service Unavailable`   | `ETCD_UNAVAILABLE`       | 无法连接 etcd                       |
| `500 - Internal Server Error` | `INTERNAL`               | 意外的服务器错误                        |

### 清理过时缓存

> 此操作与[释放缓存](#shi-fang-huan-cun)操作的不同之处在于：
>
> 1. 释放作业需要一个文件或目录列表作为输入参数，以指定要从工作节点中释放的内容。清理过时缓存操作不需要此类输入，因为“过时缓存”是通过扫描工作节点缓存存储并查询当前的一致性哈希环来自动确定的。
> 2. 释放作业需要设置正确的副本数，否则如果启用了文件复制，它可能会释放比预期少的副本。清理过时缓存操作只是向集群中的所有工作节点广播，因此它总是触发所有工作节点上的过时缓存清理，无论有多少副本。

`op` 字段用于选择模式：`clear-stale` 删除过时数据，而 `scan-stale` 仅测量过时数据 —— 每个工作节点记录其持有的过时字节数，但不删除任何数据。

#### 开始清理过时缓存

**方法：** `POST`

**路径：** `/api/v1/cache`

**参数：** 无

**请求体：** `Content-Type: application/json`

```json
{
  "op": "clear-stale"
}
```

**响应：**

* `200 - OK`：一个空的错误对象表示操作已成功提交给所有工作节点执行

  ```json
  {
    "errors": {}
  }
  ```
* `200 - OK`：非空的错误对象表示操作未能提交给至少一个工作节点执行

  ```json
  {
    "errors": {
      "worker-host": "error message"
    }
  }
  ```
* `400 - Bad Request`：请求没有正文或缺少必需字段

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `500 - Internal Server Error`：意外错误

  ```json
  {
    "status": "string"
  }
  ```
* `501 - Not Implemented`：指定的操作类型未实现

  ```json
  {
    "status": "OP not implemented"
  }
  ```

#### 停止清理过时缓存

**方法：** `DELETE`

**路径：** `/api/v1/cache`

**参数：** 无

**请求体：** `Content-Type: application/json`

```json
{
  "op": "clear-stale"
}
```

**响应：**

* `200 - OK`：一个空的错误对象表示所有工作节点都已成功收到停止清理过时缓存的通知

  ```json
  {
    "errors": {}
  }
  ```
* `200 - OK`：非空的错误对象表示Coordinator未能通知至少一个工作节点停止清理过时缓存

  ```json
  {
    "errors": {
      "worker-host": "error message"
    }
  }
  ```
* `400 - Bad Request`：请求没有正文或缺少必需字段

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `500 - Internal Server Error`：意外错误

  ```json
  {
    "status": "string"
  }
  ```
* `501 - Not Implemented`：指定的操作类型未实现

  ```json
  {
    "status": "OP not implemented"
  }
  ```

#### 扫描过时缓存而不删除

使用 `scan-stale` 在不删除任何数据的情况下测量过时缓存。每个工作节点扫描其本地存储并记录摘要（`Stale cache scan finished: scanned <N> files, found <N> stale bytes, removed <N> bytes`）；不删除任何数据。其方法、路径和响应与上述清理过时缓存操作完全相同 —— 仅 `op` 值不同。

**开始扫描** —— `POST` `/api/v1/cache`：

```json
{
  "op": "scan-stale"
}
```

**停止扫描** —— `DELETE` `/api/v1/cache`：

```json
{
  "op": "scan-stale"
}
```

### 挂载表

#### 列出挂载点

**方法：** `GET`

**路径：** `/api/v1/mount`

**参数：** 无

**响应：**

* `200 - OK`：操作成功（如果为空，将省略选项）

  ```json
  {
    "results": [
      {
        "path": "/data/",
        "ufs": "s3://my-bucket/",
        "options": {
          "s3a.secretKey": "string",
          "s3a.accessKeyId": "string"
        }
      }
    ]
  }
  ```
* `500 - Internal Server Error`：意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 获取挂载点信息

**方法：** `GET`

**路径：** `/api/v1/mount`

**参数：**

| **名称** | **描述**          |
| ------ | --------------- |
| `path` | 挂载点的 alluxio 路径 |

**响应：**

* `200 - OK`：操作成功（如果为空，将省略选项）

  ```json
  {
    "path": "/data/",
    "ufs": "s3://my-bucket/",
    "options": {
      "s3a.secretKey": "string",
      "s3a.accessKeyId": "string"
    }
  }
  ```
* `404 - Not Found`：未找到挂载点

  ```json
  {
    "status": "No mount point found for path: /data/"
  }
  ```
* `500 - Internal Server Error`：意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 创建挂载点

**方法：** `POST`

**路径：** `/api/v1/mount`

**参数：** 无

**请求体：** `Content-Type: application/json`

```json
{
  "path": "/data",
  "ufs": "s3://my-bucket",
  "options": {
    "s3a.secretKey": "string",
    "s3a.accessKeyId": "string"
  }
}
```

**响应：**

* `200 - OK`：操作成功

  ```json
  {
    "status": "ok"
  }
  ```
* `400 - Bad Request`：请求没有正文或缺少必需字段

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `409 - Conflict`：该路径已挂载，或 UFS 已挂载到另一个路径

  ```json
  {
    "status": "string"
  }
  ```
* `501 - Not Implemented`：挂载表不支持通过 API 进行管理（例如：静态文件挂载表）

  ```json
  {
    "status": "string"
  }
  ```
* `500 - Internal Server Error`：意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 删除挂载点

**方法：** `DELETE`

**路径：** `/api/v1/mount`

**参数：** 无

**请求体：** `Content-Type: application/json`

```json
{
  "path": "/data"
}
```

**响应：**

* `200 - OK`：操作成功

  ```json
  {
    "status": "ok"
  }
  ```
* `400 - Bad Request`：请求没有正文或缺少必需字段

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `410 - Gone`：该路径未挂载到任何 UFS

  ```json
  {
    "status": "string"
  }
  ```
* `501 - Not Implemented`：挂载表不支持通过 API 进行管理（例如：静态文件挂载表）

  ```json
  {
    "status": "string"
  }
  ```
* `500 - Internal Server Error`：意外错误

  ```json
  {
    "status": "string"
  }
  ```

### 配额

#### 列出所有配额状态

**方法：** `GET`

**路径：** `/api/v1/quota`

**参数：** 无

**响应：**

* `200 - OK`：操作成功

  ```json
  {
    "results": [
      {
        "path": "/data/dir/to/path",
        "state": "Available",
        "quotaBytes": 10737418240,
        "usedBytes": 9663676416,
        "reservedBytes": 1073741824
      }
    ]
  }
  ```
* `501 - Not Implemented`：未启用配额

  ```json
  {
    "status": "Quota not enabled"
  }
  ```
* `500 - Internal Server Error`：意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 获取配额状态

**方法：** `GET`

**路径：** `/api/v1/quota`

**参数：**

| **名称** | **描述**         |
| ------ | -------------- |
| `path` | 数据的 alluxio 路径 |

**响应：**

* `200 - OK`：操作成功

  ```json
  {
    "path": "/data/dir/to/path",
    "state": "Available",
    "quotaBytes": 10737418240,
    "usedBytes": 9663676416,
    "reservedBytes": 1073741824
  }
  ```
* `404 - Not Found`: 未找到配额

  ```json
  {
    "status": "No quota item found for path: /data/dir/to/path"
  }
  ```
* `501 - Not Implemented`: 未启用配额

  ```json
  {
    "status": "Quota not enabled"
  }
  ```
* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 添加或更新配额

**方法:** `POST`

**路径:** `/api/v1/quota`

**参数:** 无

**请求体:** `Content-Type: application/json`

```json
{
  "path": "/data/dir/to/path",
  "quotaBytes": 10737418240
}
```

**响应:**

* `200 - OK`: 操作成功

  ```json
  {
    "status": "ok"
  }
  ```
* `400 - Bad Request`: 请求没有正文或缺少必需字段

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `400 - Bad Request`: 该路径未指向已挂载的 UFS，但必须与现有的 UFS绑定

  ```json
  {
    "status": "No mounted UFS found"
  }
  ```
* `501 - Not Implemented`: 未启用配额

  ```json
  {
    "status": "Quota not enabled"
  }
  ```
* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 删除配额

**方法:** `DELETE`

**路径:** `/api/v1/quota`

**参数:** 无

**请求体:** `Content-Type: application/json`

```json
{
  "path": "/data/dir/to/path"
}
```

**响应:**

* `200 - OK`: 操作成功

  ```json
  {
    "status": "ok"
  }
  ```
* `400 - Bad Request`: ：请求没有正文或缺少必填字段

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `400 - Bad Request`: 未找到配额或其他问题

  ```json
  {
    "status": "string"
  }
  ```
* `501 - Not Implemented`: 未启用配额

  ```json
  {
    "status": "Quota not enabled"
  }
  ```
* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```

### TTL

#### 列出所有 TTL 策略

**方法:** `GET`

**路径:** `/api/v1/ttl`

**参数:** 无

**响应:**

* `200 - OK`: 操作成功

  ```json
   {
    "results": [
      {
        "path": "/data/dir/to/path",
        "ttlSeconds": 600
      }
    ]
  }
  ```
* `501 - Not Implemented`: 未启用TTL 策略

  ```json
  {
    "status": "TTL not enabled"
  }
  ```
* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 获取 TTL 策略

**方法:** `GET`

**路径:** `/api/v1/ttl`

**参数:**

| **名称** | **描述**         |
| ------ | -------------- |
| `path` | 数据的 alluxio 路径 |

**响应:**

* `200 - OK`: 操作成功

  ```json
  {
    "path": "/data/dir/to/path",
    "ttlSeconds": 600
  }
  ```
* `404 - Not Found`: 未找到TTL

  ```json
  {
    "status": "No TTL policy found for path: /data/dir/to/path"
  }
  ```
* `501 - Not Implemented`: 未启用TTL 策略

  ```json
  {
    "status": "TTL not enabled"
  }
  ```
* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 添加或更新 TTL

**方法:** `POST`

**路径:** `/api/v1/ttl`

**参数:** 无

**请求体:** `Content-Type: application/json`

```json
{
  "path": "/data/dir/to/path",
  "ttlSeconds": 600
}
```

**响应:**

* `200 - OK`: 操作成功

  ```json
  {
    "status": "ok"
  }
  ```
* `400 - Bad Request`: 请求没有正文或缺少必填字段

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `400 - Bad Request`: 路径未指向已挂载的 UFS，但必须与现有的 UFS绑定

  ```json
  {
    "status": "No mounted UFS found"
  }
  ```
* `501 - Not Implemented`: 未启用 TTL 策略

  ```json
  {
    "status": "TTL not enabled"
  }
  ```
* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 删除 TTL

**方法:** `DELETE`

**路径:** `/api/v1/ttl`

**参数:** 无

**请求体:** `Content-Type: application/json`

```json
{
  "path": "/data/dir/to/path"
}
```

**响应:**

* `200 - OK`: 操作成功

  ```json
  {
    "status": "ok"
  }
  ```
* `400 - Bad Request`: 请求没有正文或缺少必填字段

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `400 - Bad Request`: 未找到TTL

  ```json
  {
    "status": "string"
  }
  ```
* `501 - Not Implemented`: 未启用 TTL 策略

  ```json
  {
    "status": "TTL not enabled"
  }
  ```
* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```

### 优先级驱逐

#### 列出所有优先级驱逐策略

**方法:** `GET`

**路径:** `/api/v1/priority`

**参数:** 无

**响应:**

* `200 - OK`: 操作成功

  ```json
  {
    "results": [
      {
        "path": "/data/dir/to/path",
        "priority": "high"
      }
    ]
  }
  ```
* `501 - Not Implemented`: 未启用优先级驱逐

  ```json
  {
    "status": "Priority eviction not enabled"
  }
  ```
* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 获取优先级驱逐策略

**方法:** `GET`

**路径:** `/api/v1/priority`

**参数:**

| **名称** | **描述**         |
| ------ | -------------- |
| `path` | 数据的 alluxio 路径 |

**响应:**

* `200 - OK`: 操作成功

  ```json
  {
    "path": "/data/dir/to/path",
    "priority": "high"
  }
  ```
* `404 - Not Found`: 未找到优先级驱逐策略

  ```json
  {
    "status": "No priority rule found for path: /data/dir/to/path"
  }
  ```
* `501 - Not Implemented`: 未启用优先级驱逐

  ```json
  {
    "status": "Priority eviction not enabled"
  }
  ```
* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 添加或更新优先级

**方法:** `POST`

**路径:** `/api/v1/priority`

**参数:** 无

**请求体:** `Content-Type: application/json`

```json
{
  "path": "/data/dir/to/path",
  "priority": "high"
}
```

**响应:**

* `200 - OK`: 操作成功

  ```json
  {
    "status": "ok"
  }
  ```
* `400 - Bad Request`: 请求没有正文或缺少必填字段

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `400 - Bad Request`: 优先级字符串格式错误或存在其他问题

  ```json
  {
    "status": "string"
  }
  ```
* `501 - Not Implemented`: 未启用优先级驱逐

  ```json
  {
    "status": "Priority eviction not enabled"
  }
  ```
* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 删除优先级策略

**方法:** `DELETE`

**路径:** `/api/v1/priority`

**参数:** 无

**请求体:** `Content-Type: application/json`

```json
{
  "path": "/data/dir/to/path"
}
```

**响应:**

* `200 - OK`: 操作成功

  ```json
  {
    "status": "ok"
  }
  ```
* `400 - Bad Request`: 请求没有正文或缺少必填字段

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `501 - Not Implemented`: 未启用优先级驱逐

  ```json
  {
    "status": "Priority eviction not enabled"
  }
  ```
* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```

### 节点管理

#### 列出所有节点

**方法:** `GET`

**路径:** `/api/v1/nodes`

**参数:** 无

**响应:**

* `200 - OK`: 操作成功

  ```json
  {
    "result": [
      {
        "identity": "worker-587899dd-5da5-45d4-af40-ce481acc4087",
        "address": "192.168.1.19:29989",
        "status": "ONLINE"
      },
      {
        "identity": "worker-844db66c-d7fd-46cc-8de0-2f3989360828",
        "address": "192.168.1.19:29999",
        "status": "OFFLINE"
      }
    ]
  }
  ```
* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 查询节点

**方法:** `GET`

**路径:** `/api/v1/nodes`

**参数:**

| **名称** | **描述**                                                       |
| ------ | ------------------------------------------------------------ |
| `id`   | worker id (e.g. worker-587899dd-5da5-45d4-af40-ce481acc4087) |

**响应:**

* `200 - OK`: 操作成功\
  (空值将被省略)

  ```json
  {
    "identity": "worker-587899dd-5da5-45d4-af40-ce481acc4087",
    "address": "192.168.1.19:29989",
    "status": "ONLINE"
  }
  ```
* `404 - Not Found`: 未找到worker

  ```json
  {
    "status": "worker not found..."
  }
  ```
* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 注销节点（从 etcd 中移除节点）

**方法:** `DELETE`

**路径:** `/api/v1/nodes`

**参数:**

| **名称** | **描述**                                                       |
| ------ | ------------------------------------------------------------ |
| `id`   | worker id (e.g. worker-587899dd-5da5-45d4-af40-ce481acc4087) |

**响应:**

* `200 - OK`: 操作成功

  ```json
  {
    "status": "ok"
  }
  ```
* `404 - Not Found`: 未找到worker

  ```json
  {
    "status": "worker not found..."
  }
  ```
* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```

### 全局文件索引

#### 列出所有节点

**方法:** `GET`

**路径:** `/api/v1/file_index`

**参数:** 无

**响应:**

* `200 - OK`: 操作成功

  ```json
  {
    "results": [
      "file:///home/yimin/alluxio/ufs/10MB",
      "file:///home/yimin/alluxio/ufs/to_load/f1"
    ]
  }
  ```
* `500 - Internal Server Error`:意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 将文件添加到全局文件索引

**方法:** `POST`

**路径:** `/api/v1/file_index`

**参数:** 无

**请求体:** `Content-Type: application/json`

```json
{
  "files": [
    "s3://foo/bar/f1",
    "s3://foo/bar/f2"
  ]
}
```

**响应:**

* `200 - OK`: 操作成功（已添加条目数）

  ```json
  {
    "entries": 10
  }
  ```
* `404 - Not Found`: 功能未启用

  ```json
  {
    "status": "Global file index is not enabled"
  }
  ```
* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 从全局文件索引中移除文件

**方法:** `DELETE`

**路径:** `/api/v1/file_index`

**参数:** 无

**请求体:** `Content-Type: application/json`

```json
{
  "files": [
    "s3://foo/bar/f1",
    "s3://foo/bar/f2"
  ]
}
```

**响应:**

* `200 - OK`: 操作成功（已移除条目数）

  ```json
  {
    "entries": 10
  }
  ```
* `404 - Not Found`: 功能未启用

  ```json
  {
    "status": "worker not found..."
  }
  ```
* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```

### 缓存过滤

#### 列出所有缓存过滤规则

**方法:** `GET`

**路径:** `/api/v1/cache-filter`

**参数:** 无

**响应:**

* `200 - OK`: 操作成功

```json
{
  "results": [
    {
      "apiVersion": 1,
      "type": "metadata",
      "rules": {
        "defaultType": "immutable",
        "defaultMaxAge": null,
        "skipCache": ["s3://bucket/mutable-dir/.*"],
        "immutable": ["s3://bucket/immutable-dir/.*"],
        "maxAge": {"s3://bucket/auto-refresh/.*":  "1d"}
      }
    },
    {
      "apiVersion": 1,
      "type": "data",
      "rules": {
        "defaultType": "immutable",
        "defaultMaxAge": null,
        "skipCache": [],
        "immutable": [],
        "maxAge": {}
      }
    }
  ]
}
```

* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```
* `501 - Not Implemented`: 未启用缓存过滤

  ```json
  {
    "status": "Cache filter not enabled"
  }
  ```

#### 添加缓存过滤规则或更新默认规则

**方法:** `POST`

**路径:** `/api/v1/cache-filter`

**参数:** 无

**请求体:** `Content-Type: application/json`

```json
{
  "type": "data",
  "rule": "skipCache",
  "pattern": "s3a://data-bucket/c/.*"
}
```

如果规则是 `maxAge`, 则需要指定 `time` 。

```json
{
  "type": "data",
  "rule": "maxAge",
  "pattern": "s3a://auto-refresh/c/.*",
  "time": "1d"
}
```

如果要更新默认规则，请设置 `updateDefault`。无需指定 `pattern` ，因为所有未匹配其他规则的路径都将由默认规则捕获。

```json
{
  "type": "metadata",
  "rule": "skipCache",
  "updateDefault": true
}
```

**响应:**

* `200 - OK`: 操作成功
* `400 - Bad Request`: 请求没有正文或缺少必填字段

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```
* `501 - Not Implemented`: 未启用缓存过滤

  ```json
  {
    "status": "Cache filter not enabled"
  }
  ```

#### 移除缓存过滤规则

**方法:** `DELETE`

**路径:** `/api/v1/cache-filter`

**参数:** 无

**请求体:** `Content-Type: application/json`

```json
{
  "type": "data",
  "rule": "skipCache",
  "pattern": "s3a://data-bucket/c/.*"
}
```

如果规则是`maxAge`.，无需指定`time`。此外，默认规则无法删除，只能将默认规则更改为其他规则。

**响应:**

* `200 - OK`: 操作成功
* `400 - Bad Request`: 请求没有正文或缺少必填字段

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```
* `501 - Not Implemented`: 未启用缓存过滤

  ```json
  {
    "status": "Cache filter not enabled"
  }
  ```

### Cache Insight

查看哪些数据被缓存、缓存在哪里，以及底层存储与缓存是否一致。一次扫描是对底层存储列表和 worker 缓存元数据的实时只读遍历；它不会阻塞应用的读写，不会将数据加载到缓存中，也不会修改任何缓存状态。

由于扫描期间集群仍在正常提供服务，结果为近似值——文件可能在扫描进行中被缓存、驱逐、写入或删除。

功能指南参见 [缓存洞察](https://documentation.alluxio.io/ee-ai-cn/cache/cache-insight.md)。

#### 接口一览

| **方法** | **路径**                          | **成功响应**                   | **用途**                        |
| ------ | ------------------------------- | -------------------------- | ----------------------------- |
| POST   | /api/v1/cache-insight           | 200 `application/x-ndjson` | 执行扫描并流式返回结果                   |
| GET    | /api/v1/cache-insight/workers   | 200 `application/json`     | 列出可用于 `workers` 选择器的存活 worker |
| GET    | /api/v1/cache-insight/jobs      | 200 `application/json`     | 列出正在运行的扫描                     |
| GET    | /api/v1/cache-insight/jobs/{id} | 200 `application/json`     | 查询单个正在运行的扫描                   |
| DELETE | /api/v1/cache-insight/jobs/{id} | 202 `application/json`     | 请求协作式取消                       |

#### 执行扫描

**方法:** `POST`

**路径:** `/api/v1/cache-insight`

**请求体类型:** `Content-Type: application/json`

只有 `groups[].paths` 是必填的，其余字段均使用下表中的默认值。

```json
{
  "groups": [
    {
      "paths": [
        "s3://bucket/manifests/latest.json",
        "s3://bucket/train/**"
      ],
      "limit": 100000
    }
  ],
  "source": "both",
  "detail": "placement",
  "sample": 10,
  "sampleSize": 20,
  "scanRateLimit": 100000,
  "batchSize": 1000,
  "workers": ["10.0.0.12:29999"],
  "job_id": "audit-2026-07-14",
  "progress": false,
  "filters": [
    {"field": "completeness", "op": "==", "value": "incomplete"}
  ],
  "fields": ["ufs_path", "status", "cached_pct", "copies"],
  "maxRecordBytes": 33554432
}
```

**参数**

| **名称**               | **类型** | **默认值**   | **描述**                                                                                                                                                                                                     |
| -------------------- | ------ | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `groups[0].paths`    | array  | 必填        | UFS URI 或 Alluxio 路径。`path` 表示单个文件，`path/*` 表示目录（非递归），`path/**` 表示目录（递归）；不带这两种后缀的路径始终按单个文件查询。最多 10 万个路径。相互重叠的路径会返回 `400` 并列出冲突的路径对。目前只支持一个 group，超过一个返回 `400`                                              |
| `groups[0].name`     | string | 无         | 可选的分组标签。协议上接受，但目前仅作说明用途                                                                                                                                                                                    |
| `groups[0].limit`    | int    | 不限制       | 扫描 N 个文件后停止，并在汇总中标记 `truncated`。不填表示完整扫描                                                                                                                                                                   |
| `source`             | enum   | `ufs`     | `ufs` = 基于候选 worker 的读覆盖率，`worker` = 缓存内容（页面元数据扫描），`both` = 两者联接的一致性审计                                                                                                                                     |
| `detail`             | enum   | `summary` | 累加式级别 `summary` < `list` < `placement` < `full`，详见下文                                                                                                                                                       |
| `sample`             | int    | `1`（精确）   | 对枚举到的文件按确定性的 1/N 比例抽样。汇总变为 ×N 的估计值（相对误差约 1/√files），并带上 `sampled` 块；重复运行会选中同一批文件。显式路径永远不参与抽样                                                                                                                |
| `sampleSize`         | int    | `20`      | 汇总中每种状态保留的示例文件数量。`0` 表示禁用                                                                                                                                                                                  |
| `scanRateLimit`      | int    | `100000`  | 本次扫描在每个 worker 上每秒访问的页面元数据条目数。按请求值生效；worker 全局上限 `alluxio.worker.cache.insight.scan.rate.limit` ([动态](https://documentation.alluxio.io/ee-ai-cn/reference/dynamic-properties.md#ke-guan-ce-xing)) 仍会在其之上生效 |
| `batchSize`          | int    | `1000`    | 每次 worker RPC、列表刷新和游标翻页的文件数。范围 1–10000                                                                                                                                                                     |
| `workers`            | array  | 全部        | 将扫描限制在选中的 worker 上（worker id、host 或 `host:port`）。所有候选 worker 都落在选择范围之外的文件被归类为 `UNCHECKED`。未知选择器返回 `400` 并列出有效的 worker                                                                                      |
| `job_id`             | string | 服务端生成的指纹  | 客户端指定的 id，需匹配 `[A-Za-z0-9._-]{1,64}`。提交前即已知，因此查询进度和取消都无需回读响应流。与正在运行的作业重复时返回 `409`                                                                                                                          |
| `progress`           | bool   | `false`   | `true` 表示流式返回运行中的汇总快照。无论如何都会每约 2 秒刷新一次心跳                                                                                                                                                                   |
| `listingParallelism` | int    | `0`（串行）   | 实验性，仅 `source=ufs` 可用。`0`/`1`/不填 = 有序串行列举；`>1` = 该数量的并发范围列举器。取值范围 \[0, 16]。结果无序，以列举顺序换取大范围通配符下的速度。非 `ufs` source 返回 `400`                                                                                  |
| `filters`            | array  | 无         | 输出过滤条件，格式为 `{field, op, value}`，多个条件之间为 AND 关系。只有匹配的逐文件记录会进入响应流；汇总仍统计所有被扫描的文件，并额外给出 `filter_matched_files`、`filter_matched_bytes` 和 `filtered`。详见下文 **过滤条件**。无效条目返回 `400`，错误信息以 `invalid filter:` 开头       |
| `fields`             | array  | 完整记录      | 要输出的逐文件记录字段，在过滤之后应用。`record`、`ufs_path`、`input_path` 和 `error` 始终保留。未知字段名返回 `400` 并列出有效字段名                                                                                                                 |
| `maxRecordBytes`     | long   | `0`（不限制）  | 响应流中逐文件记录的总大小上限，以序列化后的字符数计。达到上限后停止输出行，但扫描继续，因此汇总依然精确，并报告 `records_truncated` 和 `records_emitted`。负数返回 `400`                                                                                                |
| `only`               | string | 无         | `completeness` 过滤条件的旧写法。逗号分隔的标记：`incomplete`（未完全缓存或不一致的文件，包括 `FAILED`）和 `complete`（与之相反）。与 `filters` 之间为 AND 关系。未知标记返回 `400`                                                                               |

**过滤条件**

`filters` 是一个扁平的 AND 列表，不支持 OR 或嵌套。每个条目指定下表中的一个字段，以及该字段接受的一个运算符。时间阈值为以分钟计的相对时长；数值必须为非负数。

| **字段**                              | **运算符**   | **取值**                         | **描述**                                                                                               |
| ----------------------------------- | --------- | ------------------------------ | ---------------------------------------------------------------------------------------------------- |
| `completeness`                      | `==`      | `"complete"` \| `"incomplete"` | `complete`：每个分段在所有预期副本上都已完全缓存，且没有 `inconsistency`，也没有失败的 `storage_check`。`incomplete` 与之相反           |
| `never_read`                        | `==`      | `true`                         | 有驻留页面、开启了读取时间记录、且从未有页面被读取。不接受 `false`                                                                |
| `not_read_in_minutes`               | `>=`      | 分钟数                            | 在该时间窗口内没有页面被读取，包括从未被读取的文件                                                                            |
| `newest_page_last_read_age_minutes` | `>=`、`<=` | 分钟数                            | 最近一次读取距今的时间。从未被读取的文件与两个运算符都不匹配                                                                       |
| `newest_page_age_minutes`           | `>=`、`<=` | 分钟数                            | 最近被缓存的页面距今的时间                                                                                        |
| `cached_bytes`                      | `>=`      | 字节数                            | 该文件已缓存的字节数                                                                                           |
| `file_length`                       | `>=`、`<=` | 字节数                            | 文件自身的大小。在 `ufs`/`both` 模式下来自 UFS 列表；在 `worker` 模式下来自缓存元数据                                            |
| `ufs_path`                          | `find`    | Java 正则表达式                     | 在 UFS 路径中查找匹配（不自动锚定；要匹配整条路径请写成 `^…$`）。最长 1000 个字符                                                    |
| `alluxio_path`                      | `find`    | Java 正则表达式                     | 在 Alluxio 路径中查找匹配。不属于任何挂载点的文件永远不匹配，并计入 `filter_alluxio_unmounted`。只有请求包含该过滤条件时，记录中才会带 `alluxio_path` |

最近读取类过滤条件（`never_read`、`not_read_in_minutes`、`newest_page_last_read_age_minutes`）要求 Worker 记录页面读取时间（`alluxio.worker.observability.read.time.enabled`）。如果某个持有被扫描页面的 Worker 没有记录，响应流会以一条 `error` 记录和一条带 `aborted: true, reason: "filter_unanswerable"` 的最终汇总结束。匹配单条路径耗时超过 250 ms 的路径模式也会以同样方式结束响应流。

**detail 级别**

各级别严格累加——每一级都保留低一级的全部字段。各级别的 RPC 次数相同，但响应体大小不同。

| **Detail**  | **逐文件记录** | **新增内容**                                                                                                                                                    |
| ----------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `summary`   | 否         | 仅最终汇总                                                                                                                                                       |
| `list`      | 是         | `status`、`cached_pct`、`cached_bytes`、`cached_age_minutes`、页面年龄与最近读取年龄范围、`file_length`、`length_source`、分段计数、`expected_replicas`、`complete_copies`、`copies[]` |
| `placement` | 是         | `copies[].missing_segments` / `partial_segments`，以及 `holders[]`——逐 worker 的持有情况，含 `candidate_segments` 和履行度 `cached_pct`                                    |
| `full`      | 是         | `segments[]`——分段 × 副本网格——以及显式路径的 `file_info`。响应体随分段数 × 副本数增长且无上限                                                                                            |

**响应:**

* `200 - OK`：扫描已被接受，随后返回 NDJSON 流。流内出现的问题以 `error` 记录呈现，而不是 HTTP 错误。

  响应体是 **NDJSON**，而不是单个 JSON 文档：每行一个完整的 JSON 值，随扫描进度流式返回。请逐行解析，并容忍未知字段和未知记录类型。

  ```
  header  →  file × N  →  heartbeat / progress / error …  →  aggregate (final)
  ```

  ```json
  {"record":"header","job_id":"audit-1","source":"ufs","detail":"list","segmentation":true}
  {"record":"file","ufs_path":"s3://bucket/train/a.parquet","status":"PARTIAL","cached_pct":62}
  {"record":"heartbeat"}
  {"record":"aggregate","final":true,"counts":{"PARTIAL":1},"checked":1,"truncated":false}
  ```

  只有当最后一条记录是带 `"final": true` 的 `aggregate` 时，才能认为抓取到的结果是完整的。连接中断的流，或在最终汇总到达前观察到的取消操作，都属于不完整结果。
* `400 - Bad Request`：参数无效或参数组合无效。JSON 错误信息会指出被拒绝的字段、取值、选择器、过滤条件或重叠路径
* `429 - Too Many Requests`：达到并发扫描上限（`alluxio.coordinator.cache.insight.max.concurrent.scans`，默认 5）。响应体会列出正在运行的作业，调用方可以等待或取消其中一个
* `409 - Conflict`：`job_id` 对应的作业已在运行，响应中包含该作业的信息
* `503 - Service Unavailable`：worker 成员信息不可用
* `500 - Internal Server Error`：未预期的错误

**记录类型**

| **记录**      | **字段**                                                                                                                                                    |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `header`    | 每个流的第一条记录：`job_id`、`source`、`detail`、`segmentation`、`segment_size`、`workers_filter[]`、`scan_rate_limit`、`scan_rate_limit_unit`、`sample`、`generated_at_ms` |
| `file`      | `list` 及更高级别下，每个被扫描文件一条。字段见下表                                                                                                                             |
| `aggregate` | 运行中的快照带 `final: false`；最终记录带 `final: true`。字段见下表                                                                                                          |
| `heartbeat` | 静默流上的保活记录，约 2 秒一次。除 `record` 外无其他字段                                                                                                                       |
| `error`     | `message`——流内的非致命问题（例如某个路径列举失败）。扫描继续进行，最终汇总仍会到达                                                                                                           |

**`file` 记录字段**

值为空的字段不会出现在传输内容中，因此"可选"意味着该字段只在有内容可报告时才出现。

| **字段**                                                                                       | **级别**    | **描述**                                                                                                                                                                                                 |
| -------------------------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ufs_path`、`file_length`、`length_source`                                                     | list      | 标识信息。长度未知时不包含 `file_length`。`length_source` 表示文件长度由哪一级解析得到：`listing`（UFS 列表）、`cache`（worker 元数据存储，未触及 UFS）、`worker_status`（可能查询了 UFS）或 `ufs`（兜底方案）                                                     |
| `status`                                                                                     | list      | `FULL_ALL_REPLICAS` \| `FULL_ONE_REPLICA` \| `PARTIAL` \| `NONE` \| `FAILED` \| `UNCHECKED`                                                                                                            |
| `alluxio_path`                                                                               | list      | 文件的 Alluxio 路径。仅当请求包含 `alluxio_path` 过滤条件且该文件属于某个挂载点时出现                                                                                                                                                |
| `cached_pct`、`cached_bytes`、`cached_age_minutes`                                             | list      | 可读取（最优副本）的覆盖率；最旧驻留页面的年龄。该年龄为缓存写入年龄，而非最近访问时间                                                                                                                                                            |
| `newest_page_age_minutes`、`oldest_page_age_minutes`                                          | list      | 最新和最旧驻留页面分别在多久之前被缓存                                                                                                                                                                                    |
| `last_read_tracking`、`newest_page_last_read_age_minutes`、`oldest_page_last_read_age_minutes` | list      | 最新和最旧驻留页面分别在多久之前被最后一次读取。`last_read_tracking: true` 且不含年龄字段，表示所有持有方都在记录读取时间但该文件从未被读取；`false` 表示读取时间未知（某个持有方没有记录，或其扫描失败）。文件没有驻留页面时不包含这些字段                                                                |
| `segment_size`、`segment_count`、`segment_status`、`misplaced_bytes`                            | list      | 使用同一套状态的逐分段分类计数，以及位于非候选 worker 上的字节数。这三个分段描述字段只在记录包含逐分段分析时出现（集群开启分段，或 `detail` ≥ `placement`）                                                                                                          |
| `expected_replicas`、`complete_copies`、`copies[]`                                             | list      | 逻辑副本。一个 copy 是所有分段的第 *i* 个槽位，因此在分段模式下会横跨多个 worker。每项包含 `replica_index`、`complete`、`cached_bytes`、`cached_pct`                                                                                          |
| `inconsistency`                                                                              | list      | 仅 `both` 模式。只在存储长度（通配符范围取 UFS 列表，显式路径取 `storage_check` 查询结果）与某个 worker 记录的长度不一致时出现，变大或变小均会报告：`{"ufs":{"length":N},"worker":{"length":N}}`。仅用于呈现，报告的 `file_length` 和 `cached_pct` 不受影响                  |
| `storage_check`                                                                              | list      | `both` 模式下被 worker 持有的显式路径。一次直接、不缓存的存储查询：`{"state":"ok","length":N}`、`{"state":"absent"}`（此时记录为 `ORPHAN`），或 `{"state":"failed","error":"..."}`。查询失败时保留缓存信息，不带 `inconsistency`，且永远不会被计为 `complete`      |
| `copies[].missing_segments`、`copies[].partial_segments`                                      | placement | 范围编码的无数据分段 id（`"2-4"` 表示 2、3、4），以及每个部分缓存分段的 `{id, cached_pct}`                                                                                                                                         |
| `holders[]`                                                                                  | placement | 物理视图：持有任意字节的所有 worker，以及所有零字节的候选 worker。包含 `worker_id`、`host`、`cluster`、`candidate_segments`、履行度 `cached_pct`、`cached_bytes`、`stale_bytes`、`cached_age_minutes`、上述页面年龄与最近读取年龄字段，以及 `resident_segments` |
| `segments[]`                                                                                 | full      | 每个分段一项——`id`、`offset`、`length`、`status`、`misplaced_bytes`——每项列出所有副本单元（`replica_index`、`worker_id`、`host`、`candidate`、`active`、`cached_pct`、`cached_bytes`）                                             |
| `file_info`                                                                                  | full      | 仅显式路径：`length`、`last_modified_ms`、`creation_time_ms`、`owner`、`group`、`mode`、`persisted`                                                                                                                |
| `region`                                                                                     | both      | `MISS`（存储中存在但任何地方都没有缓存）\| `CACHED`（两侧都存在）\| `ORPHAN`（缓存中驻留但当前列表中已不存在）                                                                                                                                  |
| `input_path`、`error`                                                                         | 任意        | 当请求的路径无法解析时，输出这两个字段而非上述字段                                                                                                                                                                              |

**`aggregate` 记录字段**

与所请求 `source` 无关的字段会被省略。

| **字段**                                                                       | **适用模式**    | **描述**                                                                                                                                                                                        |
| ---------------------------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `final`、`aborted`、`reason`                                                   | 全部          | 流状态。`final: true` 表示流结束；提前结束的扫描会额外带上 `aborted: true` 和 `reason`：`cancelled`，或在某个过滤条件无法判定时为 `filter_unanswerable`                                                                              |
| `counts`                                                                     | ufs、both    | 各分类下的文件数。只有本次扫描可能出现的状态才会出现（例如，只有当某个文件预期多于一个副本时才有 `FULL_ONE_REPLICA`，只有使用 `workers` 过滤时才有 `UNCHECKED`）；值为 `0` 表示可能出现但实际为空                                                                      |
| `failed_reasons`                                                             | ufs、both    | 失败原因 → 文件数，最多保留 50 种不同原因。在 `both` 模式下还包括列举失败和无法解析的显式路径                                                                                                                                        |
| `storage_checks_failed`                                                      | both        | 失败的显式路径存储查询次数。只要扫描执行过此类查询就会出现                                                                                                                                                                 |
| `regions`                                                                    | both        | `MISS` / `CACHED` / `ORPHAN` 的数量                                                                                                                                                              |
| `listing_order`                                                              | both        | 联接时 UFS 一侧的排序方式：`native`（UFS 本身按升序列举）或 `sorted`（收集后排序，上限 10 万）                                                                                                                                |
| `totals`                                                                     | worker、both | `distinct_files`、`resident_entries`、`cached_bytes`、`misplaced_files`                                                                                                                          |
| `bytes`                                                                      | 全部          | `scanned`（逻辑数据集字节数）、`cached_logical`（每个文件取最优副本）、`cached_physical`（计入所有副本）、`stale`；`both` 额外包含 `orphan`                                                                                        |
| `cached_age_buckets`                                                         | 全部          | 写入年龄直方图（`<=10m` / `<=1h` / `<=24h` / `<=7d` / `>7d`）                                                                                                                                          |
| `last_read_buckets`                                                          | 全部          | 基于相同边界的访问时间直方图，外加 `no read observed`（有记录但从未被读取）和 `unknown`（读取时间不可用）。在 `ufs` 模式下全部为零                                                                                                           |
| `file_size_buckets`、`cached_pct_buckets`                                     | 全部          | 分布统计。大小分桶使用 IEC 二进制边界                                                                                                                                                                         |
| `top_cached`、`largest_stale_files`                                           | worker、both | 按缓存字节数和过期字节数排序的 top-10                                                                                                                                                                        |
| `metadata_missing`                                                           | 全部          | `{count, samples}`——扫描无法解析长度的驻留数据                                                                                                                                                             |
| `workers[]`                                                                  | 全部          | 逐 worker 行：驻留信息（`resident_files`、`cached_bytes`、`stale_bytes`、`pages`、`cache_used_bytes`、`cache_capacity_bytes`），或在 `ufs` 模式下为检查结果（`checked`、`full`、`partial`、`miss`、`failed`、`cached_bytes`） |
| `workers_total`、`workers_scanned`、`workers_failed`、`failed_workers`、`errors` | 全部          | 扇出健康状况；`errors[]` 保存逐 worker 的异常信息                                                                                                                                                            |
| `samples`                                                                    | ufs、both    | 每种状态的示例文件蓄水池：`{ufs_path, status, cached_pct}`                                                                                                                                                 |
| `write_cache`                                                                | worker、both | `{v1: {pages, bytes}, v2: {pages, bytes}}`——写缓存的旁路统计，不计入驻留量                                                                                                                                   |
| `sampled`                                                                    | 全部          | `{rate, files}`——标记这是一次抽样扫描；计数和字节数为 ×rate 的估计值                                                                                                                                                |
| `checked`、`truncated`、`duration_ms`                                          | 全部          | 已分类的文件数、是否因 `limit` 或上限提前结束、以及墙钟耗时。`checked` 的含义按模式而定：已检查文件数（`ufs`）、去重后的驻留文件数（`worker`）、联接行数（`both`）。列举失败（例如范围不存在）不算 `truncated`，而是一次 `FAILED` 检查并附带 `error` 记录                               |
| `filter_matched_files`、`filter_matched_bytes`                                | 带过滤条件的扫描    | 过滤条件匹配的文件数及其已缓存字节数，在过滤判定处统计。在所有 detail 级别下都是精确的，包括 `summary`，以及 `maxRecordBytes` 已用完的情况                                                                                                       |
| `filtered`                                                                   | 带过滤条件的扫描    | 只针对匹配文件重新计算的上述直方图（`counts`、`regions`、`cached_age_buckets`、`last_read_buckets`、`file_size_buckets`、`cached_pct_buckets`、`top_cached`、`largest_stale_files`，以该模式实际报告的为准）                        |
| `filter_not_evaluable`、`filter_alluxio_unmounted`                            | 带过滤条件的扫描    | 因过滤条件无法判定而被排除的文件数（某个副本的扫描丢失了读取信息，或无法读取挂载表），以及因不属于任何挂载点而被 `alluxio_path` 过滤条件排除的文件数                                                                                                            |
| `records_emitted`、`records_truncated`                                        | 被截断的扫描      | 仅当 `maxRecordBytes` 提前停止输出行时出现。已发送的行是按扫描顺序最先放得下的那些，而不是最大的那些                                                                                                                                   |

**示例**

```shell
curl -sN -X POST http://coordinator:19999/api/v1/cache-insight \
  -H 'Content-Type: application/json' \
  -d '{"groups":[{"paths":["s3://bucket/train/**"]}],"source":"ufs","detail":"summary"}' \
  | tail -1 | jq .
```

在不流式返回任何行的情况下，统计不小于 1 GiB 且从未被读取的缓存文件数量及其占用的字节数：

```shell
curl -sN -X POST http://coordinator:19999/api/v1/cache-insight \
  -H 'Content-Type: application/json' \
  -d '{"groups":[{"paths":["s3://bucket/**"]}],"source":"worker","detail":"summary",
       "filters":[{"field":"never_read","op":"==","value":true},
                  {"field":"cached_bytes","op":">=","value":1073741824}]}' \
  | tail -1 | jq '{files: .filter_matched_files, bytes: .filter_matched_bytes}'
```

#### 列出存活的 worker

**方法:** `GET`

**路径:** `/api/v1/cache-insight/workers`

**响应:**

* `200 - OK`：操作成功

  ```json
  {"workers":[{"worker_id":"worker-844d...","host":"10.0.0.12","rpc_port":29999}]}
  ```
* `503 - Service Unavailable`：worker 成员信息不可用

#### 列出、查询和取消运行中的扫描

**方法:** `GET`

**路径:** `/api/v1/cache-insight/jobs`、`/api/v1/cache-insight/jobs/{id}`

**响应:**

* `200 - OK`：操作成功。`/jobs` 返回正在运行的列表，`/jobs/{id}` 返回单个作业。每个作业行都带有实时的 `checked` 计数，这是不通过流内 `progress: true` 记录即可观察进度的 REST 方式

  ```json
  {"jobs":[{"job_id":"audit-1","source":"both","paths":["s3://bucket/**"],
            "path_count":1,"checked":48210,"running_ms":6180}]}
  ```
* `404 - Not Found`：作业不存在或已结束

**方法:** `DELETE`

**路径:** `/api/v1/cache-insight/jobs/{id}`

**响应:**

* `202 - Accepted`：已请求取消。取消是协作式的——扫描在下一个工作单元处退出，其响应流以 `{"record":"aggregate","final":true,"aborted":true,"reason":"cancelled"}` 结束。直接关闭 HTTP 连接同样会取消扫描，延迟约为一个心跳间隔

  ```json
  {"cancelling":{"job_id":"audit-1","source":"both","paths":["s3://bucket/**"],
                 "path_count":1,"checked":48210,"running_ms":6180}}
  ```
* `404 - Not Found`：作业不存在或已结束

### 文件位置

> **即将废弃：** 该接口由 [Cache Insight](#cache-insight) 取代。后者报告同样的逐 worker 放置信息，并额外覆盖逐分段的缓存状态、worker 侧驻留情况以及存储与缓存的对账。新的集成请优先使用带 `"detail": "full"` 的 `POST /api/v1/cache-insight`。

计算哪些 worker 持有某个文件的缓存数据，可选择限定到特定字节段。适用于感知数据本地性的调度（Spark、Presto、Ray）以及调试缓存命中/未命中行为。

#### 获取文件或分段位置

**方法:** `GET`

**路径:** `/api/v1/location`

**参数**

| **名称**              | **必填** | **描述**                                                                          |
| ------------------- | ------ | ------------------------------------------------------------------------------- |
| `path`              | 是      | 文件的 Alluxio 或 UFS 路径                                                            |
| `segments`          | 否      | 分段规格（例如 `0,2,5-7`）。设置后，响应为分段范围位置列表                                              |
| `segment_size`      | 否      | 覆盖配置的分段大小（例如 `64MB`）。仅在设置了 `segments` 时使用；默认值为 `alluxio.user.file.segment.size` |
| `check_all_workers` | 否      | `true` 表示即使一致性哈希主节点已持有该文件，也查询所有 worker。仅在未设置 `segments` 时使用                     |

**响应:**

* `200 - OK`: 操作成功。响应体的结构取决于是否提供了 `segments`。

  未提供 `segments` 时，响应为一致性哈希环生成的文件级位置映射（每个文件对应一个或多个 worker）。

  提供了 `segments` 时，响应为每个分段的位置条目列表，每条描述字节范围及持有该分段的 worker。
* `400 - Bad Request`: 缺少 `path`

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```

### 副本放置规则

在多集群部署中，副本放置规则控制给定路径前缀的副本应分布在哪些成员集群上。规则以 Alluxio 路径前缀为键。

#### 列出所有副本规则

**方法:** `GET`

**路径:** `/api/v1/replica-rule`

**参数:** 无

**响应:**

* `200 - OK`: 操作成功。返回以路径前缀为键、对应规则为值的映射。

  ```json
  {
    "/data/shared/": {
      "...": "ReplicaClusterPlacementRule fields"
    }
  }
  ```
* `500 - Internal Server Error`: 意外错误

#### 添加或更新副本规则

**方法:** `POST`

**路径:** `/api/v1/replica-rule`

**请求体:** `Content-Type: application/json`

`numReplicasPerCluster` 和 `rules` 两者必须且只能提供其中一个。

| **名称**                  | **类型** | **必填** | **描述**                                                              |
| ----------------------- | ------ | ------ | ------------------------------------------------------------------- |
| `path`                  | string | 是      | 规则适用的 Alluxio 路径前缀，不得为 UFS 路径                                       |
| `numReplicasPerCluster` | int    | 否      | 应用于每个成员集群的统一副本数（必须 > 0）                                             |
| `rules`                 | object | 否      | 每个集群的副本数，例如 `{"cluster-a": 2, "cluster-b": 1}`。集群名称必须已在全局客户端集群信息中注册 |

示例：

```json
{
  "path": "/data/shared/",
  "numReplicasPerCluster": 2
}
```

```json
{
  "path": "/data/shared/",
  "rules": {
    "cluster-a": 2,
    "cluster-b": 1
  }
}
```

**响应:**

* `200 - OK`: 操作成功

  ```json
  {
    "status": "ok"
  }
  ```
* `400 - Bad Request`: 缺少 `path`、`path` 为 UFS 路径、`numReplicasPerCluster` 和 `rules` 同时设置或均未设置、副本数非正，或 `rules` 中包含未知集群名称
* `500 - Internal Server Error`: 意外错误

#### 删除副本规则

**方法:** `DELETE`

**路径:** `/api/v1/replica-rule`

**请求体:** `Content-Type: application/json`

```json
{
  "path": "/data/shared/"
}
```

**响应:**

* `200 - OK`: 操作成功

  ```json
  {
    "status": "ok"
  }
  ```
* `400 - Bad Request`: 请求体缺失或缺少 `path`
* `500 - Internal Server Error`: 意外错误

### 集群信息

获取集群基本信息，包括集群名称、软件版本、总缓存容量与使用量，以及在线/离线 worker 数量。

#### 获取集群信息

**方法:** `GET`

**路径:** `/api/v1/cluster-info`

**参数:** 无

**响应:**

* `200 - OK`: 操作成功

  ```json
  {
    "name": "my-alluxio-cluster",
    "version": "3.x-15.0.0",
    "capacityBytes": 1099511627776,
    "usedBytes": 536870912000,
    "onlineWorkers": 5,
    "offlineWorkers": 1,
    "features": ["job-time-filter", "job-list-all"]
  }
  ```

  `features` 列出这个 coordinator 提供的可选 API 能力，客户端可以先检查再使用：`job-time-filter` 表示作业列举路由支持 `endedAfter`，`job-list-all` 表示支持 [`GET /api/v1/jobs`](#lie-ju-suo-you-lei-xing-de-zuo-ye)。响应中没有 `features` 说明是较旧的 coordinator，两者都不支持。
* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```
