Диагностика queue mode в n8n: Redis, workers и webhooks ¶

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

Короткий ответ ¶

Если queue mode в n8n не выполняет jobs, проверьте не “сам workflow”, а связку main process → Redis → worker → database. Все процессы n8n в queue mode должны видеть одинаковые критичные переменные: EXECUTIONS_MODE=queue, параметры Redis, параметры базы, N8N_ENCRYPTION_KEY и совместимую версию n8n. Типовые причины зависаний — недоступный Redis, worker запущен без queue mode, main и worker подключены к разным базам, webhook processor не настроен или worker не может расшифровать credentials из-за другого encryption key.

Как устроить диагностику без хаоса ¶

В queue mode нельзя смотреть только на UI. UI показывает execution, но выполнение может происходить в отдельном worker-процессе. Поэтому диагностика должна идти по цепочке:

main n8n принимает запуск workflow;
Redis получает job;
worker забирает job;
worker читает workflow и credentials из базы;
результат записывается обратно;
UI показывает финальный статус.

Если сломан любой участок, execution может висеть, падать или вообще не стартовать.

Быстрая развилка по симптомам ¶

Симптом	Вероятная причина	Первая проверка
Worker `running`, но jobs не выполняются	worker не подключён к Redis или другой namespace	логи worker и Redis host
`Redis connection refused`	Redis недоступен, неверный host/port/TLS	`redis-cli ping` из той же сети
Executions висят в waiting/running	worker не забирает queue или падает при выполнении	`docker compose logs worker`
Webhook не принимает события	webhook processor не настроен или не видит Redis	env webhook-процесса
Credentials не расшифровываются	разный `N8N_ENCRYPTION_KEY`	сравнить env main/worker
Разные результаты на main и worker	разные версии образа или разные env	`docker compose config`

Шаг 1. Сравните env main и worker ¶

Самая частая ошибка — main container настроен правильно, а worker запущен с урезанным .env. В queue mode это критично: worker должен иметь доступ к той же базе, Redis и ключу шифрования.

Минимальный чек-лист:

EXECUTIONS_MODE=queue
QUEUE_BULL_REDIS_HOST=redis
QUEUE_BULL_REDIS_PORT=6379
DB_TYPE=postgresdb
DB_POSTGRESDB_HOST=postgres
DB_POSTGRESDB_DATABASE=n8n
DB_POSTGRESDB_USER=n8n
DB_POSTGRESDB_PASSWORD=...
N8N_ENCRYPTION_KEY=...

Проверьте не только файл .env, но и итоговую конфигурацию:

docker compose config > compose.rendered.yml
grep -n "EXECUTIONS_MODE\|QUEUE_BULL\|DB_POSTGRES\|N8N_ENCRYPTION_KEY" compose.rendered.yml

Если N8N_ENCRYPTION_KEY у worker отличается, workflow может стартовать, но credentials будут падать в момент выполнения.

Шаг 2. Проверьте Redis изнутри Docker-сети ¶

Не достаточно проверить, что Redis “открывается с сервера”. Важно, видит ли его контейнер worker. Если у вас отдельный контейнер Redis в compose, host обычно равен имени сервиса, например redis, а не localhost.

Проверка через временный контейнер:

docker compose exec redis redis-cli ping

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

PONG

Если Redis внешний, проверьте host, port, пароль, TLS и firewall. Если используется Redis Cluster, не смешивайте переменные обычного Redis и cluster-nodes: это разные режимы подключения.

Шаг 3. Убедитесь, что worker реально запущен как worker ¶

В Docker Compose worker должен запускать не обычный UI-процесс, а worker-команду. Если вы просто скопировали сервис n8n и назвали его worker, он может поднять второй main-процесс вместо обработчика очереди.

Проверьте команду и логи:

docker compose ps
docker compose logs --tail=150 worker

В логах worker должны быть признаки подключения к queue и ожидания jobs. Если worker падает при старте, не увеличивайте количество worker-реплик. Сначала исправьте одну реплику, затем масштабируйте.

