文档中心

对象存储

请输入

tosfsspec

tosfsspec 快速入门

本文旨在引导您快速上手 tosfsspec，完成环境准备、认证授权与基本的文件操作。

依赖说明

tosfsspec 的正常运行依赖以下核心组件，pip 会自动为您处理这些依赖的安装：

Python: >= 3.8, < 3.14。

fsspec: >= 2023.5.0，提供了文件系统规范的基类。

tos: >= 2.8.0，火山引擎官方提供的 TOS Python SDK。

tosnativeclient: >=1.1.13，为 tosfsspec 提供底层的高性能内核，负责网络请求、并发控制、CRC 校验等核心功能。

操作系统

说明

如有对特定操作系统的支持诉求，请提交工单联系我们。

仅支持 Linux x86_64 和 MacOS arm64 系统。

操作步骤

如您已安装 Python 以及对应的 pip 工具。请确认已安装版本符合 tosfsspec 依赖说明。

python --version
pip --version

使用 pip 可以直接安装 tosfsspec。

pip install tosfsspec

获取 AKSK 信息。

地域（Region）：您的 TOS 存储桶所在的地域，例如 cn-beijing。

访问密钥（Access Key）：包含 Access Key ID (AK) 和 Secret Access Key (SK)，是访问火山引擎 API 的身份凭证。

访问域名（Endpoint）：可选参数。如果留空，tosfsspec 会根据您提供的 region 自动生成。

说明

关于地域和访问域名的详细列表，请参见地域和访问域名（Endpoint）。

如何创建和管理访问密钥，请参见 API 访问密钥（Access Key）。

配置长期访问凭证。

初始化 SDK 前，您需要先配置长期访问凭证，不同操作系统下配置长期访问凭证的操作步骤如下。

macOS
Linux
打开终端并执行以下命令打开文件。

nano ~/.bash_profile

在文件末尾添加 AKSK 信息。

export TOS_ACCESS_KEY=AKTPYmI1Z****
export TOS_SECRET_KEY=T1dJM01UU****

保存文件并退出。
执行以下命令生效配置信息。

source ~/.bash_profile

执行以下命令验证配置信息。

echo $TOS_ACCESS_KEY
echo $TOS_SECRET_KEY

如果配置成功，则返回如下示例：

AKTPYmI1Z****
T1dJM01UU****
打开终端并执行以下命令打开文件。

sudo vim /etc/profile

在文件末尾添加 AKSK 信息。

export TOS_ACCESS_KEY=AKTPYmI1Z****
export TOS_SECRET_KEY=T1dJM01UU****

保存文件并退出。
执行以下命令生效配置信息。

source /etc/profile

执行以下命令验证配置信息。

echo $TOS_ACCESS_KEY
echo $TOS_SECRET_KEY

如果配置成功，则返回如下示例：

AKTPYmI1Z****
T1dJM01UU****

初始化文件系统，以下代码用于使用 TOS 域名初始化。

import tosfsspec
import os
import tos

# 从环境变量获取 AKSK 信息
key = os.getenv('TOS_ACCESS_KEY')
secret = os.getenv('TOS_SECRET_KEY')
# 初始化 TosFileSystem
fs = tosfsspec.TosFileSystem(
key=key,secret=secret,
endpoint = "your endpoint",
region = "your region"
)

基本操作示例

文件读写操作

使用 fs.open() 方法可以像操作本地文件一样读写 TOS 上的对象。它返回一个文件类对象，支持 read()、write() 等标准方法。

写入文件

以二进制写入（wb）模式打开一个路径。当 with 代码块执行完毕后，数据会自动上传至 TOS。

# 定义要写入的 Bucket 和对象 Key
bucket = 'your-bucket'
key = 'path/to/your/file.txt'
full_path = f'tos://{bucket}/{key}'

# 写入数据
data_to_write = b'Hello, tosfsspec!'
with fs.open(full_path, 'wb') as f:
f.write(data_to_write)

print(f'文件已成功写入到: {full_path}')

读取对象

以二进制读取（rb）模式打开一个已存在的对象。

# 从 TOS 读取刚刚写入的文件
with fs.open(full_path, 'rb') as f:
content = f.read()

print(f'从文件读取到的内容: {content.decode()}')
# 输出: 从文件读取到的内容: Hello, tosfsspec!

基础文件操作

TosFileSystem 提供了丰富的文件系统操作方法。

列出桶 (List Buckets)

当路径为根目录 / 或空字符串 '' 时，fs.ls()会列出您账户下所有的存储桶。

