Docker Compose: зависимый сервис ещё не готов при старте приложения

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

Контейнер приложения запускается, но не может подключиться к базе/Redis: depends_on по умолчанию гарантирует порядок запуска, а не готовность. Настройте healthcheck и ожидание service_healthy. Готовность — это способность зависимого сервиса принимать нужные запросы, а не просто состояние running. Дополнительно приложению необходимы повторы подключения на случай последующего обрыва.

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

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

1. Соберите симптомы до изменения ComposeЗапустите терминал в папке compose.yaml и выполните docker compose ps -a и docker compose logs --tail=80 app. Ищите ошибки Connection refused, timed out, DNS или authentication failed. Если пароль неверен, ожидание готовности не исправит его; если появляется connection refused лишь в первые секунды, переходите к изучению запуска зависимости. Не выводите строку подключения с паролем в публичный отчёт.
2. Проверьте реальную зависимость и её адресОткройте compose.yaml в редакторе. Найдите app → depends_on и имя службы db, затем проверьте значение host в настройках самого приложения. В Compose для другой службы используется имя db, а localhost внутри app указывает на сам app. Выполните docker compose config --services, чтобы сверить названия. Если базы нет в том же проекте, потребуется отдельно согласованная сеть и адрес.
3. Убедитесь, что БД действительно готовится дольше приложенияВыполните docker compose logs --tail=80 db, заменив db именем базы, и сравните отметки времени с журналом app. Если запуск длится дольше — проблема времени готовности вероятна; если база пишет authentication failed или сама падает, исправляйте причину базы, а не бесконечно увеличивайте задержку. docker compose ps показывает состояние running, которое само по себе не доказывает готовность.
4. Добавьте проверку здоровья именно для зависимостиВ compose.yaml под службой db добавьте healthcheck, который проверяет доступность реальной функции сервиса. Для Redis из официального образа можно использовать redis-cli ping: успешный ответ PONG означает готовность принимать команды; для PostgreSQL нужен другой инструмент и учёт авторизации. Не копируйте Redis-команду в образ, где нет redis-cli. Установите разумный interval, timeout, retries, start_period, сравнив их с временем загрузки.
5. Укажите ожидание состояния service_healthyВ разделе app → depends_on используйте длинную форму db: condition: service_healthy. Compose тогда дождётся healthy для db перед созданием/запуском зависимого сервиса, если используется поддерживаемая версия Docker Compose. Проверьте синтаксис командой docker compose config -q: если команда вернула ошибку, восстановите сохранённый файл и проверьте отступы YAML.
6. Проверьте на отдельном простом учебном проектеСоздайте новую папку и сохраните compose.yaml из примера. В терминале этой папки выполните docker compose up -d, затем docker compose ps и docker compose logs client. Сервис db должен стать healthy до запуска клиента; в журнале клиента ожидайте PONG. Не используйте для теста работающую базу и не применяйте down -v к другим проектам.
7. Добавьте повторные попытки в реальное приложениеОжидание service_healthy помогает при первоначальном старте, но не гарантирует, что БД не станет недоступной через минуту. Проверьте, поддерживает ли ваше приложение повторные попытки подключения с задержкой и ограничением по времени; настройте их штатным способом без бесконечной нагрузки на базу. Если база иногда перезагружается, такая защита нужна даже при корректном healthcheck.
8. Применяйте к рабочей системе с резервным планомПрежде чем заменять YAML на сервере, сделайте его копию и убедитесь, что есть резервная копия важных данных. Изменение depends_on/healthcheck может требовать пересоздания контейнеров и остановить пользователей; согласуйте окно. Если в учебном варианте нет PONG или client не стартует, посмотрите docker compose ps -a, логи db и результат healthcheck, а не отключайте зависимости.
9. Команды для отдельных ситуацийВыберите только подходящий вариант. Это не одна последовательность: часть команд диагностирует проблему, а часть меняет настройки или данные.
   Выберите подходящий вариант — это не команды для последовательного выполнения

   Вариант 1Просмотр состояния и журналов.

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

   Просмотр состояния и журналов. Имена app/db являются примерами и заменяются реальными именами ваших служб.

   docker compose ps -a

   docker compose config --services

   docker compose logs --tail=80 app

   docker compose logs --tail=80 db

   Вариант 2Для отдельного тестового compose.yaml из примера: синтаксическая проверка, запуск, затем вывод результата к…

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

   Для отдельного тестового compose.yaml из примера: синтаксическая проверка, запуск, затем вывод результата клиента. При запуске контейнеры меняют состояние.

   docker compose config -q

   docker compose up -d

   docker compose logs client

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

   Вариант 3Проверка в демонстрационном сервисе client, где образ Redis содержит redis-cli.

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

   Проверка в демонстрационном сервисе client, где образ Redis содержит redis-cli. Успех — PONG; имя db работает как DNS-имя Compose.

   docker compose exec client redis-cli -h db ping

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

services:
  db:
    image: redis:7-alpine
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 5
      start_period: 10s
  client:
    image: redis:7-alpine
    depends_on:
      db:
        condition: service_healthy
    command: ["sh", "-c", "redis-cli -h db ping; sleep 3600"]

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

Исправление подтверждено, если docker compose ps показывает db healthy, клиент подключается с первого штатного запуска и при последующих коротких отключениях реагирует по предусмотренной политике повторов. Если db здоров, но приложение пишет authentication failed — проверяйте учётные данные отдельно.