# 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` :

```text
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

- contrôler les comptes ;
- ouvrir plusieurs originaux ;
- vérifier albums, favoris et partages ;
- examiner `Administration > Maintenance` ;
- lancer les tâches manquantes ;
- vérifier les bibliothèques externes ;
- tester OAuth et mobile ;
- créer un nouveau dump.

## 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 :

```bash
cd /srv/immich/app
docker compose down
```

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

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

Créer les conteneurs sans lancer le serveur :

```bash
docker compose pull
docker compose create
docker start immich_postgres
```

Adapter le nom du conteneur PostgreSQL.

## Vérifier PostgreSQL

```bash
docker exec immich_postgres pg_isready -U postgres -d immich
```

## Restaurer le dump

```bash
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

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

## Si le serveur démarre trop tôt

Dans certains déploiements, utiliser temporairement :

```dotenv
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 :

- dump PostgreSQL ;
- copie des médias ;
- configuration ;
- secrets ;
- bibliothèques externes ;
- documentation des versions et montages.

## 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 :

```text
upload
library
profile
```

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

```text
thumbs
encoded-video
```

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

## Validation technique

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

TrueNAS :

```bash
sudo zpool status
sudo zfs list
nvidia-smi
```

## Validation fonctionnelle

- connexion locale ;
- utilisateurs ;
- photos de plusieurs dates ;
- vidéos ;
- albums et favoris ;
- visages et recherche ;
- bibliothèque externe ;
- Authentik ;
- application mobile ;
- upload ;
- sauvegarde automatique.

## Preuves et compte rendu

Documenter :

- origine de chaque sauvegarde ;
- sommes de contrôle ;
- version restaurée ;
- durée de chaque étape ;
- fichiers manquants ;
- décisions prises ;
- tests réalisés ;
- nouvelles mesures de prévention.

## 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

```bash
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

```bash
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

```bash
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

- 525 : certificat ou négociation TLS avec l'origine ;
- 403 : règle Cloudflare, Authentik, pare-feu ou application ;
- comparer accès direct local et domaine public ;
- examiner Caddy et Cloudflare.

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

## Upload interrompu

- taille maximale du proxy ;
- délai de 600 secondes ;
- espace libre ;
- réseau mobile ;
- limite Cloudflare ;
- journaux serveur.

## GPU absent

```bash
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

- Issuer URL ;
- Client ID et secret ;
- trois URI de redirection ;
- domaine public ;
- heure système ;
- certificat ;
- accès mobile `app.immich:///oauth-callback`.

## Diagnostic fourni

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

Examiner et masquer les informations sensibles avant partage.