Backends de stockage

Un bucket dit comment les fichiers sont organisés. Le backend dit où leurs octets aboutissent. C'est une décision d'opérateur, prise entièrement par variables d'environnement, et elle n'apparaît jamais dans le schéma — le même fichier de configuration tourne sur disque local en développement et sur S3 en production.

Les trois backends prennent en charge toute la surface : téléversement, téléchargement, suppression, URL signées et transformations d'image.

Backend	STORAGE_PROVIDER	Idéal pour	Échelle
Système de fichiers local	local	Développement, mononœud, auto-hébergé	Limité par le disque
S3 / compatible S3	s3	Production, multinœud	Illimité
MinIO, R2, Scaleway	s3 + STORAGE_S3_FORCE_PATH_STYLE=true	Stockages objet auto-hébergés ou non-AWS	Illimité
PostgreSQL bytea	bytea	Petits fichiers, déploiement mono-base, sans disque	Limité par la base

Choisir un backend

STORAGE_PROVIDER n'est pas obligatoire. Laissée vide, la variable fait suivre au backend le dialecte de base de données :

STORAGE_PROVIDER	DATABASE_URL	Backend obtenu
s3	indifférent	S3. Les cinq identifiants STORAGE_S3_* sont requis.
local	indifférent	Système de fichiers local. STORAGE_LOCAL_DIRECTORY est requis — sans repli.
non défini	défini (Postgres)	bytea — les octets vont dans la base que vous exploitez déjà.
non défini	non défini (SQLite)	Système de fichiers local sous <répertoire de données>/storage.

Les deux dernières lignes constituent le chemin zéro-configuration, et elles reflètent la posture « SQLite par défaut » : rien d'externe à provisionner, aucun identifiant à gérer. Notez l'asymétrie — un STORAGE_PROVIDER=local explicite échoue au démarrage sans STORAGE_LOCAL_DIRECTORY, alors qu'un local implicite choisit le répertoire par défaut pour vous. La forme explicite est traitée comme une affirmation délibérée sur l'emplacement : un répertoire manquant y devient une erreur qui mérite d'être signalée.

# Zéro configuration : rien de défini, base SQLite → fichiers locaux sous le répertoire de données
# Local explicite
STORAGE_PROVIDER=local
STORAGE_LOCAL_DIRECTORY=/var/lib/sovrium/uploads

# Compatible S3 (MinIO ici — retirez l'option path-style pour AWS)
STORAGE_PROVIDER=s3
STORAGE_S3_ENDPOINT=https://minio.example.com
STORAGE_S3_BUCKET=my-app-files
STORAGE_S3_REGION=eu-west-1
STORAGE_S3_ACCESS_KEY_ID=...
STORAGE_S3_SECRET_ACCESS_KEY=...
STORAGE_S3_FORCE_PATH_STYLE=true

La signature selon le backend

S3 expose une présignature native : les URL signées sur ce backend sont donc déléguées au fournisseur. Local et bytea n'offrent pas cette primitive, aussi Sovrium signe et vérifie lui-même des jetons HMAC sur sa propre route /signed. La différence est invisible pour les appelants : la même requête produit la même forme d'URL sur les trois backends, et une URL émise sur l'un n'est jamais transposable à un autre.

Pages associées

• Présentation des buckets — les buckets posés sur un backend.
• Permissions de bucket — qui peut lire et écrire.
• Opérations sur les fichiers — les points de terminaison servis par tous les backends.
• URL signées — présignées sur S3, signées en HMAC ailleurs.
• Variables d'environnement : services — la référence complète STORAGE_*.
• Écoconception — pourquoi le défaut sans dépendance est le défaut.