Sauvegarde et restauration

QuoteNode inclut un systeme de sauvegarde integre qui protege vos donnees commerciales contre les pannes materielle, les suppressions accidentelles et les incidents operationnels.

Ce qui est sauvegarde

Chaque sauvegarde capture trois composants :

1. Dump de base — un dump PostgreSQL complet au format custom (pg_dump --format=custom), incluant toutes les tables, sequences et contraintes.
2. Stockage de fichiers — tous les fichiers televerses (images produit, logos entreprise) et les PDF generes, archives dans files.tar.gz.
3. Manifest d’integrite — un fichier checksums.sha256 contenant les hashes SHA-256 du dump de base et de l’archive de fichiers, permettant de verifier qu’une sauvegarde n’a pas ete corrompue ni alteree.

Sauvegarde online (par defaut)

Les sauvegardes online tournent pendant que l’application sert des requetes. Il n’y a pas de downtime.

Comment cela fonctionne :

• pg_dump au format custom cree un snapshot transactionnellement coherent de la base sans verrouiller les tables ni bloquer les requetes.
• Le stockage de fichiers est archive en parallele. Comme les fichiers envoyes et les PDF sont immuables une fois crees, l’archive reste coherente.
• Les deux sorties recoivent un checksum et peuvent etre chiffrees avant stockage.

Limitations :

• Si une transaction est en cours au moment exact du dump, ses donnees non committees ne sont pas incluses. C’est le comportement attendu : le dump represente un etat coherent a un instant T.
• Pour la plupart des organisations, cela suffit largement. Les sauvegardes online sont l’approche recommandee.

Sauvegarde offline

Pour une garantie maximale de coherence, par exemple avant une grosse migration ou un upgrade :

1. Arretez les conteneurs applicatifs (docker compose stop backend backup-worker).
2. Lancez pg_dump directement contre le conteneur PostgreSQL en cours.
3. Archivez les volumes de stockage de fichiers.
4. Redemarrez l’application.

Cette approche elimine toute transaction en vol, mais exige une breve fenetre de maintenance, generalement de 1 a 5 minutes selon la taille de la base.

Planification

Les sauvegardes sont pilotees par le conteneur backup-worker, c’est-a-dire une instance dediee du backend en mode backup-only :

• Planification par defaut : 2h00 tous les jours (0 0 2 * * *, configurable via BACKUP_CRON)
• Activation / desactivation : BACKUP_ENABLED=true|false
• Declenchement manuel : les administrateurs peuvent lancer une sauvegarde immediate depuis le panneau d’administration ou via l’API (POST /api/v1/admin/backup/trigger)
• Protection de concurrence : le pattern SKIP LOCKED garantit qu’une seule sauvegarde tourne a la fois, meme si plusieurs workers existent

Options de stockage

Stockage local (par defaut)

Les sauvegardes sont stockees dans BACKUP_LOCAL_DIR (par defaut : /app/data/backups), mappe sur un volume Docker. Cela convient au developpement et aux petites installations.

En production, les sauvegardes locales doivent etre completees par des copies distantes. Un backup stocke sur le meme disque que la base ne protege pas contre la panne de ce disque.

Stockage distant via rclone

Si BACKUP_RCLONE_REMOTE est configure, les sauvegardes sont automatiquement poussees vers une destination distante apres leur creation locale. rclone prend en charge plus de 70 fournisseurs, notamment :

• S3-compatible — AWS S3, MinIO, DigitalOcean Spaces, Backblaze B2
• Google Cloud Storage
• Azure Blob Storage
• SFTP — n’importe quel serveur avec acces SSH
• WebDAV — Nextcloud, ownCloud, etc.

Si l’upload distant echoue, la sauvegarde locale reste preservee et l’echec est journalise.

Chiffrement

Les sauvegardes peuvent etre chiffrees au repos avec GPG :

• Definissez BACKUP_GPG_RECIPIENT avec l’ID de cle ou l’adresse email GPG.
• Le script de sauvegarde chiffre le dump de base et l’archive de fichiers avant stockage.
• Les fichiers chiffres recoivent l’extension .gpg.
• Le dechiffrement exige la cle privee correspondante. Sans elle, le backup est inutilisable.

Cela est critique pour les organisations qui stockent leurs sauvegardes chez un fournisseur cloud tiers et ne veulent pas qu’il puisse lire leur contenu.

Metadonnees et piste d’audit

Chaque sauvegarde, reussie ou echouee, est tracee dans la table backup_logs :

Champ	Description
Status	PENDING, RUNNING, COMPLETED, FAILED
Initiated by	SCHEDULER (automatique) ou ADMIN (declenchement manuel)
Start time	Moment ou le processus de sauvegarde commence
Completion time	Moment ou le processus se termine
Size (bytes)	Taille totale de l’archive
Destination	Chemin local ou URL distante
SHA-256 checksum	Hash d’integrite de l’archive
Error message	Raison de l’echec, si applicable

Les 50 dernieres entrees sont consultables via le panneau d’administration ou l’API.

Restauration

Procedure de restauration complete

1. Arretez tous les conteneurs : docker compose down
2. Restaurez la base :

   pg_restore --clean --if-exists -d quotenode backup.dump

3. Extrayez le stockage de fichiers :

   tar xzf files.tar.gz -C /app/data/

4. Redemarrez les conteneurs : docker compose up -d
5. Verifiez que le checksum correspond au manifest de sauvegarde.

