Как отлаживать Docker контейнеры на Debian 13

Введение

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

Итоговая цель: к концу этого руководства вы сможете выявлять и устранять типичные проблемы Docker контейнеров с помощью логов, инспекции и инструментов анализа во время выполнения.

Предварительные требования

• Целевая аудитория: начинающие системные администраторы
• Оценочное время: ~30 минут
• Операционная система: Debian 13
• Программное обеспечение: Docker 24.0 или новее
• Права доступа: пользователь с правами sudo или участник группы docker
• Аппаратные требования: минимум 2 ГБ ОЗУ и 10 ГБ свободного дискового пространства
• Сетевые требования: доступ в интернет для загрузки образов, специальные порты для этого руководства не требуются
• Требования: базовые навыки работы с командной строкой и запущенный сервис Docker
• Совместимость: протестировано на Debian 13 и работает на Debian 12 и Ubuntu 22.04

Шаг 1: Проверка информации о системе Docker

Перед отладкой конкретного контейнера убедитесь, что сам Docker работает корректно.
Выполните следующую команду:

docker system info

Вы увидите подробную информацию о среде Docker, включая:

• Версию сервера
• Драйвер хранения
• Количество контейнеров и образов
• Доступность CPU и памяти
• Корневую директорию Docker

Это помогает убедиться, что:

• Docker работает корректно
• В системе достаточно ресурсов
• Отсутствуют глобальные проблемы конфигурации

Чтобы проверить статус сервиса Docker:

systemctl status docker

Вы увидите, активен ли сервис Docker. Если он не запущен, запустите его:

sudo systemctl start docker

Теперь сервис должен отображаться в активном состоянии.

Шаг 2: Проверка состояния контейнера

Выполните следующую команду:

docker ps

Вы увидите список запущенных контейнеров с такими деталями, как ID контейнера, образ и статус. Если контейнер имеет статус "Up", он в данный момент работает.

Чтобы отобразить остановленные контейнеры:

docker ps -a

Теперь вы увидите все контейнеры. Если контейнер имеет статус "Exited", это означает, что он остановился из-за ошибки или завершил выполнение.

Шаг 3: Просмотр логов контейнера

Логи показывают вывод приложения внутри контейнера. Это самый важный шаг для отладки. Вы можете получить <CONTAINER_ID> с помощью команды docker ps, описанной в шаге 2.

Выполните:

docker logs <CONTAINER_ID>

Вы увидите вывод приложения, включая ошибки и предупреждения. Обратите внимание на сообщения, указывающие на сбои, например отсутствие файлов или ошибки подключения.

Чтобы отслеживать логи в реальном времени:

docker logs -f <CONTAINER_ID>

Вы увидите новые записи логов по мере их появления. Это полезно при перезапуске контейнера и наблюдении за его поведением.

Чтобы посмотреть только последние логи:

docker logs --tail 50 <CONTAINER_ID>

Вы увидите последние 50 строк вывода. Это помогает сосредоточиться на самых последних событиях.

Шаг 4: Инспекция состояния контейнера

Docker хранит подробную информацию о каждом контейнере.

Выполните:

docker inspect <CONTAINER_ID>

Вы увидите структурированный вывод в формате JSON с конфигурацией и деталями выполнения.

Чтобы проверить статус контейнера:

docker inspect -f '{{.State.Status}}' <CONTAINER_ID>

Вы увидите простое значение, например "running" или "exited", которое подтверждает состояние контейнера.

Чтобы проверить код завершения:

docker inspect -f '{{.State.ExitCode}}' <CONTAINER_ID>

Вы увидите число. Значение 0 означает успешное выполнение, любое ненулевое значение указывает на ошибку.

Чтобы проверить политику перезапуска:

docker inspect -f '{{.HostConfig.RestartPolicy.Name}}' <CONTAINER_ID>

Вы увидите, настроен ли контейнер на автоматический перезапуск.

Распространенные коды завершения, которые вы можете увидеть:

• 0 – процесс завершился успешно без ошибок. Обычно это означает, что контейнер остановился нормально. Например, скрипт завершил свою задачу и вышел.
• 1 – произошла общая ошибка. Это наиболее распространенный код сбоя и обычно означает, что внутри приложения произошла ошибка, например отсутствующий файл, неверная конфигурация или ошибка выполнения.
• 125 – Docker не смог запустить контейнер. Обычно это указывает на проблему с самой командой docker run, например неверные параметры.
• 126 – команда внутри контейнера не может быть выполнена. Часто это означает проблемы с правами доступа или то, что файл не является исполняемым.
• 127 – команда не найдена. Обычно это означает, что указанный бинарный файл или скрипт отсутствует внутри контейнера.
• 137 – контейнер был принудительно остановлен. Часто это происходит, когда системе не хватает памяти и она завершает процесс контейнера.
• 139 – контейнер завершился с ошибкой сегментации. Это указывает на серьезную ошибку приложения, часто связанную с доступом к памяти.
• 143 – контейнер был корректно остановлен. Обычно это происходит при выполнении docker stop.

Шаг 5: Доступ к среде контейнера

Иногда логов недостаточно. Вы можете войти в контейнер для прямой диагностики.

Выполните:

docker exec -it <CONTAINER_ID> /bin/bash

Вы попадете в интерактивную оболочку внутри контейнера.

Если bash недоступен:

docker exec -it <CONTAINER_ID> /bin/sh

Теперь вы можете исследовать контейнер.

Проверка процессов контейнера с хоста:

docker top <CONTAINER_ID>

Вы увидите активные процессы внутри контейнера. Если основной процесс отсутствует, контейнер может остановиться.

