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
- HEALTHCHECK i kody zakończenia, Docker Docs.
- Konfiguracja healthcheck w usługach Compose, Docker Docs.
- Kolejność startu i service_healthy, Docker Docs.
- Polityki automatycznego restartu, Docker Docs.
- Odczytywanie stanu przez docker inspect, Docker Docs.
- docker compose up i opcja wait, Docker Docs.
Data publikacji: 29.10.2026.

Dyskusja