Env-переменные n8n для production: что задавать явно ¶

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

ENV-переменные n8n управляют тем, как instance виден снаружи, где хранит данные, как шифрует credentials, как работает queue mode и что происходит с execution history.

Главные группы ENV ¶

ENV в n8n лучше воспринимать не как длинный список настроек, а как контракт окружения. В production значения должны быть явными, документированными и одинаковыми для процессов, которые вместе обслуживают один instance. Особенно это важно для WEBHOOK_URL, N8N_ENCRYPTION_KEY, переменных базы данных, Redis и pruning execution data.

Public URL и WEBHOOK_URL ¶

WEBHOOK_URL должен соответствовать внешнему HTTPS-домену, по которому сервисы реально доставляют события. Если n8n стоит за Nginx, Traefik, Cloudflare Tunnel или другим reverse proxy, внутренний порт контейнера не должен попадать во внешние webhook-ссылки. Ошибка в этой переменной приводит к странной ситуации: UI работает, manual execution запускается, но Telegram, CRM, формы или платежные webhook отправляют события не туда.

WEBHOOK_URL=https://automation.example.com/
N8N_HOST=automation.example.com
N8N_PROTOCOL=https
N8N_PORT=5678

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

Encryption key и credentials ¶

N8N_ENCRYPTION_KEY нельзя генерировать заново при каждом деплое. Он должен быть стабильным для instance и сохранён в безопасном хранилище. Если потерять ключ, база может восстановиться, но credentials останутся зашифрованными недоступным ключом. Это одна из самых дорогих ошибок при переносе n8n на новый сервер.

• создайте ключ один раз и храните его вне контейнера;
• не публикуйте .env в открытом репозитории;
• проверяйте, что backup включает способ восстановить ключ;
• при staging используйте отдельные credentials или dry-run режимы.

Postgres и Redis ¶

Для production обычно используют Postgres вместо SQLite. Переменные базы должны быть одинаково понятны в compose-файле, backup-процедуре и runbook. Если включён queue mode, main process и workers должны видеть один и тот же Redis и один и тот же набор критичных переменных. Несовпадение ENV между main и worker — частая причина ошибок, когда UI показывает одно, а фоновые executions работают иначе.

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

Pruning и хранение executions ¶

Execution history полезна для диагностики, но без ограничений она увеличивает базу и может заполнить диск. Настройте pruning с учётом юридических и операционных требований: сколько дней нужны executions, нужно ли хранить successful data, где лежат binary data и кто имеет право смотреть payload. Для workflow с персональными данными лучше хранить меньше, но логировать внешние идентификаторы и итоговый статус.

Проверка конфигурации ¶

1. Откройте UI через публичный домен и проверьте, что HTTPS корректен.
2. Создайте тестовый webhook и вызовите его снаружи, не из контейнера.
3. Перезапустите контейнер и убедитесь, что credentials сохранились.
4. Проверьте подключение к Postgres и, при queue mode, запуск worker execution.
5. Посмотрите логи после старта: предупреждения об URL, database, permissions и pruning лучше исправлять сразу.

Типичные ошибки ENV ¶

• использовать localhost в WEBHOOK_URL, когда n8n работает за публичным reverse proxy;
• не задавать N8N_ENCRYPTION_KEY и терять доступ к credentials после переноса;
• копировать переменные из примера без понимания, какие нужны именно вашему режиму запуска;
• задавать разные ENV для main и workers в queue mode;
• не включать pruning и потом искать, почему Postgres или диск переполнены.

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

ENV-конфигурация готова к production, если домен и webhook URL проверены снаружи, encryption key сохранён и участвует в backup-процедуре, база и Redis заданы явно, pruning описан, а все переменные доступны в runbook. Хороший .env не должен быть загадкой для следующего администратора.

• есть список обязательных переменных для текущего режима запуска;
• известно, какие значения являются секретами;
• main и workers получают одинаковые критичные ENV;
• изменения проходят diff-review и smoke-test;
• backup содержит способ восстановить конфигурацию и encryption key.

Практический минимум перед публикацией ¶

После изменения ENV перезапустите n8n и проверьте UI, webhook снаружи, credentials, один manual execution и, если включён queue mode, выполнение задачи worker-процессом. Если менялись DB_* переменные, дополнительно проверьте историю executions. Если менялся WEBHOOK_URL, проверьте внешний сервис, который должен доставлять событие, а не только локальный curl.

Smoke-test после изменения ¶

Production .env должен храниться как управляемый артефакт: не в памяти администратора и не только внутри панели хостинга. Хорошая практика — иметь приватный репозиторий, secrets manager или зашифрованный backup с историей изменений. При этом секретные значения нельзя раскрывать в публичной документации, issue tracker или скриншотах для поддержки.

Production-подход ¶

env_change:
  variable: WEBHOOK_URL
  old_value: https://old.example.com/
  new_value: https://automation.example.com/
  reason: production domain migration
  smoke_test: external webhook call + UI login + saved webhook URL check
  rollback: restore previous env and reload reverse proxy

Перед изменением .env создайте короткий diff-review. В нём должно быть видно, какая переменная меняется, зачем, кто согласовал изменение и какой smoke-test подтвердит результат. Особенно внимательно проверяйте переменные, которые меняют публичные URL, database connection, encryption key, execution mode и Redis. Эти значения влияют не на одну ноду, а на поведение всего instance.

Шаблон проверки .env перед deploy ¶

Что читать дальше ¶

Для связанной эксплуатации откройте backup n8n, reverse proxy checklist, Redis для queue mode и маршрут self-hosted администратора.