↓ Aller au contenu
Le Rucher de Colmaris
  1. Documentation/

Restaurer Nextcloud depuis une sauvegarde Borg (Borg UI & CLI)

··1404 mots·7 mins
Sommaire

Méthode 1 : Restauration standard via Borg UI
#

Cette procédure s’applique à une stack Nextcloud sauvegardée via Borg UI, avec :

  • un script pre-backup qui dumpe la base PostgreSQL en SQL brut (non compressé, pour une déduplication optimale) ;
  • des sources Borg pointant directement vers les dossiers ncdata et redis (pas de tar/gzip, pour permettre un vrai incrémental au niveau des blocs).

À utiliser en cas de panne, de corruption de données, ou de migration vers un nouveau serveur — tant que Borg UI et son serveur hôte fonctionnent toujours. Pour un crash total (serveur détruit, Borg UI indisponible), consultez l’article dédié : Restaurer Nextcloud sans Borg UI.

Ne restaurez jamais directement par-dessus les données de production sans étape intermédiaire. Cette procédure passe systématiquement par un dossier de staging temporaire pour vous laisser une chance de vérifier le contenu avant d’écraser quoi que ce soit.

Étapes de restauration
#

1. Arrêter la stack Nextcloud
#

Avant tout, arrêtez complètement la stack pour qu’aucun processus n’écrive dans ncdata ou la base pendant la restauration.

cd /home/olivier/stacks/nextcloud
docker compose down

Ne redémarrez rien tant que la restauration n’est pas terminée.

2. Restaurer l’archive vers un dossier temporaire
#

Dans Borg UI : Archives → sélectionnez le repository Nextcloud → choisissez l’archive à la date voulue → sélectionnez tout son contenu (ncdata, redis, nextcloud-staging) → Restore vers un dossier temporaire, par exemple :

/local/restore-nextcloud

Ne restaurez jamais directement vers les chemins de production à cette étape.

3. Remettre en place les fichiers ncdata
#

Sauvegardez d’abord l’existant par précaution :

cd /home/olivier/stacks/nextcloud
mv ncdata ncdata.old

Puis copiez le contenu restauré vers l’emplacement de production :

cp -a /home/olivier/backups/.../restore-nextcloud/ncdata \
      /home/olivier/stacks/nextcloud/ncdata

Faites de même pour redis si besoin. Son contenu est du cache de session : généralement non critique à restaurer.

4. Redémarrer uniquement PostgreSQL
#

docker compose up -d postgres
docker compose ps   # attendre l'état "healthy"

5. Réimporter le dump SQL
#

Supprimez le contenu de la base actuelle et recréez-la (remplacez les valeurs par celles de votre fichier .env) :

docker exec -i nextcloud-postgres psql -U <NEXTCLOUD_DB_USER> \
  -d postgres -c "DROP DATABASE IF EXISTS <NEXTCLOUD_DB_NAME>;"

docker exec -i nextcloud-postgres psql -U <NEXTCLOUD_DB_USER> \
  -c "CREATE DATABASE <NEXTCLOUD_DB_NAME>;"

Puis réimportez le dump restauré :

cat /chemin/vers/restore-nextcloud/db/nextcloud-db-latest.sql | \
  docker exec -i nextcloud-postgres psql -U <NEXTCLOUD_DB_USER> \
  -d <NEXTCLOUD_DB_NAME>

6. Redémarrer la stack complète
#

docker compose up -d
docker compose ps   # vérifier que tout est healthy

7. Désactiver le mode maintenance et réparer
#

Nextcloud peut démarrer automatiquement en mode maintenance après une restauration.

docker exec -u www-data nextcloud php occ maintenance:mode --off
docker exec -u www-data nextcloud php occ maintenance:repair
docker exec -u www-data nextcloud php occ files:scan --all

8. Vérifier que tout fonctionne
#

Connectez-vous à l’interface web de Nextcloud et vérifiez que fichiers, contacts, calendriers et paramètres correspondent bien à la date de l’archive restaurée. Vérifiez aussi les logs :

docker logs nextcloud

Points critiques à retenir
#

  • Restaurez toujours vers un dossier de staging d’abord, jamais directement par-dessus les données de production.
  • Le dump SQL contient la structure exacte de la base : sur un nouveau serveur, vérifiez que NEXTCLOUD_DB_USER / NEXTCLOUD_DB_PASSWORD dans le .env correspondent à ce que PostgreSQL attend.
  • Redis n’est pas critique : c’est du cache de session/verrous. Le perdre force une reconnexion des utilisateurs, sans perte de données réelle.
  • Testez cette procédure au moins une fois « à froid » (instance de test ou VM) avant d’en avoir besoin en situation réelle. Une sauvegarde jamais restaurée n’est pas une sauvegarde fiable.

Méthode 2 : Restauration d’urgence en CLI (Crash total / Sans Borg UI)
#

Cette procédure s’applique quand Borg UI lui-même n’est plus disponible : serveur détruit, disque mort, incendie, vol — tout scénario où vous repartez d’une machine vierge. Elle utilise uniquement le CLI Borg, sans interface graphique.

Pour une restauration simple (Borg UI toujours fonctionnel), consultez Restaurer Nextcloud depuis une sauvegarde Borg UI — plus rapide et plus sûre grâce à l’interface.

Cette procédure suppose que votre repository Borg est accessible depuis la nouvelle machine (stockage externe survivant, NAS, ou copie off-site / cloud mirror). Si votre unique copie du repository était sur le disque qui a crashé, il n’y a rien à restaurer — d’où l’importance d’un mirroir hors-site.

Prérequis indispensables
#

