别再让 API 每天中转 100GB 文件流量
用预签名 URL 让用户直传存储,应用只负责授权,其余交给 CDN。
要点速览
- 大文件上传和下载不要经过应用:签发预签名 URL 或 Valet Key,让客户端直接与存储通信。
- 令牌范围越窄越好:一个文件、一种方法、较短的过期时间,但要足够覆盖大文件,并提供续期途径。
- 令牌无法限制数据量和使用次数,所以上传后要校验文件;静态内容允许公开读、禁止写,并在前面加 CDN。
设想客户有 200 名现场技术员,每人每天下班前上传一段 500 MB 的巡检视频。如果每个字节都经过你的 API,应用服务器每天就要收进再转出约 100 GB 数据,而这件事存储服务自己就能完成。
微软 Azure 架构中心描述的正是这种成本:应用代理上传和下载时,会消耗计算、内存和带宽等宝贵资源。Valet Key 模式把数据传输交给存储服务,应用只保留一项职责:决定谁可以做什么。
对前线部署工程师(FDE)来说,这类需求反复出现:客户希望用户把文档、图片、日志或训练数据推送到你刚部署的系统里。下面的指南一步步带你在笔记本上搭建这套流程,再给静态内容加上 CDN。
要构建什么,需要先准备什么?
你要构建三样东西:一个签发限时上传 URL 的端点;一个客户端直传存储的流程;以及每个文件上传完成后执行的校验。最后一部分是托管静态内容的存储,前面加一层 CDN。
你需要一个带对象存储(S3 或 Azure Blob)的云账号、一个你熟悉的小型后端,以及 curl。下文代码均为伪代码,经过简化,只展示结构,不对应任何特定 SDK 的语法;真正实现时,请查阅所用 SDK 中生成预签名 URL 的函数。
第 1 步:钥匙要收得多窄?
根据 AWS 文档,预签名 URL 由四个要素确定:bucket、对象键、HTTP 方法和过期时间。持有该 URL 的人无需任何 AWS 凭证或权限,就能向这个对象上传,而且只能上传到这个对象。
微软对 Valet Key 的定义思路相同:一种有时效的令牌,只作用于特定资源,只允许预先规定的操作,例如可写不可读。其示例把令牌限制在一个容器、一个文件上,过期时间约 3 分钟,只授予 blob 的 create 权限:不能下载、更新或删除。
由此得出的规则是:每个维度都要收窄。一个文件、一种方法、一个时间窗口,不多给任何权限。
第 2 步:编写签发 URL 的端点
微软用一个运行在 Azure Functions 上的轻量 API 来签发令牌。你也可以在现有后端里加一个路由实现同样的功能:
# 伪代码,为说明而简化
POST /uploads (用户已登录)
检查该用户是否有权为此租户上传
object_key = "uploads/{tenant_id}/{new_uuid}"
url = presign(bucket="customer-uploads",
key=object_key,
method="PUT",
expires_in=<在第 4 步计算>)
将 object_key 存入数据库,状态为 "pending"
return { url, object_key }
(简单说:已登录用户调用该路由;服务器检查其是否有权为此租户上传,用租户 ID 和新 UUID 生成对象键,按第 4 步算出的过期时间为该键预签名一个 PUT,把键以 “pending” 状态存入数据库,然后返回 URL 和键。)
最关键的细节是:对象键由服务器生成,绝不取自用户提交的文件名。AWS 指出,用预签名 URL 上传到已存在的键,会覆盖原有对象。如果客户端能自选键,它就能选中别人的文件来覆盖。
本步检查:调用两次端点,应得到两个不同的对象键。
第 3 步:客户端直传,应用不再经手
客户端拿到 URL 后,把文件直接推送到存储:
curl -X PUT --upload-file video.mp4 "$UPLOAD_URL"
要测试权限范围,用同一个 URL 发起 GET:curl "$UPLOAD_URL"。方法是 URL 定义的一部分,所以这个请求必须被拒绝。如果成功了,说明你的钥匙比你以为的宽。
AWS 把预签名 URL 称为持有者令牌(bearer token):谁持有,谁就有访问权。因此不要把完整 URL 写进应用日志、分析数据或工单。
第 4 步:大文件的过期时间设多长才够?
微软建议使用较短的过期时间,以降低令牌泄露的风险,但也提醒:过短会导致大文件上传失败,因此需要续期机制。示例中的 3 分钟适合小图片,并不适用所有场景。
算一笔账。一个 1.8 GB 的文件,实际上行带宽 10 Mbps:1.8 × 1024 × 8 = 14,745.6 兆比特,除以 10 约为 1,475 秒,接近 25 分钟。3 分钟的令牌注定失败。合理的做法是按客户最大的文件和最慢的网络来设定过期时间,再留出安全余量。
关于上限,AWS 控制台允许设置 1 分钟到 12 小时,使用 CLI 或 SDK 最长可达 7 天。这里有个陷阱:如果 URL 用临时凭证签名,例如 IAM 角色会话,即使你设了更长的过期时间,它也会随凭证一起失效。
大文件下载有另一个陷阱。据 AWS 说明,S3 在请求到达时检查是否过期:已在进行的下载在 URL 过期后会继续,但如果连接中断,客户端在过期之后续传,请求就会失败。因此客户端应当知道向你的端点申请新 URL,而不是拿着过期的 URL 无限重试。
所以要在第 2 步的路由旁再加一个续期路由。它不生成新键,而是为同一个键重新签名,且只对已拥有该键的用户生效:
# 伪代码,为说明而简化
POST /uploads/{object_key}/renew (用户已登录)
在数据库中查找 object_key
如果不属于该用户,则拒绝
如果状态不是 "pending",则拒绝
url = presign(bucket="customer-uploads",
key=object_key,
method="PUT",
expires_in=<与第 4 步相同>)
return { url }
(简单说:在数据库中查找对象键;不属于该用户则拒绝;状态不是 “pending” 也拒绝;按第 4 步的过期时间为同一个键预签名一个 PUT,返回 URL。)
下载同理:服务器检查读权限后,客户端再次调用你的端点,为同一个对象获取新的 GET URL。本步检查:等一个 URL 过期,PUT 应当失败;调用续期路由,用新 URL 再 PUT,应当成功,且数据库中的对象键保持不变。
第 5 步:为什么上传后还要校验文件?
这一步很多人会跳过。微软说得很直白:通常无法创建一把能限制写入数据量的钥匙,也无法限制钥匙的使用次数。合法用户照样可以上传超大文件、格式错误的文件或恶意文件。
因此需要上传后校验:文件落入存储后,由一个任务读取处于 “pending” 状态的对象键,检查大小和格式,扫描恶意内容,通过后才改为 “ready”。第 4 步的续期路由也依赖这个状态:文件一旦变为 “ready”,就不再为它签发写入 URL。
微软还建议监控成本,及时发现存储的异常增长。在 Azure 上,create 权限让令牌实际上只能用一次,即使泄露,损失也有限。
常见错误与解决办法
| 现象 | 常见原因 | 解决办法 |
|---|---|---|
SignatureDoesNotMatch |
签发 URL 的机器时钟偏差 | 与 NTP 服务器同步;即使很小的偏差也可能导致签名失效 |
时间正确但仍出现 SignatureDoesNotMatch |
中间代理改写了请求头或查询字符串 | 直接向存储发请求,不要经过会改写 URL 的代理 |
| 大文件上传中途失败 | 过期时间相对文件大小太短 | 按最大文件设定,并使用第 4 步的续期路由 |
| URL 比设定时间更早过期 | 用临时凭证签名 | 检查签发 URL 所用角色的会话时长 |
如果客户需要确保文件在传输中没有损坏,AWS 支持在 SigV4 中使用校验和做上传完整性检查。
第 6 步:静态内容也需要钥匙吗?
并非所有文件都需要 Valet Key。微软的静态内容托管(Static Content Hosting)模式把图片、脚本和样式表直接放在存储上,前面加 CDN 以提升性能,代价是额外的费用。容器必须允许公开读,但绝不能允许公开写;需要保护的内容仍然回到 Valet Key 方案。
按 Wikipedia 的定义,CDN 是一个地理上分布的代理服务器和数据中心网络,让内容离用户更近。system-design-primer 区分了两类:拉取式 CDN(pull CDN)在第一个用户请求时才从源站获取内容,所以首次请求较慢;推送式 CDN(push CDN)适合很少被访问或很少更新的内容。
同样据 system-design-primer,CDN 的代价包括:费用;如果在 TTL 到期前更新内容,用户可能拿到陈旧内容;以及需要修改静态内容的 URL。实用的解决办法是在文件名中加入版本号,例如 app.v42.js:每次部署都生成新 URL,不会有旧副本等着 TTL 过期。
第 7 步:亲眼看 CDN 返回旧副本,再把它修好
本练习经过简化,使用一个指向你刚创建的静态容器的拉取式 CDN。先检查权限:不带任何令牌,直接往容器里写一个文件。请求必须被拒绝,就像第 3 步的 GET 测试一样。
# $CDN 是指向静态容器的 CDN 域名(简化示例)
curl "$CDN/app.js" # 第 1 次请求:CDN 需要从源站获取文件
curl "$CDN/app.js" # 第 2 次请求:应从缓存返回,速度更快
($CDN 是指向静态容器的 CDN 域名。第一次请求让 CDN 从源站获取文件;第二次应从缓存返回,速度更快。)
接着修改 app.js 的内容,用同样的文件名上传到存储,再通过 CDN 请求。如果 TTL 尚未到期,你多半还会拿到旧版本:这正是 system-design-primer 提醒的陈旧内容问题。
最后把新版本以 app.v2.js 上传,并请求这个 URL。你会立刻拿到新内容,因为对 CDN 来说这是一个从没见过的文件;首次请求可能较慢,与拉取式 CDN 的描述一致。能解释清楚这三次结果,就算通过。
这项技能在客户现场是什么样子?
在客户现场,第一个问题通常不是用 S3 还是 Blob,而是谁在代理文件。打开应用服务器的日志和带宽图表:如果上传流量占了大头,你就有了一个具体、可量化的改进方案。
阅读 FDE 岗位描述时,留意涉及接收客户文件或数据的工作,比如“file ingestion”或“data onboarding”这类说法。看到它们,就可以在面试中把这套练习完整讲一遍。
简历上不要只写“使用过 S3”。要写清楚:你把上传迁移到预签名 URL,根据真实文件大小设定令牌过期时间,增加了续期路由,并引入了上传后的内容校验。
进驻客户第一周的第一件事:找到最重的上传端点,测出每天有多少字节经过应用,把这个数字连同上面的预签名 URL 设计,带到下一次技术会议上。
这篇文章对你有帮助吗?
感谢你的反馈!
5 个信源
- Valet Key pattern - Azure Architecture Center | Microsoft Learn · 2024-05-08
- Download and upload objects with presigned URLs - Amazon S3
- Static Content Hosting pattern - Azure Architecture Center | Microsoft Learn · 2022-07-28
- system-design-primer: Content delivery network
- Content delivery network - Wikipedia