re:re:actable
Урок 044 минуты чтения

Как отлаживать контейнеры и чинить типичные ошибки

На этой странице
Кратко

Отладку ведут по слоям: статус и код выхода (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)
137SIGKILL: OOM (OOMKilled: true) или docker kill/таймаут stop
139Segfault — часто native-модуль под другую libc или архитектуру
143SIGTERM — штатная остановка

Типичные проблемы

Контейнер сразу завершается. Нет 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 | sort

node_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.

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам