跳到内容
光环标志
光环基地

存储

每个项目在 S3 存储 (SeaweedFS S3) 上的 REST API、具有派生缓存的动态图像转换、HMAC 签名 URL、公共或私有存储桶、垃圾和恢复。

说明6分钟 读取级别 中间修改于 2026年4月15日

该页面已自动翻译。英文版具有权威性。

一桶、一源、一CDN#

aura-storage 服务管理您的二进制文件:上传、下载、图像转换、签名 URL、垃圾。它在 /v1/storage/{project_id} 下公开了自己的 REST API ,并在内部依赖 S3 存储(SeaweedFS S3) - S3 工具(rclone、boto3)不直接连接到它。

对象被组织到桶中。每个存储桶都有一个策略(公共或私有)、大小限制、可选的 TTL 和一组控制谁可以读/写每个路径的 RLS 策略。

信息

元数据位于项目架构中: storage_buckets、 storage_objects、 storage_derivatives、 storage_project_settings、 storage_audit_log。这些字节位于 S3 存储中。

路径 → RLS → CDN → 起源#

在读取期间,服务检查对所请求路径的访问,然后从存储中提供字节。如果查询携带变换参数,则对应的导数已存在则重用,否则计算然后缓存。在上传时,流程是相反的:客户端→服务→存储,在写入控制和存储桶限制之后。

schematext
                              ┌──── derivative cache ────┐
   GET /v1/storage/{pid}/… ─▶ │ derivative cached?       │
                              │ no  ⇢ origin             │
                              └──────────┬───────────────┘
                                         │
                              ┌──────────▼───────────────┐
                              │ aura-storage             │
                              │  ─ access control        │
                              │  ─ transforms            │
                              │  ─ derivative cache      │
                              └──────────┬───────────────┘
                                         │
                                  S3 storage (SeaweedFS S3)

六种原生能力#

  • 每个项目 REST API。 在 S3 存储 (SeaweedFS S3) 上路由 /v1/storage/{project_id}/... — 这不是 S3 API:S3 SDK 无法插入其中。
  • 动态变换。 宽度、高度、适合、格式(jpeg/png/webp/gif)、质量、旋转、翻转。每个组合都作为派生项进行缓存。
  • 签名 URL。 HMAC 方法签名 + 存储桶 + 密钥 + 过期时间。默认 TTL 3600 秒,每个项目秘密轮换。
  • 分段上传。 在 multipart/form-data 中简单上传,或者在 init/part/complete 中上传大文件。
  • 垃圾和恢复。 软删除:/trash 列出已删除的对象,/restore/{key} 恢复它们。
  • 公共或私有存储桶。 存储桶携带访问策略、大小限制和授权的 MIME 类型列表。

四种基本操作#

avatar.tstypescript
const { data, error } = await aura.storage.upload('avatars', `${user.id}/${file.name}`, file, {
    contentType: file.type,
    upsert: true,
})

// 如果没有 upsert,已占用的路径将失败并显示 409(冲突代码)
提示

转换 URL 是不可变的参数。 ?width=240&format=png 和 ?width=240&format=webp 是两个不同的 URL,因此有两个不同的导数:每个组合仅计算一次,然后从导数缓存中重新读取。

RLS on object paths#

对象元数据位于项目架构的 storage_objects 表中(列 bucket_name、 key、 owner_id、 metadata、 deleted_at),并启用 RLS 。没有 storage 模式,也没有 storage.foldername() 函数:策略写在列上。

policies delivered by defaultsql
-- 读取:自己的对象,或公共存储桶中的任何对象
create policy storage_objects_select on storage_objects for select
  using (
    owner_id = auth.uid()
    or exists (select 1 from storage_buckets b
                  where b.name = storage_objects.bucket_name and b.public)
  );

-- Writing: only your own objects
create policy storage_objects_insert on storage_objects for insert
  with check (owner_id = auth.uid());

为了走得更远#