N8n environment variables

N8n Environment Variables: Полное руководство по настройке и управлению

Environment Variables (переменные окружения) в n8n являются фундаментальным механизмом для управления конфигурацией, обеспечения безопасности и поддержания переносимости рабочих процессов (workflows). Это ключевые пары «имя-значение», которые хранятся вне исходного кода приложения и динамически передаются в него операционной системой или контейнерной средой. В контексте n8n они используются для хранения чувствительных данных, таких как ключи API, пароли, токены доступа, а также для определения параметров самого приложения, включая URL базы данных, настройки шифрования, режимы работы и пути к файлам.

Типы переменных окружения в n8n

Переменные окружения в n8n можно условно разделить на две основные категории: системные (для конфигурации платформы) и пользовательские (для использования в рабочих процессах).

Системные переменные окружения n8n

Эти переменные управляют поведением и конфигурацией самого экземпляра n8n. Они предопределены платформой и их имена обычно начинаются с префикса N8N_.

Имя переменной	Назначение и описание	Пример значения
`N8N_ENCRYPTION_KEY`	Критически важная переменная. 256-битный ключ, используемый для шифрования учетных данных, токенов и других чувствительных данных в базе данных. Должен быть одинаковым на всех инстансах, работающих с одной БД, и никогда не меняться после начала использования.	`f5b5a2c8e7d6a9f1b5c8e7d6a9f1b5c8` (32 символа)
`N8N_DATABASE_TYPE`	Определяет тип используемой базы данных. Влияет на выбор драйвера и формат строки подключения.	`postgresdb`, `sqlite`, `mysqldb`, `mariadb`
`N8N_DATABASE_POSTGRESDB_DATABASE`	Имя базы данных PostgreSQL.	`n8n`
`N8N_DATABASE_POSTGRESDB_HOST`	Хост сервера PostgreSQL.	`localhost`, `postgres` (в Docker)
`N8N_DATABASE_POSTGRESDB_USER`	Пользователь для подключения к PostgreSQL.	`n8n_user`
`N8N_DATABASE_POSTGRESDB_PASSWORD`	Пароль пользователя PostgreSQL.	`secure_password_123`
`N8N_PROTOCOL`, `N8N_HOST`, `N8N_PORT`, `N8N_WEBHOOK_URL`	Определяют, как n8n доступен извне. Критичны для правильной работы вебхуков. `WEBHOOK_URL` часто переопределяется при работе за reverse proxy.	`https`, `n8n.mydomain.com`, `5678`, `https://n8n.mydomain.com/`
`N8N_EXECUTIONS_DATA_PRUNE`, `N8N_EXECUTIONS_DATA_MAX_AGE`	Включают и настраивают автоматическую очистку старых данных выполнений для экономии места в БД.	`true`, `336` (часов, 2 недели)
`N8N_USER_MANAGEMENT_JWT_SECRET`	Секрет для подписи JWT-токенов при включенном управлении пользователями.	`your_jwt_secret_key_here`
`N8N_EMAIL_MODE`, `N8N_SMTP_HOST`, `N8N_SMTP_USER`, `N8N_SMTP_PASS`	Настройки SMTP для отправки email (сброс пароля, приглашения).	`smtp`, `smtp.gmail.com`, `user@gmail.com`, `app_password`
`N8N_SECURE_COOKIE`	Включает флаг Secure для cookies. Обязательно для HTTPS.	`true`
`GENERIC_TIMEZONE`	Часовой пояс по умолчанию для планировщика (schedule node).	`Europe/Moscow`

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

Это переменные, которые вы определяете самостоятельно для использования внутри рабочих процессов. Они не управляют платформой, а служат контейнерами для ваших собственных значений. Доступ к ним осуществляется через специальный узел «Code» или выражение в полях других узлов.

Способы установки переменных окружения

1. Файл `.env`

