Présentation des buckets

Un bucket est un conteneur nommé pour les fichiers téléversés. Il porte sa propre limite de taille, ses propres types MIME autorisés et sa propre visibilité. Les tables y écrivent via des champs de pièce jointe, les formulaires y acceptent des téléversements, et l'API REST expose par bucket des points de terminaison de téléversement, de téléchargement, d'URL signée et de transformation d'image.

Deux préoccupations restent délibérément séparées :

Où vivent les octets — le backend de stockage — relève de l'opérateur et se règle par variables d'environnement. Cela n'apparaît jamais dans le schéma. Voir Backends de stockage.
Comment les fichiers sont organisés — les buckets — relève de la configuration applicative, déclarée dans le tableau de premier niveau buckets[].

app.yaml

buckets:
  - name: avatars
    public: true
    maxFileSize: 2097152
    allowedMimeTypes: [image/jpeg, image/png, image/webp]
    permissions:
      upload: authenticated
      download: all
      delete: [admin]

Propriétés du bucket

Propriété	Description
`name`	Nom unique, repris tel quel comme préfixe de chemin de stockage. Minuscules, chiffres et traits d'union ; doit commencer par une lettre ; 63 caractères maximum.
`public`	Booléen. À `true`, les fichiers sont servis sans session ni URL signée. Vaut `false` par défaut.
`maxFileSize`	Téléversement le plus lourd accepté, en octets (entier ≥ 1). Prime sur le `STORAGE_MAX_FILE_SIZE` global pour ce bucket.
`allowedMimeTypes`	Types MIME acceptés. Les caractères génériques fonctionnent (`image/*`). Au moins une entrée si présent ; omettre la propriété accepte tout type. Voir Sécurité des téléversements.
`permissions`	Règles d'accès par opération. Voir Permissions de bucket.

Le plafond de 63 caractères et la règle de la lettre initiale viennent de la compatibilité des préfixes S3, et ils sont vérifiés hors ligne : Avatars comme 123-bucket échouent à sovrium validate, tout comme un name dupliqué n'importe où dans le tableau.

Public ou privé

Visibilité	Comportement
`public: true`	Les téléchargements sont servis sans session ni jeton. Adapté aux avatars, logos et visuels marketing.
`public: false` (défaut)	Un téléchargement exige une session ou une URL signée valide. Une requête anonyme reçoit `404`, jamais `403`.

Le 404 est délibéré : un 403 confirmerait qu'un fichier existe à une clé devinée, aussi les buckets privés répondent-ils comme si le chemin n'avait aucun sens.

Un opérateur peut également rendre publics des préfixes de chemin sur tous les buckets avec STORAGE_PUBLIC_PATHS — voir URL signées.

Le bucket default implicite suit votre configuration d'authentification. Lorsque buckets est omis, Sovrium sert malgré tout /api/buckets/default/.... Ce bucket implicite est privé quand app.auth est configuré et public quand il ne l'est pas — une application sans système de session n'a rien à contrôler, si bien que les téléversements anonymes de formulaire continuent de fonctionner. Déclarez le bucket explicitement dès que vous voulez une autre réponse.

Backends de stockage

Déplacé vers Backends de stockage — les backends local, S3 et bytea, et la façon dont le binaire en choisit un.

Permissions

Déplacé vers Permissions de bucket — les cinq entrées par opération, leurs valeurs par défaut, et celles que l'exécution applique réellement aujourd'hui.

Exemple : plusieurs buckets

Un bucket d'images public à côté d'un bucket de documents privé et restreint par rôle :

app.yaml

buckets:
  - name: avatars
    public: true
    maxFileSize: 2097152
    allowedMimeTypes: [image/*]
    permissions:
      upload: authenticated
      download: all
      delete: [admin]

  - name: documents
    maxFileSize: 52428800
    allowedMimeTypes: [application/pdf]
    permissions:
      upload: [admin, editor]
      download: authenticated
      sign: authenticated
      signUpload: [admin, editor]
      delete: [admin]

Rien n'est partagé entre les deux hormis le backend. avatars accepte n'importe quelle image jusqu'à 2 Mo de tout utilisateur connecté et la sert au monde entier ; documents accepte des PDF jusqu'à 50 Mo de deux rôles et ne les délivre que via une session ou une URL signée.

Pages associées

Backends de stockage — où les octets atterrissent réellement.
Permissions de bucket — les règles d'accès par opération.
Opérations sur les fichiers — les points de terminaison de téléversement, téléchargement et suppression.
URL signées — accès limité dans le temps aux fichiers privés.
Redimensionnement et recadrage — transformations d'image à la volée.
Champs de pièce jointe et stockage — les fichiers rattachés aux enregistrements.

Dernière mise à jour 11 août 2026

← PrécédentServeur OAuth Suivant →Backends de stockage

Modifier cette page Signaler un problème

Cette documentation a été rédigée avec de l'IA : des erreurs ou du contenu obsolète sont donc possibles. Sovrium est en bêta. Les contributions et corrections sont les bienvenues.