# 列出所有 bucket
buckets = fs.ls('/')
for b in buckets:
print(b['name'])

列出对象 (List Objects)

fs.ls() 方法用于列出指定路径下的文件和目录。

# 创建一些文件和目录用于演示
fs.touch(f'tos://{bucket}/data/file1.txt')
fs.touch(f'tos://{bucket}/data/file2.csv')
fs.makedirs(f'tos://{bucket}/data/images/')
fs.touch(f'tos://{bucket}/data/images/photo.jpg')

# 列出 'data/' 目录下的内容
print(f'--- ls tos://{bucket}/data/ ---')
file_list = fs.ls(f'tos://{bucket}/data/')
for item in file_list:
print(f"- {item['name']} (type: {item['type']}, size: {item['size']})")

输出示例：

--- ls tos://your-bucket/data/ ---
- your-bucket/data/file1.txt (type: file, size: 0)
- your-bucket/data/file2.csv (type: file, size: 0)
- your-bucket/data/images (type: directory, size: 0)

上传与下载 (put/get)

使用 fs.put() 和 fs.get() 可以在本地文件系统和 TOS 之间传输完整文件。

# 创建一个本地文件
local_file_path = 'local_example.txt'
with open(local_file_path, 'w') as f:
f.write('This is a local file.')

# 上传本地文件到 TOS
remote_path_for_put = f'tos://{bucket}/uploads/uploaded_file.txt'
fs.put(local_file_path, remote_path_for_put)
print(f'{local_file_path} 已上传至 {remote_path_for_put}')

# 从 TOS 下载文件到本地
local_download_path = 'downloaded_from_tos.txt'
fs.get(remote_path_for_put, local_download_path)
print(f'{remote_path_for_put} 已下载至 {local_download_path}')

# 验证下载内容
with open(local_download_path, 'r') as f:
print(f'下载的文件内容: {f.read()}')

# 清理本地文件
import os
os.remove(local_file_path)
os.remove(local_download_path)

复制、移动和删除 (cp/mv/rm)

以下操作用于在 TOS 内部管理对象。

fs.cp(): 复制对象。

fs.mv(): 移动或重命名对象。

# 复制文件
src_path = f'tos://{bucket}/data/file1.txt'
dst_path = f'tos://{bucket}/data/file1_copy.txt'
fs.cp(src_path, dst_path)
print(f'文件已复制: {fs.exists(dst_path)}') # 输出: True

# 移动 (重命名) 文件
mv_src = dst_path
mv_dst = f'tos://{bucket}/data/file1_renamed.txt'
fs.mv(mv_src, mv_dst)
print(f'原文件是否存在: {fs.exists(mv_src)}') # 输出: False
print(f'新文件是否存在: {fs.exists(mv_dst)}') # 输出: True

# 删除文件
fs.rm(mv_dst)
exists = fs.exists(mv_dst)
print(f'重命名后的文件是否存在: {exists}') # 输出: False

# 递归删除目录
fs.rm(f'tos://{bucket}/data/', recursive=True)
exists = fs.exists(f'tos://{bucket}/data/')
print(f'data 目录是否存在: {exists}') # 输出: False

使用 fs.walk() 和 fs.glob() 可以实现复杂的对象查找。

fs.walk(): 递归遍历指定目录下的所有对象和子目录。

fs.glob(): 使用通配符模式（如 * 和 **）查找匹配的对象。

# 准备目录结构
fs.makedirs(f'tos://{bucket}/glob_test/a/b/')
fs.touch(f'tos://{bucket}/glob_test/a/file.txt')
fs.touch(f'tos://{bucket}/glob_test/a/b/file.log')

# 使用 walk 遍历
print('--- walk ---')
for root, dirs, files in fs.walk(f'tos://{bucket}/glob_test/'):
print(f'Root: {root}, Dirs: {dirs}, Files: {files}')

# 使用 glob 查找
print('\n--- glob ---')
log_files = fs.glob(f'tos://{bucket}/glob_test/**/*.log')
print(f'找到的 .log 文件: {log_files}')

获取元信息与检查存在性 (info/exists)

info() 或 stat(): 获取文件或目录的详细信息。

exists(): 检查路径是否存在。

path_to_check = f'tos://{bucket}/data/file1.txt'
fs.touch(path_to_check)

# 检查存在性
if fs.exists(path_to_check):
print(f'{path_to_check} 存在。')
# 获取元信息
info = fs.info(path_to_check)
print(f'{info}')
else:
print(f'{path_to_check} 不存在。')

最近更新时间：2026.09.18 18:48:43

这个页面对您有帮助吗？

有用

无用