10 - Restauration et dépannage

Restaurer Immich par l'interface ou la ligne de commande et résoudre les incidents courants.

10.1 - Restauration par l'interface et l'onboarding

Les versions récentes d'Immich permettent de restaurer un dump depuis l'interface. Cette méthode est recommandée pour la plupart des utilisateurs.

Instance existante

  1. ouvrir Administration > Maintenance ;
  2. ouvrir la section de restauration de base ;
  3. choisir un dump disponible ;
  4. vérifier sa version ;
  5. confirmer la restauration ;
  6. attendre le contrôle de santé ;
  7. examiner les journaux et l'intégrité.

Immich crée un point de restauration de la base actuelle avant l'opération et tente un retour automatique si la restauration échoue.

Nouvelle instance avec onboarding

Avant le premier démarrage, replacer les dossiers de l'ancienne instance dans le nouvel UPLOAD_LOCATION :

backups
encoded-video
library
profile
thumbs
upload

Configurer également les bibliothèques externes avec les mêmes chemins internes.

Démarrer Immich, puis :

  1. cliquer sur Restore from backup ;
  2. examiner les contrôles de lecture et d'écriture ;
  3. sélectionner un dump présent dans backups ;
  4. ou envoyer un fichier .sql.gz ;
  5. confirmer ;
  6. attendre les migrations et le contrôle de santé.

Compatibilité

Immich affiche un indicateur de compatibilité de version. Restaurer de préférence un dump produit par une version identique ou compatible.

Pour une source v2.7.5 et une cible v3, conserver une copie complète avant la migration. Si le diagnostic devient difficile, restaurer d'abord dans une instance v2.7.5 isolée, puis effectuer la montée de version.

Après restauration

Ne pas confondre

La restauration de la base ne restaure pas les photos. Les fichiers doivent déjà être présents et cohérents avec les chemins du dump.

Référence : https://docs.immich.app/administration/backup-and-restore/

10.2 - Restauration PostgreSQL en ligne de commande

La restauration en ligne de commande est réservée aux cas avancés. Utiliser un nouvel emplacement PostgreSQL vide au lieu de supprimer immédiatement l'ancien.

Préparer un nouvel emplacement

Arrêter l'instance :

cd /srv/immich/app
docker compose down

Dans .env, pointer temporairement vers un nouveau dossier vide et explicite :

DB_DATA_LOCATION=/srv/immich/postgres-restore-2026-08-07

Créer les conteneurs sans lancer le serveur :

docker compose pull
docker compose create
docker start immich_postgres

Adapter le nom du conteneur PostgreSQL.

Vérifier PostgreSQL

docker exec immich_postgres pg_isready -U postgres -d immich

Restaurer le dump

gunzip --stdout /srv/backups/immich/dump.sql.gz \
  | sed "s/SELECT pg_catalog.set_config('search_path', '', false);/SELECT pg_catalog.set_config('search_path', 'public, pg_catalog', true);/g" \
  | docker exec -i immich_postgres \
      psql --dbname=immich --username=postgres \
      --single-transaction --set ON_ERROR_STOP=on

Cette commande suit le principe documenté par Immich. Adapter les valeurs sans ajouter le mot de passe dans la ligne de commande.

Démarrer Immich

docker compose up -d
docker compose logs -f immich-server

Si le serveur démarre trop tôt

Dans certains déploiements, utiliser temporairement :

DB_SKIP_MIGRATIONS=true

Restaurer la base, retirer la variable puis recréer les conteneurs. Ne pas laisser cette variable active.

Revenir sans destruction

Si la restauration échoue :

  1. arrêter les conteneurs ;
  2. conserver le nouvel emplacement pour analyse ;
  3. remettre dans .env l'ancien DB_DATA_LOCATION ;
  4. redémarrer l'ancienne instance ;
  5. ne pas mélanger les deux bases.

TrueNAS

