#Как проявляется проблема и где искать причину
При запуске Docker Compose порядок depends_on не означает, что база уже готова принимать запросы. Кроме того, неизвестное имя зависимости или неверный отступ в YAML не позволит разобрать конфигурацию.
| Возможная причина | Как узнать | Что делать |
|---|---|---|
| Ошибочное имяСсылка на сервис отсутствует в services | docker compose config возвращает ошибку о сервисе | Исправить точное имя |
| Гонка готовностиКонтейнер базы запущен, но ещё инициализируется | Приложение получает connection refused сразу после старта | Проверять service_healthy для базы |
#Пошаговая диагностика и устранение
- 1. Откройте именно нужный проектВ терминале перейдите в каталог с compose.yaml или docker-compose.yml. Выполните проверку конфигурации: Compose проверит структуру, подстановки переменных и существование зависимостей. Не публикуйте вывод целиком — в нём возможны секреты.
- Дополнительная команда по темеLinux · Терминал (Bash)КомандаКаталог проекта, установлен плагин Compose v2; нулевой код завершения означает успешный разбор.
docker compose config --quiet
- 2. Сопоставьте названия сервисовВыполните список сервисов. Имя после services: — это имя сервиса, не container_name. Если depends_on ссылается на mysql, а в списке только db, исправьте ссылку в исходном YAML.
- Показывает все сервисы, не запускает контейнерыLinux · Терминал (Bash)КомандаПоказывает все сервисы, не запускает контейнеры.
docker compose config --services
- 3. Отделите неверную зависимость от неготовой базыПосле успешной проверки конфигурации в тестовом окружении выполните docker compose ps -a и проверьте статус базы. Если она Exited, смотрите журнал этой службы. Если она Up, но приложение всё равно получает отказ, вероятна задержка готовности.Linux · Терминал (Bash)КомандаИсполняется в каталоге проекта.
docker compose ps -a
- 4. Добавьте проверку готовности в тестовую копиюДля базы предусмотрите healthcheck с командой, которая действительно проверяет доступность именно вашей СУБД; для PostgreSQL пример — pg_isready, для MySQL — проверка через mysqladmin с учётом авторизации. В зависимом сервисе укажите condition: service_healthy.
- Пример кода по темеТекстФрагмент должен находиться внутри services.<имя приложения>; у db должен быть корректный healthcheck.
depends_on: db: condition: service_healthy
- 5. Проверьте статус здоровьяВ тестовой среде после запуска просмотрите статус контейнера и при необходимости информацию о проверках. Состояние healthy означает успешное выполнение указанного теста, но не гарантирует выполнение всех операций приложения.
- Для контейнера без healthcheck значение будет nullLinux · Терминал (Bash)КомандаДля контейнера без healthcheck значение будет null.
docker inspect --format "{{json .State.Health}}" ИМЯ_КОНТЕЙНЕРА_БД
- 6. Обновите тестовую конфигурациюИспользуйте docker compose up только после резервного копирования томов и согласования окна обслуживания. В отдельном тестовом проекте команда пересоздаст нужные сервисы, если конфигурация изменилась.Linux · Терминал (Bash)С осторожностьюВ проектном каталоге тестового окружения; может создавать и пересоздавать контейнеры.
docker compose up -dКоманда может изменить состояние системы или её настройки. Проверьте параметры и последствия перед запуском.
- 7. Проверьте связь приложения с БДДождитесь healthy, откройте приложение и повторите запрос, который ранее завершался connection refused. Если ошибка осталась, проверьте хост подключения: внутри Compose обычно используют имя сервиса базы и его внутренний порт, а не localhost и опубликованный порт.
#Как проверить результат
Файл Compose проходит проверку, база становится healthy, а приложение подключается без ошибки при холодном запуске.
#Если исправление не помогло
Если Docker сообщает «dependency failed to start», проверьте тест healthcheck и реальные учётные данные; не обходите его удалением проверки без диагностики.