# 阿里云 OSS

本指南介绍如何将[阿里云对象存储服务](https://cn.aliyun.com/product/oss)配置为 Alluxio 的底层存储系统。

阿里云对象存储服务（OSS）是阿里云提供的海量、安全、高可靠的云存储服务。OSS 提供多种存储类别，帮助您管理和降低存储成本。

有关阿里云对象存储服务的更多信息，请阅读其[文档](https://www.alibabacloud.com/help/zh/oss/)。

## 先决条件

在开始配置前，请确保已准备好以下所需信息：

| `<OSS_BUCKET>`            | [在 OSS 控制台中创建一个新桶](https://www.alibabacloud.com/help/zh/oss/getting-started/create-buckets-6#task-2013189) 或使用现有桶                  |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `<OSS_DIRECTORY>`         | 要在桶中使用的目录，可以创建新目录或使用现有目录                                                                                                           |
| `<OSS_ACCESS_KEY_ID>`     | 用于识别用户的 ID。请参阅 [如何获取访问密钥对](https://www.alibabacloud.com/help/zh/sls/developer-reference/accesskey-pair)                            |
| `<OSS_ACCESS_KEY_SECRET>` | 用于验证用户身份的密钥（secret)。请参阅 [如何获取访问密钥对](https://www.alibabacloud.com/help/zh/sls/developer-reference/accesskey-pair)                   |
| `<OSS_ENDPOINT>`          | 端点 (endpoint) 是其他服务可以用来访问 OSS 的域名。请参阅 [公共云中的区域和 OSS 端点](https://www.alibabacloud.com/help/zh/oss/user-guide/regions-and-endpoints) |

## 基本设置

使用 [挂载表操作](https://documentation.alluxio.io/ee-ai-cn/ai-3.6/ufs/pages/vItTjDEwYA3ygh6WezO1#挂载表操作) 来增加一个新的挂载点, 需指定要在其上创建挂载的 Alluxio 路径，以及作为 UFS URI 的 OSS 路径。\
在挂载操作中，也可以指定凭证和配置选项，具体方法请参见[配置挂载点](https://documentation.alluxio.io/ee-ai-cn/ai-3.6/ufs/pages/vItTjDEwYA3ygh6WezO1#对不同挂载点使用不同的配置)。

以下是一个通过 Operator 创建挂载点的 `ufs.yaml` 文件示例：

```yaml
apiVersion: k8s-operator.alluxio.com/v1
kind: UnderFileSystem
metadata:
  name: alluxio-oss
  namespace: alx-ns
spec:
  alluxioCluster: alluxio-cluster
  path: oss://<OSS_BUCKET>/<OSS_DIRECTORY>
  mountPath: /oss
  mountOptions:
    fs.oss.accessKeyId: <OSS_ACCESS_KEY>
    fs.oss.accessKeySecret: <OSS_ACCESS_KEY_SECRET>
    fs.oss.endpoint: <OSS_ENDPOINT>
```

如果不使用 Operator，可以通过以下命令将 `oss://<OSS_BUCKET>/<OSS_DIRECTORY>` 挂载到 `/oss` ：

```shell
bin/alluxio mount add --path /oss/ --ufs-uri oss://<OSS_BUCKET>/<OSS_DIRECTORY> \
  --option fs.oss.accessKeyId=<OSS_ACCESS_KEY> --option fs.oss.accessKeySecret=<OSS_ACCESS_KEY_SECRET> \
  --option fs.oss.endpoint=<OSS_ENDPOINT>
```

请注意，如果要挂载OSS bucket的根目录，请在bucket名称后面添加一个斜杠（例如`oss://OSS_BUCKET/`).

## 高级设置

请注意，配置选项可以指定为挂载选项，也可以作为`conf/alluxio-site.properties`中的配置属性。\
以下章节将介绍如何将配置作为属性来设置，但这些配置也可以通过 `--option <key>=<value>` 的方式作为挂载选项来设置。

### 启用HTTPS

要启用 HTTPS 协议来实现与OSS的安全通信，并为数据传输提供额外的安全层，请在 `conf/alluxio-site.properties` 文件中配置以下设置：

```properties
alluxio.underfs.oss.secure.http.enabled=true
```

### \[实验性] OSS 多部分上传

默认的上传方法是一次性从头到尾上传一个文件。我们使用多部分上传方法分多个部分上传一个文件，每个部分都将在一个线程中上传。上传时不会生成任何临时文件。

要启用 OSS 多部分上传，需要修改 `conf/alluxio-site.properties`，将以下内容包括在内：

```properties
alluxio.underfs.oss.multipart.upload.enabled=true
```

还可以在 `conf/alluxio-site.properties` 中指定其他参数，以加速程序运行。

```properties
# 使用分片上传时，上传分片的超时时间。
alluxio.underfs.object.store.multipart.upload.timeout
```

```properties
# OSS 分片上传的线程池大小。
alluxio.underfs.oss.multipart.upload.threads
```

```properties
# OSS 分片上传的分区大小。默认分区大小为 16MB。 
alluxio.underfs.oss.multipart.upload.part.size
```

### 设置请求重试策略

在访问底层存储系统（UFS）时，可能会因服务器暂时无法响应而出现错误。此时，可以为 UFS 请求配置重试策略。

每一个发往UnderFS的I/O请求，例如下载对象（getObject）、上传对象（putObject）、多段上传（MultipartUpload）, Alluxio 都会检查响应结果。\
如果响应是一个错误，并且错误代码表明可以重试，则将根据配置中的重试策略重新提交请求。Alluxio 将会持续重试直到请求成功或者达到了重试的最大次数。\
连续的成功重试间的等待间隔时间将会逐步从配置的基础休眠时间增长到最大休眠时间。

以下错误码被归类为可重试错误码：`500 HTTP_INTERNAL_ERROR`，`502 HTTP_BAD_GATEWAY`，`503 HTTP_UNAVAILABLE`，`503 Slow Down`，和 `504 HTTP_GATEWAY_TIMEOUT`。

**注意：**

* 4xx 错误码 通常代表客户端错误，比如：NOT\_FOUND，PERMISSION\_DENIED，UNAUTHENTICATED等等。此类错误不应重试，因为问题出在客户端。
* 5xx 错误码 通常代表服务端错误，但并不是所有的 5xx 错误都需要重试。比如 `501 HTTP_NOT_IMPLEMENTED` 就不应重试。

如需设置 UFS 访问请求的重试策略，需要修改 `conf/alluxio-site.properties` 文件，添加以下内容：

```properties
# 一个 UnderFS 访问请求的最大重试次数。
alluxio.underfs.business.retry.max.num=10

# 第一次失败后两次尝试之间的初始睡眠时间
alluxio.underfs.business.retry.base.sleep=30ms

# 两次尝试之间的最大睡眠时间
alluxio.underfs.business.retry.max.sleep=30s
```


---

# 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/ai-3.6/ufs/aliyun-oss.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.