Ir para o conteúdo
Aura Logo
aurabase

Armazenamento

API REST por projeto em armazenamento S3 (SeaweedFS S3), transformações de imagem dinâmicas com cache derivado, URLs assinados HMAC, buckets públicos ou privados, lixo e restauração.

Explicação6 min lidoNível intermediárioRevisado em 15 de abr. de 2026

Esta página foi traduzida automaticamente. A versão em inglês é oficial.

Um bucket, uma origem, um CDN#

O aura-storage service gerencia seus arquivos binários: upload, download, transformações de imagem, URLs assinados, lixo. Ele expõe o seu próprio API REST sob /v1/storage/{project_id} e depende do armazenamento S3 (SeaweedFS S3) internamente - as ferramentas S3 (rclone, boto3) não se conectam a ele diretamente.

Os objetos são organizados em buckets. Cada bucket tem uma política (pública ou privada), limites de tamanho, um TTL opcional e um conjunto de políticas RLS que controlam quem pode ler/gravar cada caminho.

Informações

Os metadados residem no esquema do projeto: storage_buckets, storage_objects, storage_derivatives, storage_project_settings, storage_audit_log. Os bytes estão no armazenamento S3.

Caminho → RLS → CDN → origem#

Durante uma leitura, o serviço verifica o acesso ao caminho solicitado e, em seguida, fornece os bytes do armazenamento. Se a consulta transportar parâmetros de transformação, a derivada correspondente será reutilizada se já existir; caso contrário, será calculada e armazenada em cache. No upload, o fluxo é invertido: cliente → serviço → armazenamento, após escrever o controle e os limites do bucket.

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

Seis habilidades nativas#

  • API REST por projeto. Rotas /v1/storage/{project_id}/… no armazenamento S3 (SeaweedFS S3) — esta não é uma API S3: SDKs S3 não se conectam a ela.
  • Transforma-se instantaneamente. largura, altura, ajuste, formato (jpeg/png/webp/gif), qualidade, girar, inverter. Cada combinação é armazenada em cache como uma derivada.
  • URLs assinados. HMAC assinatura no método + bucket + chave + expiração. TTL 3600 s por padrão, rotação secreta por projeto.
  • Multipart upload. Upload simples em multipart/form-data ou init/part/complete para arquivos grandes.
  • Lixo e restauração. Exclusão suave: /trash lista objetos excluídos, /restore/{key} os restaura.
  • Buckets públicos ou privados. O bucket contém a política de acesso, limites de tamanho e a lista de tipos MIME autorizados.

Quatro operações básicas#

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

// Sem upsert, um caminho já ocupado falha em 409 (código CONFLICT)
Dica

URLs de transformação são imutáveis por parâmetros. ?width=240&format=png e ?width=240&format=webp são duas URLs distintas, portanto, duas derivadas distintas: cada combinação é calculada apenas uma vez e depois relida no cache de derivadas.

RLS em caminhos de objetos#

Os metadados do objeto residem na tabela storage_objects do esquema do projeto (colunas bucket_name, key, owner_id, metadata, deleted_at), com RLS ativado. Não há esquema storage nem função storage.foldername(): as políticas são escritas nas colunas.

políticas entregues por padrãosql
-- Leitura: objeto próprio ou qualquer objeto de um bucket público
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)
  );

-- Escrita: apenas seus próprios objetos
create policy storage_objects_insert on storage_objects for insert
  with check (owner_id = auth.uid());

Para ir mais longe#