Sauvegarder et mettre à jour

Statut au 2026-11-05 (lot 1b) : la base est couverte. protoflix backup create, backup verify, backup restore, migrate up et migrate status sont implémentés et testés (tests d'intégration sur un vrai fichier SQLite, sous Windows et sous Linux avec -race). L'archive du reste de DATA_DIR, le manifest.json et la planification restent planifiés (phase 6). Une procédure n'est valide qu'une fois testée de bout en bout.

1. Ce qui est sauvegardé#

Les sauvegardes contiennent des données privées des comptes (historique, « Ma liste », éventuellement bibliothèques privées) : les stocker chiffrées et avec des permissions restreintes.

La clé de chiffrement des secrets (DATA_DIR) et la base doivent être restaurées ensemble ; sans la clé, les secrets stockés en base (clés API fournisseurs) sont irrécupérables et doivent être ressaisis.

2. Sauvegarde#

Commande : protoflix backup create [-o <fichier>], par défaut DATA_DIR/backups/protoflix-<horodatage>.db. Elle fonctionne service démarré : elle ouvre sa propre connexion, et en WAL la lecture ne bloque pas le serveur.

Implémenté :

• protoflix-<horodatage>.db : copie cohérente de la base par VACUUM INTO. Elle est compacte, sans fichiers -wal ni -shm, en permissions 0600, et vérifiée par PRAGMA integrity_check avant d'être déclarée réussie. Une destination existante n'est jamais écrasée.
• protoflix backup verify <fichier> contrôle l'intégrité d'une sauvegarde à tout moment.

Planifié (phase 6) :

• protoflix-<horodatage>-data.tar.zst : le reste de DATA_DIR (hors base et hors backups/) ;
• manifest.json : version du serveur, version du schéma, version de SQLite embarquée, sommes SHA-256 des fichiers.

Ne jamais copier protoflix.db à la main pendant que le service tourne, et ne jamais copier ni supprimer séparément protoflix.db-wal ou protoflix.db-shm : en mode WAL, des transactions validées peuvent ne se trouver que dans le -wal, et une copie partielle donne une base incohérente ou corrompue. Pour une sauvegarde manuelle sans la commande, il faut arrêter le service puis copier protoflix.db, -wal et -shm ensemble.

Équivalent manuel, service démarré, avec l'outil sqlite3 de l'hôte s'il est installé :

sqlite3 /var/lib/protoflix/protoflix.db "VACUUM INTO '/var/backups/protoflix/protoflix-$(date +%Y%m%dT%H%M%S).db'"

tar --zstd -cf protoflix-data.tar.zst -C /var/lib/protoflix --exclude='./protoflix.db*' --exclude='./backups' .

Recommandations : une sauvegarde quotidienne planifiée (timer systemd ou job interne), une rétention de 7 sauvegardes quotidiennes et 4 hebdomadaires, et une copie hors de la machine. Les sauvegardes locales de DATA_DIR/backups/ ne protègent pas contre la perte du disque. La sauvegarde n'arrête pas le service : VACUUM INTO lit un instantané cohérent, et les écritures concurrentes attendent au plus la durée de la copie, à mesurer sur la bibliothèque de référence. L'archive de DATA_DIR peut contenir un artwork en cours d'écriture, sans conséquence sur la cohérence, car il peut être téléchargé à nouveau.

3. Restauration#

Procédure :

1. Installer la même version de ProtoFlix que celle de la sauvegarde, ou une plus récente (voir §4.2).
2. Arrêter le service.
3. Lancer la restauration sous le compte du service :

sudo -u protoflix protoflix backup restore /var/backups/protoflix/protoflix-20261105T030000Z.db

La commande (implémentée) :

• refuse de s'exécuter si un serveur utilise le répertoire de données (verrou d'instance) ;
• vérifie l'intégrité de la sauvegarde avant de toucher quoi que ce soit ;
• conserve la base actuelle et ses fichiers -wal et -shm, renommés avec le suffixe .before-restore-<horodatage> (rien n'est supprimé) ;
• copie la sauvegarde à la place, puis vérifie de nouveau le résultat.

1. Restaurer le reste de DATA_DIR et vérifier propriétaire et permissions (0750 pour le répertoire, 0600 pour protoflix.db et la clé).
2. Démarrer le service. Si la sauvegarde est d'un schéma plus ancien, le serveur demande protoflix migrate up (ou l'applique si PROTOFLIX_AUTO_MIGRATE=true, après une nouvelle sauvegarde). Planifié (phase 2) : une réconciliation des bibliothèques vérifie ensuite la présence des fichiers sans rien supprimer.
3. Contrôler : protoflix doctor, nombre de titres, progression d'un compte témoin.

Tests : internal/sqlitedb couvre déjà sauvegarde base ouverte → modification → restauration → valeur d'origine retrouvée, ainsi que le refus d'une sauvegarde corrompue. Planifié (phase 6) : le même scénario sur une bibliothèque de référence, avec comparaison des comptes et d'un échantillon d'objets, et une sauvegarde prise pendant des écritures concurrentes soutenues.