Avant de commencer, vous avez besoin de trois choses qui ne sont pas dans le repository Borg lui-même :

  1. La passphrase du repository Borg — sans elle, les archives sont définitivement illisibles. Elle doit être stockée dans un gestionnaire de mots de passe séparé du serveur (Bitwarden, Vaultwarden hébergé ailleurs, coffre papier, etc.).
  2. Le docker-compose.yml et le .env de la stack Nextcloud — ils ne sont pas sauvegardés par le script pre-backup actuel. Idéalement, versionnez-les dans un dépôt Git privé séparé, ou ajoutez-les comme source Borg dédiée.
  3. L’emplacement du repository (chemin local, hôte SSH, ou remote cloud via rclone) — notez-le quelque part en dehors du serveur lui-même.
Si vous ne stockez pas encore ces trois éléments en dehors de votre serveur Nextcloud/Borg UI, faites-le avant d’en avoir besoin. Une sauvegarde de données sans sa configuration ni sa passphrase ne permet pas une restauration complète.

Étapes de restauration
#

1. Préparer la nouvelle machine
#

Installez Docker et Docker Compose sur le nouvel hôte, puis installez le CLI Borg :

sudo apt update
sudo apt install -y borgbackup
borg --version

2. Récupérer l’accès au repository
#

Selon où vit votre repository :

Stockage local ou disque externe reconnecté :

export BORG_REPO=/mnt/backup-externe/borg-repos/nextcloud

Repository distant en SSH :

export BORG_REPO=ssh://user@serveur-distant:22/chemin/vers/nextcloud

Renseignez la passphrase (récupérée depuis votre gestionnaire de mots de passe) :

export BORG_PASSPHRASE='votre-passphrase-ici'

3. Vérifier l’intégrité et lister les archives disponibles
#

borg check "$BORG_REPO"
borg list "$BORG_REPO"

Repérez le nom de l’archive à restaurer (format habituel : nom du plan + horodatage).

Si le message repository is locked apparaît (crash pendant un run précédent) :

borg break-lock "$BORG_REPO"

4. Extraire l’archive vers un dossier de staging
#

Créez un dossier de travail et extrayez-y l’archive :

mkdir -p /home/olivier/restore-nextcloud
cd /home/olivier/restore-nextcloud
borg extract "$BORG_REPO"::NOM-DE-L-ARCHIVE

Cette commande recrée l’arborescence complète (ncdata/, redis/, nextcloud-staging/db/nextcloud-db-latest.sql) dans le dossier courant.

Pour n’extraire qu’une partie (ex. seulement la base de données) :

borg extract "$BORG_REPO"::NOM-DE-L-ARCHIVE local/nextcloud-staging

5. Reconstituer la stack Nextcloud
#

Recréez le dossier de la stack et récupérez docker-compose.yml / .env depuis leur emplacement de sauvegarde séparé (dépôt Git privé, autre sauvegarde) :

mkdir -p /home/olivier/stacks/nextcloud
cd /home/olivier/stacks/nextcloud
# Récupérez ici votre docker-compose.yml et votre .env

Copiez les données restaurées à leur emplacement :

cp -a /home/olivier/restore-nextcloud/local/ncdata ./ncdata
cp -a /home/olivier/restore-nextcloud/local/redis ./redis

6. Démarrer uniquement PostgreSQL
#

docker compose up -d postgres
docker compose ps   # attendre l'état "healthy"

7. Réimporter le dump SQL
#

docker exec -i nextcloud-postgres psql -U <NEXTCLOUD_DB_USER> \
  -c "CREATE DATABASE <NEXTCLOUD_DB_NAME>;"

cat /home/olivier/restore-nextcloud/local/nextcloud-staging/db/nextcloud-db-latest.sql | \
  docker exec -i nextcloud-postgres psql -U <NEXTCLOUD_DB_USER> \
  -d <NEXTCLOUD_DB_NAME>

8. Démarrer la stack complète
#

docker compose up -d
docker compose ps

9. Réparer et vérifier l’intégrité de Nextcloud
#

docker exec -u www-data nextcloud php occ maintenance:mode --off
docker exec -u www-data nextcloud php occ maintenance:repair
docker exec -u www-data nextcloud php occ files:scan --all

10. Mettre à jour les domaines de confiance
#

Sur un nouveau serveur, l’IP ou le nom d’hôte peut avoir changé. Vérifiez et corrigez si besoin :

docker exec -u www-data nextcloud php occ config:system:get trusted_domains
docker exec -u www-data nextcloud php occ config:system:set trusted_domains 1 --value=votre-domaine.fr

11. Réinstaller Borg UI et reconfigurer les Backup Plans
#

Une fois Nextcloud vérifié et fonctionnel, redéployez Borg UI sur la nouvelle machine et reconfigurez les Backup Plans (voir l’article sur la mise en place initiale) pour que les futures sauvegardes reprennent normalement.

Points critiques à retenir
#

  • La passphrase Borg est le point de défaillance numéro un. Sans elle, toutes les données du repository sont irrécupérables — stockez-la impérativement en dehors du serveur qu’elle protège.
  • docker-compose.yml et .env ne sont pas dans la sauvegarde Borg actuelle. Prévoyez un dépôt Git privé (ou une sauvegarde séparée) pour ces fichiers de configuration, sans quoi vous devrez les réécrire de mémoire en pleine crise.
  • Vérifiez régulièrement que votre repository a bien une copie hors-site (cloud mirror, disque externe stocké ailleurs, serveur distant) — un repository local uniquement ne protège pas contre la perte du serveur lui-même.
  • Testez cette procédure de bout en bout au moins une fois, idéalement sur une VM isolée, avant d’en avoir besoin en urgence réelle.