Czego szukasz?

Wpisz temat, narzędzie lub problem do rozwiązania.

← Wszystkie artykuły

Docker Healthcheck: jak sprawdzać, czy kontener naprawdę działa

Srebrny serwer z zieloną kontrolką zasilania i czerwoną kontrolką przy złączu diagnostycznym

Kontener może mieć status Up, chociaż aplikacja od kilku minut zwraca błędy. Docker Healthcheck pozwala wykonać dodatkową próbę działania usługi i odróżnić uruchomiony proces od aplikacji gotowej do pracy. Sam negatywny wynik tej próby nie oznacza jednak automatycznego restartu.

Poniżej skonfigurujesz kontrolę HTTP w Compose, odczytasz przyczynę niepowodzenia i przeprowadzisz odwracalny test awarii. Przykład działa w osobnym kontenerze bez opublikowanych portów. Nie wymaga zmieniania działającej strony ani bazy danych.

Co właściwie sprawdza Docker Healthcheck

Docker uruchamia wskazaną komendę wewnątrz kontenera. Kod zakończenia 0 oznacza powodzenie, a 1 niepowodzenie. Kod 2 jest zarezerwowany i nie powinien służyć jako własny stan aplikacji. Kontener z kontrolą zdrowia otrzymuje dodatkowy status: początkowo starting, następnie healthy albo unhealthy.

To oddzielna informacja od stanu procesu. running mówi, że główny proces nadal działa. healthy mówi, że ostatnio udało się spełnić warunek zdefiniowany przez autora testu. Jeżeli ten warunek jest zbyt słaby, zielony status niewiele znaczy.

Przykładowo sprawdzenie obecności pliku konfiguracyjnego nie wykryje zawieszonego serwera HTTP. Z kolei żądanie do strony głównej może przechodzić, mimo że wszystkie operacje wymagające bazy kończą się błędem. Zanim wpiszesz komendę, określ, jaką zdolność aplikacji chcesz potwierdzić. Podstawowe pojęcia procesu, obrazu i kontenera wyjaśnia wprowadzenie do Dockera.

Najpierw wybierz dobry endpoint

Przydatny endpoint kontrolny powinien być szybki, przewidywalny i pozbawiony skutków ubocznych. Nie wysyła maila, nie tworzy zamówienia i nie zapisuje nowego rekordu przy każdym odpytaniu. Może zwracać 200, gdy aplikacja jest gotowa, oraz 503, gdy nie może przyjmować pracy.

Rozdziel dwa pytania: czy proces odpowiada i czy usługa jest gotowa obsłużyć konkretny ruch. Nie każda aplikacja potrzebuje dwóch osobnych adresów, ale nazwa /health sama nie określa zakresu testu. Opisz ten zakres w projekcie.

Jeżeli do podstawowej pracy niezbędna jest baza, kontrola gotowości może wykonać lekkie zapytanie z krótkim timeoutem. Nie uruchamiaj migracji ani kosztownego raportu. Awaria opcjonalnej usługi analitycznej nie musi blokować całej aplikacji. Decyzja zależy od tego, co użytkownik nadal może zrobić.

W przykładowej aplikacji wynik zależy wyłącznie od obecności pliku testowego. To celowo sztuczny przełącznik awarii, dzięki któremu można sprawdzić zachowanie Dockera bez uszkadzania danych.

Uruchom przykład w osobnym katalogu

Utwórz pusty katalog roboczy, a w nim pliki app.py oraz compose.yaml. Nie dopisuj tego przykładu do produkcyjnego projektu. Python jest tu zarówno serwerem, jak i klientem wykonującym kontrolę, dlatego nie trzeba instalować curl w obrazie.

Zawartość app.py:

from http.server import BaseHTTPRequestHandler, HTTPServer
from pathlib import Path

class Handler(BaseHTTPRequestHandler):
    def do_GET(self):
        if self.path != '/health':
            self.send_error(404)
            return
        failed = Path('/tmp/fail-health').exists()
        self.send_response(503 if failed else 200)
        self.end_headers()
        self.wfile.write(b'failed\n' if failed else b'ok\n')

HTTPServer(('127.0.0.1', 8000), Handler).serve_forever()

Zawartość compose.yaml:

services:
  app:
    image: python:3.13-slim
    command: ["python", "/app/app.py"]
    volumes:
      - ./app.py:/app/app.py:ro
    network_mode: none
    mem_limit: 128m
    cpus: 0.25
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/health', timeout=1).close()"]
      interval: 3s
      timeout: 2s
      retries: 2
      start_period: 5s