Restauration partielle

Il est possible de restaurer des tables individuelles ou des sous-ensembles de donnees depuis un dump custom avec pg_restore et des flags cibles. C’est utile pour recuperer des enregistrements supprimes par erreur sans relancer un restore complet.

Restauration de sauvegardes chiffrees

Pour des sauvegardes chiffrees GPG :

gpg --decrypt backup.dump.gpg > backup.dump
gpg --decrypt files.tar.gz.gpg > files.tar.gz

Ensuite, on poursuit avec la procedure standard.

Timeout de sauvegarde

Chaque operation de sauvegarde a une limite de 30 minutes. Si la sauvegarde ne se termine pas dans cette fenetre, elle est stoppee et marquee FAILED. Pour de tres grosses bases (10+ Go), cette limite peut etre etendue en configuration.

Telecharger des sauvegardes

Les administrateurs peuvent telecharger des archives de sauvegarde directement depuis le panneau d’administration :

1. Ouvrez Settings > Backup
2. Trouvez la sauvegarde souhaitee (son statut doit etre Success)
3. Cliquez sur Download sur l’entree concernée

Le fichier telecharge est une archive .tar.gz contenant le dump de base, les fichiers et le manifest d’integrite. Il faut le conserver de maniere sure, car il contient l’ensemble de vos donnees metier.

Les sauvegardes telechargees peuvent etre utilisees pour un disaster recovery sur un nouveau serveur ou pour migrer vers un autre environnement d’hebergement.

Note : les sauvegardes stockees uniquement a distance (S3, SFTP, etc.) ne peuvent pas etre telechargees via l’admin. Il faut les recuperer directement depuis le fournisseur de stockage.

Retention des sauvegardes

Les anciens fichiers de sauvegarde sont nettoyes automatiquement apres chaque sauvegarde reussie. La politique est pilotee par BACKUP_RETENTION_DAILY (par defaut : 7). Le systeme conserve les N dernieres sauvegardes reussies et supprime les anciens fichiers locaux.

Les sauvegardes distantes poussees via rclone ne sont pas supprimees par QuoteNode. Configurez plutot les regles de cycle de vie chez votre fournisseur.

Disaster recovery a partir de zero

Votre serveur a disparu. Vous possedez un fichier de sauvegarde (.tar.gz, telecharge depuis l’admin ou stocke a distance). Vous avez un nouveau serveur avec Docker. Voici comment tout reconstruire.

Etape 1 — Preparer le nouveau serveur

Creer un repertoire de projet et preparer la configuration exactement comme decrit dans le Guide d’installation :

mkdir quotenode && cd quotenode

Vous avez besoin de deux fichiers :

• docker-compose.yml — copie depuis le guide d’installation
• .env — restaure a partir de votre copie de sauvegarde

Critique : utilisez le meme DB_ENCRYPTION_KEY que dans l’installation originale. Sans lui, les donnees chiffrees (codes MFA, credentials SMTP et PII si ENCRYPT_PII=true) deviennent definitivement illisibles.

Etape 2 — Copier le fichier de sauvegarde vers le serveur

Transferer le backup via scp, rsync ou tout autre outil de copie :

scp quotenode-backup-20260320.tar.gz user@new-server:~/quotenode/

Etape 3 — Recuperer le script de restauration

cp /path/to/your/quotenode-repository/scripts/restore.sh .
chmod +x restore.sh

Si votre depot QuoteNode se trouve sur un autre poste, copiez d’abord le meme fichier sur le serveur :

scp /path/to/your/quotenode-repository/scripts/restore.sh user@new-server:~/quotenode/

Etape 4 — Lancer la restauration

./restore.sh --fresh-install ~/quotenode/quotenode-backup-20260320.tar.gz

Le script :

1. demarre le conteneur de base,
2. attend qu’il soit pret,
3. restaure le dump de base,
4. lance toute la stack applicative,
5. reinjecte les fichiers televerses et les PDF generes,
6. execute un health check final.

Etape 5 — Verification

Ouvrez votre domaine dans un navigateur et reconnectez-vous avec vos identifiants existants. Vos clients, offres, produits et reglages doivent etre identiques a l’etat capture par la sauvegarde.

Dry run (optionnel)

Pour verifier une sauvegarde sans rien modifier :

RESTORE_DRY_RUN=true ./restore.sh --fresh-install backup-file.tar.gz

Cette commande extrait et valide l’archive, verifie les checksums et affiche le plan de restauration sans toucher a la base ni au stockage de fichiers.

Strategie de sauvegarde recommandee

Pour la production :

1. Activez les sauvegardes quotidiennes automatiques avec stockage distant (S3, SFTP ou equivalent).
2. Activez le chiffrement GPG pour les sauvegardes stockees sur de l’infrastructure tierce.
3. Testez periodiquement la procedure de restauration. Une sauvegarde jamais testee n’est pas une sauvegarde fiable.
4. Telechargez une sauvegarde sur une machine locale au moins une fois par mois. Le stockage distant ne remplace pas une copie offline.
5. Surveillez les logs de sauvegarde dans le panneau d’administration. L’admin affiche un avertissement si aucune sauvegarde reussie n’a ete enregistree dans les 48 dernieres heures.
6. Conservez au moins 7 jours d’historique (BACKUP_RETENTION_DAILY=7, valeur par defaut).