# 别再让 API 每天中转 100GB 文件流量

> 用预签名 URL 让用户直传存储，应用只负责授权，其余交给 CDN。

原文: https://fdetimes.net/zh/guides/presigned-urls-large-uploads-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 来签发令牌。你也可以在现有后端里加一个路由实现同样的功能：

```text
# 伪代码，为说明而简化
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 后，把文件直接推送到存储：

```bash
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 步的路由旁再加一个续期路由。它不生成新键，而是为同一个键重新签名，且只对已拥有该键的用户生效：

```text
# 伪代码，为说明而简化
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 测试一样。

```bash
# $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 设计，带到下一次技术会议上。

**本周动手试试:**

- 写一个小端点，用服务器生成的对象键签发 PUT 预签名 URL，然后用 curl 上传，并用同一个 URL 试一次 GET。
- 算出客户真实场景中最大的文件在最低带宽下需要上传多久，再据此设定令牌过期时间，而不是凭感觉。
- 检查当前项目中托管图片、JS 和 CSS 的容器或 bucket，确认没有一个允许公开写。

## 信源

- [Valet Key pattern - Azure Architecture Center | Microsoft Learn](https://learn.microsoft.com/en-us/azure/architecture/patterns/valet-key)

- [Download and upload objects with presigned URLs - Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-presigned-url.html)

- [Static Content Hosting pattern - Azure Architecture Center | Microsoft Learn](https://learn.microsoft.com/en-us/azure/architecture/patterns/static-content-hosting)

- [system-design-primer: Content delivery network](https://github.com/donnemartin/system-design-primer)

- [Content delivery network - Wikipedia](https://en.wikipedia.org/wiki/Content_delivery_network)