L'application TrueNAS rend difficile le démarrage isolé de PostgreSQL. Préférer l'interface de restauration. Pour une intervention manuelle, effectuer d'abord snapshots et dump, puis suivre les instructions correspondant exactement à la version du catalogue.

Référence : https://docs.immich.app/administration/backup-and-restore/

10.3 - Plan de reprise après sinistre

Scénario

Le serveur Immich ou son pool principal est perdu. Les éléments disponibles sont :

Ordre de reprise

  1. isoler l'incident et protéger les sauvegardes ;
  2. choisir un nouvel hôte ;
  3. installer une version compatible d'Immich ;
  4. recréer les datasets ou dossiers ;
  5. restaurer les médias ;
  6. restaurer les bibliothèques externes ;
  7. configurer les mêmes chemins internes ;
  8. restaurer PostgreSQL ;
  9. démarrer sans exposition publique ;
  10. vérifier l'intégrité ;
  11. tester les fonctions ;
  12. basculer le reverse proxy et le DNS ;
  13. créer une nouvelle sauvegarde.

Priorité des dossiers

Si seuls les originaux sont disponibles :

upload
library
profile

Les dossiers suivants peuvent être régénérés :

thumbs
encoded-video

La régénération peut prendre longtemps et solliciter fortement CPU, stockage et GPU.

Validation technique

docker compose ps
docker exec immich_server immich-admin schema-check
docker exec immich_postgres pg_isready -U postgres -d immich
df -hT

TrueNAS :

sudo zpool status
sudo zfs list
nvidia-smi

Validation fonctionnelle

Preuves et compte rendu

Documenter :

Exercice

Réaliser un exercice isolé au moins périodiquement. Un plan non testé ne garantit ni la lisibilité du dump, ni la présence des médias, ni la connaissance des secrets nécessaires.

10.4 - Erreurs fréquentes et diagnostic

Conteneur PostgreSQL ou pgvecto_upgrade en erreur

sudo docker ps -a --format '{{.Names}} {{.Image}} {{.Status}}' | grep -Ei 'immich|postgres|pgvecto|vector'
sudo docker logs --tail 300 NOM_CONTENEUR
sudo zfs list
df -hT

Chercher la première erreur, pas seulement exit 1. Vérifier version PostgreSQL, extension, permissions, espace et migration interrompue. Ne pas supprimer pgData.

Erreur Permission denied

sudo docker exec NOM_CONTENEUR_IMMICH id
sudo docker inspect NOM_CONTENEUR_IMMICH --format '{{range .Mounts}}{{println .Source "->" .Destination}}{{end}}'
sudo stat -c '%u:%g %a %n' CHEMIN_DATASET
sudo getfacl CHEMIN_DATASET

Corriger l'utilisateur ou l'ACL exacte, pas avec 777.

Fichier .immich absent

Vérifier que le bon dataset est monté au bon chemin et que l'application peut lire et écrire. Ne pas recréer manuellement les marqueurs pour masquer un montage incorrect.

Port 30041 inaccessible

sudo ss -ltnp | grep 30041
sudo docker ps --format '{{.Names}} {{.Ports}}' | grep -i immich
curl -I http://127.0.0.1:30041

Reverse proxy 525 ou 403

curl -vI https://immich.dreamsaphir.net
journalctl -u caddy -n 100 --no-pager

Upload interrompu

GPU absent

nvidia-smi
sudo docker exec NOM_CONTENEUR_IMMICH nvidia-smi
sudo docker exec NOM_CONTENEUR_ML nvidia-smi

Si le premier fonctionne et pas les suivants, vérifier l'allocation GPU des applications. Après une mise à jour TrueNAS, contrôler le pilote et redéployer l'application.

OAuth en boucle

Diagnostic fourni

IMMICH_COMPOSE_DIR=/srv/immich/app ./scripts/diagnostic_immich.sh

Examiner et masquer les informations sensibles avant partage.