Jak debugować kontenery Docker na Debianie 13

Wprowadzenie

W tym poradniku nauczysz się debugować kontenery Docker za pomocą praktycznych, przyjaznych dla początkujących technik. Zidentyfikujesz problemy, sprawdzając status kontenera, analizując logi, sprawdzając konfigurację i uzyskując dostęp do środowiska kontenera. To podejście pomoże Ci szybko zrozumieć, dlaczego kontener nie działa i jak to naprawić.

Cel końcowy: Po zakończeniu tego poradnika będziesz w stanie zidentyfikować i rozwiązywać typowe problemy z kontenerami Docker za pomocą logów, inspekcji i narzędzi do analizy w czasie rzeczywistym.

Wymagania wstępne

• Docelowa grupa odbiorców: Początkujący administratorzy systemów
• Szacowany czas: ~30 minut
• System operacyjny: Debian 13
• Oprogramowanie: Docker 24.0 lub nowszy
• Uprawnienia: Użytkownik z uprawnieniami sudo lub członkostwo w grupie docker
• Wymagania sprzętowe: Co najmniej 2 GB RAM i 10 GB wolnego miejsca na dysku
• Wymagania sieciowe: Dostęp do Internetu w celu pobierania obrazów, brak specyficznych portów wymaganych dla tego poradnika
• Wymagania: Podstawowa obsługa linii poleceń i działająca usługa Docker
• Kompatybilność: Przetestowane na Debian 13 i działa na Debian 12 oraz Ubuntu 22.04

Krok 1: Sprawdź informacje o systemie Docker

Przed debugowaniem konkretnego kontenera upewnij się, że sam Docker działa poprawnie.
Uruchom następujące polecenie:

docker system info

Zobaczysz szczegółowe informacje o środowisku Docker, w tym:

• Wersja serwera
• Sterownik magazynu
• Liczba kontenerów i obrazów
• Dostępność CPU i pamięci
• Katalog główny Docker

To pomoże Ci potwierdzić, że:

• Docker działa poprawnie
• System ma wystarczające zasoby
• Nie ma globalnych problemów z konfiguracją

Aby sprawdzić status usługi Docker:

systemctl status docker

Zobaczysz, czy usługa Docker jest aktywna. Jeśli nie działa, uruchom ją:

sudo systemctl start docker

Powinieneś teraz zobaczyć usługę w stanie aktywnym.

Krok 2: Sprawdź status kontenera

Uruchom następujące polecenie:

docker ps

Zobaczysz listę działających kontenerów z takimi szczegółami jak ID kontenera, obraz i status. Jeśli Twój kontener pojawia się ze statusem "Up", to obecnie działa.

Aby uwzględnić zatrzymane kontenery:

docker ps -a

Teraz zobaczysz wszystkie kontenery. Jeśli Twój kontener pokazuje "Exited", oznacza to, że został zatrzymany z powodu błędu lub zakończył wykonanie.

Krok 3: Przeglądaj logi kontenera

Logi pokazują, co aplikacja wewnątrz kontenera wypisuje. To najważniejszy krok do debugowania. Możesz uzyskać <CONTAINER_ID> za pomocą polecenia docker ps opisanego w kroku 2.

Uruchom:

docker logs <CONTAINER_ID>

Zobaczysz wyjście aplikacji, w tym błędy i ostrzeżenia. Szukaj wiadomości wskazujących na awarie, takie jak brakujące pliki lub błędy połączenia.

Aby śledzić logi w czasie rzeczywistym:

docker logs -f <CONTAINER_ID>

Zobaczysz nowe wpisy logów, gdy się pojawią. To przydatne przy ponownym uruchamianiu kontenera i obserwowaniu zachowania.

Aby wyświetlić tylko ostatnie logi:

docker logs --tail 50 <CONTAINER_ID>

Zobaczysz ostatnie 50 linii wyjścia. To pomaga skupić się na najnowszych wydarzeniach.

Krok 4: Sprawdź stan kontenera

Docker przechowuje szczegółowe informacje o każdym kontenerze.

Uruchom:

docker inspect <CONTAINER_ID>

Zobaczysz ustrukturyzowane wyjście JSON z konfiguracją i szczegółami działania.

Aby sprawdzić status kontenera:

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

Zobaczysz prostą wartość, taką jak "running" lub "exited", co potwierdza stan kontenera.

Aby sprawdzić kod wyjścia:

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

Zobaczysz liczbę. Wartość 0 oznacza sukces, podczas gdy każda inna wartość wskazuje na błąd.

Aby sprawdzić politykę restartu:

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

Zobaczysz, czy kontener jest skonfigurowany do automatycznego restartu.

Typowe kody wyjścia, które możesz zobaczyć:

