# 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`，并且可以通过省略该属性来不指定端点区域。


---

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