Решение проблем деплоя

На этой странице описаны типичные проблемы при деплое, их причины и способы решения. Если что-то пошло не так, начните отсюда, прежде чем эскалировать.

Полезные команды

Держите эти команды под рукой при отладке проблем деплоя:

# Проверить общий статус задачи
nomad job status <job-name>

# Список аллокаций задачи
nomad job status <job-name> | grep -A 20 "Allocations"

# Просмотр stdout-логов аллокации
nomad alloc logs <alloc-id>

# Просмотр stderr-логов аллокации
nomad alloc logs -stderr <alloc-id>

# Стриминг логов в реальном времени
nomad alloc logs -f <alloc-id>

# Просмотр деталей аллокации (использование ресурсов, события, перезапуски)
nomad alloc status <alloc-id>

# Инспекция спецификации запущенной задачи
nomad job inspect <job-name>

# Принудительная сборка мусора (очистка мёртвых аллокаций)
nomad system gc

---

Ошибки сборки

CI-пайплайн падает на этапе build.

Симптомы

• Пайплайн останавливается на этапе сборки с красным статусом.
• Сообщения об ошибках в логе задачи сборки.

Частые причины и решения

Ошибка Dockerfile

ERROR: failed to solve: process "/bin/sh -c ..." did not complete successfully

TIP

Внимательно прочитайте полный лог сборки. Фактическая ошибка обычно находится на несколько строк выше финального сообщения "failed". Частые виновники: отсутствующие зависимости, опечатки в командах RUN, некорректные теги базового образа.

Ошибка аутентификации в реестре

ERROR: error pushing image: denied: access forbidden

CI-раннер не может аутентифицироваться в реестре контейнеров.

• Убедитесь, что CI_REGISTRY_USER и CI_REGISTRY_PASSWORD (или CI_JOB_TOKEN) корректно установлены в CI-окружении.
• Проверьте, что URL реестра в конфигурации CI совпадает с фактическим реестром.
• Убедитесь, что токен деплоя проекта не истёк.

Нехватка места на диске раннера

ERROR: no space left on device

• Попросите администратора очистить Docker-кеш раннера: docker system prune -af
• Проверьте, не накапливаются ли старые образы на раннере.

---

Ошибки деплоя

CI-пайплайн падает на этапе deploy.

Симптомы

• Сборка проходит успешно, но задача деплоя падает.
• Ошибки SSH или Nomad в логе задачи деплоя.

Частые причины и решения

SSH-соединение отклонено или истекло по таймауту

ssh: connect to host <kvm-host> port 22: Connection refused

WARNING

Если SSH не работает, проверьте следующее:

• Доступен ли KVM-хост из сети CI-раннера?
• Правильно ли настроен SSH-ключ в переменных CI/CD?
• Не упал ли или не был ли перезапущен SSH-сервис на хосте?

Ошибки в файле задачи Nomad

Error submitting job: Unexpected response code: 400

В спецификации задачи Nomad синтаксическая или конфигурационная ошибка.

• Запустите nomad job validate <job-file> локально для проверки ошибок.
• Убедитесь, что все подстановки переменных в шаблоне задачи разрешились корректно.
• Проверьте файл переменных для целевого окружения на отсутствующие или некорректные значения.

Файл задачи Nomad -- отсутствующие переменные

Error: variable "image_tag" not set

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

• Проверьте файл переменных (например, vars/dev.hcl, vars/stage.hcl, vars/prod.hcl).
• Убедитесь, что он содержит все переменные, на которые ссылается шаблон задачи.

---

Сервис нездоров

Деплой прошёл успешно (Nomad принял задачу), но сервис не работает корректно.

Симптомы

• Nomad показывает аллокацию как unhealthy или pending.
• Проверки здоровья (health checks) не проходят.
• Приложение недоступно по своему URL.

Диагностика

# Проверка событий аллокации на предмет сбоев health check
nomad alloc status <alloc-id>

# Ищите в разделе "Recent Events" сообщения вроде:
#   "Health check status: unhealthy"
#   "Killed due to failed health check"

Частые причины и решения

Приложение не запускается

Проверьте логи контейнера на ошибки запуска:

nomad alloc logs <alloc-id>
nomad alloc logs -stderr <alloc-id>

TIP

Обратите внимание на типичные проблемы запуска:

• Отсутствующие переменные окружения
• Ошибки подключения к базе данных
• Конфликты привязки портов
• Файл конфигурации не найден

Эндпоинт health не отвечает

Health check Nomad обращается к эндпоинту, который не существует или возвращает статус, отличный от 200.

• Убедитесь, что путь health check в файле задачи Nomad совпадает с фактическим health-эндпоинтом приложения.
• Подтвердите, что приложение слушает на ожидаемом порту.
• Протестируйте health-эндпоинт вручную внутри контейнера:

# Выполнить команду внутри контейнера (если поддерживается)
nomad alloc exec <alloc-id> curl -s localhost:<port>/health

