N8n cli

N8n CLI: Полное руководство по интерфейсу командной строки

N8n CLI (Command Line Interface) — это инструмент для управления n8n из терминала. Он предоставляет набор команд для установки, настройки, развертывания, администрирования и расширения функциональности платформы автоматизации n8n. CLI является неотъемлемой частью для профессионального использования n8n в production-средах, позволяя автоматизировать задачи управления самим n8n.

Установка и базовая настройка N8n CLI

N8n CLI распространяется через npm (Node Package Manager). Для его использования необходим предустановленный Node.js (версии 18 или выше). Установка выполняется глобально, что делает команду n8n доступной из любого места в системе.

Команда для установки:

• npm install -g n8n

После установки можно проверить версию, что подтвердит успешность процесса:

• n8n --version

Базовый запуск n8n через CLI выполняется командой:

• n8n start

Это запустит экземпляр n8n с конфигурацией по умолчанию, доступный по адресу http://localhost:5678.

Ключевые команды и их применение

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

Команды для управления рабочими процессами (Workflows)

• n8n export:workflow: Экспортирует указанный рабочий процесс в файл JSON. Требует идентификатора рабочего процесса (ID).
• n8n import:workflow: Импортирует рабочий процесс из JSON-файла. Позволяет указать путь к файлу.
• n8n execute: Запускает выполнение рабочего процесса напрямую из CLI, без необходимости его активации в интерфейсе. Крайне полезно для отладки и скриптового запуска.

Команды для управления пользователями

• n8n create:user: Создает нового пользователя в базе данных n8n. Обязательные параметры: --email, --firstName, --lastName, --password.
• n8n reset:password: Сбрасывает пароль для существующего пользователя.

Команды для развертывания и обновления

• n8n update: Проверяет доступность обновлений для n8n и при их наличии выполняет обновление до последней версии.
• n8n deploy: Команда для развертывания рабочих процессов, часто используется в связке с CI/CD пайплайнами.

Команды для работы с сообществом (Community Nodes)

• n8n install: Устанавливает пакет сообщества (community node). Например, n8n install @n8n/nodes-your-package.
• n8n uninstall: Удаляет ранее установленный пакет сообщества.
• n8n update:packages: Обновляет все установленные пакеты сообщества до их последних версий.

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

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

Параметр (ENV переменная)	Флаг CLI	Описание и назначение	Пример значения
N8N_PROTOCOL	—protocol	Протокол веб-интерфейса (http/https).	https
N8N_HOST	—host	Имя хоста, на котором работает n8n.	n8n.example.com
N8N_PORT	—port	Порт для веб-интерфейса.	5678
N8N_GENERIC_TIMEZONE	—generic-timezone	Часовой пояс для планировщика (cron).	Europe/Moscow
N8N_ENCRYPTION_KEY	—encryption-key	Ключ для шифрования учетных данных. Обязателен в production.	my-secret-key-32-chars
N8N_DIAGNOSTICS_ENABLED	—diagnostics-enabled	Отправка анонимной диагностической информации.	false
DB_TYPE	—db-type	Тип базы данных (sqlite, postgresdb, mysqldb).	postgresdb
DB_POSTGRESDB_HOST	—db-postgresdb-host	Хост базы данных PostgreSQL.	localhost
EXECUTIONS_DATA_PRUNE	—executions-data-prune	Включить автоматическую очистку данных выполнений.	true
EXECUTIONS_DATA_MAX_AGE	—executions-data-max-age	Максимальный возраст (в часах) данных выполнений перед очисткой.	168

Пример запуска n8n с конфигурацией для PostgreSQL и отключенной диагностикой:

• n8n start --db-type=postgresdb --db-postgresdb-host=localhost --db-postgresdb-user=n8n --db-postgresdb-password=secret --diagnostics-enabled=false

Использование в Docker и оркестраторах

Официальный образ n8n на Docker Hub уже включает CLI. Это позволяет использовать команды n8n при сборке образов или в entrypoint-скриптах. Типичный use-case — предварительная установка пакетов сообщества или импорт рабочих процессов при старте контейнера.

Пример Dockerfile:

FROM n8nio/n8n
Установка community nodes
RUN n8n install @n8n/nodes-postmark
Копирование и импорт рабочих процессов
COPY my-workflows /data/workflows/
ENTRYPOINT ["/docker-entrypoint.sh"]

Для запуска в Docker Compose или Kubernetes команды CLI можно указать в качестве точки входа (entrypoint) или команды (command) для выполнения одноразовых действий, таких как создание первого пользователя.

Интеграция в CI/CD пайплайны

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

1. Экспорт: Выгрузка рабочих процессов из среды разработки с помощью n8n export:workflow.
2. Версионирование: Сохранение JSON-файлов в системе контроля версий (Git).
3. Развертывание: В среде staging/production используется команда n8n import:workflow или n8n deploy для загрузки и активации обновленных рабочих процессов.
4. Управление зависимостями: Установка необходимых community nodes через n8n install в целевой среде.

Отладка и выполнение рабочих процессов

Команда n8n execute позволяет запустить рабочий процесс в изоляции. Это мощный инструмент для:

