Отладка: логи, exec, healthcheck, размер образа
Отладка: логи, exec, healthcheck, размер образа
Когда контейнер не работает, алгоритм простой: логи → внутрь → проверка сети/переменных.
Логи и exec
docker compose logs -f backend
docker compose exec backend sh
env | sort
exec подключается к уже работающему контейнеру: видишь его переменные, файлы и процессы именно в том состоянии, в котором он сломался. docker compose run backend sh создаёт новый контейнер из того же образа и конфигурации сервиса - удобно для разовых задач (миграции, тесты), но состояние проблемного контейнера там не увидишь. После run добавляй --rm, иначе остановленные контейнеры копятся.
Healthcheck: HTTP / TCP / exec
# HTTP - для веб-сервисов с /health endpoint
healthcheck:
test: ["CMD", "wget", "-qO-", "http://localhost:8080/health"]
interval: 10s
timeout: 3s
retries: 5
start_period: 30s # grace-период на старт (миграции, прогрев кэша)
# wget есть в alpine (busybox), а в distroless/scratch его нет - там проверку
# встраивают в сам бинарник: test: ["CMD", "/backend", "healthcheck"]
Что значат параметры и их значения по умолчанию (если параметр не указан):
interval- пауза между проверками, по умолчанию 30s;timeout- сколько ждать ответа одной проверки, после этого она считается проваленной, по умолчанию 30s;retries- сколько провалов подряд нужно, чтобы контейнер сталunhealthy, по умолчанию 3;start_period- время на старт, в течение которого провалы не засчитываются, по умолчанию 0s.
Пока проверки ещё не прошли, статус starting, после успеха - healthy, после retries провалов подряд - unhealthy. Подробный вывод последних проверок (Output, ExitCode) показывает docker inspect - см. раздел ниже.
# TCP - для БД/брокеров, где нет HTTP-эндпоинта
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres -d app || exit 1"]
interval: 5s
timeout: 5s
retries: 10
# exec - кастомный скрипт, если сервис экзотический
healthcheck:
test: ["CMD", "/app/healthcheck.sh"]
Тип Когда выбирать Подводный камень
──── ────────────────────────────────── ─────────────────────────────────
HTTP обычный REST/gRPC-сервис /health должен быть «лёгким» -
не дёргать БД на каждый probe
TCP БД, очереди, кеши «порт открыт» ≠ «сервис готов»;
пиши проверку через клиент сервиса
exec нестандартные сервисы скрипт должен работать в образе
(нет `bash` в scratch/distroless!)
⚠️
healthyне значит «готов обслуживать трафик»Docker сообщает ровно одно: команда проверки завершилась с кодом 0. Что именно она проверила - целиком на нашей совести, и здесь легко получить зелёный статус у неработающего сервиса.
Классический пример:
GET /health, который отвечает200 OKстрокой{"status":"ok"}, не касаясь базы. Контейнерhealthy, а каждый реальный запрос падает с ошибкой подключения к PostgreSQL.Полезно с самого начала различать три разных вопроса:
Вопрос Что проверяем Что делать при «нет» liveness - процесс жив? отвечает ли приложение вообще перезапустить контейнер readiness - может обслуживать запрос? есть ли соединение с базой, прогрет ли кеш, применены ли миграции убрать из балансировки, но не перезапускать dependency health - доступны ли зависимости? база, брокер, чужой API обычно алерт, а не рестарт Разница между первыми двумя практическая: перезапуск сервиса, который не готов из-за недоступной базы, ничего не исправит, но добавит downtime - и при
restart: alwaysдаст цикл рестартов.Restart-политика (
restart:у сервиса) говорит Docker, когда поднимать упавший контейнер:no(по умолчанию) - никогда;on-failure- только если процесс завершился с ненулевым кодом;always- всегда;unless-stopped- всегда, кроме случая, когда ты остановил контейнер руками (подробно - в уроке про деплой). На статусunhealthyни одна политика не реагирует: срабатывает только падение процесса.У Docker Compose один
healthcheckи один статус, поэтому обычно в него кладут readiness (её и ждётcondition: service_healthyу зависимых сервисов). В Kubernetes эти проверки разделены явно -livenessProbe,readinessProbeиstartupProbe, - и знание, чем они отличаются, пригодится там дословно.
⚠️
start_periodважнее, чем кажетсяБез
start_periodконтейнер с долгим стартом (миграции, прогрев кэшей, загрузка моделей) станетunhealthyещё до конца старта - и зависимые сервисы сcondition: service_healthyне поднимутся. Сами Docker и compose поunhealthyне перезапускают: это делают Swarm или внешний autoheal. KubernetesHEALTHCHECKиз образа игнорирует - там работают только его собственныеlivenessProbe/readinessProbe. Поставьstart_periodчуть больше, чем худший старт.
# Зависимый сервис стартует только когда БД зелёная
services:
backend:
depends_on:
db:
condition: service_healthy
Ограничения docker logs и log rotation
docker compose logs -f --tail=100 backend # последние 100 строк + хвост
Стандартный драйвер json-file пишет stdout/stderr контейнера в файл /var/lib/docker/containers/<id>/<id>-json.log. Без настройки этот файл растёт бесконечно - на проде типичный аварийный сценарий: за месяц диск забит логами одного болтливого сервиса.
services:
backend:
logging:
driver: "json-file"
options:
max-size: "10m" # ротация по 10MB
max-file: "5" # хранить максимум 5 файлов
Альтернативы - journald (системный journal), syslog, fluentd, gelf (Graylog). На проде логи обычно отправляют в централизованный сборщик, а локальный драйвер - только аварийный буфер.
⚠️ Логи в stdout, а не в файл
12-factor app: процесс пишет логи в stdout, контейнерный runtime сам решает, куда их направить. Внутрь контейнера писать в
/var/log/app.log- антипаттерн: файл пропадёт при пересоздании контейнера.
Размер образа
docker images | head
docker history <image>
ℹ️ Главная причина огромных образов
Ты копируешь в runtime весь проект с
.venv,__pycache__, кешами и тестами. Multi-stage и .dockerignore спасают.
.dockerignore
.git
.venv
dist
*.md
.env
.vscode
__pycache__
Без .dockerignore Docker копирует всё - включая .git (может быть сотни МБ). Как контекст сборки связан с кэшем слоёв и почему порядок инструкций важнее любых микрооптимизаций - в уроке про Dockerfile по шагам.
Уменьшение размера образа
# Проверь размер
docker images | grep backend
# Сравни:
# golang:1.22 → ~800MB
# golang:1.22-alpine → ~250MB
# scratch → 0MB (только бинарник)
# distroless/static → ~2MB (минимум для Go без CGO)
Рецепт для Go:
FROM golang:1.22-alpine AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -o /backend ./cmd/server
FROM gcr.io/distroless/static-debian12
COPY --from=builder /backend /backend
CMD ["/backend"]
scratch vs distroless vs alpine - что выбрать
База Размер Что внутри Когда выбирать
───────── ───── ──────────────────────── ────────────────────────────────
scratch 0 ничего (даже /tmp нет) статический бинарь Go без CGO,
shell в проде точно не понадобится
distroless/ ~2MB CA-certs, tzdata, Go-сервисы без CGO, которым нужны
static без libc HTTPS (CA-сертификаты) и timezone
distroless/ ~20MB + glibc CGO-бинарь, но без shell
base
alpine ~5MB musl libc + sh + apk нужен shell для скрипта-обёртки,
база base curl/wget для дебага, CGO=1
debian-slim ~80MB debian минимум CGO с зависимостями glibc;
совместимость > размер
⚠️ alpine ≠ glibc
Alpine использует musl libc, а не glibc. Бинарь с
CGO_ENABLED=1, собранный против glibc, в alpine просто не запустится (not foundна /lib/ld-linux). ЛибоCGO_ENABLED=0, либо собирай в alpine-image-е.
Debugging без shell (scratch / distroless)
В distroless и scratch нет sh, поэтому привычное docker exec backend sh упадёт. Что делать:
# Вариант 1: ephemeral debug container
docker run -it --rm \
--pid=container:my-backend \
--net=container:my-backend \
alpine sh
# Теперь у тебя alpine-shell в namespaces (PID, network) backend-контейнера.
# Видны его процессы, доступна его сеть.
# Вариант 2 (Kubernetes): kubectl debug
kubectl debug -it pod/backend --image=busybox --target=backend
# Вариант 3: «отладочный» tag образа со shell на тот же бинарь
FROM gcr.io/distroless/static-debian12:debug
# или
FROM busybox AS debug-runtime
distroless/static:debug включает busybox-shell - образ можно поднять для дебага, прод-образ оставить чистым.
docker stats и docker inspect для прода
docker stats --no-stream
# CONTAINER ID NAME CPU % MEM USAGE / LIMIT NET I/O BLOCK I/O
# a1b2c3d4 backend 12.3% 120MiB / 512MiB 5MB / 2MB 1MB / 0B
Быстрый ответ на «кто жрёт ресурсы?». На проде это полезно при разовых инцидентах - для постоянного мониторинга всё равно нужны Prometheus + cadvisor.
docker inspect backend | jq '.[0].State'
# {
# "Status": "running",
# "Running": true,
# "ExitCode": 0,
# "Health": { "Status": "healthy", "FailingStreak": 0, "Log": [...] }
# }
docker inspect backend --format '{{range .NetworkSettings.Networks}}{{.IPAddress}} {{end}}'
docker inspect backend --format '{{json .Config.Env}}' # без хитростей светит секреты
Полезные точки в inspect: State.Health (история health-проб), Mounts (что и куда смонтировано), NetworkSettings.Networks (в каких сетях контейнер), HostConfig.RestartPolicy.
Чек-лист отладки контейнера
docker compose logs -f service- что пишет сервис?docker compose exec service sh- зайти внутрь, проверить env, файлыdocker compose ps- статус и порты всех сервисовdocker inspect container_id- полная информация (сеть, volumes, env)docker stats- CPU/RAM в реальном времени
Мини-задание
- Добавь
.dockerignore(.venv, pycache, dist, .git, .env) - Собери образ, проверь размер через
docker images - Добавь healthcheck в Dockerfile или compose
- Зайди в работающий контейнер через
execи проверь переменные (env | sort)
Итог
- Логи - первое, на что смотришь.
exec- второе.inspect- когда совсем непонятно. .dockerignoreи multi-stage build - два главных способа уменьшить образ.- Healthcheck - не декорация: compose ждёт его в
depends_on, а Swarm использует для перезапуска (в Kubernetes для этого своиlivenessProbe).
Типичная ошибка
Не добавлять .dockerignore и удивляться, почему образ весит 2GB. Или использовать golang:latest как runtime-образ вместо distroless или scratch.
Мини-практика (10 минут)
Возьми любой свой Dockerfile. Собери образ, запомни размер (docker images). Добавь .dockerignore. Пересобери - сравни размер. Если образ не multi-stage - сделай multi-stage (builder + runtime). Сравни ещё раз. Цель - увидеть разницу своими глазами.