So debuggen Sie Docker-Container auf Debian 13

Einführung

In diesem Tutorial lernen Sie, wie Sie Docker-Container mit praktischen, anfängerfreundlichen Techniken debuggen. Sie identifizieren Probleme, indem Sie den Containerstatus überprüfen, Logs analysieren, die Konfiguration inspizieren und auf die Containerumgebung zugreifen. Dieser Ansatz hilft Ihnen, schnell zu verstehen, warum ein Container fehlschlägt und wie Sie ihn beheben können.

Endziel: Am Ende dieses Tutorials werden Sie in der Lage sein, häufige Docker-Container-Probleme mithilfe von Logs, Inspektion und Laufzeitanalysetools zu identifizieren und zu beheben.

Voraussetzungen

• Zielgruppe: Anfänger-Systemadministratoren
• Geschätzte Zeit: ~30 Minuten
• Betriebssystem: Debian 13
• Software: Docker 24.0 oder neuer
• Berechtigungen: Benutzer mit sudo-Rechten oder Mitgliedschaft in der Docker-Gruppe
• Hardwareanforderungen: Mindestens 2 GB RAM und 10 GB freier Speicherplatz
• Netzwerkanforderungen: Internetzugang zum Herunterladen von Images, keine spezifischen Ports für dieses Tutorial erforderlich
• Anforderungen: Grundlegende Befehlszeilenverwendung und ein laufender Docker-Dienst
• Kompatibilität: Getestet auf Debian 13 und funktioniert auf Debian 12 und Ubuntu 22.04

Schritt 1: Docker-Systeminformationen überprüfen

Bevor Sie einen bestimmten Container debuggen, vergewissern Sie sich, dass Docker selbst korrekt funktioniert.
Führen Sie den folgenden Befehl aus:

docker system info

Sie sehen detaillierte Informationen über die Docker-Umgebung, einschließlich:

• Serverversion
• Speichertreiber
• Anzahl der Container und Images
• Verfügbarkeit von CPU und Speicher
• Docker-Root-Verzeichnis

Dies hilft Ihnen zu bestätigen, dass:

• Docker korrekt läuft
• Das System über genügend Ressourcen verfügt
• Keine globalen Konfigurationsprobleme vorliegen

Um den Docker-Dienststatus zu überprüfen:

systemctl status docker

Sie sehen, ob der Docker-Dienst aktiv ist. Wenn er nicht läuft, starten Sie ihn:

sudo systemctl start docker

Sie sollten nun den Dienst im aktiven Zustand sehen.

Schritt 2: Containerstatus überprüfen

Führen Sie den folgenden Befehl aus:

docker ps

Sie sehen eine Liste der laufenden Container mit Details wie Container-ID, Image und Status. Wenn Ihr Container mit dem Status "Up" angezeigt wird, läuft er derzeit.

Um gestoppte Container einzuschließen:

docker ps -a

Sie sehen nun alle Container. Wenn Ihr Container "Exited" anzeigt, bedeutet dies, dass er aufgrund eines Fehlers gestoppt wurde oder die Ausführung abgeschlossen ist.

Schritt 3: Container-Logs anzeigen

Logs zeigen, was die Anwendung im Container ausgibt. Dies ist der wichtigste Schritt zum Debuggen. Sie können <CONTAINER_ID> über den in Schritt 2 beschriebenen Befehl docker ps erhalten.

Führen Sie aus:

docker logs <CONTAINER_ID>

Sie sehen die Anwendungs-Ausgabe, einschließlich Fehlern und Warnungen. Suchen Sie nach Nachrichten, die auf Fehler wie fehlende Dateien oder Verbindungsfehler hinweisen.

Um Logs in Echtzeit zu verfolgen:

docker logs -f <CONTAINER_ID>

Sie sehen neue Log-Einträge, sobald sie erscheinen. Dies ist nützlich, wenn Sie einen Container neu starten und das Verhalten beobachten.

