> 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/ufs.md).

# 底层存储

Alluxio 连接到各种各样的存储系统，称为底层文件系统 (UFS)，并通过统一的虚拟命名空间对外暴露。本节介绍 Alluxio 挂载的工作原理，并提供各支持存储系统的配置指南。

## 挂载工作原理

**挂载**将一个 Alluxio 虚拟路径绑定到一个 UFS URI。例如，将 `s3://my-bucket/data/` 挂载到 `/data`，即可通过 Alluxio 命名空间中的 `/data` 访问该存储桶内容。数据不会被复制，读写操作均由 Alluxio 代理转发到底层存储。

关键行为：

* 可同时在不同路径下挂载多个存储系统。
* **单挂载选项**（通过 `mountOptions` 或 `--option` 设置）优先于 `AlluxioCluster` `spec.properties` 或 `alluxio-site.properties` 中设置的全局属性。
* 挂载点必须位于 Alluxio 命名空间的顶层，不允许嵌套。完整规则请参阅 [挂载规则](#gua-zai-gui-ze)。

## 挂载规则

在定义命名空间时，您必须遵循两个规则，以确保挂载表有效且无歧义。

### 规则 1：挂载必须是根目录（`/`）的直接子级

您只能在 Alluxio 命名空间的顶层创建挂载点。您不能挂载到根路径（`/`）本身，也不能在不存在的目录中创建挂载点。

| 操作     | Alluxio 路径     | UFS 路径                   | 有效？  | 原因            |
| ------ | -------------- | ------------------------ | ---- | ------------- |
| 挂载存储桶  | `/s3-data`     | `s3://my-bucket/`        | ✔️ 是 | 挂载点是根目录的直接子级。 |
| 挂载到根目录 | `/`            | `s3://my-bucket/`        | ❌ 否  | 根路径不能是挂载点。    |
| 挂载到子路径 | `/data/images` | `s3://my-bucket/images/` | ❌ 否  | 挂载点不能在子目录中创建。 |

### 规则 2：挂载不能嵌套

一个挂载点不能创建在另一个挂载点内部，无论是在 Alluxio 命名空间还是在 UFS 命名空间中。例如，如果 `/data` 挂载到 `s3://my-bucket/data`，您不能在 `/data/tables` 创建新挂载（嵌套的 Alluxio 路径），也不能将另一个 UFS 挂载到 `s3://my-bucket/data/tables`（嵌套的 UFS 路径）。

假设您有一个现有的挂载点：

* **Alluxio 路径：** `/data`
* **UFS 路径：** `s3://my-bucket/data`

以下新挂载将是**无效的**：

| 新 Alluxio 路径   | 新 UFS 路径                     | 有效？ | 拒绝原因                                                      |
| -------------- | ---------------------------- | --- | --------------------------------------------------------- |
| `/data/tables` | `hdfs://namenode/tables`     | ❌ 否 | Alluxio 路径 `/data/tables` 嵌套在现有的 `/data` 挂载中。             |
| `/tables`      | `s3://my-bucket/data/tables` | ❌ 否 | UFS 路径 `s3://.../data/tables` 嵌套在现有的 `s3://.../data` 挂载中。 |

## 基本挂载配置

{% tabs %}
{% tab title="Kubernetes (Operator)" %}
每个挂载定义为一个 `UnderFileSystem` 自定义资源。无论 UFS 类型如何，字段结构相同：

```yaml
apiVersion: k8s-operator.alluxio.com/v1
kind: UnderFileSystem
metadata:
  name: my-mount               # 此挂载资源的唯一名称
  namespace: alx-ns            # 必须与 AlluxioCluster 的命名空间一致
spec:
  alluxioCluster: alluxio-cluster   # 要关联的 AlluxioCluster CR 名称
  path: <UFS_URI>              # UFS URI，例如 s3://bucket/prefix/ 或 gs://bucket/path/
  mountPath: /data             # 此 UFS 在 Alluxio 命名空间中的挂载路径
  mountOptions:                # UFS 特定的连接和凭据属性
    <property-key>: "<value>"
```

应用并验证：

```shell
kubectl apply -f ufs.yaml
kubectl exec -n alx-ns alluxio-cluster-coordinator-0 -- alluxio mount list
```

`path` 和 `mountOptions` 中 UFS 特定的值请参阅对应存储系统的指南。
{% endtab %}

{% tab title="Docker / 裸机" %}
使用 `alluxio mount add` 创建挂载点，通过 `--option` 传入 UFS 特定的连接属性：

```shell
bin/alluxio mount add \
  --path /data \
  --ufs-uri <UFS_URI> \
  --option <property-key>=<value>
```

验证挂载是否生效：

```shell
bin/alluxio mount list
```

各存储系统的 URI scheme 和属性名称请参阅对应指南。
{% endtab %}
{% endtabs %}

## 挂载多个存储桶

每个存储位置需要创建一个独立的挂载，且每个挂载必须指定唯一的 `mountPath`。挂载数量没有硬性上限。

{% tabs %}
{% tab title="Kubernetes (Operator)" %}
每个位置创建一个 `UnderFileSystem` CR（`mountOptions` 属性见各 UFS 指南），然后一起应用：

```shell
kubectl apply -f bucket-a.yaml -f bucket-b.yaml
```

{% endtab %}

{% tab title="Docker / 裸机" %}
每个位置执行一次 `alluxio mount add`：

```shell
bin/alluxio mount add --path /bucket-a --ufs-uri <UFS_URI_A> --option <key>=<value>
bin/alluxio mount add --path /bucket-b --ufs-uri <UFS_URI_B> --option <key>=<value>
```

{% endtab %}
{% endtabs %}

`mountOptions` 中的单挂载凭据优先于全局凭据，适用于跨账号或跨项目的挂载场景。

## Kubernetes：凭据管理

避免将凭据直接写入 `UnderFileSystem` CR 的 `mountOptions`——它们会出现在受版本控制的 YAML 中，且每个挂载都需重复填写。以下两种方式可在集群级别统一设置凭据：

**方式 A：在 AlluxioCluster CR 的 `spec.properties` 中设置**

全局设置 UFS 凭据属性。各挂载在未指定自身凭据时继承这些属性，单挂载的 `mountOptions` 仍可覆盖全局设置：

```yaml
apiVersion: k8s-operator.alluxio.com/v1
kind: AlluxioCluster
spec:
  properties:
    # UFS 特定的属性名称因类型而异 — 详见各 UFS 指南
    <credential-property-key>: "<credential-value>"
```

**方式 B：Kubernetes Secret + Pod 环境变量**

将凭据存储在 Secret 中以避免提交到版本控制，然后以环境变量形式注入到 UFS 驱动读取：

```shell
kubectl create secret generic ufs-credentials \
  --from-literal=credential-value=<YOUR_CREDENTIAL> \
  -n alx-ns
```

```yaml
apiVersion: k8s-operator.alluxio.com/v1
kind: AlluxioCluster
spec:
  coordinator:
    env:
      - name: <ENV_VAR_NAME>   # UFS 特定 — 详见各 UFS 指南
        valueFrom:
          secretKeyRef:
            name: ufs-credentials
            key: credential-value
  worker:
    env:
      - name: <ENV_VAR_NAME>
        valueFrom:
          secretKeyRef:
            name: ufs-credentials
            key: credential-value
```

包含 S3 特定属性和环境变量名称的完整示例，请参阅 [在 Kubernetes 中设置凭据](https://documentation.alluxio.io/ee-ai-cn/pages/0Ic94ngYtfHnZGxUnyNr#在-kubernetes-中设置凭据)。

## 管理现有挂载

挂载生效后，可用以下命令查看或移除。

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

* **列出挂载：**

  ```shell
  kubectl -n alx-ns get ufs
  ```

  ```console
  NAME         PHASE   AGE
  alluxio-s3   Ready   13d
  ```
* **移除挂载：**

  ```shell
  kubectl -n alx-ns delete ufs alluxio-s3
  ```

  ```console
  underfilesystem.k8s-operator.alluxio.com "alluxio-s3" deleted
  ```

{% endtab %}

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

* **列出挂载：**

  ```shell
  bin/alluxio mount list
  ```
* **移除挂载：**

  ```shell
  bin/alluxio mount remove --path /s3-data
  ```

{% endtab %}
{% endtabs %}

挂载表存储在 etcd 中。Alluxio 组件会定期轮询 etcd 以获取最新的挂载表，因此添加和移除会自动在整个集群中传播。

## 通用对象存储配置

以下配置适用于所有对象存储类型（S3、OSS、BOS、COS、TOS 及 S3 兼容存储）。

### 请求重试策略

当对象存储返回瞬时错误时，Alluxio 会自动重试请求。以下错误码会触发重试：`500`、`502`、`503 Slow Down`、`504`。客户端错误（`4xx`）不会重试。

在 `conf/alluxio-site.properties` 中或通过挂载选项配置重试行为：

```properties
# 每次请求的最大重试次数
alluxio.underfs.business.retry.max.num=10

# 首次重试前的等待时间
alluxio.underfs.business.retry.base.sleep=30ms

# 两次重试之间的最大等待时间（默认值：30s）
alluxio.underfs.business.retry.max.sleep=60s
```

## 支持的底层存储系统

### 云对象存储

| 存储系统                           | 描述                            | 指南                                        |
| ------------------------------ | ----------------------------- | ----------------------------------------- |
| **Amazon S3**                  | 连接到 Amazon S3 的标准指南。          | [查看指南](/ee-ai-cn/ufs/s3.md)               |
| **Google Cloud Storage (GCS)** | 连接到 Google Cloud Storage 的指南。 | [查看指南](/ee-ai-cn/ufs/gcs.md)              |
| **Azure Blob Storage**         | 连接到 Azure Blob Storage 的指南。   | [查看指南](/ee-ai-cn/ufs/azure-blob-store.md) |
| **阿里云 OSS**                    | 连接到阿里云对象存储服务的指南。              | [查看指南](/ee-ai-cn/ufs/aliyun-oss.md)       |
| **腾讯云对象存储 (COS)**              | 连接到腾讯云对象存储的指南。                | [查看指南](/ee-ai-cn/ufs/cos.md)              |
| **百度对象存储 (BOS)**               | 连接到百度云对象存储的指南。                | [查看指南](/ee-ai-cn/ufs/bos.md)              |
| **火山引擎 TOS**                   | 连接到火山引擎对象存储的指南。               | [查看指南](/ee-ai-cn/ufs/tos.md)              |

### 本地存储

| 存储系统                      | 描述                                    | 指南                                     |
| ------------------------- | ------------------------------------- | -------------------------------------- |
| **S3 兼容**                 | 用于连接到使用 S3 API 的对象存储，例如 MinIO 或 Ceph。 | [查看指南](/ee-ai-cn/ufs/s3-compatible.md) |
| **Hadoop 分布式文件系统 (HDFS)** | 连接到 HDFS 集群的标准指南。                     | [查看指南](/ee-ai-cn/ufs/hdfs.md)          |
| **网络附加存储 (NAS)**          | 用于连接到集群上挂载的任何符合 POSIX 标准的文件系统，例如 NFS。 | [查看指南](/ee-ai-cn/ufs/nas.md)           |