# 火山引擎 TOS

本指南介绍如何将[火山引擎对象存储服务(TOS)](https://www.volcengine.com/product/TOS) 配置为 Alluxio 的底层存储系统。\
火山引擎对象存储服务 (TOS) 是火山引擎提供的海量、安全、低成本、易用、高可靠、高可用的分布式云存储服务。

## 先决条件

在将 TOS 用于 Alluxio 之前，请按照 [TOS 快速入门指南](https://www.volcengine.com/docs/6349/74830) 注册 TOS 并创建一个 TOS 存储桶。

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

| `<TOS_BUCKET>`            | 创建一个新的 TOS 存储桶或使用一个现有的存储桶                                                                                                                                                                              |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `<OS_DIRECTORY>`          | 要在存储桶中使用的目录，可以是新创建的一个目录或者一个现有目录                                                                                                                                                                        |
| `<TOS_ACCESS_KEY_ID>`     | <p>TOS 的 <a href="https://www.volcengine.com/docs/6291/65568">Access Key ID</a>，<br>在 <a href="https://console.volcengine.com/iam/keymanage/">TOS AccessKey 管理控制台</a> 中创建和管理</p>                       |
| `<TOS_ACCESS_KEY_SECRET>` | <p>TOS 的 <a href="https://www.volcengine.com/docs/6291/65568">Secret Access Key</a>，<br>在 <a href="https://console.volcengine.com/iam/keymanage/">TOS AccessKey 管理控制台</a> 中创建和管理</p>                   |
| `<TOS_ENDPOINT>`          | <p>存储桶的网络接口，可在存储桶概览页面找到，其值类似 <code>tos-cn-beijing.volces.com</code> 和 <code>tos-cn-guangzhou.volces.com</code>。<br>可用的接口列在 <a href="https://www.volcengine.com/docs/6349/107356">TOS 网络接口文档</a> 中。</p> |
| `<TOS_REGION>`            | <p>存储桶所在的区域，例如 <code>cn-beijing</code> 或 <code>cn-guangzhou</code>。<br>可用的区域列在 <a href="https://www.volcengine.com/docs/6349/107356">TOS 区域文档</a> 中。</p>                                               |

## 基本设置

使用[挂载表操作](https://documentation.alluxio.io/ee-ai-cn/ai-3.6/overview/namespace#挂载表操作)来添加新的挂载点, 需指定在其上创建挂载的Alluxio路径，并指定TOS路径作为UFS URI。\
在挂载操作中，还可以同时指定凭证和配置选项，具体方法请参阅[配置挂载点](https://documentation.alluxio.io/ee-ai-cn/ai-3.6/overview/namespace#对不同挂载点使用不同的配置)的说明。

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

```yaml
apiVersion: k8s-operator.alluxio.com/v1
kind: UnderFileSystem
metadata:
  name: alluxio-tos
  namespace: alx-ns
spec:
  alluxioCluster: alluxio-cluster
  path: tos://<TOS_BUCKET>/<TOS_DIRECTORY>
  mountPath: /tos
  mountOptions:
    fs.tos.accessKeyId: <TOS_ACCESS_KEY>
    fs.tos.accessKeySecret: <TOS_ACCESS_KEY_SECRET>
    fs.tos.endpoint: <TOS_ENDPOINT>
    fs.tos.region: <TOS_REGION>
```

不使用 Operator 的情况下, 将 `tos://<TOS_BUCKET>/<TOS_DIRECTORY>` 挂载到 `/tos` 路径的示例命令如下：

```shell
bin/alluxio mount add --path /tos/ --ufs-uri tos://<TOS_BUCKET>/<TOS_DIRECTORY> \
  --option fs.tos.accessKeyId=<TOS_ACCESS_KEY> --option fs.tos.accessKeySecret=<TOS_ACCESS_KEY_SECRET> \
  --option fs.tos.endpoint=<TOS_ENDPOINT> --option fs.tos.region=<TOS_REGION>
```

请注意，如果要挂载 TOS 存储桶的根目录，请在存储桶名称后添加斜线（如 `tos://TOS_BUCKET/`）。

## 进阶设置

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

### 启用 HTTPS

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

```properties
fs.tos.endpoint=https://<TOS_ENDPOINT>
alluxio.underfs.tos.secure.http.enabled=true
```

### TOS 分片上传

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

要启用 TOS 分片上传，需要修改 `conf/alluxio-site.properties` 以包含：

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

您可以在 `conf/alluxio-site.properties` 中指定其他参数，以加速上传。

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

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

```properties
# TOS 分片上传的分区大小。默认分区大小为 16MB。
alluxio.underfs.tos.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
```

### 高并发调优

将 Alluxio 与 TOS 集成时，可以通过调整以下配置来优化性能：

* `alluxio.underfs.tos.retry.max`： 控制 TOS 的重试次数。默认值为 3。
* `alluxio.underfs.tos.read.timeout`： 控制 TOS 的读取超时时间。默认值为 30000 毫秒。
* `alluxio.underfs.tos.write.timeout`： 控制 TOS 写超时时间。默认值为 30000 毫秒。
* `alluxio.underfs.tos.streaming.upload.partition.size`： 控制 TOS 流式上传的分区大小。默认值为 64MB。
* `alluxio.underfs.tos.connect.timeout`： 控制 TOS 的连接超时时间。默认值为 30000 毫秒