Skip to main content
View as Markdown

Présentation des buckets

Les buckets sont des conteneurs nommés pour les fichiers téléversés. Chaque bucket porte sa propre limite de taille, ses types MIME autorisés, sa visibilité publique/privée et ses permissions d'accès. Les tables référencent les buckets via des champs de pièce jointe, les formulaires y écrivent des fichiers, et l'API REST expose des points de terminaison de téléversement, de téléchargement, d'URL signée et de transformation d'image.

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

  • Où les fichiers sont stockés — le backend de stockage — est contrôlé par l'opérateur via des variables d'environnement (STORAGE_PROVIDER et consorts). Il n'apparaît jamais dans le schéma de l'application.
  • Comment les fichiers sont organisés — les buckets — est une configuration d'application déclarée dans le tableau de premier niveau buckets[] de votre configuration.
buckets:
  - name: avatars
    public: true
    maxFileSize: 2097152
    allowedMimeTypes: [image/jpeg, image/png, image/webp]
    permissions:
      upload: authenticated
      download: all
      delete: [admin]

Lorsque buckets est entièrement omis, Sovrium provisionne un bucket default implicite (public: false, permissions par défaut standard).

Backends de stockage

Le backend est choisi au moment du déploiement avec STORAGE_PROVIDER. Les trois backends prennent en charge l'intégralité de la surface des opérations de fichiers, des URL signées et des transformations d'image.

Backend STORAGE_PROVIDER Idéal pour Évolutivité URL présignées natives
Système de fichiers local local (par défaut) Développement, mononœud, auto-hébergé Limité par le disque Non (Sovrium signe en interne)
S3 / compatible S3 s3 Production, scale-out Illimité Oui (délégué au fournisseur)
MinIO s3 + STORAGE_FORCE_PATH_STYLE=true Magasin d'objets compatible S3 auto-hébergé Illimité Oui
PostgreSQL bytea bytea Petits fichiers, déploiements mono-base simples Limité par la base Non (Sovrium signe en interne)

Variables d'environnement du backend

Variable Requis Par défaut Objectif
STORAGE_PROVIDER Non local Backend de stockage : s3, local ou bytea.
STORAGE_ENDPOINT S3 seul — URL du point de terminaison compatible S3.
STORAGE_BUCKET S3 seul — Nom du bucket S3 sous-jacent (le magasin d'objets hôte, pas un bucket Sovrium).
STORAGE_REGION S3 seul us-east-1 Région AWS.
STORAGE_ACCESS_KEY S3 seul — ID de clé d'accès S3.
STORAGE_SECRET_KEY S3 seul — Clé d'accès secrète S3.
STORAGE_FORCE_PATH_STYLE Non false Utiliser des URL de style chemin (requis pour MinIO).

Voir Variables d'environnement pour la référence complète des variables côté opérateur.

Propriétés du bucket

Chaque entrée du tableau buckets[] accepte les propriétés suivantes.

Propriété Description
name Nom de bucket unique. Minuscules, alphanumérique, traits d'union ; doit commencer par une lettre ; 63 caractères max (compatibilité de préfixe S3). Utilisé comme préfixe de chemin de stockage.
public Booléen. Lorsque true, les fichiers sont servis sans URL signées. Vaut false par défaut (privé).
maxFileSize Taille maximale de fichier en octets pour les téléversements vers ce bucket. Surcharge le STORAGE_MAX_FILE_SIZE global. Doit être ≥ 1.
allowedMimeTypes Tableau des types MIME autorisés pour les téléversements. Prend en charge les caractères génériques (par ex. image/*). Lorsqu'il est omis, tous les types sont acceptés. Minimum une entrée.
permissions Contrôle d'accès par opération. Voir Permissions ci-dessous.

Permissions

Les permissions de bucket utilisent le même format partagé PermissionValueSchema que les permissions de table : chaque opération accepte all, authenticated, ou une liste de noms de rôles.

Opération Description Par défaut
upload Qui peut téléverser des fichiers vers ce bucket. authenticated
download Qui peut télécharger des fichiers depuis ce bucket. all si public, authenticated si privé
sign Qui peut générer des URL de téléchargement signées. authenticated
signUpload Qui peut générer des URL de téléversement signées. [admin]
delete Qui peut supprimer des fichiers de ce bucket. [admin]

Valeurs de permission :

  • all — tout le monde, y compris les requêtes non authentifiées.
  • authenticated — tout utilisateur connecté.
  • ['admin', 'editor'] — uniquement les rôles listés.
buckets:
  - name: documents
    maxFileSize: 52428800
    allowedMimeTypes: [application/pdf, text/csv]
    permissions:
      upload: [admin, editor]
      download: authenticated
      sign: authenticated
      signUpload: [admin, editor]
      delete: [admin]

Lorsqu'un bucket omet entièrement permissions, les valeurs par défaut par opération ci-dessus s'appliquent — notamment, seul le rôle admin peut générer des URL signées.

Public vs privé

Visibilité Comportement
public: true Fichiers servis directement sans authentification ni URL signées. Convient aux avatars, logos, ressources marketing.
public: false (par défaut) Les fichiers requièrent soit une authentification (correspondant à la permission download) soit une URL signée valide.

Les opérateurs peuvent en outre exposer des préfixes de chemin globalement via STORAGE_PUBLIC_PATHS (voir URL signées).

Exemple : buckets multiples

Un bucket d'images public aux côtés d'un bucket de documents privé, restreint par rôle.

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]

Pages associées