N8n env

N8n env: Полное руководство по управлению переменными окружения

N8n env, или переменные окружения в платформе автоматизации n8n, являются фундаментальным механизмом для управления конфигурацией, обеспечения безопасности и поддержания переносимости рабочих процессов (workflows). Это ключевые пары «имя-значение», которые хранятся вне исходного кода рабочего процесса и динамически подставляются во время его выполнения. Их основное назначение — отделение конфиденциальных данных (таких как ключи API, пароли, строки подключения к базам данных) и параметров, зависящих от среды выполнения (development, staging, production), от логики самого рабочего процесса.

Архитектура и типы переменных окружения в n8n

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

Переменные окружения уровня системы

Это переменные, определяемые на уровне операционной системы или в контейнере Docker, где запущен экземпляр n8n. Они имеют наивысший приоритет для конфигурации самого n8n и используются для настройки его глобального поведения. Устанавливаются через файл .env в корневой директории n8n или непосредственно в среде выполнения (например, в переменных окружения Docker или сервера).

• N8N_ENCRYPTION_KEY: Обязательный ключ для шифрования учетных данных. Должен быть длиной 24 символа.
• N8N_USER_FOLDER: Путь к папке для хранения пользовательских данных (например, загруженных файлов).
• N8N_PROTOCOL, N8N_HOST, N8N_PORT: Параметры для настройки веб-интерфейса.
• EXECUTIONS_DATA_PRUNE: Включение автоматической очистки старых данных выполнений.

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

Это основной инструмент для работы внутри рабочих процессов. Они определяются непосредственно в интерфейсе n8n и доступны для использования в нодах (узлах). Эти переменные делятся на два вида, управляемых через раздел «Settings» -> «Variables» в левом боковом меню.

Тип	Где задается	Область видимости	Использование в нодах	Пример
Общие (General) переменные	Интерфейс n8n (Settings -> Variables)	Глобально, во всех рабочих процессах	{{ $vars.VARIABLE_NAME }}	{{ $vars.API_BASE_URL }}
Переменные для конкретного рабочего процесса (Workflow-specific)	Настройки конкретного рабочего процесса (кнопка «Variables» вверху редактора)	Только внутри того рабочего процесса, где они определены	{{ $vars.VARIABLE_NAME }} (приоритет над общими)	{{ $vars.INTERNAL_WEBHOOK_SECRET }}

Синтаксис и использование в рабочих процессах

Для подстановки значений переменных в поля нод используется выражение (expression). Нужно активировать режим выражения, нажав на иконку

• Базовая подстановка: {{ $vars.MY_API_KEY }}
• Использование в строке: https://{{ $vars.DOMAIN }}/api/v1/user
• Использование в условиях: В ноде «IF» можно сравнить: {{ $item.json.status }} === {{ $vars.SUCCESS_STATUS_CODE }}
• Использование в заголовках HTTP-запросов: В ноде «HTTP Request» в Headers указать: Authorization: Bearer {{ $vars.ACCESS_TOKEN }}

Практические шаги по настройке и управлению

1. Настройка системных переменных (.env файл)

Создайте или отредактируйте файл .env в директории установки n8n. Пример содержимого:

• N8N_ENCRYPTION_KEY=my-super-secret-encryption-key
• N8N_PROTOCOL=https
• N8N_HOST=my.n8n.server.com
• EXECUTIONS_DATA_PRUNE=true
• EXECUTIONS_DATA_MAX_AGE=168

После изменения файла .env требуется перезагрузка n8n.

2. Создание общих переменных в интерфейсе

• Перейдите в «Settings» (шестеренка) -> «Variables».
• Нажмите «Add Variable».
• Введите Key (имя) и Value (значение). Имя принято писать в верхнем регистре с подчеркиваниями.
• Нажмите «Save».

3. Создание переменных уровня рабочего процесса

• Откройте нужный рабочий процесс.
• Нажмите кнопку «Variables» в верхней части редактора.
• Добавьте необходимые пары ключ-значение.
• Эти переменные будут доступны только в этом рабочем процессе и переопределят общие переменные с такими же именами.

Безопасность и шифрование

N8n применяет многоуровневый подход к безопасности переменных.

• Шифрование системным ключом: Все пользовательские переменные, заданные в интерфейсе, а также учетные данные нод шифруются с использованием ключа N8N_ENCRYPTION_KEY перед сохранением в базе данных.
• Маскирование в интерфейсе: Значения переменных отображаются в интерфейсе как точки (•••••) для предотвращения случайного раскрытия. Для просмотра значения необходимо явно нажать на иконку глаза.
• Отсутствие в логах выполнения: Значения, подставленные через выражение {{ $vars.XXX }}, в данных выполнения (execution data) отображаются как [REDACTED]. Это предотвращает утечку секретов в логах.
• Рекомендация: Никогда не используйте «жестко» прописанные секреты в полях нод. Всегда выносите их в переменные.