Serwer nasłuchuje na pętli zwrotnej wewnątrz kontenera. network_mode: none odcina sieć zewnętrzną, ale pozostawia lokalną komunikację potrzebną do próby. To ustawienie laboratorium, a nie konfiguracja publicznej aplikacji. Nie ma sekcji ports, więc przykład nie zajmie portu strony.

Uruchom projekt z własną nazwą:

docker compose -p healthcheck-demo up --wait --wait-timeout 60
docker compose -p healthcheck-demo ps

Opcja --wait czeka na stan działający lub zdrowy, zależnie od konfiguracji usługi. Nie zastępuje testu biznesowego. Usługa bez healthchecku może spełnić ten warunek samym uruchomieniem procesu. Jeśli dopiero poznajesz plik projektu, zobacz poradnik Docker Compose.

Jak dobrać odstępy i progi

W przykładzie interval: 3s przyspiesza demonstrację. W zwykłej aplikacji tak częste sprawdzanie może być zbędne. Dobierz odstęp do czasu wykrycia awarii, obciążenia endpointu i sposobu reagowania na alarm.

Parametr Znaczenie w przykładzie
interval Odstęp pomiędzy próbami kontroli
timeout Maksymalny czas wykonania pojedynczej próby
retries Liczba kolejnych niepowodzeń potrzebna do uznania usługi za niezdrową
start_period Początkowy okres, w którym nieudane próby nie zwiększają licznika awarii

Pomyślne sprawdzenie w okresie startowym oznacza, że kontener jest już gotowy. Kolejne niepowodzenia mogą wtedy liczyć się normalnie. start_period nie jest więc poleceniem bezwarunkowego czekania przez podany czas.

Wewnętrzny timeout klienta HTTP wynosi sekundę, a limit całej komendy dwie sekundy. Dzięki temu klient zwykle zdąży sam zgłosić błąd. Nie projektuj kontroli tak, aby dziesiątki wiszących prób obciążały usługę bardziej niż normalny ruch.

Zasymuluj awarię bez zatrzymywania procesu

Utwórz plik, który przełącza odpowiedź /health na HTTP 503:

docker compose -p healthcheck-demo exec -T app touch /tmp/fail-health
docker compose -p healthcheck-demo ps

Status nie zmieni się natychmiast. Poczekaj na kolejne próby, a następnie odczytaj szczegóły:

cid=$(docker compose -p healthcheck-demo ps -q app)
docker inspect --format '{{json .State.Health}}' "$cid"
docker inspect --format '{{.State.Running}} {{.RestartCount}}' "$cid"

W rzeczywistym teście tego przykładu kontener przeszedł kolejno przez healthy, unhealthy i ponownie healthy. Przez wszystkie etapy główny proces działał z tym samym PID-em, a licznik restartów wynosił 0. Test wykonano w izolowanym kontenerze z limitem pamięci 128 MB i CPU 0,25, bez publikacji portów.

Przywróć poprawną odpowiedź:

docker compose -p healthcheck-demo exec -T app rm /tmp/fail-health
docker compose -p healthcheck-demo ps

Po udanej próbie status wróci do healthy. Po zakończeniu usuń wyłącznie projekt demonstracyjny:

docker compose -p healthcheck-demo down

Nie przenoś do procedur awaryjnych polecenia down -v bez sprawdzenia wolumenów. Kontrola zdrowia nie wymaga kasowania danych. Różnicę między cyklem życia kontenera i danych omawia poradnik o wolumenach Dockera.

Dlaczego unhealthy nie uruchamia restartu

W zwykłym Docker Engine polityka restart: unless-stopped reaguje na zakończenie kontenera zgodnie ze swoimi zasadami. Negatywny healthcheck nie kończy głównego procesu. Dlatego w demonstracji ta polityka była ustawiona, a licznik restartów pozostał zerowy.

Nie dokładaj od razu narzędzia, które restartuje wszystko po jednym czerwonym wyniku. Jeżeli przyczyną jest niedostępna baza, restart aplikacji może tylko zwiększyć liczbę połączeń i ukryć logi przydatne w diagnozie. Najpierw ustal, czy aplikacja potrafi ponowić połączenie oraz czy restart usuwa konkretną przyczynę.