• 0 – Proces zakończył się pomyślnie bez błędów. Zwykle oznacza to, że kontener zatrzymał się normalnie. Na przykład, skrypt zakończył swoje zadanie i zakończył działanie.
• 1 – Wystąpił ogólny błąd. To najczęstszy kod awarii i zwykle oznacza, że coś wewnątrz aplikacji nie powiodło się, na przykład brakujący plik, nieprawidłowa konfiguracja lub błąd w czasie wykonywania.
• 125 – Docker nie mógł uruchomić kontenera. Zwykle wskazuje to na problem z samym poleceniem docker run, takim jak nieprawidłowe opcje lub niepoprawne parametry.
• 126 – Polecenie wewnątrz kontenera nie może zostać wykonane. Często oznacza to problemy z uprawnieniami lub że plik nie jest wykonywalny.
• 127 – Polecenie nie zostało znalezione. Zwykle oznacza to, że określony plik binarny lub skrypt nie istnieje wewnątrz kontenera.
• 137 – Kontener został zatrzymany siłą. Często dzieje się tak, gdy system kończy się pamięć i zabija proces kontenera.
• 139 – Kontener uległ awarii z błędem segmentacji. Wskazuje to na poważny błąd aplikacji, często związany z problemami z dostępem do pamięci.
• 143 – Kontener został zatrzymany łagodnie. Zwykle dzieje się tak, gdy uruchamiasz docker stop i kontener zamyka się poprawnie.

Krok 5: Uzyskaj dostęp do środowiska kontenera

Czasami logi nie wystarczają. Możesz wejść do kontenera, aby go bezpośrednio sprawdzić.

Uruchom:

docker exec -it <CONTAINER_ID> /bin/bash

Wchodzisz do interaktywnej powłoki wewnątrz kontenera.

Jeśli bash nie jest dostępny:

docker exec -it <CONTAINER_ID> /bin/sh

Możesz teraz eksplorować kontener.

Sprawdź działające procesy kontenera z hosta:

docker top <CONTAINER_ID>

Zobaczysz aktywne procesy wewnątrz kontenera. Jeśli brakuje głównego procesu, kontener może się zatrzymać.

Krok 6: Monitoruj zużycie zasobów

Kontenery mogą się nie powieść z powodu ograniczonych zasobów.

Uruchom:

docker stats

Zobaczysz zużycie CPU, pamięci i sieci w czasie rzeczywistym dla wszystkich kontenerów.

Aby monitorować konkretny kontener:

docker stats <CONTAINER_ID>

Zobaczysz tabelę na żywo, która aktualizuje się ciągle z zużyciem zasobów dla wszystkich działających kontenerów. Każdy wiersz reprezentuje kontener, a każda kolumna pokazuje określony typ zużycia zasobów.
Najważniejsze kolumny to:

• CPU % – Pokazuje, ile CPU używa kontener. Wysokie wartości mogą wskazywać na intensywne przetwarzanie lub nieefektywny kod.
• MEM USAGE / LIMIT – Pokazuje, ile pamięci używa kontener w porównaniu do swojego limitu. Jeśli zużycie jest bliskie limitu, kontener może zwolnić lub zostać zatrzymany.
• MEM % – Procent używanej pamięci w stosunku do limitu.
• NET I/O – Ruch sieciowy. Pokazuje, ile danych kontener otrzymał i wysłał. Wysokie wartości mogą wskazywać na intensywną aktywność sieciową.
• BLOCK I/O – Aktywność odczytu i zapisu na dysku. Ta kolumna pokazuje, ile danych kontener odczytał z dysku i zapisał na dysku.
• PIDs – Liczba procesów działających wewnątrz kontenera. Bardzo wysoka liczba może wskazywać na wyciek procesów lub niekontrolowaną aplikację.

Krok 7: Sprawdź zdarzenia Docker

Docker rejestruje zdarzenia opisujące, co dzieje się na poziomie systemu i kontenera. Te zdarzenia pomagają zrozumieć, kiedy kontener się uruchamia, zatrzymuje, ulega awarii lub restartuje.
Uruchom następujące polecenie:

docker events

Zobaczysz strumień zdarzeń na żywo, takich jak uruchomienie, zatrzymanie i restart kontenera. Wyjście aktualizuje się ciągle w czasie rzeczywistym.

Filtruj zdarzenia dla konkretnego kontenera

Uruchom:

docker events --filter container=<CONTAINER_ID>

Zobaczysz tylko zdarzenia związane z wybranym kontenerem. To pomaga skupić się na jednym obciążeniu.

Pokaż zdarzenia z określonego zakresu czasowego

Aby wyświetlić zdarzenia od określonego momentu w czasie:

docker events --since 10m

Zobaczysz zdarzenia z ostatnich 10 minut.

Aby zdefiniować zarówno czas początkowy, jak i końcowy:

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

