Portainer zeigt Container als unhealthy: Healthchecks und Logs richtig lesen

Ein in Portainer als unhealthy markierter Container läuft meist noch, aber sein hinterlegter Docker-Healthcheck schlägt wiederholt fehl. Akute Gefahr für den NAS-Speicherpool oder das Volume besteht dadurch normalerweise nicht; betroffen ist zunächst die Überwachung des Container-Dienstes. Sichere zuerst den angezeigten Health-Status, die letzten Prüfergebnisse und die Container-Logs. Lösche, erstelle oder aktualisiere den Container noch nicht, denn dadurch können Diagnoseinformationen verloren gehen und falsche Volume-Zuordnungen ein zusätzliches Datenrisiko erzeugen.

Die zentrale Frage lautet nicht nur, ob die Anwendung im Browser erreichbar ist. Du musst feststellen, welchen Befehl der Healthcheck ausführt, welchen Rückgabecode er liefert und ob dessen Ausgabe zur gleichen Zeit in den Anwendungslogs auftaucht. Erst diese Verbindung trennt einen echten Dienstausfall von einem fehlerhaften oder unpassenden Healthcheck.

Was Portainers Status unhealthy tatsächlich bedeutet

Docker kann einen Container gleichzeitig als laufend und als fehlerhaft überwacht einstufen. Der Hauptprozess ist dann noch aktiv, während mehrere aufeinanderfolgende Healthcheck-Prüfungen nicht erfolgreich waren. Portainer zeigt diesen von der Docker-Engine gelieferten Zustand an; Portainer führt den Prüfbefehl nicht selbst aus.

Ein Healthcheck besteht im Wesentlichen aus einem Testbefehl und mehreren Zeitvorgaben:

• interval bestimmt den Abstand zwischen den Prüfungen.
• timeout begrenzt die Laufzeit eines einzelnen Versuchs.
• retries legt fest, wie viele aufeinanderfolgende Fehlschläge den Zustand unhealthy auslösen.
• start_period kann einem startenden Dienst zusätzliche Anlaufzeit geben, bevor Fehlschläge regulär gewertet werden.

Der Status beweist daher noch nicht, dass der eigentliche Dienst ausgefallen ist. Ein Webserver kann Anfragen beantworten, obwohl der Healthcheck eine nicht mehr vorhandene URL abfragt. Umgekehrt kann eine Anmeldeseite erscheinen, während eine benötigte Datenbankverbindung fehlt und der Healthcheck diesen tieferen Fehler erkennt.

Ein fehlgeschlagener Healthcheck startet den Container bei einer normalen Docker-Installation nicht automatisch neu. Auch eine übliche Restart-Policy reagiert in erster Linie auf das Beenden des Hauptprozesses, nicht allein auf den Zustand unhealthy. Ein dauerhaft fehlerhafter Status darf deshalb nicht mit einer laufenden Neustartschleife gleichgesetzt werden.

Die Diagnose in Portainer: erst Health-Ausgabe, dann Container-Log

Öffne in Portainer den betroffenen Container und notiere zunächst Name, Image einschließlich Tag, Startzeit sowie den aktuellen Status. Die Bezeichnungen und Positionen einzelner Ansichten können sich zwischen Portainer-Versionen unterscheiden. Maßgeblich sind die Container-Detailansicht beziehungsweise Inspect für den Health-Zustand und Logs für die Standardausgabe des Dienstes.

1. Öffne die Detailansicht des als unhealthy markierten Containers.
2. Suche in den Inspektionsdaten nach State, darin nach Health und anschließend nach Log.
3. Notiere bei den letzten Versuchen jeweils Start, End, ExitCode und Output.
4. Prüfe in der Health-Konfiguration den vollständigen Testbefehl sowie Intervall, Zeitüberschreitung, Wiederholungen und Anlaufzeit.
5. Öffne die normalen Container-Logs und grenze die Anzeige zeitlich auf den Bereich um den letzten fehlgeschlagenen Test ein.
6. Teste den Dienst von einem geeigneten Client aus, ohne dafür Ports oder Firewallregeln zu verändern.

