文件上传、下载与管理：直传、断点续传与签名 URL

文件上传、下载与管理：直传、断点续传与签名 URL

本节进入 Storage 的核心操作：如何把文件传上去、取下来，以及如何管理它们。重点是「前端直传」与「签名 URL」这两个对象存储特有的模式。

为什么让前端直传

传统做法是：前端把文件交给自建后端，后端再转存到存储服务。这有几个问题：

• 后端成为中转，带宽与计算压力大。
• 大文件会长时间占用后端连接。
• 用户体验受后端吞吐限制。

对象存储推荐的模式是前端直传：前端直接与 Storage 交互上传文件，后端完全不参与数据搬运，只负责必要的授权。这样上传速度只受用户网络限制，后端零负担。

上传的要素

一次上传通常包含：

• 目标桶：上传到哪个桶。
• 目标路径（键）：对象在桶内的路径，常按用户/类型组织。
• 文件内容：二进制数据。
• 内容类型：MIME 类型，如 image/png。
• 访问控制上下文：携带用户令牌，受存储策略约束。

客户端库提供上传接口，把文件流式上传到 Storage。上传时同样受 RLS 策略约束（第 4 节详述）——例如策略可要求「路径必须以当前用户 id 开头」，防止越权上传到他人目录。

上传进度与断点续传

大文件上传时，进度反馈与断点续传很重要：

• 进度反馈：客户端库提供上传进度回调，前端可显示进度条。
• 断点续传（Resumable Upload）：对大文件，可分块上传；若中途中断，下次能从断点继续，而非从头再传。这对视频等大文件尤其关键。

断点续传的实现依赖 Storage 的分块上传协议，客户端库通常已封装好，开发者按接口调用即可。

管理操作

除了上传，常见的文件管理操作包括：

• 列出文件：列出某桶或某前缀下的对象，支持分页。
• 移动 / 重命名：改变对象的路径。
• 复制：复制对象到新路径。
• 删除：删除对象。
• 获取元信息：查询对象的大小、类型、修改时间。

这些操作均可通过客户端库或控制台完成。注意移动、删除等敏感操作同样受存储策略约束。

下载与公开访问

下载方式取决于桶的公开性：

• 公开桶：对象有固定的公开 URL，可直接用（如 <项目域名>/storage/.../avatar.png）。适合公开内容，简单高效。
• 私有桶：不能匿名访问，需通过签名 URL获取临时授权。

签名 URL：临时授权下载

签名 URL 是对象存储的精髓之一：它是一段带签名的临时链接，在指定有效期内可访问某个私有对象，过期后失效。

签名 URL 的工作方式：

1. 已认证的客户端请求某个私有对象的签名 URL，并指定有效期（如 60 秒）。
2. 服务校验请求者是否有权访问该对象（受存储策略约束）。
3. 通过后生成带签名的临时 URL 返回给客户端。
4. 客户端在该 URL 有效期内可下载文件；过期则需重新生成。

签名 URL 的价值：
- 私有内容可被安全地临时分享（如生成一个 10 分钟有效的链接给协作者）
- 链接即使泄露，过期后也无法使用，风险可控
- 授权判定集中在生成时一次完成，下载本身不再校验，性能好
​

签名 URL 适合：私有文件下载、临时分享、付费内容授权访问等。

上传与下载的安全要点

• 直传仍需授权：前端直传不等于「随便传」，必须携带令牌，且受存储策略约束。
• 路径编码归属：把用户 id 编进路径，配合策略实现「只能访问自己目录」。
• 校验文件类型与大小：在桶配置与策略层面同时约束，防止上传超大或非法类型文件。
• 私有内容用签名 URL：不要为图方便把私有内容放进公开桶。

客户端库的统一接口

无论上传、下载、列出还是签名 URL，客户端库都提供风格统一的接口，与查询数据库的接口一致。你可以用同一套客户端实例管理数据与文件，体验连贯。掌握「直传 + 签名 URL」这两个核心模式，绝大多数文件场景都能覆盖。

小结

前端直传让上传不经后端、性能更好；断点续传支撑大文件可靠上传；公开桶用固定 URL，私有桶用签名 URL 实现临时授权下载；所有操作都受存储策略约束。下一节介绍如何在下载链路上叠加图片处理与 CDN 加速。