Um nur aktuelle Logs anzuzeigen:

docker logs --tail 50 <CONTAINER_ID>

Sie sehen die letzten 50 Zeilen der Ausgabe. Dies hilft Ihnen, sich auf die neuesten Ereignisse zu konzentrieren.

Schritt 4: Containerstatus inspizieren

Docker speichert detaillierte Informationen über jeden Container.

Führen Sie aus:

docker inspect <CONTAINER_ID>

Sie sehen eine strukturierte JSON-Ausgabe mit Konfigurations- und Laufzeitdetails.

Um den Containerstatus zu überprüfen:

docker inspect -f '{{.State.Status}}' <CONTAINER_ID>

Sie sehen einen einfachen Wert wie "running" oder "exited", der den Containerstatus bestätigt.

Um den Exit-Code zu überprüfen:

docker inspect -f '{{.State.ExitCode}}' <CONTAINER_ID>

Sie sehen eine Zahl. Ein Wert von 0 bedeutet Erfolg, während jeder andere Wert auf einen Fehler hinweist.

Um die Neustartpolitik zu überprüfen:

docker inspect -f '{{.HostConfig.RestartPolicy.Name}}' <CONTAINER_ID>

Sie sehen, ob der Container so konfiguriert ist, dass er automatisch neu startet.

Häufige Exit-Codes, die Sie sehen können:

• 0 – Der Prozess wurde erfolgreich ohne Fehler abgeschlossen. Dies bedeutet normalerweise, dass der Container normal gestoppt wurde. Zum Beispiel hat ein Skript seine Aufgabe abgeschlossen und beendet.
• 1 – Ein allgemeiner Fehler ist aufgetreten. Dies ist der häufigste Fehlercode und bedeutet normalerweise, dass etwas innerhalb der Anwendung fehlgeschlagen ist, wie z.B. eine fehlende Datei, ungültige Konfiguration oder Laufzeitfehler.
• 125 – Docker konnte den Container nicht ausführen. Dies weist normalerweise auf ein Problem mit dem docker run-Befehl selbst hin, wie z.B. ungültige Optionen oder falsche Parameter.
• 126 – Der Befehl im Container kann nicht ausgeführt werden. Dies bedeutet oft Berechtigungsprobleme oder dass die Datei nicht ausführbar ist.
• 127 – Der Befehl wurde nicht gefunden. Dies bedeutet typischerweise, dass das angegebene Binärprogramm oder Skript im Container nicht existiert.
• 137 – Der Container wurde gewaltsam gestoppt. Dies passiert oft, wenn dem System der Speicher ausgeht und der Containerprozess beendet wird.
• 139 – Der Container ist mit einem Segmentierungsfehler abgestürzt. Dies weist auf einen schwerwiegenden Anwendungsfehler hin, der oft mit Speicherzugriffsproblemen zusammenhängt.
• 143 – Der Container wurde ordnungsgemäß gestoppt. Dies passiert normalerweise, wenn Sie docker stop ausführen und der Container korrekt heruntergefahren wird.

Schritt 5: Auf die Containerumgebung zugreifen

Manchmal reichen Logs nicht aus. Sie können den Container betreten, um ihn direkt zu inspizieren.

Führen Sie aus:

docker exec -it <CONTAINER_ID> /bin/bash

Sie betreten eine interaktive Shell im Container.

Wenn bash nicht verfügbar ist:

docker exec -it <CONTAINER_ID> /bin/sh

Sie können nun den Container erkunden.

Überprüfen Sie laufende Containerprozesse vom Host aus:

docker top <CONTAINER_ID>

Sie sehen aktive Prozesse im Container. Wenn der Hauptprozess fehlt, kann der Container stoppen.

Schritt 6: Ressourcenverbrauch überwachen

Container können aufgrund begrenzter Ressourcen fehlschlagen.

Führen Sie aus:

docker stats

Sie sehen in Echtzeit CPU-, Speicher- und Netzwerkverbrauch für alle Container.

