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

# S3 兼容存储

Alluxio 可以连接到各种提供 S3 兼容接口的存储系统，例如 MinIO、Ceph 等。本指南介绍了如何配置 Alluxio 以将这些存储系统挂载为底层文件系统 (UFS)。

连接到 S3 兼容存储与连接到 AWS S3 的主要区别在于需要指定自定义端点。

## 先决条件

* Alluxio 已安装并正在运行。有关详细信息，请参阅先决条件。
* S3 兼容存储服务正在运行，并且可以从 Alluxio 集群访问。
* 您拥有 S3 兼容存储的以下信息：
  * **端点 URL**：S3 服务正在侦听的地址（例如 `http://minio.example.com:9000`）。
  * **访问密钥 ID 和秘密访问密钥**：用于访问存储的凭据。
  * **存储桶名称**：要挂载的存储桶的名称。

## 基本配置

### 指定存储端点

使用非 AWS S3 兼容存储时，您必须将 Alluxio 配置为使用自定义端点。否则，Alluxio 将默认为 AWS 全局 S3 服务端点。

```properties
alluxio.underfs.s3.endpoint=<S3_ENDPOINT>
alluxio.underfs.s3.endpoint.region=<S3_ENDPOINT_REGION>
```

如果没有要设置的端点区域，可以通过省略该属性来不指定。请注意，设置端点后，`alluxio.underfs.s3.region=<S3_REGION>` 将不再生效。

### 禁用 DNS 存储桶 URL 以进行路径样式访问