Jeśli potrzebujesz automatycznej reakcji, potraktuj ją jako osobny mechanizm z limitem prób, opóźnieniem i alarmem. Zewnętrzny monitoring powinien sprawdzać również drogę użytkownika przez DNS, TLS i reverse proxy. Wewnętrzna próba na 127.0.0.1 jej nie obejmuje. Do takiej kontroli pasuje gotowa konfiguracja Uptime Kuma.

Zależności Compose i oczekiwanie na bazę

Usługa zależna może czekać na pozytywny healthcheck innej usługi:

depends_on:
  db:
    condition: service_healthy

To fragment konfiguracji usługi aplikacyjnej. Usługa db musi istnieć i mieć własny sensowny test. Warunek pomaga uporządkować start projektu, ale nie zapewnia ciągłego zarządzania zależnościami. Gdy baza przestanie odpowiadać godzinę później, aplikacja nadal potrzebuje obsługi błędów i ponawiania połączeń.

Szczególnie uważaj na testy wymagające zmiennych środowiskowych. Compose może rozwinąć $ZMIENNA po stronie hosta, zanim komenda dotrze do kontenera. Jeśli potrzebujesz rozwinięcia przez powłokę wewnętrzną, sprawdź zasady $$ i formy CMD-SHELL. Praktyczne różnice opisuje poradnik o zmiennych w Compose.

Gdy kontrola nie przechodzi

Najpierw odczytaj zapis ostatnich prób w docker inspect. Potem wykonaj tę samą komendę ręcznie wewnątrz kontenera. To pozwala rozróżnić błąd aplikacji od braku narzędzia kontrolnego.

Objaw Co sprawdzić
Nie znaleziono curl Czy binarka rzeczywiście znajduje się w tym obrazie
Connection refused Adres, port i moment rozpoczęcia nasłuchiwania
HTTP 404 Ścieżkę endpointu, a nie tylko działanie serwera
HTTP 503 Warunki gotowości aplikacji i jej zależności
Przekroczony timeout Czas odpowiedzi, obciążenie i limit samej próby

Adres localhost wskazuje kontener, w którym działa test. Nie wskazuje automatycznie hosta ani sąsiedniej bazy. Przy problemach z portem skorzystaj z diagnostyki Connection refused. Podstawowe komendy podglądu zbiera ściąga Dockera.

Nie wypisuj haseł i tokenów do wyniku próby. Jej rezultat może zostać zapisany w danych diagnostycznych kontenera. Endpoint także nie powinien publicznie ujawniać szczegółów infrastruktury tylko dlatego, że służy do monitoringu.

Najczęstsze pytania

Czy Docker Healthcheck restartuje kontener?

Sam healthcheck w zwykłym Docker Engine zmienia status zdrowia, ale nie restartuje kontenera. Restart wymaga zakończenia procesu i odpowiedniej polityki albo osobnego mechanizmu reagowania.

Dlaczego kontener jest Up i jednocześnie unhealthy?

Główny proces nadal działa, ale skonfigurowana próba kończy się niepowodzeniem. Odczytaj wynik kontroli, zanim uznasz, że awarii uległa cała aplikacja.

Czy trzeba instalować curl?

Nie. Użyj klienta dostępnego w obrazie albo małej komendy aplikacji. W przykładzie żądanie wykonuje biblioteka standardowa Pythona. Samo wpisanie curl do YAML nie instaluje programu.

Jak często sprawdzać usługę?

Tak często, jak wymaga tego czas wykrycia awarii, z uwzględnieniem kosztu kontroli. Krótki odstęp z demonstracji ułatwia test, ale nie jest uniwersalnym ustawieniem produkcyjnym.

Czy pozytywny wynik potwierdza działanie strony z internetu?

Nie, jeśli test odpytuje tylko lokalny endpoint kontenera. Osobno sprawdzaj publiczną domenę, certyfikat i reverse proxy. Zielony status potwierdza wyłącznie warunek zapisany w komendzie.

Źródła

Data publikacji: 29.10.2026.

KP
O AUTORZE

Krystian Proć

Tworzę narzędzia do pracy z danymi, systemy backendowe i automatyzacje. Pracuję z SQL, PHP, TypeScriptem i Dockerem; rozwijam m.in. dragon-island.com. AI pomaga mi przyspieszać pracę, a architekturę, weryfikację i decyzje techniczne biorę na siebie. Na Trybie Technicznym dzielę się doświadczeniami z budowania i utrzymywania własnych projektów.

Dyskusja

Dodaj komentarz

Twój adres email nie zostanie opublikowany. Wymagane pola są oznaczone *