s3-turbo-list · Rust CLI

桶里有什么，一次列清

Q: aws s3 ls 不够用吗？

小规模、临时查看时，aws s3 ls 通常就够了。s3-turbo-list 面向大规模盘点和可重复对比，这时结果输出和恢复能力更重要。

Q: 需要准备 hints 文件吗？

不需要。list 会自己探测真实的 CommonPrefixes 边界。hints 文件只是反复盘点时的可选控制。

Q: 启动发现做了什么？

每次运行都先用几次 delimiter 探测找到真实的 CommonPrefixes 边界，不在工作目录里缓存。没有前缀的扁平命名空间改用 single-key 探测拆分，单个前缀下的大型扁平目录（如 data/ 下的 data/part-…）也一样，所以每次运行都能并行展开。

Q: 中断的任务能接着跑吗？

能。每次中断的 list 运行都会在 Ctrl-C 或 SIGTERM 时保存 checkpoint。用同一个 --output-dir 加上 --resume 再跑一次，只列举尚未写出的 key 范围；续跑的输出只含这些范围，需要与中断那次的输出合并。进程崩溃时保留上一次的 checkpoint，diff 和 --start-after 运行不保存 checkpoint。

自动发现可并行的工作。大规模 list 与 diff。输出 Parquet。

s3-turbo-list doctor

查看 GitHub 快速开始

RustApache-2.0 v0.39.0 （2026年9月30日） S3 兼容Parquet机器可读 JSON

s3-turbo-list v0.39.0 · 实际输出

s3-turbo-list doctor
OK    binary_version: 0.39.0
OK    working_directory: /tmp/inventory
OK    config_parse: resolved configuration is valid TOML/CLI state
OK    config_file: no config file (searched ./s3-turbo-list.toml and ~/.s3-turbo-list.toml); built-in defaults apply
OK    aws_profile: AWS_PROFILE is not set; the AWS SDK uses its default credential chain
OK    provider: no provider preset; plain S3 settings apply
OK    endpoint_url: no endpoint URL: requests go to AWS S3 (pass --endpoint-url or --provider for another service)
SKIP  proxy: the request host depends on the bucket and region (virtual-hosted or AWS endpoint), which doctor does not take; the run log names the proxy, if any, for each resolved endpoint
SKIP  network: doctor is a local preflight and does not contact S3 endpoints; use compat-probe to validate an endpoint
Resolved: provider -, endpoint -, addressing auto, concurrency 100, threads 4
Doctor status: ok

第三方基准测试 · 阿里云 OSS

单流对比 -c 8

阿里云 OSS 上的 1M 个对象，由第三方实测，数据引自项目 README。列举速度受限于服务商每秒响应的请求数。

单流与 -c 8 的完成耗时

单流: 约 55s
-c 8: 约 19s

均为报告中的近似值。实际结果取决于桶的结构和服务商的请求速率上限。

迁移前先问两件事

列一个桶，或把源桶和目标桶对比。

LIST

桶里有什么

一个桶写成 Parquet 对象清单，不必先调扫描参数。

DIFF

两端差了什么

两端并行列举、按 key 合并，得到一份标出相同、缺失和变化的 Parquet。

不负责同步对象 它不复制对象，也不替代存储浏览器，只把列举和对比的结果留给你做下一步判断。

扫描计划随桶而定

有结构的地方先并行展开，仍然耗时的长尾片段再继续拆分。

1
识别结构

先探测真实的前缀边界，再开始递归扫描。
2
并行列举

按边界展开并行任务，不必预先准备 hints 文件。
3
处理长尾

仍有可用余量时，才拆分耗时的片段。
4
写出清单

留下可分析的对象清单，而不只是终端输出。

扩大扫描前，先确认端点行为

兼容性
已验证	AWS S3 MinIO 百度 BOS
预设	Cloudflare R2 OSS B2

AWS S3、MinIO 和百度 BOS 走过项目的兼容性验证；R2、OSS、B2 提供预设。无论哪种端点，长任务前都先运行 compat-probe。

数据的去向

S3 请求只发往你设置的端点或预设填入的端点；不检查更新，没有遥测。
凭证来自标准 AWS 凭证链：profile、环境变量或实例角色；预设从不碰凭证。
对象清单、checkpoint、日志和运行记录都写在输出目录；doctor 与 --dry-run 不访问任何 S3 端点。

v0.39.02026年9月30日发布说明 ›

开始使用

从 GitHub Release 下载对应平台的二进制，用 SHA256SUMS 校验后放进 PATH。

1
本地预检，不访问 S3

s3-turbo-list doctor
2
完整递归清单 → out/ 里的 Parquet

s3-turbo-list list --bucket my-bucket --region us-east-2 --output-dir out

常见问题

aws s3 ls 不够用吗？

小规模、临时查看时，aws s3 ls 通常就够了。s3-turbo-list 面向大规模盘点和可重复对比，这时结果输出和恢复能力更重要。

需要准备 hints 文件吗？

不需要。list 会自己探测真实的 CommonPrefixes 边界。hints 文件只是反复盘点时的可选控制。

启动发现做了什么？

每次运行都先用几次 delimiter 探测找到真实的 CommonPrefixes 边界，不在工作目录里缓存。没有前缀的扁平命名空间改用 single-key 探测拆分，单个前缀下的大型扁平目录（如 data/ 下的 data/part-…）也一样，所以每次运行都能并行展开。

中断的任务能接着跑吗？

能。每次中断的 list 运行都会在 Ctrl-C 或 SIGTERM 时保存 checkpoint。用同一个 --output-dir 加上 --resume 再跑一次，只列举尚未写出的 key 范围；续跑的输出只含这些范围，需要与中断那次的输出合并。进程崩溃时保留上一次的 checkpoint，diff 和 --start-after 运行不保存 checkpoint。

s3-turbo-list

查看 GitHub 快速开始

S3 工具组

迁移和排查对象存储时，依次用到。

全部工具

桶里有什么，一次列清

单流对比 -c 8

桶里有什么

两端差了什么

识别结构

并行列举

处理长尾

写出清单