Environment variables n8n: production-настройка self-hosted ¶
Обновлено: 2026-05-30
ENV variables в n8n — это не просто .env-файл для запуска контейнера. Это контракт production-окружения: какой публичный адрес видят webhooks, где лежит база, как шифруются credentials, кто выполняет jobs и сколько истории хранит инстанс.
Принципы production ENV ¶
Хорошая конфигурация n8n задаёт критичные параметры явно и одинаково для всех компонентов, которые участвуют в выполнении workflows. Main process, workers и webhook-процессы не должны спорить о базе, Redis, encryption key, timezone и публичном URL. Если часть переменных “по умолчанию”, администратор не понимает, что именно будет восстановлено после аварии.
ENV не должен быть свалкой секретов в репозитории. Безопасная практика: шаблон `.env.example` хранится в version control, реальные значения находятся в secret manager или защищённом хранилище, а runbook объясняет, где их получить и кто имеет доступ.
Обязательные группы переменных ¶
| Группа | Что задаёт | Что проверить |
|---|---|---|
| Public URL | N8N_HOST, N8N_PROTOCOL, WEBHOOK_URL | внешний webhook приходит на правильный домен |
| Security | N8N_ENCRYPTION_KEY, basic/auth или SSO-настройки | credentials открываются после рестарта |
| Database | DB_TYPE, DB_POSTGRESDB_HOST, DB_POSTGRESDB_DATABASE, user, password | n8n пишет executions в ожидаемый Postgres |
| Queue | EXECUTIONS_MODE, QUEUE_BULL_REDIS_* | main и workers видят один Redis |
| Retention | EXECUTIONS_DATA_PRUNE, MAX_AGE, SAVE_* flags | история не заполняет диск и базу |
Public URL и WEBHOOK_URL ¶
Для SEO и production-эксплуатации важно не путать внутренний адрес контейнера и внешний адрес, по которому сервисы вызывают webhook. WEBHOOK_URL должен указывать на публичный HTTPS-домен за reverse proxy. Если он отличается от реального домена, внешние сервисы могут сохранить неправильный callback URL, а в UI будут отображаться некорректные ссылки.
После изменения public URL проверьте не только UI, но и реальный внешний запрос: отправьте тестовое событие из сервиса, который будет использовать workflow. Локальный curl внутри сервера не доказывает, что DNS, proxy, TLS и firewall работают для внешнего мира.
Database ENV и Redis ENV ¶
Для Postgres задавайте тип базы, хост, порт, database name, пользователя и пароль явно. Не смешивайте миграцию базы с включением queue mode. Сначала добейтесь стабильной записи executions в Postgres, затем подключайте Redis и workers. Для queue mode проверьте, что main и worker используют одинаковые DB_* и QUEUE_BULL_REDIS_* значения; иначе execution может попасть в очередь, которую никто не обрабатывает.
# пример структуры, не копируйте значения без адаптации
N8N_PROTOCOL=https
N8N_HOST=automation.example.com
WEBHOOK_URL=https://automation.example.com/
N8N_ENCRYPTION_KEY=stored-in-secret-manager
DB_TYPE=postgresdb
DB_POSTGRESDB_HOST=postgres
DB_POSTGRESDB_DATABASE=n8n
EXECUTIONS_MODE=queue
QUEUE_BULL_REDIS_HOST=redis
EXECUTIONS_DATA_PRUNE=trueEncryption key и секреты ¶
N8N_ENCRYPTION_KEY должен быть создан один раз для production-инстанса и сохранён так же внимательно, как backup базы. При потере ключа зашифрованные credentials в базе нельзя нормально использовать после восстановления. Не генерируйте новый key при каждом деплое, не храните его в README, примерах JSON или истории shell-команд.
Preflight checklist ENV ¶
- Все обязательные переменные заданы в одном источнике правды, а не разбросаны между compose, shell и панелью хостинга.
- Main, webhook и worker контейнеры получают одинаковые DB, Redis, timezone и encryption key.
- WEBHOOK_URL проверен внешним запросом через HTTPS.
- Секреты не попали в репозиторий, build logs, search index или LLM markdown.
- После изменения ENV выполнен smoke-test: UI, credential test, manual execution, webhook, schedule и queue worker.
Типичные ошибки ENV n8n ¶
- использовать localhost для базы или Redis внутри Docker Compose, хотя контейнеры видят друг друга по service name;
- поменять encryption key при переносе и решить, что сломался Postgres;
- включить queue mode только на main process, но забыть worker;
- оставить WEBHOOK_URL от staging на production-домене;
- публиковать реальные secrets в обучающих статьях, issue, чатах и скриншотах.
ENV-конфигурация должна изменяться так же аккуратно, как код. Минимальный процесс: diff старого и нового значения без раскрытия секретов, pre-flight проверка, restart, smoke-test webhook и запись результата. Если после изменения выросли 401, 500 или connection refused, откат выполняется на прежний набор переменных, а не на память администратора.
Change control для ENV ¶
Отдельно проверьте переменные, которые нельзя менять без миграционного окна: N8N_ENCRYPTION_KEY, параметры базы, WEBHOOK_URL, queue mode и настройки binary data. Для каждой такой переменной должен быть владелец и причина изменения. Если изменение связано с секретом, сразу планируйте ротацию зависимых credentials.
Перед любым изменением переменных окружения сделайте короткий audit: где хранится текущий .env, кто имеет доступ, какой файл реально подключён контейнером и какие переменные переопределяются на уровне платформы. Частая ошибка — править один файл, а production использует другой источник значений. В runbook укажите команду проверки активной конфигурации и способ безопасного отката.
Audit ENV перед изменением ¶
Критерий готовности ¶
ENV-конфигурация готова к production, если она воспроизводима, документирована, проверена внешним webhook, не раскрывает secrets и позволяет восстановить n8n вместе с credentials. Следующий администратор должен понять источник каждой переменной без устных пояснений автора установки.
Что читать дальше ¶
Для короткой практической версии откройте ENV-переменные n8n. Для прокси и домена проверьте n8n за Nginx. Если вы включаете queue mode, переходите к Redis для n8n и масштабированию workers.