Zobaczysz zdarzenia, które miały miejsce w tym przedziale czasowym.

Formatuj wyjście zdarzeń

Uruchom:

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

Zobaczysz sformatowane wyjście z wybranymi polami. To ułatwia czytanie lub integrację ze skryptami.

Filtruj określone typy zdarzeń

Możesz filtrować zdarzenia, aby skupić się na konkretnych problemach.

Zatrzymania lub awarie kontenera

Uruchom:

docker events --filter event=die

Zobaczysz zdarzenia, gdy kontenery się zatrzymują. To pomaga zidentyfikować niespodziewane wyłączenia.

Zdarzenia braku pamięci

Uruchom:

docker events --filter event=oom

Zobaczysz zdarzenia, gdy kontener zostaje zabity z powodu limitów pamięci. To jest kluczowe dla diagnozowania problemów z zasobami.

Restarty kontenera

Uruchom:

docker events --filter event=restart

Zobaczysz, kiedy kontenery się restartują. Częste zdarzenia restartu mogą wskazywać na pętlę awarii.

Łącz filtry i zakresy czasowe

Uruchom:

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

Zobaczysz zdarzenia zatrzymania kontenera z ostatnich 10 minut. To pomaga zawęzić ostatnie awarie.

Krok 8: Sprawdź użycie dysku i wyczyść nieużywane obrazy

Docker przechowuje obrazy, kontenery, wolumeny i pamięć podręczną na dysku. Z czasem nieużywane dane mogą zajmować znaczną przestrzeń i powodować problemy.

Uruchom następujące polecenie:

docker system df

Zobaczysz podsumowanie użycia dysku, w tym:

• Obrazy
• Kontenery
• Wolumeny lokalne
• Pamięć podręczna budowania

Każda sekcja pokazuje:

• Całkowitą liczbę
• Aktywne elementy
• Rozmiar
• Przestrzeń do odzyskania

To pomaga zrozumieć, ile miejsca na dysku używa Docker i ile można wyczyścić.

Aby wyświetlić nieużywane obrazy, uruchom:

docker images -f dangling=true

Zobaczysz obrazy, które nie są oznaczone i nie są używane przez żaden kontener. Są to bezpieczni kandydaci do usunięcia.

Aby usunąć nieużywane obrazy, uruchom:

docker image prune

Zostaniesz poproszony o potwierdzenie. Po potwierdzeniu nieużywane obrazy zostaną usunięte, a miejsce na dysku zostanie zwolnione.

Aby usunąć wszystkie nieużywane obrazy, nie tylko te wiszące:

docker image prune -a

Usuwasz wszystkie obrazy, które nie są używane przez żaden kontener.

Weryfikacja i testowanie

• Uruchom docker ps i potwierdź, że status kontenera jest poprawny.
• Uruchom docker logs i zweryfikuj, czy błędy zostały zidentyfikowane lub rozwiązane.
• Uruchom docker inspect i potwierdź, że status i kod wyjścia są zgodne z oczekiwaniami.
• Użyj docker exec, aby potwierdzić, że procesy działają wewnątrz kontenera.
• Jeśli debugowanie zakończy się sukcesem, kontener powinien pozostać w stanie działającym bez krytycznych błędów w logach.

Cofanie zmian

Jeśli dokonałeś zmian podczas debugowania, możesz przywrócić czysty stan.

Zatrzymaj kontener:

docker stop <CONTAINER_ID>

Zobaczysz potwierdzenie, że kontener został zatrzymany.

Usuń kontener:

docker rm <CONTAINER_ID>

Zobaczysz potwierdzenie, że kontener został usunięty.

Odtwórz kontener:

docker run <OPTIONS> <IMAGE_NAME>

Nowy kontener zostaje utworzony z obrazu.

Rozwiązywanie problemów

Kontener natychmiast się wyłącza

Sprawdź docker logs pod kątem komunikatów o błędach. Zwykle wyjaśniają one problem.

Nie można uzyskać dostępu do kontenera

Upewnij się, że działa, używając docker ps.

Brak dostępnych logów

Upewnij się, że aplikacja zapisuje wyjście do stdout lub stderr.

Kontener restartuje się wielokrotnie

Sprawdź politykę restartu i logi, aby zidentyfikować pętle awarii.

Wysokie zużycie zasobów

Użyj docker stats, aby potwierdzić skoki CPU lub pamięci.

Podsumowanie

Nauczyłeś się, jak debugować kontenery Docker, sprawdzając ich status, analizując logi, sprawdzając konfigurację i uzyskując dostęp do środowiska kontenera. Te techniki pozwalają szybko zidentyfikować i rozwiązać typowe problemy. Jako kolejny krok, eksploruj debugowanie Docker Compose i scentralizowane systemy logowania do zarządzania wieloma kontenerami.