Шаг 6: Мониторинг использования ресурсов

Контейнеры могут завершаться из-за ограниченных ресурсов.

Выполните:

docker stats

Вы увидите использование CPU, памяти и сети в реальном времени для всех контейнеров.

Чтобы отслеживать конкретный контейнер:

docker stats <CONTAINER_ID>

Вы увидите таблицу, которая обновляется в реальном времени с данными об использовании ресурсов для всех запущенных контейнеров. Каждая строка представляет контейнер, а каждый столбец показывает определенный тип использования ресурсов.
Наиболее важные столбцы:

• CPU % – показывает, сколько CPU использует контейнер. Высокие значения могут указывать на интенсивные вычисления или неэффективный код.
• MEM USAGE / LIMIT – показывает, сколько памяти использует контейнер по сравнению с его лимитом. Если использование близко к лимиту, контейнер может замедлиться или быть остановлен.
• MEM % – процент использования памяти относительно лимита.
• NET I/O – сетевой трафик. Показывает, сколько данных контейнер получил и отправил.
• BLOCK I/O – операции чтения и записи на диск. Показывает, сколько данных контейнер прочитал и записал.
• PIDs – количество процессов внутри контейнера. Очень большое значение может указывать на утечку процессов или неконтролируемое поведение приложения.

Шаг 7: Проверка событий Docker

Docker записывает события, которые описывают происходящее на уровне системы и контейнеров. Эти события помогают понять, когда контейнер запускается, останавливается, аварийно завершается или перезапускается.
Выполните следующую команду:

docker events

Вы увидите поток событий, таких как запуск, остановка и перезапуск контейнера. Вывод обновляется в реальном времени.

Фильтрация событий для конкретного контейнера

Выполните:

docker events --filter container=<CONTAINER_ID>

Вы увидите только события, относящиеся к выбранному контейнеру. Это помогает сосредоточиться на одной нагрузке.

Просмотр событий за определенный период времени

Чтобы посмотреть события за определенный момент времени:

docker events --since 10m

Вы увидите события за последние 10 минут.

Чтобы задать начальное и конечное время:

docker events --since 2026-01-01T10:00:00 --until 2026-01-01T11:00:00

Вы увидите события, произошедшие в указанном диапазоне.

Форматирование вывода событий

Выполните:

docker events --format '{{.Time}} {{.Type}} {{.Action}} {{.Actor.ID}}'

Вы увидите форматированный вывод с выбранными полями. Это упрощает чтение или интеграцию со скриптами.

Фильтрация по типам событий

Вы можете фильтровать события, чтобы сосредоточиться на конкретных проблемах.

Остановка или сбой контейнера

Выполните:

docker events --filter event=die

Вы увидите события остановки контейнеров. Это помогает выявить неожиданные завершения.

События нехватки памяти

Выполните:

docker events --filter event=oom

Вы увидите события, когда контейнер был завершен из-за ограничений памяти. Это критично для диагностики проблем с ресурсами.

Перезапуски контейнера

Выполните:

docker events --filter event=restart

Вы увидите события перезапуска. Частые перезапуски могут указывать на цикл сбоев.

Комбинирование фильтров и времени

Выполните:

docker events --since 10m --filter event=die

Вы увидите события остановки за последние 10 минут. Это помогает сосредоточиться на недавних сбоях.

Шаг 8: Проверка использования диска и очистка неиспользуемых образов

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

Выполните следующую команду:

docker system df

Вы увидите сводку использования диска, включая:

• Образы
• Контейнеры
• Локальные тома
• Кэш сборки

Каждый раздел показывает:

• Общее количество
• Активные элементы
• Размер
• Освобождаемое пространство

Это помогает понять, сколько дискового пространства использует Docker и сколько можно освободить.

Чтобы посмотреть неиспользуемые образы:

docker images -f dangling=true

Вы увидите образы без тегов, которые не используются ни одним контейнером. Их можно безопасно удалить.

Чтобы удалить неиспользуемые образы:

docker image prune

Появится запрос на подтверждение. После подтверждения образы будут удалены.

Чтобы удалить все неиспользуемые образы:

docker image prune -a

Вы удалите все образы, не используемые ни одним контейнером.

Проверка и тестирование

• Выполните docker ps и убедитесь, что статус контейнера корректный.
• Выполните docker logs и убедитесь, что ошибки обнаружены или устранены.
• Выполните docker inspect и убедитесь, что статус и код завершения соответствуют ожиданиям.
• Используйте docker exec, чтобы убедиться, что процессы внутри контейнера работают.
• Если отладка выполнена успешно, контейнер должен оставаться в состоянии running без критических ошибок в логах.

Откат изменений

Если вы внесли изменения во время отладки, вы можете вернуть систему в чистое состояние.

Остановить контейнер:

docker stop <CONTAINER_ID>

Вы увидите подтверждение остановки контейнера.

Удалить контейнер:

docker rm <CONTAINER_ID>

Вы увидите подтверждение удаления контейнера.

Создать контейнер заново:

docker run <OPTIONS> <IMAGE_NAME>

Будет создан новый контейнер из образа.

Устранение неполадок

Контейнер сразу завершается

Проверьте docker logs на наличие сообщений об ошибках. Обычно они объясняют проблему.

Невозможно получить доступ к контейнеру

Убедитесь, что он запущен с помощью docker ps.

Логи отсутствуют

Убедитесь, что приложение выводит данные в stdout или stderr.

Контейнер постоянно перезапускается

Проверьте политику перезапуска и логи, чтобы выявить цикл сбоев.

Высокое использование ресурсов

Используйте docker stats, чтобы подтвердить скачки CPU или памяти.

Заключение

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