Der Zeitabgleich ist besonders wichtig. Meldet der Healthcheck um 14:32 Uhr einen Verbindungsfehler und protokolliert die Anwendung zur gleichen Sekunde einen fehlgeschlagenen Datenbankzugriff, hängen beide Beobachtungen wahrscheinlich zusammen. Bleiben die Anwendungslogs dagegen unauffällig und ist der Dienst erreichbar, rückt ein ungeeigneter Prüfbefehl in den Vordergrund.

ExitCode und Output richtig auswerten

Der Rückgabecode zeigt, ob Docker den Prüflauf als erfolgreich bewerten konnte. ExitCode 0 steht für Erfolg. Ein anderer Wert bedeutet einen Fehlschlag; seine genaue Bedeutung hängt vom ausgeführten Programm ab. Der Text in Output liefert häufig den entscheidenden Hinweis.

• connection refused: Am geprüften Ziel nimmt zu diesem Zeitpunkt kein Dienst die Verbindung an. Möglich sind ein noch nicht gestarteter Prozess, ein falscher interner Port oder eine falsche Zieladresse.
• timed out oder eine Zeitüberschreitung: Der Prüfbefehl antwortet nicht innerhalb des gesetzten Limits. Das kann auf hohe NAS-Last, blockierende Abhängigkeiten oder ein zu knappes Timeout hinweisen.
• not found beziehungsweise Rückgabecode 127: Das im Test verwendete Programm oder Skript ist im Container wahrscheinlich nicht vorhanden oder nicht über den erwarteten Pfad aufrufbar.
• HTTP-Status 401 oder 403: Der geprüfte Endpunkt verlangt eine Anmeldung oder verweigert den Zugriff. Der Dienst kann trotzdem laufen, der gewählte Endpunkt ist dann aber möglicherweise nicht als anonymer Gesundheitstest geeignet.
• HTTP-Status 404: Pfad, Basis-URL oder Anwendungskontext stimmen nicht mit der laufenden Version überein.
• Namensauflösungsfehler: Der im Healthcheck verwendete Hostname ist aus dem Container nicht auflösbar. Prüfe Container-Netzwerk, DNS-Konfiguration und den tatsächlichen Dienstnamen.
• Zertifikatsfehler: Der Test greift per HTTPS zu, vertraut aber der Zertifikatskette oder dem verwendeten Namen nicht. Das Abschalten der Zertifikatsprüfung verdeckt nur das Problem und ist nicht der erste Schritt.

Ein Rückgabecode allein reicht nicht für die Ursache. So kann ExitCode 1 von einem HTTP-Werkzeug, einem Shell-Skript oder einem anwendungseigenen Diagnoseprogramm stammen. Lies immer den zugehörigen Befehl und dessen Ausgabe zusammen.

Healthcheck-Log und Anwendungslog beantworten verschiedene Fragen

Das Healthcheck-Log dokumentiert einzelne Prüfversuche. Es beantwortet: Wann wurde getestet, war der Test erfolgreich und welche kurze Ausgabe entstand? Das normale Container-Log enthält dagegen das, was der Hauptprozess an Standardausgabe und Standardfehler sendet. Dort findest du eher Startmeldungen, Datenbankfehler, Zugriffsprobleme oder interne Ausnahmen.

Ein leerer Container-Log beweist nicht, dass keine Störung vorliegt. Manche Anwendungen schreiben in Dateien innerhalb des Containers oder in ein eingebundenes Verzeichnis. Portainer kann nur die Ausgaben zeigen, die Docker für diesen Container erfasst. Prüfe bei einem leeren Log die Dokumentation des verwendeten Images und die Container-Konfiguration darauf, wo die Anwendung ihre Protokolle ablegt. Verändere die Protokollierung nicht während der ersten Bestandsaufnahme.

Auch die Log-Zeitzone kann vom NAS oder vom Browser abweichen. Vergleiche bei scheinbar nicht zusammenpassenden Zeitstempeln die Systemzeit des NAS, die Container-Zeitzone und Zeitangaben mit einem angehängten Z, das für UTC steht. Eine Zeitverschiebung kann zusammengehörige Meldungen sonst wie getrennte Ereignisse aussehen lassen.

Vier Diagnosezweige führen zur passenden Maßnahme

Der Dienst ist erreichbar, nur der Healthcheck scheitert

