文档中心

对象存储

请输入

tosutil

快速入门

本文介绍使用 tosutil 工具前，需要执行的初始化操作及常见的操作。

前提条件

已下载并安装 tosutil 工具，具体步骤，请参见下载与安装。

已获取 Region 及 Endpoint 信息，TOS 支持的 Region 及 Endpoint 信息，请参见地域及访问域名。

已获取访问密钥（Access Key ID 和 Secret Access Key）信息，查看 AK 和 SK 信息的具体步骤，请参见查看 AKSK 信息。

注意事项

本帮助文档中所有命令均是以 Linux 或 macOS 系统为例，Windows 系统的命令格式说明，请参见命令格式。

步骤一：初始化配置

（可选）使用 Linux 或 macOS 操作系统时，您需要执行以下命令，添加可运行权限。

Windows 系统可跳过该步骤，直接进行初始化设置。

chmod +x tosutil

使用 config 命令进行初始化配置，您可以参考使用场景，选择合适的初始化方式：

使用永久访问密钥

# -i 参数指定账号/子账号的 access key
# -k 参数指定账号/子账号的 secret key
# -e 参数指定访问的 endpoint
# -re 参数指定访问的 region
./tosutil config -i <access key> -k <secret key> -e <endpoint> -re <region>

使用临时访问密钥

# -i 参数指定临时 access key
# -k 参数指定临时 secret key
# -t 参数指定临时 security token
# -e 参数指定访问的 endpoint
# -re 参数指定访问的 region
./tosutil config -i <access key> -k <secret key> -t <security token> -e <endpoint> -re <region>

注意

请确保配置的 Endpoint 是 TOS 协议域名，而不是 S3 协议的域名，TOS 支持的 Region 及 Endpoint 信息，请参见地域及访问域名。

配置访问密钥命令运行后，会在操作系统的用户目录（macOS 或 Linux 操作系统的~目录，Windows 操作系统的 C:\Users\<username> 目录）下自动生成一个名为 .tosutilconfig 的配置文件，它包含了 tosutil 的所有配置信息。为了保证密钥安全避免泄露，tosutil 会自动加密您的信息。

匿名访问

tosutil 支持匿名访问功能。当您通过匿名的方式访问存储桶时，可以获取公共读的数据，也可以向设置为公共写的存储桶中写入数据。

使用 config 命令进行初始化配置时，无需指定密钥信息，设置密钥参数为 -i=、-k=、-t= 即可。

# -i 参数置空
# -k 参数置空
# -t 参数置空
# -e 参数指定访问的 endpoint
# -re 参数指定访问的 region
./tosutil config -i= -k= -t= -e <endpoint> -re <region>

步骤二：检查版本和连通性

初始化配置后，您可以通过以下方式检查 tosutil 工具的版本和连通性。

使用version命令检查工具的版本：

# 检查工具版本
./tosutil version

返回结果如下：

tosutil version: v1.1.0
operating system: darwin, arch: amd64

使用 ls 命令检查连通性：

# 该命令会返回当前账号的桶列表
./tosutil ls

返回结果如下：

Start at 2022-10-27 09:29:45.79638 +0000 UTC
Bucket CreationDate Location
tos://db-storage 2022-07-28T06:53:37Z cn-beijing

tos://tosutil 2022-07-05T09:40:35Z cn-beijing

Bucket number is: 2

说明

运行ls命令后，您可以根据命令回显结果，判断配置结果：

如果返回结果中包含 Bucket number is:，表明配置正确。

如果返回结果中包含 Http status [403]，表明访问密钥配置有误或访问密钥无权限。

如果返回结果中包含 A connection attempt failed，表明无法连接 TOS，请检查网络环境是否正常。

步骤三：快速使用

本文介绍使用 tosutil 工具创建存储桶、上传文件、下载文件及删除文件的常见命令。

执行以下命令，创建一个命名为 bucketname 的存储桶。

# 创建桶
./tosutil mb tos://bucketname

说明

创建存储桶的默认地域为工具初始化时设置的地域，如果您希望在其他地域创建存储桶，您可以使用 -re 命令，详细说明，请参见通用参数。

执行以下命令，将 file.txt 文件上传至 bucketname 存储桶。

# 上传单个对象，
./tosutil cp /temp/file.txt tos://bucketname/file.txt

执行以下命令，将 bucketname 存储桶中的 file.txt 文件下载至本地。

# 下载单个对象
./tosutil cp tos://bucketname/file.txt /temp/file.txt

执行以下命令，删除 bucketname 存储桶中的 file.txt 文件。

# 删除单个对象
./tosutil rm tos://bucketname/file.txt

注意

使用rm命令删除对象时，工具会提示您输入 y/n 进行二次确认，如果您希望强制删除，可以添加 -f 参数，详细说明，请参见 rm 命令。

执行以下命令，将 test_folder 文件夹上传至 bucketname 存储桶。

# 上传文件夹
./tosutil cp /temp/test_folder tos://bucketname -r

执行以下命令，将 bucketname 存储桶中的 test_folder 文件夹下载至本地。

# 下载文件夹
./tosutil cp tos://bucketname/test_folder/ /temp/ -r

执行以下命令，删除 bucketname 存储桶中的 test_folder 文件夹。

# 删除文件夹
./tosutil rm tos://bucketname/test_folder/ -r

帮助文档

tosutil 工具内置了帮助文档，您可以使用 help 命令查看帮助文档。

# 查看帮助文档
./tosutil help

帮助文档支持中文和英文两种语言，您可以参考以下命令，修改帮助文档的语种。

# 修改帮助文档的语种
vim ~/.tosutilconfig
# 修改 helpLanguage 枚举值支持的值：
# Chinese
# English

最近更新时间：2025.08.20 14:36:49

这个页面对您有帮助吗？

有用

无用