Таймаут health check слишком короткий

Приложению требуется больше времени на запуск, чем позволяет health check.

• Увеличьте check_restart.grace в файле задачи Nomad.
• По возможности оптимизируйте время запуска приложения.

---

Ошибки 502 / 503

Домен доступен, но браузер показывает ошибку 502 Bad Gateway или 503 Service Unavailable от Traefik.

Симптомы

• URL разрешается, но возвращает ошибку 502 или 503.
• Traefik работает, но не может достучаться до бэкенд-сервиса.

Частые причины и решения

Traefik не может маршрутизировать к сервису

Traefik обнаруживает сервисы через каталог сервисов Nomad. Если сервис зарегистрирован некорректно, Traefik некуда маршрутизировать трафик.

# Проверить, зарегистрирован ли сервис в Nomad
nomad job status <job-name>

# Ищите раздел "Service" -- проверьте:
#   - Имя сервиса совпадает с конфигурацией роутера Traefik
#   - Метка порта совпадает с открытым портом
#   - Теги содержат правильные лейблы Traefik

WARNING

Частая ошибка -- несовпадение между меткой port в задаче Nomad и портом, который ожидает Traefik. Перепроверьте обе стороны.

Несовпадение портов

Приложение слушает на порту, отличном от того, что открывает Nomad.

• Проверьте логи запуска приложения на фактический порт прослушивания.
• Сравните с определением port в файле задачи Nomad.
• Убедитесь, что тег сервиса Traefik ссылается на правильную метку порта.

Сервис падает (см. следующий раздел)

Если сервис постоянно перезапускается, Traefik может периодически терять бэкенд. Сначала устраните проблему перезапусков.

---

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

Контейнер запускается, работает недолго, затем падает и перезапускается в цикле.

Симптомы

• nomad alloc status показывает множество событий перезапуска.
• Аллокация циклично переходит между running и pending.
• Счётчик перезапусков продолжает расти.

Диагностика

# Проверить счётчик перезапусков и события
nomad alloc status <alloc-id>

# Ищите в разделе "Recent Events":
#   "OOM Killed" -- нехватка памяти
#   "Exit Code: 1" -- падение приложения
#   "Exit Code: 137" -- убит (обычно OOM)

# Прочитать последние логи перед падением
nomad alloc logs <alloc-id>
nomad alloc logs -stderr <alloc-id>

Частые причины и решения

Нехватка памяти (OOM)

Recent Events:
  OOM Killed

Контейнер превышает лимит памяти.

DANGER

Не увеличивайте лимит памяти вслепую. Сначала разберитесь, почему приложение использует больше памяти, чем ожидалось. Проверьте на утечки памяти, неограниченные кеши или слишком большие данные.

Если лимит действительно слишком низкий:

# В файле задачи Nomad увеличьте выделение памяти
resources {
  memory = 512  # было 256, увеличьте при обоснованной необходимости
}

Падение приложения при запуске

Exit Code: 1

Приложение падает сразу при запуске. Проверьте логи на причину:

nomad alloc logs -stderr <alloc-id>

Частые причины:

• Отсутствующая или некорректная переменная окружения
• Невозможно подключиться к требуемому сервису (база данных, кеш и т.д.)
• Синтаксическая ошибка в файле конфигурации
• Отсутствующая зависимость или бинарный файл

Слишком жёсткие лимиты ресурсов

Троттлинг CPU может вызывать таймауты health check, что приводит к перезапускам.

# В файле задачи Nomad
resources {
  cpu    = 500   # МГц -- увеличьте, если приложению нужно больше
  memory = 512   # МБ
}

---

Краткий справочник: ошибки и их причины

Ошибка	Вероятная причина	Первый шаг
Сборка падает с ошибкой Docker	Проблема в Dockerfile	Прочитайте полный лог сборки
denied: access forbidden	Аутентификация реестра	Проверьте CI-токены
ssh: Connection refused	KVM-хост недоступен	Проверьте хост / SSH-ключ
Unexpected response code: 400	Ошибка в файле задачи Nomad	nomad job validate
Сервис unhealthy	Приложение не запускается	nomad alloc logs
502 Bad Gateway	Проблема маршрутизации Traefik	Проверьте регистрацию сервиса
503 Service Unavailable	Нет здорового бэкенда	Проверьте health-эндпоинт
Контейнер OOM Killed	Превышен лимит памяти	Проверьте лимиты ресурсов
Exit Code: 1	Падение приложения	Проверьте stderr-логи
Exit Code: 137	Убит (OOM или сигнал)	Проверьте использование памяти

---

Не удалось решить?

Если вы исчерпали все вышеперечисленные шаги:

1. Соберите все релевантные логи (nomad alloc logs, вывод CI-пайплайна).
2. Зафиксируйте точное сообщение об ошибке и когда она началась.
3. Проверьте, не деплоил ли кто-то ещё недавно (возможен конфликт изменений).
4. Обратитесь в канал команды по деплою с подробностями.

TIP

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