Как отлаживать контейнеры и чинить типичные ошибки
На этой странице
Отладку ведут по слоям: статус и код выхода (docker ps -a) → логи (docker logs) → конфигурация (docker inspect: команда, env, порты, mounts, сети, health) → внутри контейнера (docker exec, если он работает, или временный контейнер с утилитами в той же сети). Большинство проблем — это одна из типовых причин: неверная команда запуска, нехватка переменных, localhost вместо имени сервиса, сервер слушает 127.0.0.1, затёртые node_modules, права на файлы, OOM.
Вопрос
Как отлаживать контейнеры и какие типичные ошибки Docker нужно уметь чинить?
Алгоритм
docker compose ps # статус: Exited (1)? Restarting? unhealthy?
docker compose logs --tail 100 api # причина падения
docker inspect api # Cmd, Env, Mounts, NetworkSettings, State.Health
docker compose exec api sh # если контейнер работает
docker compose run --rm --entrypoint sh api # если падает: войти в такой же контейнер
docker compose config # что Compose реально применяетКоды выхода
| Код | Обычная причина |
|---|---|
0 | Процесс штатно завершился — например, команда не держит процесс на переднем плане |
1 | Ошибка приложения: смотри логи |
126 | Файл не исполняемый (нет прав на entrypoint-скрипт) |
127 | Команда не найдена (npm в distroless, опечатка в CMD) |
137 | SIGKILL: OOM (OOMKilled: true) или docker kill/таймаут stop |
139 | Segfault — часто native-модуль под другую libc или архитектуру |
143 | SIGTERM — штатная остановка |
Типичные проблемы
Контейнер сразу завершается. Нет dist/main.js (забыли build), не хватает переменной, неверный CMD, процесс уходит в фон. docker logs и docker run --rm -it --entrypoint sh image.
Порт недоступен с хоста.
- нет
-p/portsили перепутан порядокHOST:CONTAINER; - приложение слушает
127.0.0.1— нужно0.0.0.0; - порт хоста занят (
port is already allocated).
Backend не видит базу. localhost вместо db в DATABASE_URL; сервисы в разных сетях или проектах; база ещё не готова (нет healthcheck); неверный пароль после изменения POSTGRES_PASSWORD — он применяется только при первой инициализации volume.
docker compose exec api getent hosts db
docker run --rm --network shop_default nicolaka/netshoot nc -zv db 5432Переменные не применились. Значение есть в .env, но не передано через environment/env_file; после изменения сделали restart вместо up -d; frontend-переменная вшита при сборке.
docker compose exec api printenv | sortnode_modules пропали или «не тот бинарник». Bind mount .:/app перекрыл зависимости образа — добавить /app/node_modules как volume. Ошибка invalid ELF header или exec format error — в образ попали модули с хоста или собранные под другую архитектуру.
Permission denied. Процесс работает от node (UID 1000), а volume или bind mount принадлежит root или другому UID. Решения: COPY --chown=node:node, создать каталог и выдать права в Dockerfile до USER, согласовать UID с хостом.
Изменения кода не видны. Запущен старый образ — нужен up -d --build; file watcher не получает события на macOS/Windows — polling или compose watch.
Сборка падает на COPY. Файл исключён .dockerignore или лежит вне build context.
Закончилось место. docker system df, затем docker builder prune и docker image prune.
Отладка образов без shell
В distroless нет sh. Варианты: временно собрать debug-вариант (:debug-теги distroless), использовать docker debug (Docker Desktop) или контейнер-«соседа» в том же PID и network namespace:
docker run --rm -it --pid=container:api --network=container:api nicolaka/netshootЧастые ошибки
- Пересобирать вслепую, не прочитав логи.
- Пытаться
execв остановленный контейнер. - «Чинить» через
down -vи терять данные. - Исправлять что-то вручную внутри контейнера вместо Dockerfile.
- Не различать проблемы сборки и проблемы запуска.
Что важно помнить
- Код выхода и
OOMKilledсужают поиск ещё до чтения логов. POSTGRES_PASSWORDи init-скрипты работают только на пустом volume.- Всё, что исправлено руками в контейнере, исчезнет при пересоздании — фикс должен попасть в код.
Мини-шпаргалка
ps -a→logs→inspect→exec.- 127 — нет команды, 137 — OOM/kill, 139 — native-модуль.
0.0.0.0, имя сервиса, healthcheck.printenv,getent hosts,netshoot.up -d --buildпосле изменений.
Документация
Docker: Container CLI, Docker: docker debug, Docker Desktop: Troubleshoot.