Prüfe zuerst, ob der Healthcheck die richtige interne Adresse verwendet. Innerhalb eines Containers bezeichnet localhost genau diesen Container, nicht das NAS und nicht einen anderen Container. Der veröffentlichte Host-Port ist für einen internen Selbsttest häufig ebenfalls nicht der passende Bezugspunkt; maßgeblich ist meist der Port, auf dem die Anwendung im Container lauscht.

Kontrolliere außerdem, ob das getestete Werkzeug im aktuellen Image vorhanden ist. Schlanke Images enthalten nicht zwangsläufig curl, wget, eine Shell oder andere Hilfsprogramme. Wurde das Image aktualisiert, kann ein zuvor funktionierender Test dadurch unbrauchbar werden, obwohl die Anwendung selbst weiterhin startet. Die sichere Lösung ist ein zum Image passender Test und nicht die spontane Installation zusätzlicher Werkzeuge in einen laufenden Container, weil diese Änderung beim nächsten Neuaufbau verloren geht.

Der Healthcheck und der Benutzerzugriff schlagen beide fehl

In diesem Fall spricht mehr für eine Störung des Dienstes oder einer notwendigen Abhängigkeit. Suche im Container-Log zum Zeitpunkt des Health-Fehlers nach Hinweisen auf Datenbankverbindungen, nicht erreichbare Backend-Dienste, fehlende Konfigurationsdateien oder verweigerte Dateizugriffe. Prüfe danach in Portainers Container-Details die zugeordneten Netzwerke, Umgebungsvariablen und Mounts, ohne geheime Werte unnötig zu kopieren oder zu veröffentlichen.

Zeigt das Log einen Berechtigungsfehler an einem eingebundenen NAS-Ordner, müssen Pfad, Besitzer und die vom Container verwendete Benutzer- beziehungsweise Gruppen-ID zusammenpassen. Ändere Rechte nicht pauschal auf vollständigen Zugriff. Eine weitreichende Freigabe kann das Symptom verdecken und den Schutz anderer NAS-Daten schwächen.

Der Status kippt nur während des Starts auf unhealthy

Ein Dienst kann länger zum Initialisieren benötigen als der Healthcheck erlaubt. Das tritt unter anderem bei Datenbankmigrationen, Medienindizierung oder hoher Laufwerkslast auf. Vergleiche die Startzeit des Containers, die ersten erfolgreichen Anwendungsaktionen und die Zeitpunkte der Healthchecks. Wird der Dienst nach einer nachvollziehbaren Anlaufphase stabil gesund, kann eine passende start_period sinnvoller sein als ein großzügigeres Timeout für jeden späteren Test.

Bleibt der Status nach jedem Neustart über längere Zeit fehlerhaft, ist eine Verlängerung der Zeitwerte keine eigentliche Fehlerbehebung. Sie würde lediglich die Anzeige verzögern.

Der Status wechselt regelmäßig zwischen healthy und unhealthy

Ein wechselnder Zustand verlangt einen Vergleich der fehlgeschlagenen Zeitpunkte mit NAS-Auslastung und Abhängigkeiten. Prüfe, ob die Ereignisse mit Backup-Jobs, Scrubbing, Medienanalyse, hoher Arbeitsspeichernutzung oder dem Neustart eines anderen Containers zusammenfallen. Eine zeitliche Übereinstimmung ist ein Hinweis, aber noch kein Beweis.

Bei sehr knapp gesetzten Timeouts kann bereits eine kurze Lastspitze den Test scheitern lassen. Wiederkehrende Verbindungsabbrüche zu einer Datenbank oder einem Backend sprechen dagegen eher für ein Netzwerk-, Ressourcen- oder Dienstproblem. Vergrößere den Timeout erst, wenn ein manuell beobachteter Test zuverlässig funktioniert und nur seine Laufzeit gelegentlich knapp über dem bisherigen Grenzwert liegt.

Health-Daten bei Bedarf über die Docker-Konsole prüfen

Falls Portainer die Health-Ausgabe in deiner Version nicht übersichtlich darstellt, kannst du den von Docker gespeicherten Zustand über eine administrativ freigegebene Shell des NAS auslesen. Dafür muss dein Konto berechtigt sein, Docker-Befehle auszuführen. Ersetze CONTAINER_NAME durch den tatsächlichen Namen; die Befehle verändern den Container nicht.

