OBS 分片上传的三个坑:ETag 算法、分片序号与断点续传边界
OBS 分片上传的三个坑:ETag 算法、分片序号与断点续传边界
做端云协同的文件上传,绕不开一个分水岭:文件小的时候怎么传都对,一旦过了几十兆,整文件 PUT 就开始随机失败——不是网络断,而是超时、内存爆、重传成本高。这时唯一的正解是分片上传。
但分片上传的坑不在"分成几片",而在三个容易被忽略的细节上。这篇把我踩过的三个坑和对应的验证方法写清楚。
一、为什么不该整文件直传
整文件 PUT 的问题很具体:
- 一次请求要持有完整文件流,移动端很容易被内存限制打断
- 中途失败只能从头重传,文件越大重传成本越高
- 单请求有超时上限,弱网下必然触发
分片上传把一次大请求拆成三阶段:
POST ?uploads发起分片上传,拿到uploadIdPUT ?partNumber=N&uploadId=xxx逐片上传,每片返回自己的 ETagPOST ?uploadId=xxx提交分片清单,服务端拼装成完整对象
听上去是流水账,问题全在第二步到第三步之间的对账上。
二、坑一:Complete 的 ETag 不是整个文件的 MD5
这是最容易踩的一个。很多人想当然地以为:把文件整体算一遍 MD5,和 Complete 之后返回的 ETag 对比,就能校验上传完整性。
分片上传的对象,ETag 长这样:
5cc5d14cf6f197a202f6c885586d9ca7-3
末尾那个 -3 表示由 3 个分片拼成。它不是文件内容的 MD5,而是:
把每个分片的 MD5 二进制摘要按分片顺序拼接,再对这串拼接结果做一次 MD5,转十六进制,最后加上
-分片数。
用一个可复现的小例子验证。假设三个分片内容分别是 part-1、part-2、part-3:
分片 1 part-1 78429f7462d636a84d9c922f495599c5
分片 2 part-2 bca7c72402361f2a3af235b051ce87f4
分片 3 part-3 6d063ffc152b9b78c048d4f25a3ff703
把这 3 个 MD5 的二进制(不是十六进制字符串)顺序拼起来,再算一次 MD5:
ETag = 5cc5d14cf6f197a202f6c885586d9ca7-3
而整个文件 part-1part-2part-3 的 MD5 是 32590c5cf1f5adf6d8fe37e8188526db——和上面完全不是一回事。
这里有两个高频写错的地方:
- 拼接的是二进制摘要,不是 32 位十六进制字符串。拼字符串会得到完全不同的结果,而且不会报错,只是永远对不上。
- 分片数要拼在末尾,少写
-3也会判定不一致。
所以校验的正确姿势是:Complete 之后拿到 ETag,自己按上面的算法算一遍再比对;不要拿整文件 MD5 去比。
三、坑二:PartNumber 必须连续,乱序上传要靠 ListParts 还原
分片的 partNumber 从 1 开始,最大 10000。规则是:
- 提交时清单里的 partNumber 会被按升序重排,最终对象顺序由 partNumber 决定,不由上传先后决定
- 缺号直接导致 Complete 失败,不会"跳过空洞"拼装
- 单片的限制:除最后一片外,每片不小于 100KB(按 S3 兼容规范通常要求 5MB 以上,OBS 允许 100KB 起),单片最大 5GB
并发上传时,完成顺序是乱的,所以你不能靠"我发出去的第几片"来记 partNumber,只能靠每片上传响应里回带的 partNumber + ETag 建表。
断线重连后更麻烦:内存里的表没了。这时唯一可靠的还原手段是 GET ?uploadId=xxx(ListParts),它返回已经成功上传的分片及其 ETag。拿这份清单和服务端对账,只补缺失的号段,已完成的一片都不重传。
四、坑三:断点续传的分片边界必须与首次一致
这一条最隐蔽。断点续传时如果重新按"当前剩余字节数 ÷ 固定片大小"来切分,很可能切出和首次不一样的边界。
后果是:第 5 片在服务端已有一份按旧边界切的 ETag,你按新边界重传同一 partNumber,覆盖是覆盖了,但其他已完成分片的边界仍是旧的,拼出来的对象字节序就错了——文件能上传成功,ETag 也对得上,打开却是损坏的。
正确做法是把"分片方案"本身持久化,而不是每次现算:
- 首次上传时确定
partSize,连同uploadId、文件大小、文件修改时间一起落盘 - 续传时先读方案,只在"文件大小 + 修改时间"都一致时才复用
- 任何一项变了,直接放弃旧 uploadId,重新发起
片大小的经验值:总数控制在 1000 片以内,单片 5~10MB。10000 片是硬上限,不是目标。
五、Node 示例:三段式对账
下面这段是核心逻辑的骨架,省略了签名部分(签名是另一个话题):
const crypto = require('crypto');
const md5bin = (buf) => crypto.createHash('md5').update(buf).digest();
// 1) 发起
async function initiate(key) {
const r = await req('POST', `/${key}?uploads`);
return parseUploadId(r); // 取出 UploadId
}
// 2) 逐片上传(可并发),每片记下 ETag
async function putPart(key, uploadId, partNumber, buf) {
const r = await req('PUT', `/${key}?partNumber=${partNumber}&uploadId=${uploadId}`, buf);
return { partNumber, etag: r.headers.etag };
}
// 3) 提交,清单按 partNumber 升序
async function complete(key, uploadId, parts) {
const xml =
'<CompleteMultipartUpload>' +
parts
.sort((a, b) => a.partNumber - b.partNumber)
.map((p) => `<Part><PartNumber>${p.partNumber}</PartNumber><ETag>${p.etag}</ETag></Part>`)
.join('') +
'</CompleteMultipartUpload>';
return req('POST', `/${key}?uploadId=${uploadId}`, xml);
}
// 4) 自算分片 ETag 用于校验
function multipartEtag(partBuffers) {
const cat = Buffer.concat(partBuffers.map(md5bin));
return crypto.createHash('md5').update(cat).digest('hex') + '-' + partBuffers.length;
}
注意第 4 步和第 2 步的区别:上传时每片返回的 ETag 是该片自己的 MD5,只有 Complete 返回的才是带 -N 的合成值。两者用途不同,别混用。
六、上线前的验证清单
按这五条过一遍,基本能把分片上传的问题挡在测试环境:
- 单文件 200MB,正常网络跑通,校验 ETag 与自算值一致
- 传到 60% 强杀进程,重启后走 ListParts,确认没有重传已完成分片(看服务端请求日志)
- 人为把某片 partNumber 跳号,确认 Complete 明确失败而不是静默成功
- 续传前把源文件追加一个字节,确认程序识别到大小变化并重新发起
- 分片并发度拉到 10 以上,确认内存占用不随文件大小线性增长
结语
分片上传的复杂度不在"切",在"对账":对 ETag 的算法、对 partNumber 的序号、对分片边界的方案。这三件事只要有一件靠"现算"而不是"记下来",就会在弱网和断点场景里以数据损坏的形式暴露出来。
把方案持久化、把 ETag 算法写对、用 ListParts 而不是内存表来恢复现场,这三步做完,分片上传才算真的可用。
- 点赞
- 收藏
- 关注作者
评论(0)