4. Migrations#

4.1 Politique#

• Migrations SQL versionnées (goose, ADR 0005), embarquées dans le binaire, appliquées au démarrage par le coordinateur, seul processus qui ouvre la base (ADR 0019, 0020). Le verrou d'instance DATA_DIR/protoflix.lock (une petite base SQLite tenue en verrouillage exclusif, libérée par le système même après un arrêt brutal) empêche deux coordinateurs, une migration et un serveur, ou une restauration et un serveur, de travailler en même temps sur le même DATA_DIR.
• Démarrage : une base neuve (schéma 0) est initialisée directement, puisqu'il n'y a rien à perdre. Une base existante en retard n'est migrée que par protoflix migrate up ou avec PROTOFLIX_AUTO_MIGRATE=true (valeur de l'image Docker). Sinon le serveur refuse de démarrer et indique la commande à lancer. Une base plus récente que le binaire est toujours refusée.
• En avant uniquement en production. Les migrations down existent pour le développement et les tests ; elles ne sont pas une stratégie de retour arrière.
• Sauvegarde automatique avant migration (implémentée) : avant de migrer une base existante, une copie vérifiée est écrite dans DATA_DIR/backups/pre-migrate-v<version>-<horodatage>.db. Si la sauvegarde échoue, rien n'est migré. Si une migration échoue, elle est annulée (une transaction par migration), et le message d'erreur donne le chemin de la sauvegarde.
• Compatibilité N-1 : une version N doit pouvoir démarrer sur un schéma migré par N, et une version N-1 en cours d'arrêt ne doit pas casser pendant la migration. Concrètement, les changements destructifs (suppression/renommage de colonne) se font en deux versions : ajout + double écriture en N, suppression en N+1 (motif expand/contract).
• Migrations longues (réindexation, remplissage) : exécutées en jobs de fond après le démarrage plutôt que dans la migration bloquante, si elles dépassent un budget de quelques secondes sur la bibliothèque de référence.
• Le moteur SQLite est embarqué dans le binaire : il n'y a pas de montée de version de moteur à gérer par l'administrateur. Le format de fichier SQLite est rétrocompatible. Une mise à jour du pilote qui changerait la version de SQLite est notée dans le CHANGELOG.md.
• Les limites d'ALTER TABLE dans SQLite (recréer la table, copier, renommer) sont gérées dans les migrations elles-mêmes (ADR 0005).

4.2 Restaurer une sauvegarde ancienne sur une version récente#

Supporté : une sauvegarde d'une version N peut être restaurée sous N+k, les migrations rattrapant le schéma. Non supporté : restaurer une sauvegarde d'un schéma plus récent que le binaire (le serveur refuse de démarrer avec un message explicite).

5. Mise à jour#

Procédure cible :

1. Lire les notes de version (CHANGELOG.md) : changements de configuration, migrations longues, dépréciations d'API.
2. Sauvegarde (automatique avant migration, §4.1).
3. Arrêt gracieux : SIGTERM ⇒ le serveur cesse d'accepter de nouvelles sessions, laisse se terminer les requêtes en cours (délai configurable, 20 s par défaut), arrête proprement les processus FFmpeg, rend les leases de jobs, effectue un checkpoint WAL, puis ferme la base et quitte. Les workers distants voient l'API interne indisponible et se reconnectent avec backoff. Les lectures en cours sont interrompues ; les clients reprennent à la dernière position durable.
4. Remplacer le binaire ou l'image.
5. Démarrer : migrations, puis /readyz passe à prêt.
6. Retour arrière : réinstaller l'ancienne version et restaurer la sauvegarde pré-migration si le schéma a changé.

Le module « Mises à jour » (ADR 0027) fait tout cela en un clic dans l'administration, ou seul la nuit, et revient en arrière si la nouvelle version ne répond pas dans ses 5 minutes. Le résultat de la dernière tentative se lit dans GET /api/v1/admin/updates, et le détail dans journalctl -u protoflix-update.

6. Provenance des binaires#

À définir avant la première publication (phase 6) :

• sommes SHA-256 publiées pour chaque archive et image ;
• signature des artefacts (outil à choisir : signatures détachées, Sigstore/cosign ou équivalent) ;
• SBOM incluant le binaire FFmpeg distribué et ses options de compilation ;
• builds reproductibles à évaluer (Go les facilite ; FFmpeg et l'image de base les compliquent).

La mise à jour en un clic ou automatique (ADR 0027) n'exécute qu'une version signée par le projet, vérifiée par le binaire déjà installé. Le module qui contacte la source est désactivé par défaut (secrets-and-privacy.md §7).

Seule exception au téléchargement de code, et sur demande de l'administrateur : les modules externes (ADR 0024), signés, confinés dans leur propre processus et hors du binaire. Ils ne modifient jamais le serveur. Leurs données sont dans DATA_DIR/modules/ et n'entrent pas encore dans protoflix backup : à sauvegarder avec DATA_DIR.

Source : docs/operations/backup-restore-upgrade.md, dans le dépôt de ProtoFlix.