You need to enable JavaScript to run this app.
文档中心
对象存储

对象存储

请输入
  • 文档首页
    • 对象存储工具指南tosfsspectosfsspec 使用进阶
复制全文
下载 pdf
我的收藏
tosfsspec
tosfsspec 使用进阶
复制全文
下载 pdf
我的收藏
tosfsspec 使用进阶
本文主要介绍 tosfsspec 的进阶能力，聚焦高性能、数据一致性以及特定业务场景的实践需求。​
分片上传与下载​
处理大文件时，tosfsspec 会自动启用分片（Multipart）机制，将文件拆分为多个部分并行传输，以提升速度与稳定性。​
分片大小 (part_size 和 block_size)​
  • TosFileSystem(part_size=...)：初始化 TosFileSystem 时设置的 part_size 是全局默认值，主要影响 cp_file 等涉及服务端复制/分片复制的操作。​
  • fs.open(..., block_size=...)：在 open() 方法中的 block_size 更为常用，直接决定写入 (wb, ab) 或读取 (rb) 文件时的缓冲块大小。​
  • 写入模式 (wb, ab)：​
  • block_size 决定每次向 TOS 上传的分片大小。为满足 TOS 要求，该值必须大于等于 4MB；未显式设置时，则使用 TosFileSystem 的 part_size。​
说明​
写入大文件时，建议将 block_size 设置为 8MB～128MB 之间，具体取决于网络状况和文件大小。大多数场景可从 8MB 起步。​
  • 读取模式 (rb)：​
  • block_size 决定了每次从 TOS 下载的数据块大小，即是执行 file.read(size) 时，底层客户端预取的数据量。合理的 block_size 可以优化随机读性能。​
  • 代码示例如下：​
  • ​
    # 写入时指定 10MB 的分片大小​
    with fs.open('tos://my-bucket/large_file.dat', 'wb', block_size=10 * 1024 * 1024) as f:​
    # 写入 20MB 数据，将会被拆分为 2 个分片上传​
    f.write(b'a' * 20 * 1024 * 1024) ​
    ​
并发任务控制​
tosfsspec 底层使用高性能内核执行高并发网络请求，可通过初始化参数调整并发池规模。​
  • shared_prefetch_tasks：读取数据时的预拉取任务并发数。​
  • shared_upload_part_tasks：分片上传任务并发数。​
  • shared_upload_part_copy_tasks：分片复制任务并发数。​
提高并发可增加并行度，在网络条件良好时可能提升传输速度，但也会带来更高的 CPU 与内存开销。代码示例如下所示：​
​
# 增加上传并发数到 64​
fs = tosfsspec.TosFileSystem(​
...,​
shared_upload_part_tasks=64​
)​
​
追加写入 ('ab' 模式）​
tosfsspec 支持以追加模式（ab）打开对象，适用于持续写入日志、增量更新等场景；底层依赖 TOS 的 AppendObject 能力。代码示例如下所示：​
注意​
追加写要求目标对象必须为 Appendable 类型。tosfsspec 在首次以 wb 创建对象时，默认会创建可追加对象；若对非可追加对象（例如由其他工具上传的普通对象）执行追加，可能失败。​
​
path = f'tos://{bucket}/logs/app.log'​
# 第一次写入​
with fs.open(path, 'wb') as f:​
f.write(b'Log entry 1\n')​
# 第二次追加​
with fs.open(path, 'ab') as f:​
f.write(b'Log entry 2\n')​
# 读取验证​
with fs.open(path, 'rb') as f:​
content = f.read()​
print(content)​
# 输出: b'Log entry 1\nLog entry 2\n'​
​
内容类型 (Content-Type)​
上传对象时，tosfsspec 会尝试自动推断 Content-Type（MIME 类型），便于浏览器等客户端按正确类型访问。​
  • put_file()：根据本地文件的扩展名自动推断。​
  • open(..., 'wb') 或 touch()：根据对象 Key 的扩展名自动推断。​
如需覆盖自动推断，可在 open()、touch() 或 put_file() 中通过 ContentType 参数进行显式覆盖指定。代码示例如下所示：​
​
# 自动推断​
fs.touch('tos://my-bucket/assets/style.css') # Content-Type 会被设为 'text/css'​
​
# 显式指定​
# 即使文件扩展名为 .txt，也将其 Content-Type 设为 'application/json'​
with fs.open('tos://my-bucket/config.txt', 'wb', ContentType='application/json') as f:​
f.write(b'{"key": "value"}')​
​
数据校验 (enable_crc)​
默认情况下，enable_crc=True，tosfsspec 会在数据传输完成后使用 CRC64 校验，确保本地与远端数据一致，提供强有力的数据完整性保障。若对性能要求极高且可接受极低概率的数据损坏风险，可关闭该校验。代码示例如下所示：​
​
# 关闭 CRC 校验​
fs_no_crc = tosfsspec.TosFileSystem(​
...,​
enable_crc=False​
)​
​
HNS/FNS 与 maxdepth 限制​
TOS Bucket 主要有两类：​
  • FNS (Flat Namespace)：扁平命名空间，所有对象都在一个层级，目录结构是模拟的。​
  • HNS (Hierarchical Namespace)：分层命名空间，提供原生目录结构，性能更优，体验类似于 HDFS。​
tosfsspec 对这两种类型都提供支持，但在某些操作上存在差异：​
  • mv()：在 HNS bucket 内移动目录是原子操作，效率更高。在 FNS bucket 内则需要逐一复制再删除。​
  • walk(), find(), rm(), copy()：递归操作中的 maxdepth 参数用于限制递归深度。此参数仅在 FNS 类型的 Bucket 中有效。在 HNS Bucket 中使用 maxdepth 会引发 ValueError，因为 HNS 的原生目录遍历机制不支持该限制。​
​
# 在 FNS Bucket 中，只遍历 2 层深度​
# 假设 bucket 'my-fns-bucket' 是 FNS 类型​
for root, dirs, files in fs.walk('tos://my-fns-bucket/deep/folder/', maxdepth=2):​
print(root)​
​
# 在 HNS Bucket 中，以下代码会报错​
# 假设 bucket 'my-hns-bucket' 是 HNS 类型​
# fs.glob("tos://my-hns-bucket/data/**", maxdepth=1) # 会引发 ValueError​
​
最近更新时间：2026.03.19 17:45:47
这个页面对您有帮助吗？
有用
有用
无用
无用