文档中心

对象存储

请输入

使用第三方工具访问 TOS

使用 Rclone 访问 TOS

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

背景信息

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

前提条件

已创建火山引擎账号，并已开通对象存储 TOS 服务。

已获取当前账号的 AccessKeyID 和 AccessKeySecret 信息。

说明

您可以登录火山引擎控制台，然后单击右上角头像，选择开发者与工具 > API 密钥管理，即可查看 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/rclone-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 为例，请确保您已准备前提条件中的相关信息，示例如下。

注意

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 # bucket-demo 为桶名称。

上传本地文件

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

将本地文件夹中 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
表示保存的日志类型。

同步本地目录

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

警告

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

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

查看目录大小

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

例如您需要统计 bucket-demo 桶中的文件总数和容量大小，可执行如下命令。

rclone size volces-tos:bucket-demo

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

rclone size volces-tos:bucket-demo/testdir

文件比对校验

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

可选参数如下：

--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

最近更新时间：2026.09.10 18:52:08

这个页面对您有帮助吗？

有用

无用

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

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