Um einen bestimmten Container zu überwachen:

docker stats <CONTAINER_ID>

Sie sehen eine Live-Tabelle, die kontinuierlich mit Ressourcennutzung für alle laufenden Container aktualisiert wird. Jede Zeile repräsentiert einen Container, und jede Spalte zeigt eine bestimmte Art von Ressourcennutzung.
Die wichtigsten Spalten sind:

• CPU % – Zeigt, wie viel CPU der Container verwendet. Hohe Werte können auf intensive Verarbeitung oder ineffizienten Code hinweisen.
• MEM USAGE / LIMIT – Zeigt, wie viel Speicher der Container im Vergleich zu seinem Limit verwendet. Wenn die Nutzung nahe am Limit liegt, kann der Container langsamer werden oder gestoppt werden.
• MEM % – Prozentsatz des verwendeten Speichers relativ zum Limit.
• NET I/O – Netzwerkverkehr. Dies zeigt, wie viel Daten der Container empfangen und gesendet hat. Hohe Werte können auf intensive Netzwerkaktivität hinweisen.
• BLOCK I/O – Lese- und Schreibaktivität auf der Festplatte. Diese Spalte zeigt, wie viel Daten der Container von der Festplatte gelesen und auf die Festplatte geschrieben hat.
• PIDs – Anzahl der im Container laufenden Prozesse. Eine sehr hohe Zahl kann auf ein Prozessleck oder eine außer Kontrolle geratene Anwendung hinweisen.

Schritt 7: Docker-Ereignisse überprüfen

Docker zeichnet Ereignisse auf, die beschreiben, was auf System- und Containerebene passiert. Diese Ereignisse helfen Ihnen zu verstehen, wann ein Container startet, stoppt, abstürzt oder neu startet.
Führen Sie den folgenden Befehl aus:

docker events

Sie sehen einen Live-Stream von Ereignissen wie Containerstart, -stopp und -neustart. Die Ausgabe wird kontinuierlich in Echtzeit aktualisiert.

Ereignisse für einen bestimmten Container filtern

Führen Sie aus:

docker events --filter container=<CONTAINER_ID>

Sie sehen nur Ereignisse, die sich auf den ausgewählten Container beziehen. Dies hilft Ihnen, sich auf eine einzelne Arbeitslast zu konzentrieren.

Ereignisse aus einem bestimmten Zeitraum anzeigen

Um Ereignisse ab einem bestimmten Zeitpunkt anzuzeigen:

docker events --since 10m

Sie sehen Ereignisse der letzten 10 Minuten.

Um sowohl Start- als auch Endzeit zu definieren:

docker events --since 2026-01-01T10:00:00 --until 2026-01-01T11:00:00

Sie sehen Ereignisse, die innerhalb dieses Zeitraums aufgetreten sind.

Ereignisausgabe formatieren

Führen Sie aus:

docker events --format '{{.Time}} {{.Type}} {{.Action}} {{.Actor.ID}}'

Sie sehen formatierte Ausgaben mit ausgewählten Feldern. Dies erleichtert das Lesen oder die Integration in Skripte.

Bestimmte Ereignistypen filtern

Sie können Ereignisse filtern, um sich auf spezifische Probleme zu konzentrieren.

Container stoppt oder stürzt ab

Führen Sie aus:

docker events --filter event=die

Sie sehen Ereignisse, wenn Container stoppen. Dies hilft, unerwartete Abschaltungen zu identifizieren.

Out of Memory-Ereignisse

Führen Sie aus:

docker events --filter event=oom

Sie sehen Ereignisse, wenn ein Container aufgrund von Speicherlimits beendet wird. Dies ist entscheidend für die Diagnose von Ressourcenproblemen.

Container-Neustarts

Führen Sie aus:

docker events --filter event=restart

Sie sehen, wann Container neu starten. Häufige Neustart-Ereignisse können auf eine Absturzschleife hinweisen.

Filter und Zeitbereich kombinieren

