
上传一个 10 GiB 的视频素材,传到 90% 时网络抖了一下,整次上传失败、从头再来,这是对象存储里最让人烦躁的体验之一。S3 的分片上传(Multipart Upload)协议就是为这种场景设计的:把一个大对象切成若干片,逐片独立上传,哪片失败只重传哪片,全部到齐后再"组装"成完整对象。RustFS 作为 S3 兼容的对象存储,走的是同一套协议。本文给一条最小可验证流程,照着跑通,你就拿到了断点续传的能力。

先确认一件事:RustFS 支持到什么程度
断点续传的能力边界,取决于服务端对分片上传协议的支持范围。RustFS 的官方 S3 兼容性矩阵(2026-08-09 快照,基于提交 1e6f5f1e 核验)把分片上传拆成了三档:
- 创建、上传分片、完成和中止 ------ ✅ 已测试,纳入默认兼容性门禁;
- 部分分片复制、校验和及对象属性行为 ------ ✅ 已测试;
- 分片上传列表和分片查询的边界行为(也就是
ListParts/ListMultipartUploads)------ ⊘ 已排除在默认门禁之外。
前两档正是断点续传依赖的核心:能发起、能逐片传、能完成、能中止。第三档的边界结论,恰好决定了"断点续传到底靠谁记录进度",这一点下面会展开说,它是这套流程里最该留意的中性边界。
一条能直接照抄的最小流程
下面用标准 AWS CLI 的 s3api 子命令演示,配合 --endpoint-url 指向你的 RustFS 地址。假设 RustFS 监听在 http://localhost:9000,按你的实际部署地址替换即可。
bash
aws s3api create-multipart-upload \
--endpoint-url http://localhost:9000 \
--bucket my-bucket \
--key bigfile.bin \
--region us-east-1
aws s3api upload-part \
--endpoint-url http://localhost:9000 \
--bucket my-bucket \
--key bigfile.bin \
--part-number 1 \
--upload-id <UploadId> \
--body part1.bin
aws s3api complete-multipart-upload \
--endpoint-url http://localhost:9000 \
--bucket my-bucket \
--key bigfile.bin \
--upload-id <UploadId> \
--multipart-upload '{"Parts":[{"PartNumber":1,"ETag":"<etag-1>"},{"PartNumber":2,"ETag":"<etag-2>"}]}'
aws s3api abort-multipart-upload \
--endpoint-url http://localhost:9000 \
--bucket my-bucket \
--key bigfile.bin \
--upload-id <UploadId>
完成之后,对象就以完整形态出现在桶里,和一次普通 put-object 上传的结果没有区别。
断点续传的关键:进度记在客户端
分片协议天然支持"续传",但"续"的凭据不在服务端默认门禁里。因为 ListParts / ListMultipartUploads 的边界行为不在 RustFS 默认兼容性门禁中,最稳妥的做法是:进度由客户端自己记,而不是上传失败后去问服务端"我传了哪几片"。
具体落地成三个动作:
- 每上传成功一个分片,就把
{part-number: ETag}写进本地一个小文件(或数据库); - 上传过程中崩溃或网络断了,拿着同一个
UploadId重启任务,读本地记录,只重传"本地没有 ETag"的那些分片; - 全部补齐后,用本地这份列表调
complete-multipart-upload。

这样做的好处是:续传逻辑完全不依赖 ListParts 的行为边界,只要 UploadId 还有效、已传的分片还在服务端,就能无缝接着传。至于 UploadId 的有效期和已传分片的保留时长,以你所部署版本的官方文档为准,这不属于本文能替你拍板的范围。
为什么不直接一次 PUT,分片大小怎么选
小于几十 MiB 的对象,一次 put-object 最简单,也最省事。但对象越大,单次 PUT 的风险越高:连接一旦断开,已传的字节全部作废,只能从头再来;而且单连接的上行带宽往往跑不满。分片上传把风险摊薄到"单片"粒度,还能多个分片并行上传,把多条连接的带宽叠起来。
分片大小没有银弹,只有一个硬约束要守住:单片(除最后一片)最大 5 GiB、单次任务最多 10000 片。反推过来,对象越大,单片应该切得越大,否则片数会撞上 10000 的上限。例如一个 100 GiB 的文件,若按 128 MiB 切片,大约 800 个分片,离上限还很远;若按 16 MiB 切,就会逼近 6400 片,虽然没超,但元数据列表已经不小。常见做法是按对象总大小估算,让分片数落在几百到一两千的区间,既保留断点续传的粒度,又不让 complete 时的列表膨胀。RustFS 侧的校验和支持(分片上传的校验和行为已纳入测试)意味着每片上传可以带校验,单片传坏能被发现、单独重传,不必怀疑整次任务。
几个容易踩的坑
- 分片号必须连续且从 1 开始 ,但可以不按顺序上传;
complete时列表按PartNumber升序排好即可,服务端按序号拼装,不关心你先传了哪片。 - 最后一个分片可以小于 5 GiB ,其余分片建议贴近上限以减少请求数;片数越多,元数据开销和
complete时的列表越大。 - ETag 一个都不能漏 。
complete的Parts列表里每一项的PartNumber和ETag必须和实际上传一一对应,漏一项就会组装失败。 - 别忘了中止 。任务放弃时一定要调
abort-multipart-upload;只删本地记录而不中止,服务端已收的分片会成孤儿,占用空间直到被回收。
现在就能做的四件事
- 在本地的 RustFS 桶上跑通上面的最小流程,确认
create → upload-part → complete三步返回正常。 - 把"分片号 + ETag"的本地记录逻辑接进你的上传脚本,先做到崩溃可重传。
- 用一次故意中断(传一半杀掉进程)验证:用同一
UploadId只补传缺失分片,能complete成功。 - 给放弃路径补上
abort-multipart-upload,别留孤儿分片。
大文件上传真正的成本不在带宽,而在"传错了能不能少传点"。把分片协议用起来、把进度记在自己这边,断点续传就是顺手的事。