# 底层存储

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)           |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://documentation.alluxio.io/ee-ai-cn/ufs.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.