Immich hat sich schnell zu einer beliebten Self-Hosted-Alternative für die Verwaltung digitaler Fotos und Videos entwickelt. Seine Leistungsfähigkeit und die ständige Weiterentwicklung machen es zu einer attraktiven Wahl für alle, die die Kontrolle über ihre Medien behalten möchten. Eine der nützlichsten Funktionen ist die Möglichkeit, externe Libraries einzubinden. Anstatt alle Ihre Medien in den internen Speicher von Immich zu kopieren, können Sie einfach auf bestehende Ordner zugreifen, die sich auf Ihrem Host-System, einem NAS oder einem anderen Speicher befinden. Das spart Speicherplatz, vermeidet Duplikate und ermöglicht eine flexible Organisation.
Doch wie so oft bei komplexen Systemen, die auf Docker oder ähnlichen Technologien basieren, können beim Einrichten dieser externen Libraries Schwierigkeiten auftreten. Nichts ist frustrierender, als wenn Immich hartnäckig „Zugriff verweigert” meldet oder die externen Medien einfach nicht auftauchen. Wenn Sie sich in dieser Situation wiederfinden, sind Sie hier genau richtig. Dieser umfassende Leitfaden führt Sie durch die häufigsten Fallstricke und bietet detaillierte Schritte zur Fehlerbehebung, damit Ihre externe Library endlich reibungslos mit Immich zusammenarbeitet.
Die Grundlagen verstehen: Wie Immich externe Libraries handhabt
Bevor wir uns in die Fehlersuche stürzen, ist es wichtig zu verstehen, wie Immich mit externen Libraries umgeht. Im Kern ist Immich ein Satz von Docker-Containern, die in einer isolierten Umgebung laufen. Damit diese Container auf Dateien auf Ihrem Host-System oder einem Netzwerkfreigabe zugreifen können, müssen diese Speicherorte über sogenannte Volume Mounts in den Container „eingehängt” werden. Immich scannt dann diese eingebundenen Pfade und fügt die gefundenen Medien zu seiner Datenbank hinzu, ohne sie physisch zu verschieben. Die externen Libraries werden dabei in der Regel als Nur-Lese-Speicherorte behandelt, um unbeabsichtigte Änderungen an Ihren Originaldateien zu vermeiden.
Diese Trennung zwischen dem Host-System und dem Container, gepaart mit der Notwendigkeit korrekter Dateiberechtigungen, ist der häufigste Ursprung von Problemen. Ein scheinbar einfacher Fehler im Pfad oder eine nicht passende Berechtigung kann dazu führen, dass Immich die Dateien nicht sehen kann, selbst wenn sie für Sie auf dem Host-System sichtbar sind.
Erste Schritte zur Fehlerbehebung: Die Basis-Checks
Manchmal sind die einfachsten Lösungen die effektivsten. Bevor Sie tief in Konfigurationsdateien eintauchen, überprüfen Sie diese grundlegenden Punkte:
- Immich Status prüfen: Stellen Sie sicher, dass alle Immich-Dienste ordnungsgemäß laufen. Nutzen Sie
docker compose psin Ihrem Immich-Installationsverzeichnis, um den Status aller Container zu überprüfen. Alle sollten den Status „running” oder „healthy” haben. - Neustart von Immich: Der Klassiker! Ein einfacher Neustart kann oft kleinere, temporäre Probleme beheben. Führen Sie
docker compose downgefolgt vondocker compose up -daus. - Immich-Version überprüfen: Sind Sie auf dem neuesten Stand? Veraltete Versionen können Bugs enthalten, die in neueren Versionen behoben wurden. Ein Update kann oft Wunder wirken.
- Eintrag in der Immich UI: Haben Sie die externe Library in der Immich Weboberfläche auch wirklich hinzugefügt? Gehen Sie zu „Einstellungen” -> „Bibliotheken” und fügen Sie den internen Pfad hinzu (z.B.
/mnt/external, nicht den Host-Pfad).
Der häufigste Übeltäter: Pfad- und Volume-Mount-Probleme
Dies ist der Bereich, in dem die meisten Fehler passieren. Ein kleiner Tippfehler oder ein Missverständnis der Docker-Volumekonfiguration kann Immich den Zugriff verweigern.
1. Korrekte Volume-Konfiguration in `docker-compose.yml`
Ihre docker-compose.yml-Datei ist das Herzstück Ihrer Immich-Bereitstellung. Hier definieren Sie, wie Host-Verzeichnisse in Ihre Docker-Container gemountet werden. Suchen Sie den Dienst, der für den Dateizugriff zuständig ist (oft immich-microservices oder immich-server, je nach Konfiguration) und überprüfen Sie den volumes-Abschnitt. Er sollte etwa so aussehen:
services:
immich-microservices:
# ... andere Konfigurationen ...
volumes:
- /path/to/your/immich/data:/mnt/data
- /pfad/zu/ihren/externen/fotos:/mnt/external
# ...
immich-server:
# ... andere Konfigurationen ...
volumes:
- /path/to/your/immich/data:/mnt/data
- /pfad/zu/ihren/externen/fotos:/mnt/external
# ...- Absolute Pfade: Verwenden Sie immer absolute Pfade auf der Host-Seite (z.B.
/home/user/Fotos, nicht./Fotos). - Konsistenz: Stellen Sie sicher, dass der Host-Pfad (links vom Doppelpunkt) genau der Ordner ist, den Sie einbinden möchten. Der Container-Pfad (rechts vom Doppelpunkt, z.B.
/mnt/external) ist der Pfad, den Sie später in der Immich UI angeben müssen. - Mehrere Dienste: Oft benötigen mehrere Immich-Dienste (z.B.
immich-serverundimmich-microservices) Zugriff auf die externen Libraries. Stellen Sie sicher, dass der Volume Mount in allen relevanten Diensten vorhanden ist. - Neustart nach Änderung: Jede Änderung an der
docker-compose.ymlerfordert einen Neustart von Immich:docker compose downgefolgt vondocker compose up -d.
2. Pfad in der Immich UI
Wenn Sie die externe Library in der Immich Weboberfläche hinzufügen, müssen Sie den *internen* Pfad angeben, den Sie in der docker-compose.yml definiert haben. Wenn Sie beispielsweise /pfad/zu/ihren/externen/fotos:/mnt/external gemountet haben, geben Sie in Immich /mnt/external ein. Achten Sie auf:
- Groß- und Kleinschreibung: Linux ist case-sensitive.
/mnt/externalist nicht dasselbe wie/mnt/External. - Slashes: Vermeiden Sie überflüssige Schrägstriche am Ende (z.B.
/mnt/external/ist nicht falsch, aber/mnt/externalist oft besser).
Berechtigungsprobleme: Der heimliche Saboteur
Auch wenn der Pfad korrekt ist, kann Immich keinen Zugriff erhalten, wenn die Berechtigungen nicht stimmen. Dies ist der zweithäufigste Grund für „Zugriff verweigert”-Meldungen.
1. Host-System-Berechtigungen
Ihr Host-System (der Server, auf dem Docker läuft) muss dem Benutzer, unter dem die Docker-Container laufen, Lesezugriff auf die externen Bibliotheksordner gewähren. Immich benötigt in der Regel Nur-Lese-Zugriff für externe Libraries, aber oft werden Probleme durch unzureichende Lese- oder Ausführungsrechte verursacht.
Der Schlüsselbegriff: PUID und PGID
Docker-Container laufen oft als ein bestimmter Benutzer innerhalb des Containers. Um Berechtigungsprobleme zu vermeiden, ist es Best Practice, die User ID (UID) und Group ID (GID) des Benutzers auf Ihrem Host-System, der die Rechte an den Mediendateien besitzt, an den Docker-Container zu übergeben. Dies geschieht in der docker-compose.yml mit den Umgebungsvariablen PUID und PGID.
So finden Sie Ihre PUID und PGID:
Melden Sie sich auf Ihrem Host-System an und führen Sie folgende Befehle aus:
id -u(gibt Ihre User ID aus, z.B. 1000)id -g(gibt Ihre Group ID aus, z.B. 1000)
Diese Werte tragen Sie dann in Ihre docker-compose.yml im environment-Abschnitt ein:
services:
immich-microservices:
environment:
- PUID=1000 # Ersetzen Sie dies durch Ihre User ID
- PGID=1000 # Ersetzen Sie dies durch Ihre Group ID
# ...
immich-server:
environment:
- PUID=1000
- PGID=1000
# ...Auch hier gilt: Nach Änderungen in der docker-compose.yml müssen Sie Immich neu starten.
Dateisystem-Berechtigungen anpassen:
Stellen Sie sicher, dass der Ordner Ihrer externen Library und alle darin enthaltenen Dateien und Unterordner die richtigen Berechtigungen haben. Sie können dies mit chmod und chown anpassen. Zum Beispiel:
sudo chown -R 1000:1000 /pfad/zu/ihren/externen/fotos(ersetzen Sie 1000 durch Ihre PUID/PGID)sudo chmod -R 755 /pfad/zu/ihren/externen/fotos(gewährt Lese- und Ausführungsrechte für alle, Schreibrechte nur für den Besitzer). Für reine Leserechte wäre755(rwxr-xr-x) für Ordner und644(rw-r–r–) für Dateien meist ausreichend.
Überprüfen Sie nach den Änderungen die Berechtigungen mit ls -la /pfad/zu/ihren/externen/fotos.
2. NFS/SMB-Freigaben (NAS-Integration)
Wenn Ihre externe Library auf einem NAS oder einer Netzwerkfreigabe (NFS, SMB/CIFS) liegt, müssen Sie nicht nur die Berechtigungen auf dem Host-System prüfen, sondern auch die Freigabe-Berechtigungen auf dem NAS selbst.
- NFS: Achten Sie auf Optionen wie
no_root_squash(wenn der Docker-Container als root auf das Share zugreifen soll, was selten nötig ist) oderall_squashmitanonuid/anongid, die den Zugriff auf eine bestimmte Benutzer-ID auf dem NAS abbilden. Die einfachste Methode ist oft, dem Host-System des Docker-Servers Lesezugriff auf das Share zu gewähren und dann diePUID/PGID-Einstellungen im Docker Compose zu verwenden. - SMB/CIFS: Stellen Sie sicher, dass der Benutzer, den Sie für die Freigabe verwenden, die erforderlichen Lesezugriffsrechte hat. Wenn Sie Gastzugriff verwenden, prüfen Sie, ob dieser die notwendigen Rechte besitzt.
- Mount-Optionen auf dem Host: Wenn Sie die NAS-Freigabe auf Ihrem Host-System mounten (z.B. über
/etc/fstab), achten Sie auf die Mount-Optionen, insbesondereuidundgid, die den Besitz der gemounteten Dateien festlegen können, und_netdev, um sicherzustellen, dass das Mounten nach der Netzwerkkonnektivität erfolgt.
Dateisystem- und Netzwerkprobleme (für NAS/NFS/SMB)
Manchmal liegt das Problem nicht bei Docker oder Immich, sondern tiefer:
- Verfügbarkeit der Freigabe: Ist Ihr NAS eingeschaltet und die Freigabe erreichbar? Können Sie auf dem Host-System auf die Dateien zugreifen? Testen Sie dies, indem Sie z.B.
ls /pfad/zu/ihren/externen/fotosauf dem Host ausführen. - Netzwerkkonnektivität: Überprüfen Sie die Netzwerkverbindung zwischen Ihrem Immich-Host und dem NAS. Pingen Sie die IP-Adresse des NAS.
- Firewall: Blockiert eine Firewall (auf dem Immich-Host, auf dem NAS oder dazwischen) den Zugriff auf die benötigten Ports (NFS: 111, 2049; SMB: 139, 445)?
Debugging mit Protokollen: Ihr bester Freund bei der Fehlersuche
Die Protokolle (Logs) der Docker-Container sind eine unschätzbare Quelle für Informationen, wenn etwas schiefläuft. Sie geben Ihnen oft genaue Hinweise darauf, wo das Problem liegt.
1. Docker-Container-Protokolle einsehen
Verwenden Sie folgenden Befehl in Ihrem Immich-Installationsverzeichnis, um die Logs der relevanten Dienste anzuzeigen:
docker compose logs -f immich-server immich-microservicesAchten Sie auf Fehlermeldungen wie:
permission denied(Zugriff verweigert): Deutet stark auf Berechtigungsprobleme (PUID/PGID, Dateisystemberechtigungen) hin.no such file or directory: Wahrscheinlich ein Fehler im Pfad indocker-compose.ymloder in der Immich UI.error reading directory: Kann auf Berechtigungsprobleme, einen nicht existierenden Pfad oder ein Dateisystemproblem hindeuten.- Meldungen im Zusammenhang mit „scanner”, „library”, „watchdog”: Diese Dienste sind oft für das Einlesen externer Bibliotheken zuständig.
2. Innerhalb des Containers prüfen (fortgeschritten)
Sie können direkt in einen laufenden Docker-Container „eintreten”, um zu sehen, was Immich „sieht”.
docker exec -it immich-microservices ls -la /mnt/externalDieser Befehl versucht, den Inhalt Ihres gemounteten Verzeichnisses im immich-microservices-Container aufzulisten. Wenn Sie hier eine „permission denied”-Meldung oder eine leere Ausgabe sehen, obwohl der Host-Pfad voll ist, haben Sie das Problem eingegrenzt.
Sie können auch überprüfen, welcher Benutzer im Container läuft:
docker exec -it immich-microservices whoamiDies hilft Ihnen zu bestätigen, dass die PUID/PGID-Einstellungen korrekt angewendet wurden.
Häufige Fehler und ihre Lösungen zusammengefasst
- „Container sieht das Verzeichnis nicht”:
- Mögliche Ursachen: Falscher Host-Pfad in
docker-compose.yml, Container-Pfad indocker-compose.ymlfalsch, Immich UI Pfad falsch. - Lösung:
docker-compose.ymlüberprüfen, Immich UI Pfad überprüfen, Immich neu starten.
- Mögliche Ursachen: Falscher Host-Pfad in
- „Container sieht das Verzeichnis, aber keine Dateien”:
- Mögliche Ursachen: Berechtigungsprobleme (PUID/PGID), fehlende Lese- oder Ausführungsrechte auf Host-Seite.
- Lösung:
PUID/PGIDindocker-compose.ymlanpassen,chown/chmodauf Host-Verzeichnis ausführen.
- „Immich UI meldet ‘Fehler beim Scannen der Bibliothek'”:
- Mögliche Ursachen: Kombinierte Pfad- oder Berechtigungsprobleme, temporäre Netzwerkprobleme, Immich-Dienst nicht korrekt gestartet.
- Lösung: Logs prüfen, alle oben genannten Schritte durchgehen.
Best Practices, um zukünftige Probleme zu vermeiden
- Dedizierter Benutzer: Erstellen Sie auf Ihrem Host-System einen dedizierten Benutzer und eine Gruppe für Ihre Docker-Anwendungen (z.B. `dockeruser`). Geben Sie diesem Benutzer die korrekten Berechtigungen für Ihre Mediendateien und verwenden Sie dessen PUID/PGID in allen Ihren Docker-Compose-Dateien.
- Standardisierte Pfade: Verwenden Sie konsistente interne Mount-Pfade (z.B.
/mnt/external,/mnt/photos) für alle Ihre Docker-Anwendungen. - Testen vor Produktion: Testen Sie neue externe Libraries immer mit ein paar Beispielbildern, bevor Sie ganze Sammlungen hinzufügen.
- Aktualisierungen: Halten Sie Immich und Docker (sowie Ihr Betriebssystem) regelmäßig auf dem neuesten Stand, um von Bugfixes und Verbesserungen zu profitieren.
- Dokumentation: Dokumentieren Sie Ihre
docker-compose.yml-Dateien und alle manuellen Berechtigungseinstellungen, die Sie vorgenommen haben.
Fazit
Die Integration externer Libraries in Immich ist eine mächtige Funktion, die Ihnen immense Flexibilität bietet. Auch wenn der Weg dorthin manchmal steinig sein kann, ist die Behebung von „Zugriff verweigert”-Problemen in den meisten Fällen eine Frage der systematischen Überprüfung von Pfaden, Berechtigungen und Docker-Konfigurationen. Nehmen Sie sich die Zeit, die Schritte sorgfältig zu befolgen, nutzen Sie die Docker-Logs als Ihren Kompass, und Sie werden Ihre Medien in Immich im Handumdrehen genießen können. Die Immich-Community ist zudem sehr hilfsbereit – zögern Sie nicht, bei hartnäckigen Problemen dort nach Unterstützung zu suchen, nachdem Sie diese Schritte durchgegangen sind!