# 百度智能云对象存储 BOS

本指南介绍如何将[百度智能云对象存储(BOS)](https://cloud.baidu.com/doc/BOS/index.html) 配置为 Alluxio 的底层存储系统。\
百度智能云对象存储BOS(Baidu Object Storage)提供稳定、安全、高效以及高扩展存储服务。

## 先决条件

在将 BOS 用于 Alluxio 之前，请按照 [BOS 快速入门流程](https://cloud.baidu.com/doc/BOS/s/Ik4xtp41n) 注册 BOS 并创建一个 BOS 存储桶。

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

| `<BOS_BUCKET>`            | 创建一个新的 BOS 存储桶或使用一个现有的存储桶                                                                                                                                                                       |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<OS_DIRECTORY>`          | 要在存储桶中使用的目录，可以是新创建的一个目录或者一个现有目录                                                                                                                                                                 |
| `<BOS_ACCESS_KEY_ID>`     | <p>BOS 的 <a href="https://cloud.baidu.com/doc/Reference/s/jjwvz2e3p">Access Key ID</a>，<br>在 <a href="https://cloud.baidu.com/doc/Reference/s/9jwvz2egb">BOS AccessKey 管理控制台</a> 中创建和管理</p>     |
| `<BOS_ACCESS_KEY_SECRET>` | <p>BOS 的 <a href="https://cloud.baidu.com/doc/Reference/s/jjwvz2e3p">Secret Access Key</a>，<br>在 <a href="https://cloud.baidu.com/doc/Reference/s/9jwvz2egb">BOS AccessKey 管理控制台</a> 中创建和管理</p> |
| `<BOS_ENDPOINT>`          | <p>存储桶的网络接口，可在存储桶概览页面找到，其值类似 <code>bj.bcebos.com</code> 和 <code>gz.bcebos.com</code>。<br>可用的接口列在 <a href="https://cloud.baidu.com/doc/BOS/s/akrqd2wcx">Region与Endpoint</a> 中。</p>               |
| `<BOS_REGION>`            | <p>存储桶所在的区域，例如 <code>cn-beijing</code> 或 <code>cn-guangzhou</code>。<br>可用的区域列在 <a href="https://cloud.baidu.com/doc/BOS/s/akrqd2wcx">Region与Endpoint</a> 中。</p>                                 |

## 基本设置

使用[挂载表操作](https://documentation.alluxio.io/ee-ai-cn/ai-3.6/ufs/pages/vItTjDEwYA3ygh6WezO1#挂载表操作)来添加新的挂载点, 需指定在其上创建挂载的Alluxio路径，并指定BOS路径作为UFS URI。\
在挂载操作中，还可以同时指定凭证和配置选项，具体方法请参阅[配置挂载点](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-bos
  namespace: alx-ns
spec:
  alluxioCluster: alluxio-cluster
  path: bos://<BOS_BUCKET>/<BOS_DIRECTORY>
  mountPath: /bos
  mountOptions:
    fs.bos.accessKeyId: <BOS_ACCESS_KEY>
    fs.bos.accessKeySecret: <BOS_ACCESS_KEY_SECRET>
    fs.bos.endpoint: <BOS_ENDPOINT>
```

不使用 Operator 的情况下, 将 `bos://<BOS_BUCKET>/<BOS_DIRECTORY>` 挂载到 `/bos`的命令示例如下：

```shell
bin/alluxio mount add --path /bos/ --ufs-uri bos://<BOS_BUCKET>/<BOS_DIRECTORY> \
  --option fs.bos.accessKeyId=<BOS_ACCESS_KEY> --option fs.bos.accessKeySecret=<BOS_ACCESS_KEY_SECRET> \
  --option fs.bos.endpoint=<BOS_ENDPOINT>
```

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

## 进阶设置

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

### 启用HTTPS访问

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

```properties
fs.bos.endpoint=<BOS_ENDPOINT>
alluxio.underfs.bos.secure.http.enabled=true
```

### BOS 分片上传

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

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

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

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

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

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

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

### 设置请求重试策略

有时可能会因为服务器暂时无法响应，而在访问UFS时出现错误。您可以为UFS请求配置一个重试政策。

每一个发往UnderFS的I/O请求，例如下载对象、上传对象、多段上传, 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 与 BOS 集成时，可以通过调整以下配置来优化性能：

* `alluxio.underfs.bos.connection.max`: 控制 BOS 的最大连接数。默认值为 1024。
* `alluxio.underfs.bos.io.threads.num`: 控制 BOS 的IO线程数。默认值为 256。
* `alluxio.underfs.bos.socket.timeout`: 控制 BOS 的socket超时时间。默认值为 50 秒。
* `alluxio.underfs.bos.connect.timeout`： 控制 BOS 的连接超时时间。默认值为 50 秒。


---

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