
Hello,我是小兔大白糖。 头像上传看起来是「multipart 一下完事」。上线后常见事故:桶被灌垃圾图、换完头像仍见旧图、API 被大图拖超时、客户端自造路径穿越。业界怎么拆?
写成这篇,给要做小对象上传架构调研的初中级后端同学:不是某云 SDK 说明书,而是可复述的通道选型 + 对象合同清单。
说明:文中的档位、伪流程与路径形态均为教学脱敏 / 示意。对象存储举例会提到 S3 兼容预签名一类公开形态,只钉概念与代价,不绑定某一家控制台或内部桶名。读完带走的是选型清单,不是可粘贴的联调脚本。
估计阅读时间:10 分钟
目录
为什么现在要关心
小图上传先选通道:经应用代理同步上传,还是预签名直传对象存储——合同不同(超时、鉴权、流量、病毒扫描位)。路径与校验必须由服务端裁定:别信客户端给的最终存储键;MIME、大小、尺寸是门禁,不是「建议」。
现场里常见误伤,几乎都来自把「传上去」当成唯一问题:
| 你看到的现象 | 常见真相 |
|---|---|
| 上传偶发 504 / worker 被拖死 | 代理同步吃满带宽与超时,却无大小硬顶 |
| 桶里一堆奇怪扩展名的「图片」 | 只信客户端 Content-Type,未嗅探 / 白名单 |
| 用户换头像后仍见旧图 | URL 永久不变,又无版本或缓存破坏 |
| 弱网重试后同人多张 orphan | 无客户端媒体 ID / 幂等键 |
| 「换成直传就稳了」却校验失效 | 签发前策略与上传后确认拆开了,后半截没签合同 |
本文只钉一件事:头像 / 群头像这类小对象,通道怎么选,以及无论选哪条路,服务端必须签哪些合同。
问题空间:两层决策,不是一次 multipart
硬规则:先分「字节流走哪条路」与「对象键 / 校验 / 幂等 / 缓存谁说了算」;答错层,换什么存储产品都像在治错病。
头像、群头像属于小对象、强鉴权、弱工作流媒体:通常可同步完成,不像大视频要转码管线。但仍有两层决策:
| 层 | 问题 | 成功标准 |
|---|---|---|
| 传输通道 | 字节流走 API,还是直达对象存储? | 超时、带宽、鉴权位与扫描位匹配体量 |
| 对象合同 | 谁生成键、如何校验、如何幂等、如何让 CDN / 客户端失效旧图? | 可引用 URL + 门禁 + 不信客户端最终路径 |
通道选对,不自动带出对象合同。把「multipart 通了」当成「上传架构做完了」,是最常见的层错位。
业界常见形态对比
头像默认常落在应用代理同步;量起来或 API 成瓶颈再迁预签名。完整异步媒体管线多留给附件 / 视频——不是小图默认选项。
| 形态 | 做法 | 优点 | 代价 / 边界 |
|---|---|---|---|
| A. 应用代理同步上传 | Client → API(鉴权 + 校验)→ 对象存储 → 返回 URL | 实现简单;校验集中;适合小图 | API 吃带宽与超时;水平扩展成本高 |
| B. 预签名直传 | API 只发短期上传凭证;Client 直传存储 | API 减压;大流量更稳 | 校验要拆成「签发前策略 + 上传后回调 / 轮询」;实现面更大 |
| C. 异步媒体管线 | 先落临时对象再转码 / 审核 | 适合大文件与审核流水线 | 头像常过重;状态机与运维成本高 |
选型时先定通道层,再定产品。A → B 是减压迁移,不是「更现代就更好」;C 的代价要当着写,避免把头像做成完整媒体平台。
心智模型:柜台收件 vs 仓库自提柜
主比喻:快递收发。
- 应用代理同步 = 柜台代收:小包裹过安检、称重、贴单,一次办完——适合头像这种小件。
- 预签名直传 = 仓库自提柜:高峰减压,柜台只发「柜门密码」(短期凭证);你要核对密码过期,以及有没有放错柜。
类比局限一句说清:柜台 / 自提柜解释通道与凭证时效;解释不了图片内容安全(鉴黄、病毒扫描等)——那是另开审核合同,不是存储品牌自带的。
服务端必须裁定的合同
无论 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」。
-
信客户端
Content-Type,不嗅探 / 不白名单
改扩展名就能绕过。类型门禁要落在服务端(或签发策略里),不是前端下拉框。 -
客户端指定最终对象键
覆盖他人对象或路径穿越。键由服务端生成;客户端最多给幂等用的媒体 ID。 -
代理同步却无超时与大小硬顶
API worker 被大图拖死。小图通道也要有界——同步不等于无限。 -
无幂等键
弱网重试制造 orphan。媒体 ID 去重或覆盖同一业务键,二选一写进合同。 -
URL 永久不变又无版本 / 缓存破坏
用户换头像仍见旧图。版本查询参数、内容哈希路径或 CDN purge,至少做一种。 -
把头像做成完整异步媒体平台
状态机、转码队列、审核工单全上——对小图常是过度设计。量与合规真需要时再迁 C,并单独签审核合同。
选型结论
- 先分两层:通道(代理同步 vs 预签名)与对象合同(键、校验、幂等、缓存破坏)不是一次 multipart。
- 默认常落 A:小对象、强鉴权、要集中校验时,柜台代收够用;API 成带宽 / 超时瓶颈再迁 B。
- 迁 B 的代价当着写:签发前策略 + 上传后确认;实现面变大,不是「直传就更稳」。
- 服务端裁定键与门禁:MIME / 大小 / 尺寸是硬顶;客户端媒体 ID 做幂等,不做最终路径。
- 安全与缓存破坏写进合同:消毒、版本或失效策略、临时文件即清——别等客诉再补。
相关阅读:同站异步分层心智见 /blog/inprocess_pool_vs_managed_queue/——「解耦请求」与「跨进程可靠」不是一层;小图上传里「通道减压」与「对象合同」同样不要混成一件事。