• Тестирования логики рабочего процесса перед его развертыванием.
• Интеграции n8n в скрипты обработки данных, где n8n выступает как шаг в конвейере.
• Планирования выполнения через системный cron, минуя встроенный планировщик n8n.

Пример команды для выполнения рабочего процесса из файла:

• n8n execute --file=workflow.json

При этом можно переопределить входные данные узлов, используя параметр --data.

Безопасность и администрирование

CLI предоставляет инструменты для базового администрирования и усиления безопасности:

• Управление доступом: Создание пользователей через CLI гарантирует, что можно настроить доступ к production-среде до первого входа через веб-интерфейс.
• Конфигурация секретов: Критичные параметры, такие как N8N_ENCRYPTION_KEY или пароли БД, никогда не должны передаваться через флаги в скриптах. Вместо этого следует использовать переменные окружения, управляемые секрет-менеджерами (HashiCorp Vault, AWS Secrets Manager).
• Аудит: Логи выполнения команд CLI должны собираться и анализироваться для отслеживания изменений в системе.

Практические сценарии использования

Сценарий 1: Первоначальная настройка production-сервера.

1. Установить n8n глобально: npm install -g n8n.
2. Создать системного пользователя для n8n и настроить права.
3. Установить и настроить PostgreSQL.
4. Сгенерировать надежный ключ шифрования.
5. Запустить n8n с нужными параметрами, используя systemd или процесс-менеджер:

   N8N_ENCRYPTION_KEY=your_key_here 
   DB_TYPE=postgresdb 
   DB_POSTGRESDB_HOST=localhost 
   n8n start --port=5678 --skip-webhook-download=true
   

6. Создать административного пользователя: n8n create:user --email=admin@example.com --firstName=Admin --lastName=User --password=securePass123 --role=owner.

Сценарий 2: Ежедневное резервное копирование рабочих процессов.

1. Написать скрипт, который через API или CLI (если доступен экспорт) выгружает все рабочие процессы.
2. Сохранять их с меткой времени в надежное хранилище (S3, SFTP).
3. Добавить скрипт в планировщик задач cron.

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

Как полностью удалить n8n, установленную через CLI?

Чтобы полностью удалить n8n, установленную глобально через npm, выполните команду: npm uninstall -g n8n. Также необходимо удалить каталог данных n8n, расположение которого зависит от вашей ОС и конфигурации (по умолчанию это ~/.n8n или путь, указанный в переменной окружения N8N_USER_FOLDER).

Можно ли использовать CLI для управления удаленным экземпляром n8n?

Нет, CLI по умолчанию предназначен для управления локально установленным экземпляром n8n. Для удаленного управления следует использовать REST API n8n, который предоставляет аналогичные возможности (управление рабочими процессами, пользователями, выполнениями).

Как решить проблему с правами доступа (EACCES) при установке через npm?

Ошибка EACCES возникает при попытке установки пакета глобально без необходимых прав. Решения:

• Использовать менеджер версий Node.js (nvm), который устанавливает пакеты в домашний каталог пользователя.
• Перенастроить права на каталог npm глобально (не рекомендуется из соображений безопасности).
• Выполнить установку с помощью sudo, но это может привести к проблемам с безопасностью и последующим конфликтам прав.

Чем отличается команда `n8n start` от прямого запуска с помощью `node`?

Команда n8n start является оберткой, которая обеспечивает корректную загрузку окружения, обработку флагов и переменных, а затем запускает основной процесс n8n. Прямой запуск через node bin/n8n возможен из исходного кода, но для стандартного использования всегда предпочтительнее использовать CLI.

Как настроить несколько экземпляров n8n на одном сервере?

Для запуска нескольких независимых экземпляров необходимо обеспечить уникальность следующих параметров для каждого экземпляра:

• Порт (—port).
• Каталог данных (N8N_USER_FOLDER).
• Если используется база данных SQLite, путь к файлу БД должен быть уникальным. Для PostgreSQL/MySQL можно использовать разные базы данных или схемы в рамках одной БД.

Пример: N8N_USER_FOLDER=/home/user/.n8n-instance2 n8n start --port=5679.

Как обновить n8n CLI и сам n8n?

Для обновления самого инструмента CLI используйте команду: npm update -g n8n. Для обновления запущенного экземпляра n8n до последней версии (при условии, что используется та же глобальная установка) можно остановить процесс и запустить его заново. Команда n8n update также проверяет наличие обновлений и предлагает их установить.

Какие есть альтернативы хранения конфигурации кроме флагов и ENV?

N8n также поддерживает использование файла конфигурации .n8n/config в пользовательском каталоге. Однако, для production-среды использование переменных окружения является стандартом, так как это лучше интегрируется с Docker, оркестраторами и секрет-менеджерами.

Как импортировать рабочий процесс, если уже существует workflow с таким ID?

При импорте через CLI или интерфейс, если рабочий процесс с таким идентификатором уже существует, он будет перезаписан. Если необходимо создать копию, следует предварительно изменить поле "id" в JSON-файле рабочего процесса на новое уникальное значение (например, сгенерировать UUID v4).