Docker Compose: частые ошибки и решения для разработчиков

[kirilljsx]

Docker Compose упрощает запуск нескольких контейнеров, но ошибки в конфигурации быстро ставят всё на паузу. В этой статье разберём типичные проблемы: конфликты портов, сетевые сбои, неудачные сборки и внезапные выходы контейнеров. Вы узнаете, как диагностировать и исправлять их шаг за шагом.

Это поможет сэкономить часы отладки и сделать деплой стабильным. Мы пройдёмся по реальным примерам из docker-compose.yml и командам для проверки. Давайте разберёмся, почему возникают эти ошибки и как их побеждать.

Конфликты портов и сетевые проблемы

Конфликты портов происходят, когда хост-машина уже использует нужный порт, а Docker пытается его занять. Например, если на порту 3000 крутится локальный сервер Node.js, команда docker-compose up выдаст ошибку вроде “Bind for 0.0.0.0:3000 failed: port is already allocated”. Это классика для разработчиков, тестирующих приложения.

Сетевые проблемы добавляют хаоса: контейнеры не видят друг друга, хотя всё запущено. Причина часто в неправильной настройке сетей или использовании external: true без создания сети заранее. Docker ожидает, что сеть существует, но её нет — и связь рвётся. Ещё ловушка: сервисы на разных сетях или с network_mode: bridge, где DNS не работает.

Вот как проверить и исправить:

• Проверьте занятые порты: lsof -i :3000 или ss -tlnp | grep 3000. Остановите процесс или смените порт в compose-файле: ports: - "3001:3000".
• Осмотрите сети: docker network ls и docker network inspect <network_name>. Убедитесь, что все сервисы в одной сети.
• Очистите всё: docker-compose down -v удалит volumes и сети, пересоздаст заново.

Проблема	Симптом	Быстрое решение
Порт занят	Bind failed	Сменить хост-порт или kill процесса
Нет связи	Connection refused	Убрать network_mode: bridge
External сеть	Network not found	docker network create <name>

Важно: Имена сервисов — это DNS-имена, используйте их вместо localhost.

Ошибки сборки Dockerfile в Compose

Сборка падает из-за синтаксиса в Dockerfile, отсутствующих зависимостей или проблем с контекстом. Команда docker-compose build может выдать “no build stage in current context” или зависнуть на слое. Часто виноваты кэш или .dockerignore, блокирующий файлы.

Пример: если в Dockerfile COPY копирует несуществующий файл, сборка рухнет. Или base-образ недоступен. Ещё ошибка с путями: mount path must be absolute в volumes. Docker требует абсолютные пути, относительные игнорирует.

Шаги по исправлению:

1. Пересоберите без кэша: docker-compose build --no-cache service_name.
2. Проверьте config: docker-compose config покажет parsed yaml, выявит пути и ошибки.
3. Осмотрите логи: docker-compose logs build для деталей.

Ошибка сборки	Причина	Решение
No build stage	Синтаксис Dockerfile	Проверить стадии
Missing deps	Нет пакетов	Добавить RUN apt install
Context issue	.dockerignore	Убрать лишнее из ignore

Кэш — частый убийца: Меняйте инструкции по одной, чтобы не потеряться.

Контейнеры выходят сразу после старта

Контейнер стартует и тут же exits с кодом 0 или 1. Причина: команда в образе завершилась (например, скрипт без цикла) или приложение крашится из-за env-переменных. Без healthcheck зависит_on не ждёт готовности БД.

Типичный случай: webapp пытается к db до её запуска. Или mounts denied из-за прав доступа. Ещё pool overlaps — сети конфликтуют по подсетям.

Диагностика и фикс:

• Логи: docker-compose logs service_name покажет, почему exit.
• Healthcheck: Добавьте в db: healthcheck: test: ["CMD-SHELL", "pg_isready"] interval: 5s.
• Зависимости: depends_on: db: condition: service_healthy.

Exit-код	Значение	Действие
0	Успех, но завершился	Добавить tail -f /dev/null
1	Ошибка app	Проверить env и логи
137	Out of memory	Увеличить limits

Нюанс: Используйте service_name, а не container_name для DNS.

Когда Compose не слушается: права и окружение

Ошибки вроде “Mounts denied” или “error storing credentials” — из-за прав на файлы или Docker config. На Linux selinux блокирует volumes, на Windows — пути с пробелами. Env не подставляются, если ${VAR} не определена.

Проверьте: docker compose run --rm service env покажет переменные внутри. Для credentials настройте helper.

Быстрые фиксы:

• Права volumes: chmod -R 755 volumes/ или chown.
• Abs пути: volumes: - /full/path:/app.
• Subnets: В networks укажите ipam с уникальной подсетью.

Сетап без сюрпризов в production

Большинство ошибок решает правильная диагностика: logs, config и network inspect. Остаётся копать редкие кейсы вроде runtime unknown или Podman-совместимости, но базовые 90% покрыты.

Думайте о multi-stage builds для скорости и healthchecks для надёжности. Тестируйте изменения по одному — так проще откатить. В production добавьте restart: unless-stopped для устойчивости.