Führen Sie aus:

docker events --since 10m --filter event=die

Sie sehen Container-Stopp-Ereignisse der letzten 10 Minuten. Dies hilft, kürzliche Fehler einzugrenzen.

Schritt 8: Speicherplatz überprüfen und ungenutzte Images bereinigen

Docker speichert Images, Container, Volumes und Cache auf der Festplatte. Im Laufe der Zeit kann ungenutzte Daten erheblichen Speicherplatz beanspruchen und Probleme verursachen.

Führen Sie den folgenden Befehl aus:

docker system df

Sie sehen eine Zusammenfassung der Speichernutzung, einschließlich:

• Images
• Container
• Lokale Volumes
• Build-Cache

Jeder Abschnitt zeigt:

• Gesamtanzahl
• Aktive Elemente
• Größe
• Wiederherstellbarer Speicherplatz

Dies hilft Ihnen zu verstehen, wie viel Speicherplatz Docker verwendet und wie viel bereinigt werden kann.

Um ungenutzte Images anzuzeigen, führen Sie aus:

docker images -f dangling=true

Sie sehen Images, die nicht getaggt und von keinem Container verwendet werden. Diese sind sichere Kandidaten für die Entfernung.

Um ungenutzte Images zu entfernen, führen Sie aus:

docker image prune

Sie werden aufgefordert, zu bestätigen. Nach der Bestätigung werden ungenutzte Images gelöscht und Speicherplatz freigegeben.

Um alle ungenutzten Images zu entfernen, nicht nur die hängenden:

docker image prune -a

Sie entfernen alle Images, die von keinem Container verwendet werden.

Verifizierung und Testen

• Führen Sie docker ps aus und bestätigen Sie, dass der Containerstatus korrekt ist.
• Führen Sie docker logs aus und überprüfen Sie, ob Fehler identifiziert oder behoben wurden.
• Führen Sie docker inspect aus und bestätigen Sie, dass Status und Exit-Code den Erwartungen entsprechen.
• Verwenden Sie docker exec, um zu bestätigen, dass Prozesse im Container laufen.
• Wenn das Debuggen erfolgreich ist, sollte der Container im laufenden Zustand bleiben, ohne kritische Fehler in den Logs.

Änderungen rückgängig machen

Wenn Sie während des Debuggens Änderungen vorgenommen haben, können Sie einen sauberen Zustand wiederherstellen.

Stoppen Sie einen Container:

docker stop <CONTAINER_ID>

Sie sehen die Bestätigung, dass der Container gestoppt wurde.

Entfernen Sie einen Container:

docker rm <CONTAINER_ID>

Sie sehen die Bestätigung, dass der Container entfernt wurde.

Erstellen Sie den Container neu:

docker run <OPTIONS> <IMAGE_NAME>

Ein neuer Container wird aus dem Image erstellt.

Fehlerbehebung

Container beendet sich sofort

Überprüfen Sie docker logs auf Fehlermeldungen. Diese erklären normalerweise das Problem.

Kein Zugriff auf den Container

Stellen Sie sicher, dass er mit docker ps läuft.

Keine Logs verfügbar

Stellen Sie sicher, dass die Anwendung Ausgaben an stdout oder stderr schreibt.

Container startet wiederholt neu

Überprüfen Sie die Neustartpolitik und Logs, um Absturzschleifen zu identifizieren.

Hoher Ressourcenverbrauch

Verwenden Sie docker stats, um CPU- oder Speicherspitzen zu bestätigen.

Fazit

Sie haben gelernt, wie Sie Docker-Container debuggen, indem Sie ihren Status überprüfen, Logs analysieren, die Konfiguration inspizieren und auf die Containerumgebung zugreifen. Diese Techniken ermöglichen es Ihnen, häufige Probleme schnell zu identifizieren und zu lösen. Als nächster Schritt erkunden Sie das Debuggen von Docker Compose und zentrale Loggingsysteme zur Verwaltung mehrerer Container.