# 火山引擎 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 存储桶或使用现有的存储桶                                                                                                                                                                                    |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<TOS_DIRECTORY>`         | 您要在存储桶中使用的目录，可以是创建新目录或使用现有目录                                                                                                                                                                               |
| `<TOS_ACCESS_KEY_ID>`     | <p>TOS 的 <a href="https://www.volcengine.com/docs/6291/65568">访问密钥 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">秘密访问密钥</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>                                                    |

## 基本设置

通用挂载机制和 `UnderFileSystem` CR 字段参考，请参阅[底层存储](https://documentation.alluxio.io/ee-ai-cn/ufs/pages/QHxxAwAliFxrTQ5jOZw7#基本挂载配置)。

{% tabs %}
{% tab title="Kubernetes (Operator)" %}
使用 operator 创建 TOS 挂载点的 `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>
```

{% endtab %}

{% tab title="Docker / 裸机" %}
如果不使用 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/`）。
{% endtab %}
{% endtabs %}

## 高级设置

请注意，配置选项可以指定为挂载选项或 `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 分片上传

我们使用分片上传方法将一个文件分多个部分上传，每个部分将在一个线程中上传。上传时不会生成任何临时文件。

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

```properties
# Timeout for uploading part when using multipart upload.
alluxio.underfs.object.store.multipart.upload.timeout
```

```properties
# Thread pool size for TOS multipart upload.
alluxio.underfs.tos.multipart.upload.threads
```

```properties
# Multipart upload partition size for TOS. The default partition size is 64MB.
alluxio.underfs.tos.multipart.upload.part.size
```

禁用 TOS 分片上传，上传方法将一次性从头到尾完整上传一个文件。您需要修改 `conf/alluxio-site.properties` 以包含：

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

### 设置请求重试策略

适用于所有对象存储 UFS 类型的重试配置，请参阅 UFS 概览中的[请求重试策略](https://documentation.alluxio.io/ee-ai-cn/ufs/pages/QHxxAwAliFxrTQ5jOZw7#请求重试策略)。

### 高并发调优

将 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 毫秒。


---

# 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/tos.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.