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. Quatre variables STORAGE_S3_* sont requises — voir plus bas. |
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=trueQuatre d'entre elles sont requises : posez STORAGE_PROVIDER=s3 avec au moins l'une d'elles et une sœur manquante fait échouer le démarrage en la nommant. Les deux autres ont une valeur par défaut et ne méritent d'être posées que si celle-ci ne convient pas à votre fournisseur.
| Variable | Requise | Par défaut |
|---|---|---|
STORAGE_S3_ENDPOINT |
Oui | — |
STORAGE_S3_BUCKET |
Oui | — |
STORAGE_S3_ACCESS_KEY_ID |
Oui | — |
STORAGE_S3_SECRET_ACCESS_KEY |
Oui | — |
STORAGE_S3_REGION |
Non | us-east-1 |
STORAGE_S3_FORCE_PATH_STYLE |
Non | false |
Un seul bucket hôte, quel que soit le nombre déclaré. Chaque bucket de buckets[] range ses objets dans l'unique magasin d'objets nommé par STORAGE_S3_BUCKET. Vous ne créez pas un bucket S3 par bucket Sovrium, et vous n'avez même pas besoin du droit d'en créer.
Un bucket déclaré n'est pas un dossier : les clés sont plates, et chaque objet mémorise le bucket vers lequel il a été téléversé au lieu de le porter dans son chemin. C'est ce rattachement qui tient les objets d'un bucket hors de portée d'un autre — voir Rattachement au bucket.
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.
Dernière mise à jour 1 septembre 2026
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.