Контейнер Docker перезапускается: как проверить healthcheck и действительную причину

#Что означает ошибка и при каких условиях возникает

Если контейнер Docker показывает unhealthy и одновременно перезапускается, выясните, из-за чего завершается основной процесс и что управляет перезапуском. Проверка HEALTHCHECK сама по себе не перезапускает контейнер в обычном Docker Engine. Статус unhealthy и цикл Restarting могут иметь разные причины; внешняя система наблюдения может связывать их.

#Как различить причины

#Пошаговая диагностика и исправление

1. Выберите способ в командной строке или терминалеЕсли предыдущие действия не помогли, прочитайте назначение каждого варианта ниже. Не выполняйте их все подряд: выбирайте только соответствующий вашей ситуации.
   Выберите подходящий вариант — это не команды для последовательного выполнения

   Вариант 1Команды для каталога compose.yaml; web — пример имени сервиса.

   Linux · Терминал (Bash)КомандаКопировать всёВыделить

   Команды для каталога compose.yaml; web — пример имени сервиса. -a показывает в том числе остановленные контейнеры, --tail=60 ограничивает вывод журнала. Требуется разрешённый доступ к Docker, а не sudo.

   docker compose version

   docker compose ps -a

   docker compose logs --tail=60 web

   Вариант 2Вторую строку выполняют отдельно, заменив ИДЕНТИФИКАТОР значением из первой.

   Linux · Терминал (Bash)КомандаКопировать всёВыделить

   Вторую строку выполняют отдельно, заменив ИДЕНТИФИКАТОР значением из первой. Без этого замещения команда не сработает. Показывает число перезапусков, последний код выхода и политику.

   docker compose ps -q web

   docker inspect --format "{{.RestartCount}} {{.State.ExitCode}} {{.HostConfig.RestartPolicy.Name}}" ИДЕНТИФИКАТОР

   Вариант 3Замените ИДЕНТИФИКАТОР на реальный идентификатор.

   Linux · Терминал (Bash)КомандаКопировать всёВыделить

   Замените ИДЕНТИФИКАТОР на реальный идентификатор. Показывает состояние проверки здоровья; Output может содержать внутренние адреса и информацию приложения.

   docker inspect --format "{{json .State.Health}}" ИДЕНТИФИКАТОР

   Вариант 4Первая команда только проверяет конфигурацию.

   Linux · Терминал (Bash)С осторожностьюКопировать всёВыделить

   Первая команда только проверяет конфигурацию. Вторая изменяет/пересоздаёт тестовый контейнер web и прерывает его работу; не применять к продуктивному сервису без согласования и резервной копии.

   docker compose config -q

   docker compose up -d --no-deps --force-recreate web

   Команда может изменить состояние системы или её настройки. Проверьте параметры и последствия перед запуском.

2. Не путайте перезапуск с unhealthyВыполните docker compose ps -a и найдите имя сервиса, например web. Если в STATUS написано Up (unhealthy), контейнер продолжает работать — Docker Engine только зафиксировал неудачную проверку. Если видно Restarting или повторные короткие периоды Up, изучайте завершение основного процесса. Запомните точное имя сервиса и не применяйте перезапуск как способ диагностики.
3. Установите, завершается ли основной процессПолучите идентификатор через docker compose ps -q web (замените web названием своего сервиса). Подставьте полученный идентификатор в docker inspect --format ..., приведённую ниже. В результате ищите State.ExitCode, RestartCount и RestartPolicy. Если RestartCount увеличивается, проверяйте логи приложения; если он равен нулю, ошибка может быть исключительно в healthcheck. Не публикуйте полный вывод inspect: там могут быть переменные окружения с секретами.
4. Посмотрите подробность неудачной проверкиПо идентификатору контейнера выполните docker inspect --format "{{json .State.Health}}" ИДЕНТИФИКАТОР. В ответе ищите Status и Log/Output: например, wget: not found показывает отсутствующую утилиту, connection refused — неправильный порт или ещё не готовый сервис. Если поле Health отсутствует, проверка в контейнере не задана: переходите к диагностике лога основного процесса, а не придумывайте healthcheck.
5. Сравните проверку с фактическим сервисомОткройте compose.yaml в редакторе (например, VS Code: «Файл» → «Открыть папку»). Найдите services → нужную службу → healthcheck.test. Сравните адрес: 127.0.0.1 внутри контейнера — это сам контейнер, не ваш компьютер; порт должен совпадать с тем, на котором слушает программа внутри. Убедитесь, что названная в test программа установлена в образе. Для образа Python можно использовать встроенный urllib.request, а не требовать curl.
6. Настройте период проверки для медленного запускаЕсли сервис исправно начинает отвечать лишь после инициализации, сначала по журналу определите примерное время прогрева. В compose.yaml для этой службы задайте разумные start_period, interval, timeout, retries; проверьте YAML командой docker compose config -q. Если проверка синтаксиса ошибочна, верните копию compose.yaml и исправьте отступы. Изменение healthcheck требует пересоздания затронутой службы, поэтому на рабочей системе согласуйте остановку и сохраните состояние.
7. Пересоздайте только тестовый сервис и перепроверьтеДля локального тестового проекта выполните docker compose up -d --no-deps --force-recreate web, заменив имя сервиса своим. Команда пересоздаёт контейнер (возможна краткая недоступность), поэтому её нельзя без согласования применять к базе данных либо приложению с данными исключительно в слое контейнера. Затем docker compose ps и docker compose logs --tail=60 web: ожидайте Up (healthy) после старта; если появляется Restarting, проверяйте фактическую ошибку процесса.
8. Если процесс стабильный, ищите внешний перезапускНа обычном Docker Engine значение unhealthy не является условием restart policy. Проверьте, нет ли у проекта стороннего монитора, скриптов проверки, заданий cron или оркестратора; при их наличии изучайте события и правила только с администратором. Не отключайте наблюдение на рабочем сервере. Если причина не найдена, зафиксируйте время, RestartCount, отредактированные сообщения Health.Log и docker compose logs без секретов.

#Минимальный пример для отдельного тестового проекта

services:
  web:
    image: python:3.12-alpine
    command: ["python", "-m", "http.server", "8000", "--bind", "0.0.0.0"]
    healthcheck:
      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/', timeout=3)"]
      interval: 10s
      timeout: 5s
      retries: 3
      start_period: 15s

#Как проверить результат и что делать, если проблема осталась

После исправления дождитесь нескольких интервалов проверки, выполните docker compose ps и убедитесь в стабильном Up (healthy) и неизменном RestartCount. Если статус unhealthy при отсутствии Restarting, проблема именно в проверке; если Restarting продолжается — передайте администратору безопасные выдержки из журналов и сведений о завершении основного процесса.