docker inspect --format '{{json .State.Health}}' CONTAINER_NAME
docker inspect --format '{{json .Config.Healthcheck}}' CONTAINER_NAME
docker logs --since 15m --timestamps CONTAINER_NAME

Die erste Zeile zeigt Status, Fehlversuche und die gespeicherten Health-Ausgaben. Die zweite liest die wirksame Healthcheck-Konfiguration aus. Die dritte gibt die letzten 15 Minuten der normalen Container-Logs mit Zeitstempeln aus. Enthält das Ergebnis Zugangsdaten, Tokens oder interne Adressen, solltest du diese Angaben vor einer Weitergabe entfernen.

Führe den Healthcheck-Befehl nicht blind per docker exec aus. Lies ihn zuerst vollständig und prüfe, ob er ausschließlich diagnostisch arbeitet. Ein fremdes Image könnte einen ungewöhnlichen oder veralteten Test enthalten. Sichere Shell- und Diagnosebefehle lassen sich gezielt nachvollziehen; schreibende Skripte gehören nicht in einen ungeprüften Testlauf.

Wo die wirksame Healthcheck-Definition herkommt

Ein Healthcheck kann bereits im Container-Image definiert sein oder bei der Bereitstellung durch eine Compose-Datei beziehungsweise die Portainer-Konfiguration überschrieben werden. Entscheidend ist nicht nur die aktuell sichtbare Stack-Datei, sondern die wirksame Konfiguration des laufenden Containers. Genau diese zeigt Docker unter Config.Healthcheck.

Bei einem als Stack verwalteten Dienst solltest du Änderungen in der maßgeblichen Stack- oder Compose-Definition vornehmen. Eine ausschließlich am laufenden Container vorgenommene Anpassung kann beim nächsten Deployment verschwinden. Prüfe vor jeder erneuten Bereitstellung:

• Welche persistenten NAS-Verzeichnisse oder benannten Volumes eingebunden sind.
• Ob die vorhandenen Umgebungsvariablen und Geheimnisse vollständig gesichert sind.
• Welches Image und welcher Tag bisher verwendet werden.
• Ob der Stack weitere abhängige Dienste enthält.
• Ob eine aktuelle Sicherung der Anwendungsdaten wiederherstellbar ist.

Ein Recreate kann notwendig werden, damit eine geänderte Healthcheck-Definition wirksam wird. Er ist aber kein sinnvoller erster Diagnoseversuch. Bei Datenbank- oder Anwendungscontainern muss vorher klar sein, dass die Nutzdaten außerhalb der flüchtigen Container-Schicht gespeichert und gesichert sind.

Erfolgskontrolle ohne vorschnellen Neustart

Eine Änderung ist erst dann überzeugend, wenn mehrere aufeinanderfolgende Healthchecks erfolgreich sind und der eigentliche Dienst seine Funktion erfüllt. Warte mindestens die in der Konfiguration vorgesehene Folge von Prüfintervallen ab. Kontrolliere zusätzlich eine echte, aber risikoarme Anwendungsfunktion, etwa das Laden einer Statusseite oder eine Anmeldung ohne Datenänderung.

Bleibt die Anwendung nutzbar, der Status jedoch fehlerhaft, vergleiche erneut den wirksamen Test mit dem tatsächlichen Endpunkt im Container. Wird der Container gesund, während im Anwendungslog weiterhin schwere Fehler stehen, ist umgekehrt der Healthcheck möglicherweise zu oberflächlich. Ein guter Test prüft die für den Dienst notwendige Funktion, ohne bei jeder Ausführung Daten zu verändern oder unnötig hohe Last zu erzeugen.

Breche Änderungen ab, wenn Mounts unklar sind, mehrere Container gleichzeitig Datenbank- oder Dateisystemfehler melden oder das NAS selbst Speicherpool- beziehungsweise Volume-Warnungen zeigt. Dann liegt die Priorität bei der Sicherung des Systemzustands und der Anwendungsdaten. Der Zustand unhealthy ist eine Diagnoseinformation, kein Auftrag zum schnellen Neuaufbau.