Использование в n8n Cloud и самохостируемых версиях

Подход к управлению переменными отличается в облачной и локальной версиях.

Аспект	n8n Cloud	Самохостируемый n8n
Системные переменные	Управляются через панель «Project Settings» -> «Environment variables». Пользователь не имеет доступа к файлу .env.	Управляются через файл .env или переменные окружения ОС/контейнера.
Пользовательские переменные	Аналогично самохостируемой версии: через Settings -> Variables.	Аналогично облачной версии.
Безопасность	Полностью управляется платформой n8n. Шифрование включено по умолчанию.	Безопасность зависит от пользователя: необходимо правильно настроить N8N_ENCRYPTION_KEY и защитить доступ к серверу и файлу .env.

Интеграция с внешними системами хранения секретов

Для профессионального использования в корпоративной среде n8n позволяет интегрироваться с внешними хранилищами секретов, такими как HashiCorp Vault, AWS Secrets Manager или Azure Key Vault. Это достигается через:

• Специальные ноды: Использование ноды «HTTP Request» или «Code» для запроса секрета из API внешнего хранилища перед выполнением основной логики.
• Кастомные хуки: В самохостируемой версии можно написать кастомный хук, который будет загружать переменные из внешнего источника при старте n8n.
• Инициализация через .env: В файл .env можно поместить только ключ доступа к внешнему хранилищу, а основные конфигурационные данные подгружать из него при запуске.

Ответы на часто задаваемые вопросы (FAQ)

В чем разница между переменными окружения и параметрами (parameters) рабочего процесса?

Переменные окружения ($vars) — это статические (или редко меняющиеся) значения, используемые для конфигурации и хранения секретов. Параметры рабочего процесса (Workflow Parameters) — это динамические входные данные, которые можно передать вручную при запуске рабочего процесса (вручную или через API). Параметры идеальны для сценариев, где значение нужно задавать каждый раз новое (например, имя отчета или дата).

Как организовать разные конфигурации для dev, staging и prod?

Рекомендуется использовать комбинацию подходов:

• Заведите отдельные экземпляры n8n для каждой среды.
• В каждом экземпляре настройте свои общие переменные с одинаковыми именами, но разными значениями (например, DATABASE_URL будет указывать на dev, staging или prod базу).
• Рабочие процессы, экспортированные из одной среды, при импорте в другую будут использовать переменные из целевой среды, что обеспечивает переносимость.

Можно ли использовать переменные в именах нод или для создания динамических путей в «IF» ноде?

Нет, выражение {{ $vars.XXX }} работает только внутри полей ввода данных нод (как строковые или числовые значения). Его нельзя использовать для именования нод, указания типа триггера или в структурных элементах рабочего процесса.

Что произойдет, если переменная с заданным именем не найдена?

Если выражение {{ $vars.NONEXISTENT }} не может быть разрешено (переменная не существует), нода завершит выполнение с ошибкой. В данных выполнения будет указано, что переменная не найдена. Важно обеспечивать наличие всех используемых переменных или реализовывать логику обработки ошибок через ноду «IF» или «Code».

Как массово обновить переменные или перенести их на другой сервер?

Общие переменные можно экспортировать и импортировать. В разделе «Settings» -> «Variables» есть кнопки «Import» и «Export». Данные экспортируются в формате JSON. Это удобно для резервного копирования конфигурации или переноса между средами. Переменные уровня рабочего процесса экспортируются и импортируются вместе с самим рабочим процессом (файлом .json).

Есть ли ограничения на количество или длину переменных?

Строгих ограничений, встроенных в n8n, нет. Однако стоит руководствоваться здравым смыслом и ограничениями вашей базы данных. Для хранения очень больших конфигураций (например, больших JSON-объектов) лучше использовать внешнее хранилище, а в переменной держать только ссылку или ключ доступа к нему.

Как обеспечить ротацию секретов (например, истекший API-ключ)?

Процесс ротации включает несколько шагов:

• Создайте новое значение секрета во внешней системе.
• В интерфейсе n8n обновите значение соответствующей переменной на новое.
• Все новые выполнения рабочих процессов автоматически начнут использовать новое значение.
• Старое значение можно отключить во внешней системе после подтверждения работы нового ключа.
• Для сложных сценариев можно создать временную переменную-флаг и использовать ноду «IF» для плавного переключения между старым и новым ключом.