Standalone files & media application: React/Vite frontend with the @cohaise/ui design system, Hono + MariaDB backend, nginx reverse proxy, Docker Compose stack, migrations 000-006, and project docs. Adds Gitea Actions workflows for deployment, automatic pull requests, and Renovate dependency updates.
10 KiB
Cloud — modèle de données
Stockage privé de fichiers. Le contenu ne vit jamais dans la base : MariaDB ne
décrit que des métadonnées, les octets restent sur le disque sous
storage_locations.mount_path.
Le service existe et sert ce modèle : 10 routes sous /api/cloud
(src/routes/{auth,folders,files}.ts). Le détail des endpoints, des droits et
du déploiement est dans ../../docs/api.md,
../../docs/security.md et
../../docs/architecture.md.
Modèle de données
erDiagram
roles ||--o{ users : "attribue"
users ||--o{ user_sessions : "ouvre"
users ||--o{ user_avatars : "a pour photo"
users ||--o{ password_reset_tokens : "demande"
users ||--o{ email_change_requests : "demande"
users ||--o{ folders : "proprietaire"
users ||--o{ files : "proprietaire"
users ||--o{ folder_permissions : "beneficie"
users ||--o{ audit_logs : "trace"
storage_locations ||--o{ folders : "contient"
storage_locations ||--o{ files : "contient"
storage_locations ||--o{ user_avatars : "contient"
folders ||--o{ folders : "parent de"
folders ||--o{ files : "contient"
folders ||--o{ folder_permissions : "accede"
files ||--o{ media_metadata : "decrit"
files ||--o{ file_variants : "derive"
Tables
15 tables en base après 005 (share_links ayant été supprimée par 004).
Seules celles marquées « /… » sont atteignables depuis le front.
| Table | Rôle | Exposée par l'API |
|---|---|---|
roles |
admin et user (le readonly de 002 a été retiré par 004) |
indirectement (users.role_slug) |
users |
Comptes : prénom, nom, e-mail, mot de passe, quotas | /auth/* |
user_sessions |
Appareils connectés, révocation, expiration | session interne |
user_avatars |
Photo de profil, une ligne par compte | non |
password_reset_tokens |
Réinitialisation de mot de passe, hachée | non (aucune route) |
email_change_requests |
Validation du nouvel e-mail d'un compte | non (aucune route) |
storage_locations |
Volumes de stockage et quotas globaux | non (interne à storage.ts) |
folders |
Arborescence, avec access_type |
/folders |
folder_permissions |
Droits nominatifs sur un dossier shared |
non (aucune route) |
files |
Métadonnées de l'original, jamais ré-écrit | /files |
media_metadata |
Dimensions, durée, codecs, EXIF, couleur dominante | non (galerie non exposée) |
file_variants |
Miniatures et aperçus WebP dérivés | non |
settings |
Configuration clé-valeur | non |
audit_logs |
Piste d'audit | non (écrit par audit()) |
schema_migrations |
Versions appliquées | non |
Trois notions à ne pas confondre
| Notion | Où elle vit | Ce que c'est |
|---|---|---|
| Le fichier | le disque | les octets d'origine, jamais ré-encodés |
La ligne files |
la base | le nom, la taille, la somme de contrôle, le chemin |
La ligne media_metadata |
la base | ce qu'un lecteur sait du fichier : dimensions, durée, appareil |
Un fichier dénué de media_metadata reste valide : un PDF ou un ZIP n'ont pas
de dimensions. C'est le comportement voulu, une entrée de galerie non encore
analysée doit rester listable.
Originaux intacts, aperçus dérivés
Aucun fichier téléversé n'est ré-encodé. Le contenu reçu est écrit tel quel et
sa somme SHA-256 est mémorisée, ce qui sert à la fois de preuve d'intégrité et
de détection de doublon. Les WebP d'aperçu sont des fichiers supplémentaires
décrits par file_variants, avec un purpose valant thumbnail ou preview ;
un UNIQUE sur (file_id, purpose) interdit d'en empiler deux du même type.
La conséquence assumée : une photo contient ses coordonnées GPS, et puisqu'aucun fichier n'est modifié, ces coordonnées restent lisibles dans l'original. Les aperçus WebP sont ré-encodés et ne les portent pas.
Trois types d'accès aux dossiers
folders.access_type porte l'intention, et non une garde :
| Valeur | Qui accède | Écriture |
|---|---|---|
private |
le propriétaire seul | le propriétaire |
shared |
le propriétaire et les comptes listés dans folder_permissions |
selon le niveau read, write ou admin |
public |
tous les comptes de l'installation | tous peuvent ajouter, personne ne supprime les fichiers d'autrui |
Un seul dossier de l'instance porte is_system = 1, et l'unicité est réelle en
base : la colonne générée system_marker vaut 1 pour lui et NULL pour tous
les autres, donc un second dossier système viole uq_folders_system.
chk_folders_system impose en outre qu'un dossier système soit public.
Les dossiers enfants d'un dossier public restent soumis à l'unicité de nom :
deux enfants ne peuvent pas s'appeler pareil, puisque leur parent_id n'est pas
NULL. La limite ne concerne que la racine, dont les éléments ont
parent_id IS NULL.
Le niveau d'accès est vérifié à chaque requête en base, depuis la session :
voir ../../docs/api.md.
Budget et plafond par utilisateur
Deux réglages distincts, tous deux portés par users :
| Colonne | Effet |
|---|---|
quota_bytes |
volume total que le compte peut occuper, borné par chk_users_quota |
max_file_bytes |
taille maximale d'un dépôt unique |
used_bytes est maintenu par l'application et borné en base : impossible
d'écrire used_bytes > quota_bytes, quelle que soit la requête. Le quota est en
outre re-vérifié en transaction au moment de l'écriture. max_file_bytes, en
revanche, ne peut pas être garanti par une contrainte, car il compare une ligne
de files à une ligne d'users : c'est à l'application de le vérifier, sur la
taille déclarée et sur la taille réellement reçue.
default_quota_bytes et max_upload_bytes dans settings ne sont pas des
plafonds globaux, seulement les valeurs proposées à la création d'un compte.
Unicité après suppression logique
Un nom ou une adresse peut être réutilisé après une suppression logique, grâce à des colonnes générées :
active_email VARCHAR(255) GENERATED ALWAYS AS (IF(deleted_at IS NULL, email, NULL)) STORED,
UNIQUE KEY uq_users_email (active_email)
La ligne supprimée produit NULL, et en SQL plusieurs NULL ne sont pas
égaux : l'index ne la voit plus. C'est cette propriété qui sert deux fois, pour
libérer une adresse de compte et pour autoriser la réimportation d'un fichier au
même nom.
Métadonnées : la part utile et le reste
Ce que la galerie filtre ou affiche est mis en colonnes indexées : taken_at,
width, height, duration_ms, kind, video_codec, camera_make,
camera_model, dominant_color. Le reste des EXIF, qui peut représenter une
trentaine de réglages d'objectif pour quelques kilo-octets et n'est jamais lu,
est facultatif et compressé dans extra_metadata. Rien n'oblige à le remplir.
Chemin physique
Le nom affiché n'entre jamais dans le chemin : ${MEDIA_DIR}/<slug>/<uuid><ext>,
avec resolveInside() qui refuse toute cible hors base. Le choix de
l'emplacement se fait parmi les storage_locations actifs, en privilégiant la
plus grande marge disponible.
Migrations
| Fichier | Contenu |
|---|---|
000_schema_migrations.sql |
table de suivi des versions |
001_initial_schema.sql |
11 tables, 17 clés étrangères, 14 CHECK |
002_reference_data.sql |
rôles, emplacement principal, réglages |
003_integrity_backstop.sql |
CHECK d'audit, interdiction du dossier parent de lui-même |
004_cloud_requirements.sql |
identité complète, sessions, validation d'e-mail, avatar, access_type, médias, variantes, budget par compte, suppression des liens publics |
005_storage_location_realign.sql |
mount_path réaligné sur /data/media, quota 400 Go, garde-fou sur les emplacements sans quota |
006_public_folder.sql |
crée le dossier système « Public », retire les réglages devenus morts |
004 porte le passage d'un modèle de partage public vers un stockage privé :
elle supprime share_links, scinde display_name en first_name et
last_name, et remplace le plafond global max_upload_bytes par les deux
colonnes portées par users. Elle a aussi supprimé le rôle readonly, qui
venait d'une supposition et non d'un besoin formulé.
Une migration appliquée ne se modifie jamais : le checksum la fige. Voir
../../docs/deployment.md.
Sécurité (couche modèle)
- Suppression d'un rôle encore attribué, ou d'un emplacement contenant des
données : refusée par la base (
ON DELETE RESTRICT). - Sessions et jetons stockés hachés en
CHAR(64);password_changed_atpermet de dater un changement. - Les identifiants de dossier et de fichier sont des UUID, non devinables.
audit_logssurvit à la suppression d'un utilisateur (ON DELETE SET NULL) plus un instantanéuser_email,ip_address,user_agent.
En-têtes (CSP/HSTS), CORS et limitation de débit sont décrits dans
../../docs/security.md. Il n'y a pas de jeton
CSRF : les écritures sont des POST/PUT/DELETE et le cookie de session est
SameSite=Lax, ce qui bloque les écritures inter-origines.
Limites actuelles
- La règle « ne pas supprimer les fichiers d'autrui » n'est pas en base.
Aucune contrainte SQL ne peut exprimer « le propriétaire ou un administrateur » :
elle ne vit que dans l'API, et une personne ouvrant un client SQL la contourne.
audit_logsest le seul rempart réel. max_file_bytesn'est pas appliqué en base (voir plus haut).- Les cycles profonds ne sont pas empêchés.
chk_folders_not_self_parentbloque le parent direct de lui-même, maisA → B → Areste possible et demande un parcoursWITH RECURSIVEau moment d'un déplacement. - Deux éléments racine peuvent porter le même nom, dossier ou fichier, puisque
leur clé étrangère de parent vaut
NULL. extra_metadatan'est pas contraint en taille.- Partages publics par lien : retirés par
004; le seul espace partagé est le dossier système « Public » (006), ouvert à tout compte authentifié. - Les réglages
allow_public_sharesetdefault_share_expiry_daysont été supprimés par006(données mortes).