Vai al contenuto
Logo Aurabase
aurabase

Stoccaggio

API REST per progetto su storage S3 (SeaweedFS S3), trasformazioni di immagini al volo con cache derivata, URL firmati HMAC, bucket pubblici o privati, cestino e ripristino.

Spiegazione6 min lettoLivello intermedioRevisionato il 15 apr 2026

Questa pagina è stata tradotta automaticamente. Fa fede la versione inglese.

Un bucket, un'origine, un CDN#

Il servizio aura-storage gestisce i tuoi file binari: caricamento, download, trasformazioni di immagini, URL firmati, cestino. Espone la propria API REST sotto /v1/storage/{project_id} e si basa sullo storage S3 (SeaweedFS S3) internamente: gli strumenti S3 (rclone, boto3) non si connettono direttamente ad esso.

Gli oggetti sono organizzati in bucket. Ogni bucket ha una policy (pubblica o privata), limiti di dimensione, un TTL opzionale e un set di policy RLS che controllano chi può leggere/scrivere ciascun percorso.

Informazioni

I metadati risiedono nello schema del progetto: storage_buckets, storage_objects, storage_derivatives, storage_project_settings, storage_audit_log. I byte sono nella memoria S3.

Percorso → RLS → CDN → origine#

Durante una lettura, il servizio verifica l'accesso al percorso richiesto e quindi serve i byte dall'archivio. Se la query contiene parametri di trasformazione, la derivata corrispondente viene riutilizzata se esiste già, altrimenti calcolata e quindi memorizzata nella cache. In caricamento il flusso è invertito: client → servizio → storage, dopo aver scritto i limiti di controllo e bucket.

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

Sei abilità native#

  • API REST per progetto. Routes /v1/storage/{project_id}/… sullo storage S3 (SeaweedFS S3) — questa non è un'API S3: gli SDK S3 non si collegano ad essa.
  • Si trasforma al volo. larghezza, altezza, adattamento, formato (jpeg/png/webp/gif), qualità, rotazione, capovolgimento. Ogni combinazione viene memorizzata nella cache come derivata.
  • URL firmati. HMAC firma sul metodo + bucket + chiave + scadenza. TTL 3600 s per impostazione predefinita, rotazione segreta per progetto.
  • Caricamento in più parti. Caricamento semplice in multipart/form-data o init/part/complete per file di grandi dimensioni.
  • Cestino e ripristino. Eliminazione temporanea: /trash elenca gli oggetti eliminati, /restore/{key} li ripristina.
  • Bucket pubblici o privati. Il bucket contiene la policy di accesso, i limiti di dimensione e l'elenco dei tipi MIME autorizzati.

Quattro operazioni fondamentali#

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

// Senza upsert, un percorso già occupato fallisce in 409 (codice CONFLICT)
Suggerimento

Gli URL di trasformazione sono immutabili in base ai parametri. ?width=240&format=png e ?width=240&format=webp sono due URL distinti, quindi due derivate distinte: ogni combinazione viene calcolata una sola volta, quindi riletta dalla cache delle derivate.

RLS sui percorsi degli oggetti#

I metadati dell'oggetto si trovano nella tabella storage_objects dello schema del progetto (colonne bucket_name, key, owner_id, metadata, deleted_at), con RLS abilitato. Non esiste uno schema storage né una funzione storage.foldername(): le policy sono scritte sulle colonne.

politiche fornite per impostazione predefinitasql
-- Leggi: oggetto proprio o qualsiasi oggetto da un bucket pubblico
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)
  );

-- Scrittura: solo i tuoi oggetti
create policy storage_objects_insert on storage_objects for insert
  with check (owner_id = auth.uid());

Per andare oltre#