客户端 API

Alluxio 提供三种客户端 API，均可访问相同的缓存数据——选择哪种取决于您应用程序的语言、框架和运维约束。

选择 API

	POSIX API	S3 API	Python FSSpec
适用场景	应用使用标准文件系统调用；无需修改任何代码	应用已使用 boto3 / AWS SDK / 任意 S3 兼容客户端	纯 Python：Pandas、PyArrow、Ray、Hugging Face Datasets
语言	任意	任意（HTTP）	仅 Python
部署方式	每个客户端节点运行 FUSE 守护进程（K8s 用 CSI 或 DaemonSet）	在 Worker 上启用 S3 端点；将 SDK 指向 worker-ip:29998	pip install alluxiofs
状态	GA	GA	实验性

快速决策指南

• K8s 上的 ML 训练（PyTorch、TensorFlow）→ POSIX API（CSI 方式），或 S3 API（PyTorch S3 Connector）

• 现有 S3 工作负载（boto3、Spark 等）→ S3 API——替换 endpoint URL，无需其他改动

• Pandas / PyArrow / Ray → FSSpec（alluxiofs）——无需挂载或守护进程

• 性能敏感、高吞吐场景 → S3 API（启用 HTTP 307 redirect）

API 简介

POSIX API

将 Alluxio 挂载为本地目录。任何使用标准文件系统调用（open、read、write、ls、cp）的工具均无需修改即可使用——无需改代码，无需引入 SDK。

每个客户端节点上运行一个 FUSE 守护进程，将文件系统调用转换为 Alluxio RPC——对应用完全透明。代价是每次操作都需要经过 FUSE 进程（相比直接使用 SDK 多一跳），且守护进程需要在每个客户端节点上单独部署。

# FUSE 挂载后，无需任何代码改动
ls /mnt/alluxio/fuse/s3/
cat /mnt/alluxio/fuse/s3/dataset/train.csv

→ POSIX API 指南

S3 API

在每个 Alluxio Worker 进程内直接暴露 S3 兼容的 HTTP 端点（端口 29998）。使用任意 AWS S3 SDK 的应用只需修改 endpoint URL，无需其他代码改动。

S3 端点直接运行在每个 Worker 进程内，无需额外守护进程。部署模式和吞吐调优请参阅详细指南。

import boto3
client = boto3.client(
    "s3",
    endpoint_url="http://<WORKER_IP>:29998",
    aws_access_key_id="alluxio",
    aws_secret_access_key="alluxio",
)
client.list_objects_v2(Bucket="s3")

→ S3 API 指南

Python FSSpec API

alluxiofs 实现了 fsspec 接口，使 Alluxio 可作为 Pandas、PyArrow、Ray Dataset 和 Hugging Face Datasets 中 s3fs 的直接替代。

实验性：alluxiofs 尚未 GA。请使用 UFS 原生路径（如 s3://bucket/path），而非 Alluxio 虚拟挂载路径。

import fsspec
from alluxiofs import AlluxioFileSystem
fsspec.register_implementation("alluxiofs", AlluxioFileSystem, clobber=True)

fs = fsspec.filesystem("alluxiofs", worker_hosts="<WORKER_IP>", target_protocol="s3")

import pandas as pd
df = pd.read_parquet("s3://my-bucket/dataset/train.parquet", filesystem=fs)

→ FSSpec API 指南

路径映射

三种 API 共用同一个路径命名空间。Alluxio 根据挂载表解析路径：每个挂载点将一个 Alluxio 虚拟路径绑定到一个 UFS URI。例如，将 s3://my-bucket/data/ 挂载到 /data 后：

• POSIX：cat /mnt/alluxio/fuse/data/file.csv

• S3 API：client.get_object(Bucket="data", Key="file.csv")

• FSSpec：fs.open("s3://my-bucket/data/file.csv")

三种方式访问的是相同的缓存数据。挂载点必须位于 Alluxio 命名空间的顶层，不支持嵌套。挂载的添加与管理方式请参阅底层存储。

虚拟路径映射

当挂载表本身无法满足需求时——例如命名空间隔离、UFS 零停机迁移或多版本路径别名——Alluxio 提供虚拟路径映射功能。它是服务端的路径重写层，在路径解析前对 POSIX、S3 API 和 CLI 透明生效，应用代码无需任何改动。

示例：将 /model/latest/ 重定向到 /model/v3/，无需修改任何客户端配置。

→ 虚拟路径映射指南