N8n config

Конфигурация N8N: Полное руководство по настройке и управлению

N8n (pronounced «n-eight-n») — это инструмент автоматизации рабочих процессов с открытым исходным кодом, который использует визуальный редактор на основе узлов (nodes). Конфигурация системы является критически важным этапом для обеспечения стабильности, безопасности и масштабируемости развертывания. Данная статья детально рассматривает все аспекты конфигурации N8n, от базовых настроек до продвинутых сценариев.

Базовые принципы конфигурации N8n

N8n настраивается преимущественно через переменные окружения (environment variables). Это соответствует принципам 12-факторных приложений и позволяет гибко управлять настройками в разных средах (разработка, тестирование, продакшн). Основной файл конфигурации отсутствует; вместо этого все параметры задаются при запуске контейнера, в файле .env или через командную строку. Существует три основных способа развертывания: с использованием Docker (рекомендуемый), npm-пакетов или прямого запуска исходного кода.

Ключевые переменные окружения для конфигурации

Переменные окружения в N8n имеют префикс N8N_. Ниже представлена таблица наиболее важных из них, сгруппированных по категориям.

Категория: Базовые настройки и безопасность

Переменная	Описание	Значение по умолчанию	Пример
N8N_PROTOCOL	Протокол для веб-интерфейса (http/https).	http	https
N8N_HOST	Хост, на котором работает N8n.	localhost	automation.yourcompany.com
N8N_PORT	Порт для веб-интерфейса.	5678	443
N8N_ENCRYPTION_KEY	Критически важная переменная. 32-символьный ключ для шифрования учетных данных. Должен быть одинаковым при всех перезапусках.	Генерируется случайно при первом запуске.	my-super-secret-encryption-key-32
N8N_SECURITY_EXCLUDE_ENDPOINTS	Список эндпоинтов, исключенных из проверки аутентификации (через запятую).	healthz, webhook	healthz, webhook, status

Категория: Аутентификация и пользователи

Переменная	Описание	Значение по умолчанию	Пример
N8N_BASIC_AUTH_ACTIVE	Включает базовую HTTP-аутентификацию для всего интерфейса.	false	true
N8N_BASIC_AUTH_USER	Имя пользователя для базовой аутентификации.	—	admin
N8N_BASIC_AUTH_PASSWORD	Пароль для базовой аутентификации.	—	SecurePass123!
N8N_USER_MANAGEMENT_JWT_SECRET	Секрет для подписи JWT-токенов при включенном управлении пользователями.	Генерируется случайно.	your-jwt-signing-secret-key

Категория: База данных и хранение данных

N8n поддерживает несколько баз данных для хранения рабочих процессов, учетных данных и информации о выполнении.

Переменная	Описание	Значение по умолчанию	Пример
DB_TYPE	Тип СУБД: sqlite, postgresdb, mysqldb, mariadb.	sqlite	postgresdb
DB_POSTGRESDB_HOST	Хост PostgreSQL.	localhost	postgres-db
DB_POSTGRESDB_DATABASE	Имя базы данных.	n8n	n8n_production
DB_POSTGRESDB_USER	Пользователь БД.	root	n8n_user
DB_POSTGRESDB_PASSWORD	Пароль пользователя БД.	—	StrongDbPassword
N8N_DEFAULT_BINARY_DATA_MODE	Режим хранения бинарных данных (файлов): ‘default’ (в памяти), ‘filesystem’, ‘s3’.	default	filesystem
N8N_BINARY_DATA_STORAGE_PATH	Путь для хранения файлов при использовании режима ‘filesystem’.	/home/node/.n8n	/data/n8n/files

Категория: Исполнение рабочих процессов (Executions)

Переменная	Описание	Значение по умолчанию	Пример
EXECUTIONS_DATA_PRUNE	Включить автоматическое удаление старых данных об исполнении.	false	true
EXECUTIONS_DATA_MAX_AGE	Максимальный возраст (в часах) данных об исполнении перед удалением.	168	336 (14 дней)
EXECUTIONS_DATA_PRUNE_TIMEOUT	Таймаут (в минутах) для задачи удаления старых данных.	60	120
N8N_PROCESS_WAIT_TIME	Максимальное время (в миллисекундах) ожидания завершения процесса при graceful shutdown.	30000	60000

Категория: Масштабирование и режимы работы

