Kontener może poprawnie uruchomić się po awarii procesu, a pozostać zatrzymany po ręcznym docker stop. To nie musi być błąd. Docker restart policy określa, kiedy silnik ponownie uruchamia kontener, i rozróżnia zakończenie aplikacji od działania administratora.
Wybór polityki powinien wynikać z roli usługi. Długotrwały serwer HTTP, jednorazowa migracja i zadanie eksportujące dane nie powinny automatycznie dostać tego samego ustawienia.
Cztery podstawowe polityki
| Polityka | Typowe zachowanie |
|---|---|
no |
Brak automatycznego restartu |
on-failure |
Restart po niezerowym kodzie zakończenia |
always |
Ponowne uruchamianie kontenera, z regułami dotyczącymi ręcznego zatrzymania |
unless-stopped |
Podobnie jak always, ale zachowuje intencję pozostawienia zatrzymanego kontenera także po restarcie silnika |
on-failure:3 ogranicza liczbę ponowień po błędzie. Polityka on-failure nie służy do gwarantowanego startu kontenera po ponownym uruchomieniu demona. To istotne, gdy chcesz, aby usługa wracała wraz z serwerem.
Ręczne zatrzymanie wstrzymuje działanie polityki. Przy always ponowne uruchomienie silnika może przywrócić kontener, a unless-stopped zachowuje zatrzymanie. Dokładnie tę różnicę trzeba uwzględnić w procedurze serwisowej.
Ustawienie w Compose
W usłudze działającej stale typowy zapis wygląda tak:
services:
app:
image: twoj-obraz:ustalona-wersja
restart: unless-stopped
Nazwa obrazu jest miejscem na rzeczywisty obraz twojej aplikacji. Nie kopiuj przykładu jako gotowego projektu. Po zmianie konfiguracji użyj właściwej procedury wdrożenia Compose i sprawdź finalne ustawienie kontenera.
docker inspect --format '{{json .HostConfig.RestartPolicy}}' NAZWA_KONTENERA
docker compose restart uruchamia ponownie istniejące kontenery, ale nie jest sposobem zastosowania wszystkich zmian pliku Compose. Zasady odtwarzania usług wyjaśnia poradnik Compose.
Sprawdź politykę na jednorazowym teście
Poniższy kontener nie otwiera portów i nie ma sieci. Po jedenastu sekundach kończy pracę kodem 1, a Docker może ponowić ją dwa razy:
docker run -d --name restart-demo \
--network none --memory 32m --cpus .2 \
--restart on-failure:2 \
alpine:3.22 sh -c 'sleep 11; exit 1'
Odczekaj, aż zakończą się próby, i odczytaj wynik:
docker inspect --format '{{.RestartCount}} {{.State.Status}}' restart-demo
W rzeczywistym teście otrzymano licznik 2 i stan exited. Potwierdzono więc ograniczoną liczbę restartów po błędzie procesu. Nie restartowano VPS-a ani demona Dockera; opis ich zachowania wynika z dokumentacji.
Po zakończeniu usuń wyłącznie demonstrację:
docker rm restart-demo
Docker dokumentuje warunek poprawnego rozpoczęcia monitorowania polityki po udanym starcie kontenera. Test z opóźnieniem dłuższym niż dziesięć sekund nie sprowadza się do błędu polegającego na natychmiastowym nieudanym uruchomieniu.
Restart nie naprawia przyczyny
Brak pliku, złe hasło i niezgodna migracja zwykle nie znikną po kolejnym starcie. Nieograniczona pętla może zwiększać obciążenie, zapełniać logi i utrudniać zauważenie problemu.
Najpierw odczytaj logi oraz stan zakończenia:
docker logs --tail 100 NAZWA_KONTENERA
docker inspect --format '{{json .State}}' NAZWA_KONTENERA
Sprawdź kod zakończenia, informację o OOM i czas ostatnich zmian stanu. Pamiętaj, że wynik opisuje konkretny kontener. Jeżeli wdrożenie utworzyło nowy, jego licznik nie jest historią całej usługi.
Przy problemach z połączeniem do bazy osobno sprawdź sieć i nazwę usługi. Przy błędnej konfiguracji środowiska skorzystaj z poradnika o zmiennych Compose.
Healthcheck to inna informacja
Status unhealthy nie oznacza zakończenia głównego procesu. W zwykłym Docker Engine sam healthcheck nie uruchamia polityki restartu. Aplikacja może więc działać jako proces i pozostawać niezdrowa bez wzrostu licznika restartów.
W osobnym teście Docker Healthcheck pokazano właśnie tę sytuację. Nie próbuj rozwiązywać jej przez przypadkową zmianę on-failure na always, bo proces nadal nie kończy pracy.
Jeśli potrzebujesz reakcji na niezdrowy stan, zaprojektuj ją osobno: określ próg, limit prób i alarm. Zewnętrzny monitoring Uptime Kuma może sprawdzać także publiczną drogę użytkownika przez domenę i proxy.
Zadania jednorazowe wymagają ostrożności
Migracja lub eksport może wykonać trwały zapis, a potem zakończyć się błędem przy wysyłaniu odpowiedzi. Restart całego zadania może powtórzyć zmianę. Dla takiej pracy potrzebna jest kontrola identyfikatora operacji i etapów zatwierdzania.
Nie ustawiaj always na zadaniu, którego normalnym rezultatem jest zakończenie kodem 0, jeśli nie chcesz wykonywać go w pętli. Dla cyklicznego uruchamiania wybierz harmonogram, a nie restart jako zegar.
Trwałe dane powinny znajdować się w właściwie zarządzanym magazynie. Restart nie zastępuje backupu ani kontroli wolumenów. Przy czyszczeniu nie usuwaj danych tylko dlatego, że kontener wielokrotnie się uruchamia.
Kontrola po wdrożeniu
Sprawdź politykę odczytaną z kontenera, stan procesu i odpowiedź usługi. Test samego pliku YAML nie dowodzi, że działający kontener ma tę konfigurację. Zapisz też, kto i jak może celowo pozostawić usługę zatrzymaną.
Nie łącz niezależnych mechanizmów restartujących bez przemyślenia odpowiedzialności. Gdy Docker i dodatkowy supervisor jednocześnie próbują sterować tą samą usługą, diagnoza przyczyny staje się trudniejsza.
Najczęstsze pytania
Czy unless-stopped uruchomi ręcznie zatrzymany kontener po restarcie hosta?
Polityka zachowuje intencję zatrzymania. Jeśli chcesz przywrócić usługę, uruchom ją jawnie i sprawdź jej stan.
Dlaczego unhealthy nie powoduje restartu?
To stan kontroli zdrowia, a nie zakończenie procesu. Zwykła restart policy nie jest automatycznym obserwatorem healthchecka.
Czy restart policy uruchamia brakującą aplikację po usunięciu kontenera?
Nie. Dotyczy istniejącego kontenera. Usunięty zasób wymaga ponownego utworzenia, np. przez Compose.
Jak ograniczyć pętlę po błędzie?
Dla właściwego scenariusza użyj on-failure:N, ale przede wszystkim odczytaj przyczynę zakończenia. Limit nie naprawia konfiguracji.
Źródła
- Polityki restartu i ręczne zatrzymanie, Docker Docs.
- Konfiguracja usług Compose, Docker Docs.
- Odczyt stanu kontenera, Docker Docs.
- Stan zdrowia kontenera, Docker Docs.
- Odtwarzanie usług Compose, Docker Docs.
Data publikacji: 08.11.2026.

Dyskusja