头像类小图上传:代理同步还是预签名直传

头像类小图上传:代理同步还是预签名直传

Hello,我是小兔大白糖。 头像上传看起来是「multipart 一下完事」。上线后常见事故:桶被灌垃圾图、换完头像仍见旧图、API 被大图拖超时、客户端自造路径穿越。业界怎么拆?

写成这篇,给要做小对象上传架构调研的初中级后端同学:不是某云 SDK 说明书,而是可复述的通道选型 + 对象合同清单。

说明:文中的档位、伪流程与路径形态均为教学脱敏 / 示意。对象存储举例会提到 S3 兼容预签名一类公开形态,只钉概念与代价,不绑定某一家控制台或内部桶名。读完带走的是选型清单,不是可粘贴的联调脚本。

估计阅读时间:10 分钟


目录


为什么现在要关心

小图上传先选通道:经应用代理同步上传,还是预签名直传对象存储——合同不同(超时、鉴权、流量、病毒扫描位)。路径与校验必须由服务端裁定:别信客户端给的最终存储键;MIME、大小、尺寸是门禁,不是「建议」。

现场里常见误伤,几乎都来自把「传上去」当成唯一问题:

你看到的现象常见真相
上传偶发 504 / worker 被拖死代理同步吃满带宽与超时,却无大小硬顶
桶里一堆奇怪扩展名的「图片」只信客户端 Content-Type,未嗅探 / 白名单
用户换头像后仍见旧图URL 永久不变,又无版本或缓存破坏
弱网重试后同人多张 orphan无客户端媒体 ID / 幂等键
「换成直传就稳了」却校验失效签发前策略与上传后确认拆开了,后半截没签合同

本文只钉一件事:头像 / 群头像这类小对象,通道怎么选,以及无论选哪条路,服务端必须签哪些合同。


问题空间:两层决策,不是一次 multipart

硬规则:先分「字节流走哪条路」与「对象键 / 校验 / 幂等 / 缓存谁说了算」;答错层,换什么存储产品都像在治错病。

头像、群头像属于小对象、强鉴权、弱工作流媒体:通常可同步完成,不像大视频要转码管线。但仍有两层决策:

层问题成功标准
传输通道字节流走 API,还是直达对象存储?超时、带宽、鉴权位与扫描位匹配体量
对象合同谁生成键、如何校验、如何幂等、如何让 CDN / 客户端失效旧图?可引用 URL + 门禁 + 不信客户端最终路径
小图上传两层决策:传输通道(代理同步 vs 预签名直传)与对象合同(键、校验、幂等、缓存破坏)
小图上传两层决策:传输通道(代理同步 vs 预签名直传)与对象合同(键、校验、幂等、缓存破坏) · 点击查看 SVG 原图

通道选对,不自动带出对象合同。把「multipart 通了」当成「上传架构做完了」,是最常见的层错位。


业界常见形态对比

头像默认常落在应用代理同步;量起来或 API 成瓶颈再迁预签名。完整异步媒体管线多留给附件 / 视频——不是小图默认选项。

形态做法优点代价 / 边界
A. 应用代理同步上传Client → API(鉴权 + 校验)→ 对象存储 → 返回 URL实现简单;校验集中;适合小图API 吃带宽与超时;水平扩展成本高
B. 预签名直传API 只发短期上传凭证;Client 直传存储API 减压;大流量更稳校验要拆成「签发前策略 + 上传后回调 / 轮询」;实现面更大
C. 异步媒体管线先落临时对象再转码 / 审核适合大文件与审核流水线头像常过重;状态机与运维成本高

选型时先定通道层,再定产品。A → B 是减压迁移,不是「更现代就更好」;C 的代价要当着写,避免把头像做成完整媒体平台。


心智模型:柜台收件 vs 仓库自提柜

主比喻:快递收发。

  • 应用代理同步 = 柜台代收:小包裹过安检、称重、贴单,一次办完——适合头像这种小件。
  • 预签名直传 = 仓库自提柜:高峰减压,柜台只发「柜门密码」(短期凭证);你要核对密码过期,以及有没有放错柜。
心智模型:代理同步如柜台代收一次办完;预签名直传如自提柜减压但要核对凭证过期与放错柜
心智模型:代理同步如柜台代收一次办完;预签名直传如自提柜减压但要核对凭证过期与放错柜 · 点击查看 SVG 原图

类比局限一句说清:柜台 / 自提柜解释通道与凭证时效;解释不了图片内容安全(鉴黄、病毒扫描等)——那是另开审核合同,不是存储品牌自带的。