N8n может работать в двух основных режимах, определяемых переменной N8N_DEPLOYMENT_TYPE:

• production (по умолчанию): Полнофункциональный режим с веб-интерфейсом и движком исполнения.
• worker: Режим «рабочего», который только исполняет рабочие процессы, полученные из очереди (например, Redis). Не имеет веб-интерфейса. Используется для горизонтального масштабирования.

Переменная	Описание	Пример для режима Worker
N8N_DEPLOYMENT_TYPE	Тип развертывания: ‘production’ или ‘worker’.	worker
N8N_QUEUE_HEALTH_CHECK_ACTIVE	Включает health check для очереди в режиме worker.	true
EXECUTIONS_MODE	Режим запуска процессов: ‘regular’ (в собственном процессе), ‘queue’ (через очередь, например, Redis).	queue
N8N_REDIS_HOST	Хост Redis для очереди сообщений.	redis-server
N8N_REDIS_PORT	Порт Redis.	6379

Практические примеры конфигурации

Пример 1: Базовый Docker-комpose файл для продакшн с PostgreSQL

Ниже приведен пример docker-compose.yml для запуска N8n с внешней базой данных PostgreSQL и базовой аутентификацией.

version: '3.8'
services:
  n8n:
    image: n8nio/n8n
    container_name: n8n
    restart: unless-stopped
    ports:
      - "5678:5678"
    environment:
      - N8N_PROTOCOL=https
      - N8N_HOST=automation.example.com
      - N8N_ENCRYPTION_KEY=your-32-char-encryption-key-keep-safe
      - N8N_BASIC_AUTH_ACTIVE=true
      - N8N_BASIC_AUTH_USER=admin
      - N8N_BASIC_AUTH_PASSWORD=your_strong_password
      - DB_TYPE=postgresdb
      - DB_POSTGRESDB_HOST=postgres
      - DB_POSTGRESDB_PORT=5432
      - DB_POSTGRESDB_DATABASE=n8n
      - DB_POSTGRESDB_USER=n8n
      - DB_POSTGRESDB_PASSWORD=db_password
      - N8N_DEFAULT_BINARY_DATA_MODE=filesystem
      - N8N_BINARY_DATA_STORAGE_PATH=/data/n8n/files
      - EXECUTIONS_DATA_PRUNE=true
      - EXECUTIONS_DATA_MAX_AGE=168
    volumes:
      - n8n_data:/home/node/.n8n
      - n8n_files:/data/n8n/files
    depends_on:
      - postgres

  postgres:
    image: postgres:13-alpine
    container_name: postgres
    restart: unless-stopped
    environment:
      - POSTGRES_USER=n8n
      - POSTGRES_PASSWORD=db_password
      - POSTGRES_DB=n8n
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  n8n_data:
  n8n_files:
  postgres_data:

Пример 2: Конфигурация для горизонтального масштабирования (Main + Worker)

Для масштабирования необходимо разделить веб-интерфейс и движок исполнения. Основной инстанс (n8n_main) обрабатывает UI/API и ставит задачи в очередь Redis. Рабочие инстансы (n8n_worker_1, n8n_worker_2) берут задачи из очереди и исполняют их.

Основной сервис (Web-UI + Queue Producer)
n8n_main:
  image: n8nio/n8n
  environment:
    - N8N_DEPLOYMENT_TYPE=production
    - EXECUTIONS_MODE=queue
    - N8N_REDIS_HOST=redis
    - N8N_QUEUE_BULL_REDIS_HOST=redis
    - DB_TYPE=postgresdb
    
... остальные настройки БД и безопасности

Сервис-воркер (Только исполнитель)
n8n_worker_1:
  image: n8nio/n8n
  environment:
    - N8N_DEPLOYMENT_TYPE=worker
    - EXECUTIONS_MODE=queue
    - N8N_REDIS_HOST=redis
    - N8N_QUEUE_BULL_REDIS_HOST=redis
    - N8N_QUEUE_HEALTH_CHECK_ACTIVE=true
    - DB_TYPE=postgresdb
    
... настройки БД (такие же как у main)
  
Порт не публикуется, т.к. UI отсутствует

redis:
  image: redis:7-alpine

Общая БД PostgreSQL

Настройка вебхуков и обратных вызовов (Callbacks)

Для корректной работы вебхуков в продакшн-среде с обратным прокси (nginx, Apache, cloud load balancer) необходимо правильно настроить переменные, отвечающие за формирование URL.