Наиболее распространенный и рекомендуемый способ для локальных и Docker-развертываний. N8n автоматически загружает переменные из файла .env, расположенного в корневой директории проекта. Формат файла — ключ=значение, по одной переменной на строку. Комментарии начинаются с

.

Пример содержимого файла .env:

N8N_ENCRYPTION_KEY=your_super_secret_encryption_key_32_chars
N8N_DATABASE_TYPE=postgresdb
N8N_DATABASE_POSTGRESDB_HOST=localhost
N8N_DATABASE_POSTGRESDB_PORT=5432
N8N_DATABASE_POSTGRESDB_DATABASE=n8n
N8N_DATABASE_POSTGRESDB_USER=n8n
N8N_DATABASE_POSTGRESDB_PASSWORD=db_password
N8N_HOST=0.0.0.0
N8N_PORT=5678
N8N_PROTOCOL=https
N8N_WEBHOOK_URL=https://n8n.yourdomain.com
Пользовательские переменные
MY_API_ENDPOINT=https://api.example.com/v1
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/XXX/YYY/ZZZ
DATABASE_CONNECTION_STRING=postgresql://user:pass@prod-host:5432/prod_db

2. Передача напрямую в командной строке или Docker

В Linux/macOS можно задать переменные непосредственно перед запуском команды:

N8N_ENCRYPTION_KEY=key N8N_PORT=8080 n8n start

В Docker через флаг -e или в файле docker-compose.yml:

version: '3.8'
services:
  n8n:
    image: n8nio/n8n
    environment:
      - N8N_ENCRYPTION_KEY=${N8N_ENCRYPTION_KEY}
      - N8N_HOST=0.0.0.0
      - N8N_PORT=5678
      - N8N_WEBHOOK_URL=https://n8n.example.com
    volumes:
      - ./.env:/usr/src/app/.env

3. Использование секретов в облачных средах

В облачных платформах (AWS, GCP, Azure, Heroku, Kubernetes) используются встроенные менеджеры секретов (Secrets Manager, Kubernetes Secrets, ConfigMaps). Переменные задаются через интерфейс панели управления или CLI и автоматически внедряются в среду выполнения контейнера.

Использование переменных окружения в рабочих процессах

Доступ к пользовательским переменным окружения внутри workflow осуществляется с помощью выражений (expressions). Синтаксис зависит от контекста.

В узле «Code» (Function/Function Item)

Используйте глобальный объект $env.

const apiKey = $env.MY_API_KEY;
const endpoint = $env.API_ENDPOINT;
return { apiKey, endpoint };

В полях других узлов (выражения)

Используйте выражение {{ $env.VARIABLE_NAME }}.

В поле «URL» HTTP Request узла: {{ $env.API_BASE_URL }}/users
В поле «Password» узла аутентификации: {{ $env.DB_PASSWORD }}
В заголовках (Headers) HTTP Request: Authorization: Bearer {{ $env.JWT_TOKEN }}

Безопасность и лучшие практики

Никогда не храните секреты в коде workflow. Всегда выносите их в переменные окружения.
Используйте отдельный .env файл для каждого окружения (development, staging, production). Никогда не используйте production-ключи в разработке.
Файл .env должен быть внесён в .gitignore и никогда не попадать в систему контроля версий. Для шаблона создайте файл .env.example с именами переменных, но без реальных значений.
Ключ шифрования (N8N_ENCRYPTION_KEY) — это корневой секрет. Сгенерируйте его надежно (например, openssl rand -hex 16 для 32 символов). Его потеря или изменение сделает все зашифрованные данные в БД нечитаемыми.
Регулярно ротируйте (меняйте) секреты API, но помните, что изменение N8N_ENCRYPTION_KEY требует специальной процедуры.
При использовании Docker Secrets или облачных менеджеров секретов монтируйте их как файлы, а не передавайте как переменные окружения в командной строке, чтобы избежать их отображения в списке процессов.
Ограничивайте права доступа к файлам .env и директориям с конфигурацией (chmod 600).