服务端必须裁定的合同

无论 A 还是 B:最终存储键、类型 / 大小门禁、对象归属,必须由服务端裁定;客户端只可提供媒体 ID 一类幂等线索,不可拼绝对路径。

项人话若不处理
鉴权与归属未登录不能传;对象绑定主体(用户 / 群等)匿名灌桶;越权覆盖
类型与大小白名单 MIME + 上限;可按用途分档(用户头像更严、群头像略宽——示意)垃圾文件进桶;API / 账单被拖垮
尺寸可选探测宽高,挡超大图炸弹解码时打爆内存
存储键服务端生成分层键(示意:avatar/{purpose}/{yyyy}/{mm}/{id}.ext);禁客户端拼最终路径覆盖 / 路径穿越
幂等客户端媒体 ID:重试不造双对象或可去重弱网 orphan 对象堆
同步完成语义返回可引用 URL + 元数据;临时文件立即清理半成品 URL;磁盘泄漏
安全消毒扩展名 / 文件名消毒;不把原始文件名当存储键奇怪文件名进 CDN 日志与缓存键
缓存破坏URL 带版本 / 哈希,或主动失效 CDN换头像仍见旧图

教学示意(非某产品字段名):签发预签名时,策略里钉死允许的 MIME、最大字节、目标前缀;上传完成后,用服务端记录的「预期键 + 校验结果」再暴露公开 URL——不要把「上传成功」等同于「业务可引用」。


教学伪流程

代理同步:鉴权 → 门禁 → 服务端生成键 → 写入存储 → 返回可引用 URL。预签名:先签发带策略的短期凭证,上传后再确认合同。

# A. 应用代理同步(示意)
on_upload(auth, file, client_media_id):
  require_login(auth)
  enforce_mime_size_dims(file)          # 门禁,不是建议
  key = server_make_key(purpose, id)    # 禁止客户端最终路径
  put_object(store, key, file)
  cleanup_temp(file)
  return public_url(key, version) + meta

# B. 预签名直传(示意)
on_presign(auth, purpose, client_media_id, declared_meta):
  require_login(auth)
  policy = mime_size_prefix_policy(purpose)
  key = server_make_key(purpose, id)
  return short_lived_upload_cred(key, policy)

on_confirm(auth, key, client_media_id):
  verify_object_exists_and_matches_policy(key)
  return public_url(key, version) + meta

以上合计二十来行,教学示意,不是可粘贴的 SDK。各云预签名字段名与回调形态不同,但「签发前策略 + 上传后确认 + 服务端键」这三条合同仍然成立。


常见坑

从架构视角看,下面几条会把「小图上传」重新用成「开放写桶 + 永久 URL」。

  1. 信客户端 Content-Type,不嗅探 / 不白名单
    改扩展名就能绕过。类型门禁要落在服务端(或签发策略里),不是前端下拉框。

  2. 客户端指定最终对象键
    覆盖他人对象或路径穿越。键由服务端生成;客户端最多给幂等用的媒体 ID。

  3. 代理同步却无超时与大小硬顶
    API worker 被大图拖死。小图通道也要有界——同步不等于无限。

  4. 无幂等键
    弱网重试制造 orphan。媒体 ID 去重或覆盖同一业务键,二选一写进合同。

  5. URL 永久不变又无版本 / 缓存破坏
    用户换头像仍见旧图。版本查询参数、内容哈希路径或 CDN purge,至少做一种。

  6. 把头像做成完整异步媒体平台
    状态机、转码队列、审核工单全上——对小图常是过度设计。量与合规真需要时再迁 C,并单独签审核合同。


选型结论

  1. 先分两层:通道(代理同步 vs 预签名)与对象合同(键、校验、幂等、缓存破坏)不是一次 multipart。
  2. 默认常落 A:小对象、强鉴权、要集中校验时,柜台代收够用;API 成带宽 / 超时瓶颈再迁 B。
  3. 迁 B 的代价当着写:签发前策略 + 上传后确认;实现面变大,不是「直传就更稳」。
  4. 服务端裁定键与门禁:MIME / 大小 / 尺寸是硬顶;客户端媒体 ID 做幂等,不做最终路径。
  5. 安全与缓存破坏写进合同:消毒、版本或失效策略、临时文件即清——别等客诉再补。

相关阅读:同站异步分层心智见 /blog/inprocess_pool_vs_managed_queue/——「解耦请求」与「跨进程可靠」不是一层;小图上传里「通道减压」与「对象合同」同样不要混成一件事。