• N8N_PROTOCOL=https
• N8N_HOST=your-public-domain.com
• N8N_PORT=443 (или не указывать, если 80/443)
• WEBHOOK_URL=https://your-public-domain.com/ (может потребоваться, если обратный прокси меняет путь).

Также важно настроить доверенные прокси (trust proxy), если N8n находится за обратным прокси, используя переменную N8N_TRUSTED_PROXIES (например, N8N_TRUSTED_PROXIES=loopback, 172.18.0.1).

Управление пакетами сообщества (Community Nodes)

N8n позволяет устанавливать пользовательские узлы через npm. В Docker-окружении для этого необходимо смонтировать volume для папки /usr/local/lib/node_modules и установить пакеты при сборке или запуске.

Пример Dockerfile для установки пакетов
FROM n8nio/n8n
USER root
RUN npm install -g n8n-nodes-your-custom-package
USER node

Или через переменную окружения при первом запуске: N8N_DISABLE_PRODUCTION_MAIN_PROCESS=true npm install n8n-nodes-custom.

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

Как сбросить забытый пароль базовой аутентификации?

Пароль хранится в зашифрованном виде в базе данных. Самый простой способ — отключить аутентификацию, задав N8N_BASIC_AUTH_ACTIVE=false, перезапустить N8n, зайти без пароля, установить новый пароль через интерфейс настроек (Settings > User management), а затем снова включить переменную N8N_BASIC_AUTH_ACTIVE=true и перезапустить.

Почему вебхуки не работают после выноса N8n за обратный прокси (nginx)?

Наиболее вероятные причины:

• Неправильно заданы N8N_PROTOCOL, N8N_HOST, N8N_PORT. Они должны соответствовать публичному URL, по которому клиенты обращаются к N8n.
• Прокси не передает оригинальные заголовки (например, X-Forwarded-Proto, X-Forwarded-Host). Убедитесь, что в конфигурации nginx есть директивы proxy_set_header.
• Не настроены N8N_TRUSTED_PROXIES. Добавьте IP-адрес вашего прокси в эту переменную.

Как выбрать между SQLite и PostgreSQL?

• SQLite: Подходит для тестирования, разработки или личного использования с небольшим объемом данных. Все данные хранятся в одном файле на диске. Не поддерживает одновременный доступ из нескольких инстансов N8n.
• PostgreSQL (рекомендуется для продакшн): Обязательна для любого развертывания с высокой доступностью, горизонтальным масштабированием (режим worker) или просто для надежного хранения данных в production. Обеспечивает целостность данных и параллельный доступ.

Как мигрировать данные с SQLite на PostgreSQL?

1. Создайте резервную копию всех рабочих процессов через интерфейс N8n (Export All Workflows).
2. Остановите N8n с SQLite.
3. Настройте и запустите новый инстанс N8n с переменными окружения, указывающими на PostgreSQL.
4. Импортируйте рабочие процессы через интерфейс.
5. Учетные данные, история исполнений и настройки пользователей не переносятся автоматически. Для полной миграции требуется ручной перенос таблиц базы данных с использованием инструментов миграции.

Что делать, если появляется ошибка «Encryption key is missing or invalid»?

Ключ шифрования (N8N_ENCRYPTION_KEY) должен быть:

• Установлен явно в продакшн-среде (не оставляйте значение по умолчанию).
• Оставаться неизменным на протяжении всего жизненного цикла инстанса N8n.
• Иметь длину ровно 32 символа.

Если ключ потерян или изменен, все зашифрованные данные (учетные данные узлов) станут нечитаемыми. Их необходимо будет ввести заново. Сам ключ не хранится в БД, он используется только в оперативной памяти для шифрования/расшифровки.

Как оптимизировать производительность N8n при большом количестве рабочих процессов?

• Используйте PostgreSQL вместо SQLite.
• Включите регулярную очистку истории исполнений (EXECUTIONS_DATA_PRUNE=true).
• Для ресурсоемких или частых workflow рассмотрите режим масштабирования с отдельными worker-инстансами и очередью Redis.
• Настройте хранение бинарных данных (файлов) в файловой системе или S3, а не в памяти (N8N_DEFAULT_BINARY_DATA_MODE=filesystem).
• Увеличьте лимит памяти для контейнера/процесса Node.js.