默认情况下，构造的请求 URL 将符合[虚拟托管样式访问](https://docs.aws.amazon.com/AmazonS3/latest/userguide/VirtualHosting.html#virtual-hosted-style-access)。如果存储需要[路径样式访问](https://docs.aws.amazon.com/AmazonS3/latest/userguide/VirtualHosting.html#path-style-access)请求，则需要设置以下配置。

```properties
alluxio.underfs.s3.disable.dns.buckets=true
```

## 支持的存储提供商

已知以下存储提供商支持 Alluxio 的 S3 集成。请注意，此列表并非详尽无遗——其他 S3 兼容系统也可能通过适当的配置工作。

### MinIO

[MinIO](https://min.io/docs/minio/linux/index.html) 是用于本地部署的对象存储解决方案。

```properties
alluxio.underfs.s3.endpoint=<S3_ENDPOINT>
alluxio.underfs.s3.endpoint.region=<S3_ENDPOINT_REGION>
s3a.accessKeyId=<ACCESS_KEY_ID>
s3a.secretKey=<SECRET_KEY>
alluxio.underfs.s3.disable.dns.buckets=true
alluxio.underfs.s3.inherit.acl=false
```

端点地址通常采用 `http://<minioServerHostname>:<port>` 的形式，例如 `http://127.0.0.1:9000`。如果创建存储桶时未指定区域，则可以通过省略该属性来不指定端点区域。

### Oracle 云基础设施 (OCI) 对象存储

[OCI 对象存储](https://docs.oracle.com/en-us/iaas/Content/Object/home.htm) 是 Oracle 提供的对象存储服务。

OCI 对象存储提供 S3 兼容 API，端点格式如下：

```
https://<NAMESPACE>.compat.objectstorage.<REGION>.oraclecloud.com
```

其中 `<NAMESPACE>` 是您 OCI 租户的对象存储命名空间（可在 OCI 控制台的对象存储设置中找到），`<REGION>` 是 OCI 区域标识符（例如 `us-phoenix-1`、`eu-frankfurt-1`）。

所需的配置属性：

```properties
alluxio.underfs.s3.endpoint=https://<NAMESPACE>.compat.objectstorage.<REGION>.oraclecloud.com
alluxio.underfs.s3.endpoint.region=<REGION>
s3a.accessKeyId=<OCI_CUSTOMER_SECRET_KEY_ID>
s3a.secretKey=<OCI_CUSTOMER_SECRET_KEY>
alluxio.underfs.s3.disable.dns.buckets=true
alluxio.underfs.s3.inherit.acl=false
alluxio.underfs.s3.sdk.version=1
```

**OCI 关键说明：**

* **`alluxio.underfs.s3.disable.dns.buckets=true`**：OCI 必须设置此项。OCI 的 S3 兼容 API 使用路径样式访问（`endpoint/bucket`），而非虚拟托管样式（`bucket.endpoint`）。不设置此项请求将失败。
* **`alluxio.underfs.s3.endpoint.region`**：必须与 OCI 区域标识符匹配。设置 `endpoint` 后，`alluxio.underfs.s3.region` 将被忽略，仅 `endpoint.region` 生效。
* **`alluxio.underfs.s3.sdk.version=1`**：OCI 写入必须设置。OCI 的 S3 兼容端点不接受 AWS SDK v2 的 chunked transfer encoding；不设置此项时写入操作会返回 HTTP 501 "AWS chunked encoding not supported"。
* **凭据**：使用 OCI Customer Secret Keys（在 OCI 控制台的 **用户设置 → Customer Secret Keys** 下生成），这是 OCI 中与 AWS Access Key / Secret Key 等价的凭据。

**Kubernetes CR 示例：**

```yaml
apiVersion: k8s-operator.alluxio.com/v1
kind: UnderFileSystem
metadata:
  name: oci-bucket
  namespace: alx-ns
spec:
  alluxioCluster: alluxio-cluster
  path: s3://<OCI_BUCKET>/
  mountPath: /oci
  mountOptions:
    s3a.accessKeyId: "<OCI_CUSTOMER_SECRET_KEY_ID>"
    s3a.secretKey: "<OCI_CUSTOMER_SECRET_KEY>"
    alluxio.underfs.s3.endpoint: "https://<NAMESPACE>.compat.objectstorage.<REGION>.oraclecloud.com"
    alluxio.underfs.s3.endpoint.region: "<REGION>"
    alluxio.underfs.s3.disable.dns.buckets: "true"
    alluxio.underfs.s3.inherit.acl: "false"
    alluxio.underfs.s3.sdk.version: "1"
```

**挂载多个 OCI 区域的存储桶：**

每个挂载指定各自的端点和区域。如果所有存储桶共享相同凭据，可在 `AlluxioCluster` CR 的 `spec.properties` 中全局设置凭据，各 `UnderFileSystem` CR 只需指定各自的端点和区域：

```yaml
# oci-mounts.yaml
apiVersion: k8s-operator.alluxio.com/v1
kind: UnderFileSystem
metadata:
  name: oci-phoenix
  namespace: alx-ns
spec:
  alluxioCluster: alluxio-cluster
  path: s3://oci-bucket-phoenix/
  mountPath: /oci-phoenix
  mountOptions:
    alluxio.underfs.s3.endpoint: "https://<NAMESPACE>.compat.objectstorage.us-phoenix-1.oraclecloud.com"
    alluxio.underfs.s3.endpoint.region: "us-phoenix-1"
    alluxio.underfs.s3.disable.dns.buckets: "true"
    alluxio.underfs.s3.inherit.acl: "false"
    alluxio.underfs.s3.sdk.version: "1"
---
apiVersion: k8s-operator.alluxio.com/v1
kind: UnderFileSystem
metadata:
  name: oci-frankfurt
  namespace: alx-ns
spec:
  alluxioCluster: alluxio-cluster
  path: s3://oci-bucket-frankfurt/
  mountPath: /oci-frankfurt
  mountOptions:
    alluxio.underfs.s3.endpoint: "https://<NAMESPACE>.compat.objectstorage.eu-frankfurt-1.oraclecloud.com"
    alluxio.underfs.s3.endpoint.region: "eu-frankfurt-1"
    alluxio.underfs.s3.disable.dns.buckets: "true"
    alluxio.underfs.s3.inherit.acl: "false"
    alluxio.underfs.s3.sdk.version: "1"
```

```shell
kubectl apply -f oci-mounts.yaml
```

### Tigris 数据

[Tigris](https://www.tigrisdata.com/docs/overview/) 是 Tigris 数据提供的对象存储服务。

```properties
alluxio.underfs.s3.endpoint=<S3_ENDPOINT>
alluxio.underfs.s3.endpoint.region=<S3_ENDPOINT_REGION>
s3a.accessKeyId=<ACCESS_KEY_ID>
s3a.secretKey=<SECRET_KEY>
alluxio.underfs.s3.disable.dns.buckets=true
alluxio.underfs.s3.inherit.acl=false
```

例如，开发存储桶使用端点 `https://fly.storage.tigris.dev`，并且可以通过省略该属性来不指定端点区域。