Docker Compose: DNS сервисов и готовность базы при запуске

Сначала проверьте адрес подключения API

Допустим, API использует postgres://localhost:15432/app. Такой адрес подходит клиенту на ноутбуке, если порт базы опубликован на хосте. Внутри контейнера API localhost указывает на сам контейнер API. Публикация порта этого не меняет. Запишите в диагностический лог хост и порт соединения, исключив пароль.

В примере сервисы подключены к общей сети Compose по умолчанию. Внутренний адрес базы — db:5432, а клиент на Docker-хосте обращается к 127.0.0.1:15432. При собственных сетях проверьте, что API и база имеют хотя бы одну общую сеть. Два отдельных Compose-проекта автоматически общую сеть не получают.

• Docker: Compose networking and service discovery

Добавьте проверку готовности базы

Пример предполагает Dockerfile для Node API в текущем каталоге и приложение, слушающее 0.0.0.0:8080. Пароль local-demo предназначен только для временного локального стенда. Версия образа PostgreSQL выбрана для упражнения; хранение данных и выбор образа для production требуют отдельного решения.

Сохраните конфигурацию в compose.yaml. Healthcheck выполняется внутри db и проверяет локальный сервер. Условие service_healthy заставляет Compose дождаться успешной проверки перед запуском api. Краткая форма depends_on задаёт порядок запуска, но не гарантирует готовность базы. Для соединения контейнеров публикация порта 15432 не нужна.

services:
  api:
    build: .
    environment:
      DATABASE_URL: postgres://app:local-demo@db:5432/app
    depends_on:
      db:
        condition: service_healthy
    ports:
      - "127.0.0.1:8080:8080"
  db:
    image: postgres:17
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: local-demo
      POSTGRES_DB: app
    ports:
      - "127.0.0.1:15432:5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -h 127.0.0.1 -U app -d app"]
      interval: 5s
      timeout: 3s
      retries: 12
      start_period: 10s

• Docker: Compose startup order and health checks
• Docker: Compose service configuration

Разделите ошибки DNS, TCP и PostgreSQL

Выполняйте команды из каталога с compose.yaml и замените имена сервисов своими. Последние две проверки требуют работающего контейнера API с Node. Если api сразу завершается, сначала изучите его логи или используйте диагностический контейнер в той же сети.

Ошибка разрешения имени указывает на название сервиса или состав сети. Имя разрешается, но соединение отклонено — проверяйте слушающий процесс, порт и состояние запуска. Успешное TCP-соединение ещё не подтверждает пароль, наличие базы и выполнение SQL. Сопоставьте сообщение приложения с конкретным уровнем, прежде чем менять конфигурацию.

docker compose config --quiet
docker compose ps -a
docker compose logs --tail=50 db api
docker compose port db 5432
docker compose exec -T api node -e 'require("dns").lookup("db", (error, address) => { if (error) throw error; console.log(address); })'
docker compose exec -T api node -e 'const socket = require("net").createConnection({ host: "db", port: 5432 }); socket.setTimeout(3000); socket.on("connect", () => { console.log("TCP connected"); socket.end(); }); socket.on("timeout", () => { socket.destroy(); process.exitCode = 1; }); socket.on("error", error => { console.error(error.message); process.exitCode = 1; });'

• Docker: docker compose exec
• Docker: Compose networking and service discovery

Проверяйте готовность к нужной операции

pg_isready проверяет, принимает ли сервер PostgreSQL соединения. Он не доказывает, что пароль API верен или нужная таблица уже создана. Если сначала требуется миграция, выполните её отдельной задачей и явно дождитесь успешного завершения либо обеспечьте понятную ошибку инициализации в приложении.

В нашем примере сначала исправьте localhost. Если затем при старте иногда появляется connection refused, добавьте проверку готовности. Если после успешного healthcheck возникает relation does not exist, исследуйте миграции. Это разные результаты, требующие разных исправлений, даже если все они проявляются при запуске API.

• PostgreSQL 17: pg_isready
• Docker: Compose startup order and health checks

Восстанавливайте соединения после запуска

Успешная проверка описывает состояние в конкретный момент. База может перезапуститься позже, а пересозданный контейнер — получить другой IP. Сохраните db как имя хоста. Пул соединений должен отбрасывать разорванные соединения, заново разрешать имя и подключаться с ограниченными повторами, задержкой и общим дедлайном.

Таймаут после записи может оставить неизвестный результат: операция могла выполниться. Повторяйте её только при безопасной семантике или защите от дубликатов. depends_on restart: true относится к явным операциям Compose над зависимостью; это не универсальный механизм восстановления API после любого падения базы.

• Docker: Compose networking and service discovery
• Docker: Compose service configuration
• HTTP, безопасные повторы и идемпотентность

Проверяйте каждое исправление отдельно

Проверьте итоговую конфигурацию Compose, запустите стенд и сопоставьте состояние базы с логами старта API. Затем на временном стенде перезапустите db и наблюдайте, восстановится ли API без ручного вмешательства. Критерий успеха — выполнение нужной операции с базой, а не только разрешение имени.

Сохраните отдельные результаты для неверного адреса, медленного старта и разрыва после запуска. Такой небольшой набор проверок помогает объяснить диагноз и на собеседовании, и при разборе инцидента. После этого переходите к общим вопросам о Docker.

• Вопросы о Docker, CI/CD и Linux

Коротко

Частые вопросы