OBS 分片上传的三个坑:ETag 算法、分片序号与断点续传边界

举报
yd_290540706 发表于 2026/11/11 09:38:26 2026/11/11
【摘要】 OBS 分片上传的三个坑:ETag 算法、分片序号与断点续传边界做端云协同的文件上传,绕不开一个分水岭:文件小的时候怎么传都对,一旦过了几十兆,整文件 PUT 就开始随机失败——不是网络断,而是超时、内存爆、重传成本高。这时唯一的正解是分片上传。但分片上传的坑不在"分成几片",而在三个容易被忽略的细节上。这篇把我踩过的三个坑和对应的验证方法写清楚。一、为什么不该整文件直传整文件 PUT 的问...

OBS 分片上传的三个坑:ETag 算法、分片序号与断点续传边界

做端云协同的文件上传,绕不开一个分水岭:文件小的时候怎么传都对,一旦过了几十兆,整文件 PUT 就开始随机失败——不是网络断,而是超时、内存爆、重传成本高。这时唯一的正解是分片上传。

但分片上传的坑不在"分成几片",而在三个容易被忽略的细节上。这篇把我踩过的三个坑和对应的验证方法写清楚。

一、为什么不该整文件直传

整文件 PUT 的问题很具体:

  • 一次请求要持有完整文件流,移动端很容易被内存限制打断
  • 中途失败只能从头重传,文件越大重传成本越高
  • 单请求有超时上限,弱网下必然触发

分片上传把一次大请求拆成三阶段:

  1. POST ?uploads 发起分片上传,拿到 uploadId
  2. PUT ?partNumber=N&uploadId=xxx 逐片上传,每片返回自己的 ETag
  3. POST ?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 的合成值。两者用途不同,别混用。

六、上线前的验证清单

按这五条过一遍,基本能把分片上传的问题挡在测试环境:

  1. 单文件 200MB,正常网络跑通,校验 ETag 与自算值一致
  2. 传到 60% 强杀进程,重启后走 ListParts,确认没有重传已完成分片(看服务端请求日志)
  3. 人为把某片 partNumber 跳号,确认 Complete 明确失败而不是静默成功
  4. 续传前把源文件追加一个字节,确认程序识别到大小变化并重新发起
  5. 分片并发度拉到 10 以上,确认内存占用不随文件大小线性增长

结语

分片上传的复杂度不在"切",在"对账":对 ETag 的算法、对 partNumber 的序号、对分片边界的方案。这三件事只要有一件靠"现算"而不是"记下来",就会在弱网和断点场景里以数据损坏的形式暴露出来。

把方案持久化、把 ETag 算法写对、用 ListParts 而不是内存表来恢复现场,这三步做完,分片上传才算真的可用。

【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。