Переменные окружения в n8n: храним API-ключи безопасно через .env

Введение

Когда вы только начинаете работать в n8n, логично сохранять все пароли, API-ключи от OpenAI, Telegram-токенов или доступов к базе данных прямо внутри узлов (Credentials-менеджер n8n). Это удобно и быстро. Но как только ваш проект выходит в продакшн, или если вы работаете в команде, такой подход становится миной замедленного действия.

Представьте: вы решили выложить свой крутой сценарий (Workflow) в открытый доступ на GitLab или поделиться экспортом JSON с коллегой. Если вы забудете очистить Credentials или случайно оставите хардкод-ключ в узле HTTP Request, ваш платежный аккаунт OpenAI могут опустошить за пару часов.

В этой статье мы разберем лучший стандарт безопасности для self-hosted инсталляций n8n — переменные окружения (Environment Variables) и файл .env.

Что такое переменные окружения?

Переменная окружения — это значение, которое "внедряется" в программу из операционной системы (или от Docker-контейнера) в момент её запуска. Программа (в нашем случае n8n) знает название переменной, но само значение хранится глубоко на сервере и никогда не попадает в браузер или базу данных сценариев.

Создаем файл .env для Docker

Чаще всего n8n устанавливают через Docker Compose. В папке, где лежит ваш docker-compose.yml, нужно создать скрытый файл с названием .env. Именно в него мы будем складывать все наши секреты.

Пример структуры файла .env (откройте его через nano .env):

# Базовые настройки n8n
N8N_BASIC_AUTH_ACTIVE=true
N8N_BASIC_AUTH_USER=admin
N8N_BASIC_AUTH_PASSWORD=SuperSecretAdminPassword123

# Мои рабочие ключи
OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxxxxxxxxxx
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz
DATABASE_PASSWORD=production_db_pass_999

Проброс переменных в docker-compose.yml

Чтобы n8n "увидел" эти переменные, нужно указать их в файле docker-compose.yml в секции environment. Откройте файл и добавьте:

services:
  n8n:
    image: n8nio/n8n
    environment:
      - N8N_BASIC_AUTH_ACTIVE=${N8N_BASIC_AUTH_ACTIVE}
      - N8N_BASIC_AUTH_USER=${N8N_BASIC_AUTH_USER}
      - N8N_BASIC_AUTH_PASSWORD=${N8N_BASIC_AUTH_PASSWORD}
      # Пробрасываем наши ключи внутрь контейнера
      - MY_OPENAI_KEY=${OPENAI_API_KEY}
      - MY_TELEGRAM_TOKEN=${TELEGRAM_BOT_TOKEN}

После сохранения файлов выполните перезапуск контейнера: docker compose down && docker compose up -d.

Как использовать .env ключи внутри n8n?

Теперь самое интересное: как заставить сценарий использовать эти ключи?

Способ 1: Использование ноды Code (JavaScript/Python)

Если вы пишете сложную логику, в Code Node (на JavaScript) можно обратиться к системным переменным через встроенный объект $env.

// Забираем ключ из переменной среды
const openAiKey = $env.MY_OPENAI_KEY;

// Добавляем к данным, которые пойдут дальше
return {
  json: {
    key: openAiKey
  }
};

Внимание: По умолчанию функция $env отключена по соображениям безопасности. Чтобы разрешить её использование в узлах Code, вам нужно добавить в .env еще одну строчку: N8N_ENV_VARIABLES_IN_CODE_NODE=MY_OPENAI_KEY,MY_TELEGRAM_TOKEN (перечислить разрешенные переменные через запятую).

Способ 2: Expressions (Выражения) в полях

В любом текстовом поле n8n (например, в URL узла HTTP Request или в теле сообщения) вы можете нажать шестеренку, выбрать "Add Expression" и вставить: {{ $env["MY_OPENAI_KEY"] }}.

Способ 3: В настройках Credentials (Самый правильный)

Вместо того чтобы хардкодить токен везде через Expressions, зайдите в раздел Credentials в n8n, выберите создание новых доступов (например, Telegram API). В поле Token вместо самого длинного ключа впишите формулу {{ $env["MY_TELEGRAM_TOKEN"] }}. Сохраните. Теперь все Telegram-узлы будут использовать этот "динамический" доступ.

Почему это безопасно?

1. GitOps: Когда вы пушите папку с сервером в GitHub, вы добавляете файл .env в .gitignore. В репозиторий улетает только docker-compose.yml и сам сценарий JSON. Ни один секрет не утекает в сеть.
2. Экспорт JSON: Если вы делаете экспорт сценария n8n в файл workflow.json, чтобы скинуть клиенту, вместо реальных ключей в нем будут просто ссылки вида {{ $env["MY_OPENAI_KEY"] }}. Клиент загрузит сценарий к себе и пропишет свои ключи в своем .env.
3. Разделение Dev и Prod: Вы можете развернуть два сервера n8n (Тестовый и Боевой). Сценарии будут абсолютно одинаковые. Но на тестовом сервере переменная DATABASE_URL в файле .env будет смотреть на тестовую БД, а на боевом — на боевую. Не нужно переписывать узлы руками при переносе!

Заключение

Для простых хобби-проектов встроенного менеджера Credentials в n8n вполне достаточно. Но если вы разрабатываете интеграции на заказ или строите корпоративную ИИ-архитектуру, освойте работу с переменными окружения .env. Это "гигиена" разработки, которая спасает от бессонных ночей, взломанных аккаунтов и бесконечной перебивки ключей при переносе сценариев с сервера на сервер.