Отладка проблем с переменными окружения

Проверка загруженных переменных: В настройках n8n (Settings > Variables) отображаются только пользовательские переменные, определенные через интерфейс. Системные переменные можно проверить в логах при запуске n8n (первые строки) или через отладку в узле Code: Object.keys($env).sort().
Переменная не найдена: Убедитесь, что файл .env находится в правильной директории (рядом с package.json или в корне Docker-контейнера). Проверьте синтаксис файла (нет ли пробелов вокруг =, корректны ли имена).
Ошибка шифрования: «Encryption key is missing or invalid» — проверьте, что N8N_ENCRYPTION_KEY установлен, имеет длину 32 символа и одинаков на всех инстансах, подключенных к одной БД.
Вебхуки не работают: Проверьте переменные N8N_PROTOCOL, N8N_HOST, N8N_WEBHOOK_URL. За reverse proxy часто требуется явно задать N8N_WEBHOOK_URL с публичным доменным именем.

Часто задаваемые вопросы (FAQ)

Как сгенерировать надежный N8N_ENCRYPTION_KEY?

Используйте криптографически безопасный генератор. В терминале Linux/macOS: openssl rand -hex 16 (выдаст 32 символа). В PowerShell: [System.Convert]::ToHexString((1..16 | % {[byte](Get-Random -Max 256)})). Можно также использовать онлайн-генераторы, которым вы доверяете, но предпочтительнее локальная генерация.

Можно ли менять N8N_ENCRYPTION_KEY после начала работы?

Да, но это нетривиальная операция. Старый ключ нужен для расшифровки всех существующих данных (учетных данных, токенов) в БД, а новый — для шифрования новых. N8n не предоставляет встроенного механизма для этой операции. Рекомендуемый путь — экспортировать все workflows и учетные данные, создать новый экземпляр n8n с новым ключом и импортировать их заново, заново вводя секреты. Поэтому крайне важно установить правильный ключ с самого начала.

Чем отличаются «Variables» в интерфейсе n8n от Environment Variables?

Это две разные сущности. Environment Variables — низкоуровневые переменные операционной системы/контейнера, используемые для конфигурации приложения и доступные через $env. Variables (или «User Settings») в интерфейсе n8n — это встроенная функция n8n для хранения ключ-значение, управляемая через веб-интерфейс (Settings > Variables). Они хранятся в базе данных n8n, шифруются и доступны через выражение {{ $vars.VARIABLE_NAME }}. Environment Variables более фундаментальны и используются для настройки самой платформы.

Как использовать переменные окружения в Docker Compose, не раскрывая их в файле?

Используйте внешний файл .env (который в .gitignore) и передавайте его имена переменных в docker-compose.yml с помощью синтаксиса ${VARIABLE_NAME}. Docker Compose автоматически подставит значения из файла .env, расположенного в той же директории. Также можно использовать отдельные файлы секретов Docker (secrets: в compose).

Почему мой workflow на production пытается использовать dev API ключи?

Наиболее вероятная причина — в production-окружении не переопределены переменные окружения, и используются значения по умолчанию или из dev-файла .env. Убедитесь, что ваш production-сервер (Docker-контейнер, облачная среда) имеет правильно заданные переменные окружения для production, такие как API_BASE_URL, API_KEY и другие. Всегда явно задавайте все необходимые переменные для каждого окружения.

Как защитить переменные окружения при использовании публичных репозиториев для хранения workflows?

Экспортируйте workflows без учетных данных (флаг «Export without credentials» при экспорте). Все секреты должны оставаться только в переменных окружениях на сервере развертывания. В самом workflow будут только ссылки на эти переменные через {{ $env.XXX }}, которые без реальных значений бесполезны. Таким образом, файл workflow можно безопасно хранить в публичном репозитории.