Шаг 4. Webhook processor — отдельная зона риска ¶

В production с большим числом webhook-событий можно выносить обработку входящих webhook в отдельные процессы. Но webhook processors также зависят от Redis и queue mode. Если основной UI работает, а входящие события теряются или не создают execution, проверьте именно webhook-процесс.

Минимальная проверка:

webhook-процесс запущен;
у него есть EXECUTIONS_MODE=queue;
у него те же Redis env;
внешний reverse proxy отправляет /webhook/ туда, куда нужно;
production workflow активирован;
логи webhook-процесса видят входящий запрос.

Не стоит включать отдельный webhook processor на маленькой установке только “для production-ощущения”. Если трафика мало, начните с main + один worker, а масштабирование добавляйте после измерений.

Шаг 5. Очередь есть, но execution висит ¶

Если job попал в Redis, но не завершается, причина часто не в Redis. Worker может зависнуть на внешнем API, долгой AI-нody, недоступной базе, бесконечном loop, rate limit или workflow без корректной обработки ошибок.

Что проверить:

docker compose logs --tail=200 worker
# затем найти execution id в UI и сравнить время

На уровне workflow добавьте контрольные точки: Set node с stage, логирование execution_id, timeout для HTTP Request, явную ветку ошибок. Для интеграций с платежами и CRM не делайте бесконечный retry внутри workflow: лучше записать failed-событие и обработать его отдельно.

Шаг 6. Масштабирование workers без гонок ¶

Увеличение количества workers не всегда ускоряет систему. Если bottleneck в базе, Redis или внешнем API, дополнительные workers только усилят очереди и rate limit. Перед масштабированием снимите базовые метрики: число jobs в минуту, среднее время execution, ошибки API, CPU/RAM workers, нагрузку PostgreSQL и Redis.

Практичный порядок:

один main;
один Redis;
один PostgreSQL;
один worker;
smoke-test;
второй worker;
повторный smoke-test;
лимиты concurrency и rate limit для внешних API.

Если workflow работает с общими ресурсами, например одной Google Sheet или одним CRM-объектом, добавьте идемпотентность и защиту от гонок. Queue mode не отменяет необходимость думать о дубликатах.

Контрольный smoke-test после исправления ¶

Создайте тестовый workflow: Webhook → Set → Wait 3 seconds → Set result → Respond to Webhook. Запустите 5–10 запросов подряд и проверьте, что все executions завершились успешно, а worker-логи показывают обработку.

for i in $(seq 1 10); do
  curl -s -X POST 'https://n8n.example.ru/webhook/queue-smoke' \
    -H 'content-type: application/json' \
    -d "{\"i\":$i}" &
done
wait

После теста проверьте UI, логи worker, логи Redis и отсутствие зависших executions.

Что не делать ¶

Не запускайте несколько main-процессов вместо workers. Не используйте разные версии n8n для main и worker. Не храните разные .env без контроля. Не меняйте одновременно Redis, базу и количество workers. Не лечите зависшие executions рестартом всего стека без анализа логов: так можно потерять повторяемость проблемы.

FAQ ¶

Нужно ли включать queue mode на маленькой установке?
Не всегда. Если workflow мало и нет тяжёлых задач, обычный режим проще. Queue mode нужен, когда важно отделить UI от выполнения и масштабировать workers.

Почему worker idle, хотя execution есть в UI?
Возможно, worker подключён не к тому Redis, не к той базе или не запущен в queue mode. Сравните env main и worker.

Можно ли использовать localhost как Redis host?
В Docker это почти всегда ошибка. Для контейнера localhost — он сам, а не соседний Redis. Используйте имя сервиса или внешний host.

Почему credentials ломаются только на worker?
Проверьте N8N_ENCRYPTION_KEY. Если main и worker используют разные ключи, credentials могут быть видны в UI, но не расшифровываться при выполнении.

Что смотреть первым при зависших executions?
Логи worker, доступность Redis, итоговый compose config и конкретный execution id. Потом уже анализируйте сам workflow.