文档中心

使用 Rclone 访问 TOS

最近更新时间：2023.05.22 18:50:29

首次发布时间：2021.12.15 10:23:00

Rclone 是一款功能强大的开源命令行工具，支持对接各种云存储系统（包括兼容 S3 协议的对象存储），可用来执行数据上传、下载、同步、管理等操作。火山引擎对象存储 TOS 兼容标准 S3 协议，本文介绍如何使用 Rclone 工具访问 TOS。

背景信息

关于 Rclone 的详细信息，请参见 Rclone 官网。

前提条件

请确保您已创建火山引擎账号，并已开通对象存储 TOS 服务。
请确保您已获取当前账号的 AccessKeyID 和 AccessKeySecret 信息。
说明
您可以登录火山引擎控制台，然后单击右上角头像，选择密钥管理，即可查看 AccessKeyID 和 AccessKeySecret 信息，更多信息，请参见密钥管理。
获取 TOS 的 S3 Endpoint 信息，详情请参见地域和访问域名（Endpoint）。

步骤一：安装工具

使用 Rclone 访问 TOS 前，您需要先安装工具，本章节介绍在不同操作系统下的安装方式。

macOS 操作系统（或 Linux 及 BSD 操作系统）
本章节以在 macOS 操作系统下安装 Rclone 为例（Linux 及BSD 操作系统下安装命令相同），您可以直接执行如下命令。
```
curl https://rclone.org/install.sh | sudo bash
```

火山引擎 ECS Linux 云主机

如果您是在火山引擎 ECS Linux 云主机上安装 Rclone，可以执行如下命令：

//下载安装包并解压
wget https://tos-tools.tos-cn-beijing.volces.com/third-party%2Frclone-current-linux-amd64.zip
unzip rclone-current-linux-amd64.zip
cd rclone-v1.58.0-linux-amd64

//拷贝二进制文件并修改权限
sudo cp rclone /usr/bin/
sudo chown root:root /usr/bin/rclone
sudo chmod 755 /usr/bin/rclone

//检查是否已安装成功
rclone version

其他安装方式
其他安装方式，您可参见安装 Rclone。

步骤二：配置连接信息

本文以火山引擎华北2（北京）区域 TOS 为例，请确保您已准备前提条件中的相关信息，示例如下。

AccessKey ID：AKLTYTBjY*******
AccessKey Secret：TVdaaFkyRTNNa*****
Region：cn-beijing
Endpoint：https://tos-s3-cn-beijing.volces.com ##如果是内网访问，则 Endpoint 为 https://tos-s3-cn-beijing.ivolces.com

注意

Endpoint 需设置为 S3 Endpoint 信息，S3 Endpoint 详情，请参见地域和访问域名（Endpoint）。
请注意 Endpoint 的内外网区别，使用外网 Endpoint 会产生公网访问流量费用。

执行如下命令，在 Rclone 工具中配置 TOS 连接。
```
rclone config
```

依次选择如下选项或输入相关信息。

注意

Rclone 版本不同，配置选项的数字编号可能会不同，请您根据选项的文字描述进行选择。

n) New remote  //新建远程连接。

name> volces-tos  //输入连接名称，本文中以 volces-tos 为例。

5 / Amazon S3 Compliant Storage Providers including AWS, Alibaba, Ceph, Digital Ocean, Dreamhost, IBM COS, Minio, SeaweedFS, and Tencent COS
   \ "s3"   //选择兼容 S3 协议的存储类型。

14 / Any other S3 compatible provider
   \ "Other"   //选择其他 S3 兼容的存储提供商。

1 / Enter AWS credentials in the next step
   \ "false"   //在下一步输入密钥。

access_key_id> AKLTYTBjY*******  //输入AK。

secret_access_key> TVdaaFkyRTNNa*****  //输入SK。

region> cn-beijing  //输入 Region ID。

endpoint> https://tos-s3-cn-beijing.volces.com //输入 Endpoint。

location_constraint>    //按 Enter 键置空，保持默认即可。

acl>  //按 Enter 键置空，保持默认即可。

n) No (default) //不编辑高级配置，保持默认即可。

y) Yes this is OK (default)  //查看配置预览信息，然后选择 y。

q) Quit config  //退出配置界面。

配置完成后，您可以执行如下命令查看当前已存在的连接信息。

rclone config show

注意

配置完成后，Rclone 默认会使用 Path 模式访问对象存储，在访问 TOS 时需要您修改为虚拟主机模式。
Rclone 默认会使用 HTTP2 访问对象存储，在访问 TOS 时需要禁用 HTTP2 模式。

修改步骤如下所示。

执行如下命令获取配置文件的详细路径。
```
rclone config file
```

打开配置文件，在连接配置的末尾增加如下内容。

参数	是否必选	说明
force_path_style = false	必选	禁用 Path 模式访问对象存储。
disable_http2 = true	必选	禁用 HTTP2 模式访问对象存储。
list_version = 2	可选	使用 V2 版本的接口列举对象。与 V1 接口相比，V2 接口调用参数更全面，优化了 V1 接口存在的超时问题。说明如果您未在配置文件中添加该参数，您也可以在使用列举命令时添加 `--s3-list-version 2`参数。具体示例，请参见查看桶或目录。

修改后的配置文件如下所示。

[volces-tos]
type = s3
provider = Other
access_key_id = AKLTYTBjY*******
secret_access_key = TVdaaFkyRTNNa*****
region = cn-beijing
endpoint = https://tos-s3-cn-beijing.volces.com
force_path_style = false
disable_http2 = true
list_version = 2

其他：常用操作

