Healthcheck и автоперезапуск n8n: Docker, workers, Redis, Postgres и алерты

Обновлено: 2026-05-29

Healthcheck в n8n нужен не для красивой зелёной галочки. Он должен отвечать на практический вопрос: может ли инстанс принять событие, выполнить workflow и записать результат? Простая проверка “порт 5678 открыт” полезна, но недостаточна: UI может открываться, а workers не брать jobs, Redis быть недоступным, PostgreSQL отвечать медленно, а webhooks возвращать 504.

Хорошая схема наблюдения состоит из трёх уровней: process health, dependency readiness и бизнесовый smoke-test. Первый показывает, что контейнер жив. Второй — что есть связь с Redis/Postgres. Третий — что реальный workflow проходит от webhook до ответа.

Что именно проверять

Проверка	Что ловит	Чего не ловит
HTTP health endpoint	процесс n8n отвечает	ошибки конкретного workflow
Docker healthcheck	зависший контейнер	логическую ошибку интеграции
worker readiness	worker видит Redis и DB	rate limit внешнего API
synthetic webhook	полный путь через n8n	редкие payload-ошибки
error workflow alert	failed executions	полное падение инстанса

Docker Compose healthcheck для main

services:
  n8n:
    image: n8nio/n8n:latest
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "wget -qO- http://localhost:5678/healthz || exit 1"]
      interval: 30s
      timeout: 5s
      retries: 5
      start_period: 60s

Если в вашем окружении /healthz занят платформой или прокси, задайте отдельный путь через N8N_ENDPOINT_HEALTH. Не делайте healthcheck слишком агрессивным: во время обновления, миграции базы или холодного старта n8n может подниматься дольше обычного.

Healthcheck для workers в queue mode

Для workers включите health endpoints отдельно. Иначе контейнер может быть запущен, но не готов обрабатывать jobs.

services:
  n8n-worker:
    image: n8nio/n8n:latest
    command: worker --concurrency=5
    environment:
      - EXECUTIONS_MODE=queue
      - QUEUE_HEALTH_CHECK_ACTIVE=true
      - QUEUE_HEALTH_CHECK_PORT=5678
    healthcheck:
      test: ["CMD-SHELL", "wget -qO- http://localhost:5678/healthz/readiness || exit 1"]
      interval: 30s
      timeout: 5s
      retries: 5
      start_period: 60s

Readiness полезнее обычного “контейнер жив”, потому что worker должен видеть Redis и базу. Если readiness падает, перезапуск worker может помочь, но сначала смотрите логи Redis/Postgres.

Systemd и автозапуск Docker Compose

Если n8n живёт на VPS, удобно контролировать весь stack через systemd:

[Unit]
Description=n8n docker compose stack
Requires=docker.service
After=docker.service network-online.target

[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/opt/n8n
ExecStart=/usr/bin/docker compose up -d
ExecStop=/usr/bin/docker compose down
TimeoutStartSec=0

[Install]
WantedBy=multi-user.target

Это не заменяет restart policy внутри compose, но помогает stack подниматься после перезагрузки сервера. Для managed VPS проверьте, что Docker действительно стартует при boot.

Бизнесовый smoke-test webhook

Самая полезная проверка — маленький workflow, который принимает тестовый webhook, пишет запись в лог/таблицу и возвращает ожидаемый JSON.

curl -fsS -X POST "https://n8n.example.ru/webhook/health-smoke" \
  -H "Content-Type: application/json" \
  -d '{"source":"monitor","check":"health","ts":"2026-05-29T10:00:00+03:00"}'

Ожидаемый ответ:

{"ok":true,"service":"n8n","check":"health"}

Этот тест ловит больше проблем, чем проверка UI: домен, HTTPS, reverse proxy, Webhook node, Respond to Webhook, workflow activation и базовую обработку.

Что отправлять в алерт

Плохой alert говорит “n8n упал”. Хороший alert помогает действовать:

какой endpoint упал;
HTTP status и время ответа;
main или worker;
последние 20 строк логов;
свободная память и диск;
ссылка на runbook.

Для команды поддержки лучше отправлять краткое сообщение в Telegram/Mattermost, а подробности — в лог-систему.

Когда перезапуск вреден

Автоперезапуск не должен скрывать ошибку. Если контейнер перезапускается 20 раз в час, это не “самовосстановление”, а инцидент. Частые причины:

неверный N8N_ENCRYPTION_KEY или env;
PostgreSQL недоступен при старте;
порт занят другим контейнером;
OOM из-за большого workflow;
миграция после обновления не завершилась.

Добавьте rate limit на уведомления, но не глушите сам факт restart loop.

Минимальный набор для self-hosted n8n

Docker restart policy для main, worker, Redis и Postgres.
HTTP healthcheck main.
Readiness healthcheck workers.
Внешний uptime monitor по публичному URL.
Synthetic webhook каждые 1–5 минут.
Error workflow для failed executions.
Алерт на диск, память, restart count и Redis/Postgres.

Такой набор не делает систему идеальной, но резко сокращает время от “что-то не работает” до понятной причины.

Операционный runbook для self-hosted ¶

Для темы «Healthcheck и автоперезапуск n8n» важно разделять настройку и эксплуатацию. Настройка отвечает на вопрос “запустилось ли”, эксплуатация — “сможем ли мы восстановиться, обновиться и расследовать инцидент без потери credentials и execution history”.

Перед изменениями проверьте бэкап базы, значение N8N_ENCRYPTION_KEY, состояние volume, логи web-процесса и worker-процесса. Главный риск — сделать неидемпотентную запись, поймать lock/timeout или незаметно нарушить схему данных.

Слой	Что зафиксировать	Зачем
Вход	запись из базы или SQL-операция с уникальным ключом, timestamp и результатом транзакции	позволяет повторить проблему без доступа к production-секретам
Контроль	query_duration, conflict_count, transaction_failures, row_count_delta, lock_wait	показывает деградацию раньше, чем пользователи начинают писать в поддержку
Безопасность	сделать неидемпотентную запись, поймать lock/timeout или незаметно нарушить схему данных	снижает риск скрытых дублей, утечки данных и неконтролируемых write-действий
Готовность	есть тест на happy path, пустой вход, повтор и сбой внешнего сервиса для «Healthcheck и автоперезапуск n8n»	делает статью пригодной для runbook, а не только для чтения

Пример безопасного входного контракта ¶

docker compose ps
docker compose logs --tail=200 n8n
docker compose logs --tail=200 n8n-worker
printenv | grep -E 'N8N_|WEBHOOK_|DB_|QUEUE_'
# перед изменениями: backup базы + проверка N8N_ENCRYPTION_KEY

Критерий готовности ¶

есть свежий backup базы и проверено значение N8N_ENCRYPTION_KEY
web, worker, queue и database используют согласованные переменные окружения
после изменения проверены логи, healthcheck и запуск критичных workflow
записан rollback-план с командами и ответственным

Связанные материалы

Ответы на частые вопросы

Достаточно ли проверять порт 5678?

Нет. Открытый порт показывает, что процесс отвечает, но не гарантирует, что workers, Redis, PostgreSQL и реальные webhooks работают.

Какой healthcheck нужен для worker?

В queue mode включите QUEUE_HEALTH_CHECK_ACTIVE и проверяйте readiness endpoint, чтобы убедиться, что worker видит Redis и базу.

Что лучше: healthcheck или Error Trigger?

Оба нужны. Healthcheck ловит недоступность сервиса, а Error Trigger ловит failed executions внутри работающего n8n.