安装工具并配置 TOS 连接信息后，您可以执行相应操作。本文介绍您在使用 TOS 过程中的常见命令，例如查看目录、上传文件、查看目录大小等。更多命令介绍，请参见 Rclone 命令。

查看桶或目录

说明

推荐您使用 V2 接口列举对象。相比 V1 接口，V2 接口调用参数更全面，优化了 V1 接口存在的超时问题。您可以通过以下方式使用 V2 接口：

在配置文件中设置 list_version = 2。
直接在命令后增加 --s3-list-version 2 参数。

查看当前账号下所有桶列表，可执行如下命令。

rclone lsd volces-tos: --s3-list-version 2 //volces-tos 为配置的远程连接名称。

查看某个桶内的一级文件夹列表，可执行如下命令。

rclone lsd volces-tos:bucket-demo --s3-list-version 2 //bucket-demo 为桶名称。

上传本地文件

通过使用 rclone copy 命令可将源端数据拷贝到目标端，通用命令格式如下。

rclone copy source:sourcepath dest:destpath

将本地文件夹中 testdir 中的所有文件复制到 bucket-demo 桶中，并放置到桶根目录下，可执行如下命令。
```
rclone copy testdir volces-tos:bucket-demo
```
将本地文件夹 testdir 复制到 bucket-demo 桶中，并让 testdir 作为桶内的一级目录，可执行如下命令。
```
rclone copy testdir volces-tos:bucket-demo/testdir
```

当原始文件大于 5GiB（对象存储普通上传接口只支持不超过 5GiB 的文件）或者想要提升大文件上传速率，可执行如下命令调用分片上传参数。

rclone copy  testdir  volces-tos:bucket-demo/testdir -P  --s3-upload-cutoff 1G --s3-upload-concurrency 8 --s3-chunk-size 16M

分片上传参数说明如下。

参数	说明
--s3-upload-cutoff	文件大于设置值时，会使用分片上传，默认值为 200M，最大值为 5G。
--s3-upload-concurrency	同时上传的分片数量，默认值为 4。上传少量大型文件时，提高该参数可以提升带宽，建议该值不要超过 16。
--s3-chunk-size	分片的大小，默认值为 5M，建议不要超过 32M。

增加传输数据并发度可提升传输速率，但是并发越高占用主机资源也会越多，建议执行如下命令灵活调整主机规格。
```
rclone copy  testdir  volces-tos:bucket-demo/testdir --transfers=32 --checkers=32   -P
```
参数说明如下。
参数说明
--transfers 表示并发迁移的文件个数，默认值为 4，建议不超过 128。
--checkers 表示校验的文件个数，默认值为 8，建议不超过 128。
当目的端文件较多时，可执行如下命令直接查找目标文件，而不需要通过目的端文件列表。
```
rclone copy  testdir  volces-tos:bucket-demo/testdir --no-traverse
```
说明
--no-traverse 表示不遍历目的端文件。
可执行如下命令保存文件传输过程中的日志文件，支持 DEBUG|INFO|NOTICE|ERROR (default "NOTICE")。
```
rclone copy  testdir  volces-tos:bucket-demo/testdir  --log-file /root/rclone.log  --log-level DEBUG
```
参数说明如下。
参数说明
--log-file 表示日志保存的路径。
--log-level 表示保存的日志类型。

参数	说明
--transfers	表示并发迁移的文件个数，默认值为 4，建议不超过 128。
--checkers	表示校验的文件个数，默认值为 8，建议不超过 128。

参数	说明
--log-file	表示日志保存的路径。
--log-level	表示保存的日志类型。

同步本地目录

当您需要同步增量数据到目标端（包括新增文件和被修改过的文件）时，可使用 rclone sync 命令。

rclone sync source:path dest:path [flags]

警告

该命令会修改目标端数据，使得目标端和源端数据完全一致，即可能会删除目标端某些数据，请谨慎操作。

如果您需要让桶内 testdir 文件夹中数据和本地文件夹 testdir 完全一致，可执行如下命令。

rclone sync testdir volces-tos:bucket-demo/testdir

查看目录大小

如果您需要统计桶或者目录下的文件个数和总容量，可执行 rclone size 命令。

rclone size remote:path [flags]

例如您需要统计 bucket-demo 桶中的文件总数和容量大小，可执行如下命令。
```
rclone size volces-tos:bucket-demo
```
例如您需要统计 bucket-demo 桶中 testdir 文件夹的文件总数和容量大小，可执行如下命令。
```
rclone size volces-tos:bucket-demo/testdir
```

文件比对校验

如果您需要比对源端和目标端的数据，可执行 rclone check 命令。

rclone check source:path dest:path [flags]

可选参数如下：

--size-only：只比较文件大小。
--download：下载远程文件并对比。

常见问题

使用 rclone 工具上传对象时发现速率无法提升，是什么原因？
这种情况可能是 rclone 的使用姿势不对，您可以尝试携带跳过数据检查的参数 --no-check-dest 和 --no-traverse，确认能否提升上传速率。更多关于 rclone 的参数说明，请参见 rclone global flags。
使用 rclone 工具上传对象时，报错 Forbidden path to access server 怎么办？
对象存储不支持 Path Style 形式访问，应使用 Virtual Style 形式（即虚拟主机访问方式）访问。目前第三方 SDK 默认仍使用 Path Style 形式访问，所以会产生此问题。Path 和 VirtualHost 的区别主要在于 HTTP URL 中桶名的位置，如下所示：
```
# Path 访问方式
https://tos-s3-cn-beijing.volces.com/{bucketname}

# VirtualHost 访问方式
https://{bucketname}.tos-s3-cn-beijing.volces.com
```