This is the full developer documentation for N8N + MCP # n8n — автоматизация с AI > Open-source платформа для автоматизации рабочих процессов с нативной поддержкой AI агентов и Model Context Protocol ## Быстрая навигация [Заголовок раздела «Быстрая навигация»](#быстрая-навигация) Быстрый старт Установка и первый workflow за 5 минут [Перейти →](/start/quickstart/) AI агенты Автономные AI-ассистенты с инструментами [Перейти →](/ai-mcp/ai-agent/) MCP серверы Model Context Protocol для AI [Перейти →](/ai-mcp/mcp/) Workflows Создание и управление автоматизациями [Перейти →](/workflows/overview/) Хостинг Docker, масштабирование, безопасность [Перейти →](/hosting/overview/) Справочник API, CLI, горячие клавиши [Перейти →](/reference/cli/) *** ## 🚀 Self-hosted n8n без блокировок AI [Заголовок раздела «🚀 Self-hosted n8n без блокировок AI»](#-self-hosted-n8n-без-блокировок-ai) Проблема с доступом из России OpenAI, Anthropic (Claude), Google AI и другие глобальные AI-провайдеры **блокируют запросы с российских IP-адресов**. Это означает, что n8n на домашнем сервере или VPS в РФ не сможет использовать ноды ChatGPT, Claude, Gemini и другие AI-интеграции. ### Решение: VDS в свободной юрисдикции [Заголовок раздела «Решение: VDS в свободной юрисдикции»](#решение-vds-в-свободной-юрисдикции) Закажите VDS в **Нидерландах** или **Казахстане** — и получите полный доступ ко всем AI API: 🇳🇱 VDS Нидерланды Европейский IP без блокировок. Идеально для OpenAI, Claude, любых западных сервисов. [Заказать VDS →](/vps_vds_netherlands) 🇰🇿 VDS Казахстан Минимальная задержка из РФ. Доступ к AI API без ограничений. [Заказать VDS →](/vps-vds-kazakhstan) Промокод для скидки: `648429339` ✓ Без VPN и прокси • ✓ Оплата в рублях • ✓ Готов за 5 минут *** ## Что такое n8n? [Заголовок раздела «Что такое n8n?»](#что-такое-n8n) **n8n** (произносится «n-eight-n») — это open-source платформа автоматизации рабочих процессов, которая позволяет соединять приложения, данные и AI в единые автоматизированные потоки. Почему n8n? В отличие от Zapier и Make, n8n можно развернуть на своём сервере, получив полный контроль над данными и неограниченные возможности кастомизации. ### Ключевые возможности [Заголовок раздела «Ключевые возможности»](#ключевые-возможности) 400+ интеграций Готовые коннекторы к Google, Slack, Notion, Telegram, базам данных и сотням других сервисов. Любой API — через HTTP Request. AI-native платформа 70+ нод для AI: LangChain, OpenAI, Claude, Ollama. Встроенная поддержка MCP (Model Context Protocol) для подключения AI к внешним инструментам. Self-hosted бесплатно Разверните на своём сервере и не платите за количество workflows. Ваши данные остаются под вашим контролем. Код когда нужен Визуальный редактор для простых задач. JavaScript/Python когда требуется сложная логика. Лучшее из двух миров. *** ## Что вы теряете без автоматизации [Заголовок раздела «Что вы теряете без автоматизации»](#что-вы-теряете-без-автоматизации) Время на рутину **10+ часов в неделю** уходит на ручной перенос данных между системами, копирование, проверку и согласование. Человеческие ошибки Опечатки, забытые задачи, потерянные письма. **87% ошибок** в бизнес-процессах — результат ручной работы. Невозможность масштабирования Когда объём данных растёт, ручные процессы становятся узким местом. **Бизнес упирается в потолок**. Разрозненные системы CRM не связана с поддержкой, поддержка не связана с биллингом. **Данные в разных местах** — решения на ощупь. Заметка n8n решает эти проблемы: один раз настроил workflow — работает автоматически, без ошибок, в любом масштабе. *** ## Почему именно n8n? [Заголовок раздела «Почему именно n8n?»](#почему-именно-n8n) Сравнение с популярными альтернативами: | Критерий | n8n | Zapier | Make | | --------------------------- | ------------------------------- | ---------- | ---------- | | **Self-hosted** | Да, бесплатно | Нет | Нет | | **Открытый код** | Да (fair-code) | Нет | Нет | | **AI интеграция** | 70+ нод, LangChain, MCP | Базовая | Средняя | | **Стоимость (self-hosted)** | Бесплатно | — | — | | **Кастомный код** | JS/Python в любом месте | Ограничено | Ограничено | | **Сложные сценарии** | Ветвления, циклы, sub-workflows | Линейно | Средне | | **Количество интеграций** | 400+ | 6000+ | 1500+ | | **Кривая обучения** | Средняя | Низкая | Средняя | Совет **Для кого n8n?** Технические команды, стартапы, enterprise с требованиями к безопасности данных, и все, кто хочет полный контроль над автоматизацией. *** ## AI-возможности 2025 [Заголовок раздела «AI-возможности 2025»](#ai-возможности-2025) n8n — одна из немногих платформ автоматизации с **нативной поддержкой AI**: * AI агенты Автономные AI-ассистенты, которые: * Принимают решения на основе контекста * Используют инструменты (поиск, API, базы данных) * Общаются с пользователями через чат * Выполняют многошаговые задачи ```plaintext Пользователь: "Найди все просроченные задачи и отправь напоминания" AI Agent → Jira API → Фильтрация → Slack → Отчёт ``` [Подробнее об AI агентах →](/ai-mcp/ai-agent/) * MCP интеграция **Model Context Protocol** — стандарт подключения AI к внешним инструментам: * Файловая система, Git, базы данных * Поиск в интернете, браузер * Любые кастомные инструменты n8n поддерживает MCP **и как клиент, и как сервер**. [Документация MCP →](/ai-mcp/mcp/) * LangChain ноды **70+ специализированных нод** для AI: | Категория | Примеры | | ------------ | --------------------------------------- | | Модели | OpenAI, Claude, Gemini, Ollama, Mistral | | Память | Buffer, Window, Redis, Postgres | | Векторные БД | Pinecone, Qdrant, Supabase, PGVector | | Инструменты | Calculator, Wikipedia, Code, HTTP | | Chains | Conversation, Summarization, Q\&A | [Все LangChain ноды →](/ai-mcp/langchain/) * RAG **Retrieval Augmented Generation** — ответы AI на основе ваших документов: 1. Загрузите документы (PDF, DOCX, веб-страницы) 2. Создайте векторную базу 3. AI отвечает на вопросы, цитируя источники [Гайд по RAG →](/ai-mcp/rag/) *** ## Разделы документации [Заголовок раздела «Разделы документации»](#разделы-документации) Начало работы Установка, интерфейс, путь обучения [Перейти →](/start/quickstart/) Workflows Создание, компоненты, выполнение, примеры [Перейти →](/workflows/overview/) Ключевые концепции Данные, логика, циклы, объединение [Перейти →](/concepts/flow-logic/) AI и MCP Агенты, LangChain, RAG, MCP серверы [Перейти →](/ai-mcp/overview/) Интеграции Триггеры, ноды, credentials [Перейти →](/integrations/overview/) Хостинг Docker, переменные, масштабирование [Перейти →](/hosting/overview/) Код в n8n Expressions, Code node, JS/Python [Перейти →](/code/overview/) Справочник CLI, API, FAQ, горячие клавиши [Перейти →](/reference/cli/) *** ## Начните прямо сейчас [Заголовок раздела «Начните прямо сейчас»](#начните-прямо-сейчас) Самый быстрый способ попробовать n8n — Docker: ```bash docker run -it --rm --name n8n -p 5678:5678 n8nio/n8n ``` Откройте [localhost:5678](http://localhost:5678) и создайте первый workflow. [Полный гайд по установке ](/hosting/docker/)Docker, npm, облачные платформы [Первый AI-агент ](/ai-mcp/tutorial-ai-agent/)Туториал: создаём агента за 15 минут *** ## Полезные ссылки [Заголовок раздела «Полезные ссылки»](#полезные-ссылки) | Ресурс | Описание | | ------------------------------------------------ | ------------------------------ | | [Официальная документация](https://docs.n8n.io/) | Английская версия документации | | [n8n Community](https://community.n8n.io/) | Форум сообщества | | [GitHub n8n](https://github.com/n8n-io/n8n) | Исходный код платформы | | [n8n Cloud](https://n8n.io/cloud/) | Управляемый хостинг | | [MCP Doc](https://mcpdoc.ru/) | Документация по MCP серверам | # AI Agent > Создание автономных AI агентов в n8n с инструментами и памятью ## Что такое AI Agent? [Заголовок раздела «Что такое AI Agent?»](#что-такое-ai-agent) AI Agent — это автономная система, которая: 1. Получает задачу от пользователя 2. Разбивает её на шаги 3. Использует инструменты для выполнения 4. Возвращает результат ## Создание AI Agent [Заголовок раздела «Создание AI Agent»](#создание-ai-agent) 1. **Добавьте AI Agent ноду** В панели нод найдите “AI Agent” 2. **Подключите Chat Model** Добавьте модель (OpenAI, Anthropic, Ollama) 3. **Добавьте инструменты (опционально)** Calculator, HTTP Request, Code Tool, MCP 4. **Настройте память (опционально)** Buffer Memory, Window Memory 5. **Настройте System Prompt** Определите поведение агента ## Конфигурация Agent [Заголовок раздела «Конфигурация Agent»](#конфигурация-agent) ### Основные параметры [Заголовок раздела «Основные параметры»](#основные-параметры) | Параметр | Описание | | ----------------------------- | ------------------------------- | | **System Message** | Инструкции для агента | | **Human Message** | Шаблон запроса пользователя | | **Max Iterations** | Максимум итераций (default: 10) | | **Return Intermediate Steps** | Показывать шаги рассуждения | ### System Prompt [Заголовок раздела «System Prompt»](#system-prompt) ```plaintext Ты полезный ассистент. Отвечай на русском языке. Твои возможности: - Поиск информации в интернете - Математические вычисления - Анализ данных При ответе: 1. Сначала проанализируй запрос 2. Используй доступные инструменты 3. Дай структурированный ответ ``` ## Подключение Chat Model [Заголовок раздела «Подключение Chat Model»](#подключение-chat-model) ### OpenAI [Заголовок раздела «OpenAI»](#openai) * GPT-4 ```plaintext Model: gpt-4-turbo Temperature: 0.7 Max Tokens: 4096 ``` * GPT-3.5 ```plaintext Model: gpt-3.5-turbo Temperature: 0.7 Max Tokens: 2048 ``` ### Anthropic Claude [Заголовок раздела «Anthropic Claude»](#anthropic-claude) ```plaintext Model: claude-3-5-sonnet Temperature: 0.7 Max Tokens: 4096 ``` ### Ollama (локально) [Заголовок раздела «Ollama (локально)»](#ollama-локально) ```plaintext Base URL: http://localhost:11434 Model: llama3.2 Temperature: 0.7 ``` ## Инструменты (Tools) [Заголовок раздела «Инструменты (Tools)»](#инструменты-tools) ### Calculator [Заголовок раздела «Calculator»](#calculator) Математические вычисления: ```plaintext Input: "Посчитай 15% от 1500" Agent: Использую Calculator... Output: 225 ``` ### HTTP Request Tool [Заголовок раздела «HTTP Request Tool»](#http-request-tool) Запросы к API: | Параметр | Пример | | --------------- | --------------------------------- | | **URL** | `https://api.example.com/data` | | **Method** | GET | | **Description** | ”Получить данные о пользователях” | Совет Добавьте понятное описание инструмента — агент использует его для выбора. ### Code Tool [Заголовок раздела «Code Tool»](#code-tool) Выполнение JavaScript: ```javascript // Description: Форматирование даты const date = new Date(input); return date.toLocaleDateString('ru-RU'); ``` ### Workflow Tool [Заголовок раздела «Workflow Tool»](#workflow-tool) Вызов другого workflow: | Параметр | Описание | | --------------- | ----------------------------- | | **Workflow** | Выберите workflow | | **Description** | ”Отправка email пользователю” | ### MCP Client [Заголовок раздела «MCP Client»](#mcp-client) Подключение MCP серверов: * Файловая система * База данных * Web browsing * И другие ## Memory (Память) [Заголовок раздела «Memory (Память)»](#memory-память) ### Buffer Memory [Заголовок раздела «Buffer Memory»](#buffer-memory) Хранит всю историю в памяти: ```plaintext ✅ Простая настройка ✅ Быстрый доступ ❌ Теряется при перезапуске ❌ Не масштабируется ``` ### Window Buffer Memory [Заголовок раздела «Window Buffer Memory»](#window-buffer-memory) Скользящее окно последних N сообщений: | Параметр | Описание | | --------------- | --------------------------------- | | **Window Size** | Количество сообщений (default: 5) | ```plaintext ✅ Ограниченное использование памяти ✅ Актуальный контекст ❌ Теряет старый контекст ``` ### Postgres Chat Memory [Заголовок раздела «Postgres Chat Memory»](#postgres-chat-memory) Персистентное хранение: | Параметр | Описание | | -------------- | --------------------- | | **Session ID** | Идентификатор сессии | | **Connection** | PostgreSQL credential | | **Table Name** | Таблица для хранения | ```plaintext ✅ Персистентность ✅ Масштабируется ✅ Можно шарить между инстансами ``` ## Примеры [Заголовок раздела «Примеры»](#примеры) ### Customer Support Bot [Заголовок раздела «Customer Support Bot»](#customer-support-bot) System Prompt: ```plaintext Ты агент поддержки компании X. Твои задачи: 1. Ответить на вопрос из базы знаний 2. Создать тикет если не можешь помочь 3. Найти информацию о клиенте в CRM Всегда: - Будь вежливым - Отвечай на русском - Предлагай связаться с оператором при сложных вопросах ``` ### Research Assistant [Заголовок раздела «Research Assistant»](#research-assistant) ### Data Analyst [Заголовок раздела «Data Analyst»](#data-analyst) ## Отладка Agent [Заголовок раздела «Отладка Agent»](#отладка-agent) ### Return Intermediate Steps [Заголовок раздела «Return Intermediate Steps»](#return-intermediate-steps) Включите для просмотра рассуждений: ```json { "thought": "Пользователь спрашивает о погоде. Нужно использовать Weather API.", "action": "http_request", "action_input": { "city": "Moscow" }, "observation": "Temperature: 15°C" } ``` ### Логирование [Заголовок раздела «Логирование»](#логирование) В Code Tool: ```javascript console.log('Tool input:', $json); console.log('Processing...'); const result = processData($json); console.log('Tool output:', result); return result; ``` ## Лучшие практики [Заголовок раздела «Лучшие практики»](#лучшие-практики) 1. **Чёткий System Prompt** — определите роль и ограничения 2. **Описания инструментов** — агент выбирает по описанию 3. **Ограничьте итерации** — установите разумный Max Iterations 4. **Fallback** — добавьте обработку когда агент не справляется 5. **Мониторинг токенов** — следите за потреблением 6. **Тестируйте edge cases** — проверяйте нестандартные запросы ## Следующие шаги [Заголовок раздела «Следующие шаги»](#следующие-шаги) * [LangChain](/ai-mcp/langchain/) — цепочки обработки * [RAG](/ai-mcp/rag/) — работа с документами * [MCP](/ai-mcp/mcp/) — Model Context Protocol # Chat Hub > Централизованный AI-чат интерфейс для работы с моделями и агентами **Chat Hub** — централизованный интерфейс для работы с AI моделями, n8n агентами и создания персональных ассистентов. Заметка Chat Hub доступен на платных планах n8n Cloud (Starter, Pro, Business, Enterprise). ## Возможности Chat Hub [Заголовок раздела «Возможности Chat Hub»](#возможности-chat-hub) | Функция | Описание | | ----------------------- | -------------------------------------------------- | | **Множество моделей** | GPT-4, Claude, Gemini в одном интерфейсе | | **n8n Агенты** | Доступ к вашим workflow-агентам | | **Персональные агенты** | Создание простых агентов с кастомными инструкциями | | **Chat User роль** | Пользователи без доступа к workflows | *** ## Как использовать [Заголовок раздела «Как использовать»](#как-использовать) 1. Найдите **Chat** в навигационной панели n8n 2. Выберите модель или агента из списка 3. Начните разговор *** ## Персональные агенты [Заголовок раздела «Персональные агенты»](#персональные-агенты) Персональные агенты — простые AI-ассистенты с кастомными инструкциями для повторяющихся задач. ### Создание персонального агента [Заголовок раздела «Создание персонального агента»](#создание-персонального-агента) 1. Нажмите **Personal Agents** → **+New Agent** 2. Заполните настройки 3. Нажмите **Save** ### Настройки агента [Заголовок раздела «Настройки агента»](#настройки-агента) | Поле | Описание | | ----------------- | -------------------------------- | | **Name** | Название агента (видно в списке) | | **Description** | Краткое описание назначения | | **System Prompt** | Инструкции для AI | | **Model** | Выбор LLM модели | | **Tools** | Доступные инструменты | ### Пример системного промпта [Заголовок раздела «Пример системного промпта»](#пример-системного-промпта) ```text Ты — ассистент по написанию маркетинговых текстов. Твои задачи: - Писать продающие заголовки - Создавать описания продуктов - Редактировать тексты Правила: - Используй активный залог - Пиши кратко и ёмко - Добавляй призывы к действию - Всегда на русском языке ``` *** ## Workflow-агенты [Заголовок раздела «Workflow-агенты»](#workflow-агенты) Для сложных сценариев используйте n8n workflows как агентов в Chat Hub. ### Требования к workflow [Заголовок раздела «Требования к workflow»](#требования-к-workflow) * Нода **Chat Trigger** (новейшая версия) * Нода **AI Agent** с включённым streaming * Workflow должен быть активирован ### Настройка workflow для Chat Hub [Заголовок раздела «Настройка workflow для Chat Hub»](#настройка-workflow-для-chat-hub) 1. Откройте workflow с AI Agent 2. Откройте **Chat Trigger** 3. Включите **Make Available in n8n Chat** 4. Задайте имя и описание 5. В **AI Agent** включите **Enable Streaming** 6. Активируйте workflow Осторожно **Важно:** Используйте Chat Trigger новейшей версии. Если у вас старый триггер — удалите его и добавьте новый. ### Доступ к workflow-агентам [Заголовок раздела «Доступ к workflow-агентам»](#доступ-к-workflow-агентам) Коллеги увидят ваш workflow-агент, если: * Workflow расшарен с ними * Они имеют доступ к проекту (минимум viewer) *** ## Роль Chat User [Заголовок раздела «Роль Chat User»](#роль-chat-user) **Chat User** — специальная роль для пользователей, которые только используют AI-функции без создания workflows. ### Возможности Chat User [Заголовок раздела «Возможности Chat User»](#возможности-chat-user) | Может | Не может | | --------------------- | ----------------------------- | | Использовать Chat Hub | Создавать workflows | | Общаться с моделями | Редактировать credentials | | Использовать агентов | Видеть внутренности workflows | ### Когда использовать [Заголовок раздела «Когда использовать»](#когда-использовать) * Команды поддержки * Менеджеры * Маркетологи * Любые сотрудники без технического бэкграунда Совет Chat User роль экономит лицензии — пользователи получают AI-функции без полного доступа к n8n. *** ## Настройки провайдеров [Заголовок раздела «Настройки провайдеров»](#настройки-провайдеров) Администраторы могут контролировать доступ к моделям. ### Доступные настройки [Заголовок раздела «Доступные настройки»](#доступные-настройки) | Настройка | Описание | | ----------------------------- | -------------------------------------- | | Включение/отключение моделей | Какие модели доступны пользователям | | Блокировка добавления моделей | Запрет на добавление своих моделей | | Default credentials | Credentials по умолчанию | | Ограничение credentials | Запрет на добавление своих credentials | ### Как настроить [Заголовок раздела «Как настроить»](#как-настроить) 1. Перейдите в **Settings** → **Chat** 2. Отредактируйте провайдеров 3. Сохраните изменения *** ## Примеры использования [Заголовок раздела «Примеры использования»](#примеры-использования) ### Пример 1: Ассистент по документации [Заголовок раздела «Пример 1: Ассистент по документации»](#пример-1-ассистент-по-документации) ```plaintext ┌─────────────────────────────────────────────┐ │ Персональный агент "Docs Helper" │ │ │ │ System Prompt: │ │ Ты — ассистент по внутренней документации. │ │ Отвечай на вопросы о процессах компании. │ │ Если не знаешь ответ — направь к HR. │ │ │ │ Model: gpt-4o-mini │ │ Tools: None │ └─────────────────────────────────────────────┘ ``` ### Пример 2: Агент поддержки (workflow) [Заголовок раздела «Пример 2: Агент поддержки (workflow)»](#пример-2-агент-поддержки-workflow) ```plaintext ┌─────────────────────────────────────────────┐ │ Workflow "Support Agent" │ │ │ │ ┌────────────┐ ┌────────────┐ │ │ │Chat Trigger│───→│ AI Agent │ │ │ └────────────┘ └─────┬──────┘ │ │ │ │ │ ┌──────────┼──────────┐ │ │ ↓ ↓ ↓ │ │ ┌────────┐ ┌────────┐ ┌────────┐ │ │ │ Model │ │Zendesk │ │Knowledge│ │ │ │(GPT-4o)│ │ Tool │ │ Base │ │ │ └────────┘ └────────┘ └────────┘ │ │ │ │ Возможности: │ │ - Поиск в базе знаний │ │ - Создание тикетов в Zendesk │ │ - Эскалация сложных вопросов │ └─────────────────────────────────────────────┘ ``` ### Пример 3: Анализатор данных [Заголовок раздела «Пример 3: Анализатор данных»](#пример-3-анализатор-данных) ```plaintext ┌─────────────────────────────────────────────┐ │ Workflow "Data Analyst" │ │ │ │ Tools: │ │ - PostgreSQL (чтение данных) │ │ - Code (вычисления) │ │ - Google Sheets (экспорт) │ │ │ │ Команды пользователей: │ │ "Покажи продажи за Q4" │ │ "Сравни показатели с прошлым годом" │ │ "Экспортируй топ-10 клиентов в таблицу" │ └─────────────────────────────────────────────┘ ``` *** ## Ограничения [Заголовок раздела «Ограничения»](#ограничения) Осторожно Текущие ограничения Chat Hub: * Нельзя добавлять файлы/документы к персональным агентам * Ограниченный выбор tools для персональных агентов * Только workflows с Chat Trigger + streaming работают как агенты *** ## Best Practices [Заголовок раздела «Best Practices»](#best-practices) ### 1. Чёткие инструкции [Заголовок раздела «1. Чёткие инструкции»](#1-чёткие-инструкции) ```text ✅ Хорошо: "Отвечай только на вопросы о продуктах из каталога. При вопросах о ценах — уточняй количество. Если вопрос вне твоей компетенции — вежливо откажи." ❌ Плохо: "Будь полезным ассистентом." ``` ### 2. Выбор правильного типа агента [Заголовок раздела «2. Выбор правильного типа агента»](#2-выбор-правильного-типа-агента) | Задача | Тип агента | | ------------------------------- | ------------------------ | | Простые ответы | Персональный агент | | Работа с данными | Workflow-агент | | Интеграции с внешними системами | Workflow-агент | | FAQ бот | Персональный агент + RAG | ### 3. Тестирование [Заголовок раздела «3. Тестирование»](#3-тестирование) Перед публикацией workflow-агента: 1. Протестируйте в режиме разработки 2. Проверьте edge cases 3. Убедитесь в стабильности streaming *** ## Связанные темы [Заголовок раздела «Связанные темы»](#связанные-темы) AI Agent [AI агенты](/ai-mcp/ai-agent/) — создание агентов LLM модели [Модели](/ai-mcp/llm-models/) — выбор модели RAG [RAG](/ai-mcp/rag/) — ответы по документам # AI Evaluations > Тестирование и оценка качества AI workflows в n8n **Evaluations** позволяют тестировать AI workflows на наборе примеров и измерять качество ответов. ## Типы оценки [Заголовок раздела «Типы оценки»](#типы-оценки) | Тип | Описание | Доступность | | --------------------- | ------------------------------- | ---------------------------- | | **Light Evaluations** | Визуальная проверка результатов | Community (зарег.), Starter+ | | **Metric-based** | Численные метрики качества | Pro, Enterprise | *** ## Light Evaluations [Заголовок раздела «Light Evaluations»](#light-evaluations) Light evaluations — быстрая проверка workflow на нескольких примерах с визуальным сравнением результатов. ### Когда использовать [Заголовок раздела «Когда использовать»](#когда-использовать) * На этапе разработки * Для небольшого набора тестов (5-20 примеров) * Когда достаточно визуальной проверки ### Процесс [Заголовок раздела «Процесс»](#процесс) 1. Создайте датасет с примерами 2. Подключите датасет к workflow 3. Запишите результаты обратно в датасет 4. Запустите оценку 5. Просмотрите и сравните результаты ### Шаг 1: Создание датасета [Заголовок раздела «Шаг 1: Создание датасета»](#шаг-1-создание-датасета) Создайте Google Sheet или Data Table с колонками: | Колонка | Описание | Пример | | -------------------- | ----------------------------- | ---------------------- | | **input** | Входные данные | ”Привет, как дела?“ | | **expected\_output** | Ожидаемый ответ (опционально) | “Привет! Я в порядке…“ | | **actual\_output** | Фактический результат (пусто) | — | **Пример датасета для классификации тикетов:** | input | expected\_category | expected\_priority | actual\_category | actual\_priority | | ------------------------- | ------------------ | ------------------ | ---------------- | ---------------- | | ”Не могу войти в аккаунт” | auth | high | | | | ”Как изменить пароль?“ | auth | low | | | | ”Сайт работает медленно” | performance | medium | | | ### Шаг 2: Подключение к workflow [Заголовок раздела «Шаг 2: Подключение к workflow»](#шаг-2-подключение-к-workflow) Добавьте **Evaluation Trigger** в начало workflow: ```plaintext ┌──────────────────┐ ┌────────────┐ ┌────────────┐ │ Evaluation │───→│ AI Agent │───→│ Set Outputs│ │ Trigger │ │ │ │ (запись) │ │ (датасет) │ │ │ │ │ └──────────────────┘ └────────────┘ └────────────┘ ``` При каждом запуске триггер выдаёт **одну строку** из датасета. Совет Во время разработки установите **Max rows to process: 1** или используйте **Execute node** вместо **Evaluate all**. ### Шаг 3: Запись результатов [Заголовок раздела «Шаг 3: Запись результатов»](#шаг-3-запись-результатов) Добавьте **Evaluation** ноду с операцией **Set Outputs**: 1. Подключите после AI Agent 2. Укажите маппинг: output workflow → колонка датасета ### Шаг 4: Запуск оценки [Заголовок раздела «Шаг 4: Запуск оценки»](#шаг-4-запуск-оценки) Нажмите **Evaluate all** у Evaluation Trigger — workflow выполнится для каждой строки датасета. ### Шаг 5: Анализ результатов [Заголовок раздела «Шаг 5: Анализ результатов»](#шаг-5-анализ-результатов) Откройте датасет и сравните `expected_output` с `actual_output`. *** ## Metric-based Evaluations [Заголовок раздела «Metric-based Evaluations»](#metric-based-evaluations) Заметка Доступно на Pro и Enterprise планах. Community/Starter — только для одного workflow. Metric-based evaluations вычисляют **численные метрики** качества для автоматического сравнения версий workflow. ### Когда использовать [Заголовок раздела «Когда использовать»](#когда-использовать-1) * Большой датасет (50+ примеров) * Продакшн AI workflows * A/B тестирование промптов * Отслеживание регрессий ### Доступные метрики [Заголовок раздела «Доступные метрики»](#доступные-метрики) | Метрика | Описание | Шкала | | --------------------- | ----------------------------------- | ------- | | **Correctness** | Соответствие эталонному ответу (AI) | 1-5 | | **Helpfulness** | Полезность ответа (AI) | 1-5 | | **String Similarity** | Похожесть строк (edit distance) | 0-1 | | **Categorization** | Точное совпадение категорий | 0 или 1 | | **Tools Used** | Использовались ли инструменты | 0-1 | ### Кастомные метрики [Заголовок раздела «Кастомные метрики»](#кастомные-метрики) Вы можете создать свои метрики: ```javascript // Пример: проверка длины ответа const responseLength = $json.response.length; const score = responseLength > 100 && responseLength < 500 ? 1 : 0; return { json: { length_score: score } }; ``` ### Добавление метрик [Заголовок раздела «Добавление метрик»](#добавление-метрик) 1. Настройте Light evaluation (шаги 1-3) 2. Добавьте **Evaluation** ноду с **Set Metrics** 3. Выберите метрики или создайте кастомные 4. Запустите оценку из вкладки **Evaluations** ### Пример workflow с метриками [Заголовок раздела «Пример workflow с метриками»](#пример-workflow-с-метриками) ```plaintext ┌──────────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ Evaluation │───→│ AI Agent │───→│ Set Outputs│───→│ Set Metrics│ │ Trigger │ │ │ │ │ │ │ └──────────────────┘ └────────────┘ └────────────┘ └────────────┘ ``` ### Просмотр результатов [Заголовок раздела «Просмотр результатов»](#просмотр-результатов) 1. Перейдите на вкладку **Evaluations** 2. Нажмите **Run evaluation** 3. После завершения — сводные метрики по каждому измерению *** ## Примеры оценки [Заголовок раздела «Примеры оценки»](#примеры-оценки) ### Пример 1: Классификация тикетов [Заголовок раздела «Пример 1: Классификация тикетов»](#пример-1-классификация-тикетов) **Датасет:** | ticket\_text | expected\_category | expected\_priority | | -------------------- | ------------------ | ------------------ | | ”Не работает оплата” | billing | high | | ”Вопрос по тарифам” | billing | low | **Метрики:** * `Categorization` для category * `Categorization` для priority **Результат:** Accuracy = 0.95 (95% правильных классификаций) ### Пример 2: RAG качество [Заголовок раздела «Пример 2: RAG качество»](#пример-2-rag-качество) **Датасет:** | question | expected\_answer | relevant\_docs | | --------------------- | ---------------- | -------------- | | ”Как установить n8n?" | "docker run…“ | doc\_id: 123 | **Метрики:** * `Correctness` — правильность ответа * `Helpfulness` — полезность * Кастомная метрика: Document relevance ### Пример 3: Чат-бот [Заголовок раздела «Пример 3: Чат-бот»](#пример-3-чат-бот) **Датасет:** | user\_message | expected\_response | | ----------------- | ----------------------- | | ”Привет” | Дружелюбное приветствие | | ”Цена продукта X” | Точная цена | **Метрики:** * `Helpfulness` (1-5) * `String Similarity` (для точных ответов) *** ## Условное выполнение метрик [Заголовок раздела «Условное выполнение метрик»](#условное-выполнение-метрик) Метрики добавляют latency и стоимость (AI-based). Выполняйте их только при оценке: ```plaintext ┌────────────────────┐ │ Check if evaluating│ │ (Evaluation node) │ └─────────┬──────────┘ │ ┌────┴────┐ ↓ ↓ Yes No │ │ ↓ ↓ ┌─────────┐ ┌─────────┐ │ Metrics │ │ Skip │ └─────────┘ └─────────┘ ``` *** ## Best Practices [Заголовок раздела «Best Practices»](#best-practices) ### 1. Начинайте с Light evaluations [Заголовок раздела «1. Начинайте с Light evaluations»](#1-начинайте-с-light-evaluations) ```plaintext Development → Light eval (5-10 примеров) Staging → Light eval (20-50 примеров) Production → Metric-based (100+ примеров) ``` ### 2. Создавайте репрезентативные датасеты [Заголовок раздела «2. Создавайте репрезентативные датасеты»](#2-создавайте-репрезентативные-датасеты) * Включайте edge cases * Добавляйте примеры из продакшн ошибок * Балансируйте категории ### 3. Отслеживайте изменения [Заголовок раздела «3. Отслеживайте изменения»](#3-отслеживайте-изменения) Перед изменением промпта: 1. Запустите baseline evaluation 2. Сохраните метрики 3. Внесите изменения 4. Сравните новые метрики ### 4. Автоматизируйте [Заголовок раздела «4. Автоматизируйте»](#4-автоматизируйте) Запускайте evaluations: * При изменении промптов * Еженедельно для мониторинга * Перед деплоем в продакшн *** ## Ограничения [Заголовок раздела «Ограничения»](#ограничения) Осторожно * AI-based метрики требуют дополнительных API вызовов * Оценка больших датасетов занимает время * Некоторые метрики субъективны (Helpfulness) *** ## Связанные темы [Заголовок раздела «Связанные темы»](#связанные-темы) AI Agent [AI агенты](/ai-mcp/ai-agent/) — создание агентов RAG [RAG](/ai-mcp/rag/) — ответы по документам Troubleshooting [Решение проблем](/reference/troubleshooting/) — отладка # LangChain в n8n > Использование LangChain концепций для построения AI цепочек ## LangChain концепции в n8n [Заголовок раздела «LangChain концепции в n8n»](#langchain-концепции-в-n8n) n8n реализует ключевые концепции LangChain через визуальные ноды: Chains Последовательные цепочки обработки Agents Автономные агенты с инструментами Memory Хранение контекста диалога Retrievers Поиск релевантных документов ## Chains (Цепочки) [Заголовок раздела «Chains (Цепочки)»](#chains-цепочки) ### Basic LLM Chain [Заголовок раздела «Basic LLM Chain»](#basic-llm-chain) Простейшая цепочка: prompt → LLM → output. | Компонент | Описание | | ------------------- | ---------------------------- | | **Prompt Template** | Шаблон с переменными | | **LLM** | Языковая модель | | **Output Parser** | Парсинг ответа (опционально) | ### Пример: Классификация текста [Заголовок раздела «Пример: Классификация текста»](#пример-классификация-текста) ```plaintext Prompt Template: "Классифицируй следующий текст по категориям: положительный, отрицательный, нейтральный. Текст: {{ $json.text }} Категория:" Output: "положительный" ``` ### Sequential Chain [Заголовок раздела «Sequential Chain»](#sequential-chain) Последовательные LLM вызовы: ## Prompt Templates [Заголовок раздела «Prompt Templates»](#prompt-templates) ### Переменные в промптах [Заголовок раздела «Переменные в промптах»](#переменные-в-промптах) ```plaintext Системное сообщение: "Ты эксперт по {{ $json.domain }}. Отвечай на {{ $json.language }}." Пользовательское сообщение: "{{ $json.question }}" ``` ### Chat Messages [Заголовок раздела «Chat Messages»](#chat-messages) | Роль | Назначение | | ---------- | ----------------------- | | **System** | Инструкции для модели | | **Human** | Сообщение пользователя | | **AI** | Предыдущий ответ модели | ### Few-Shot Prompting [Заголовок раздела «Few-Shot Prompting»](#few-shot-prompting) ```plaintext Примеры: Вход: "Привет" → Выход: "greeting" Вход: "Сколько стоит?" → Выход: "pricing" Вход: "Не работает!" → Выход: "support" Классифицируй: "{{ $json.message }}" ``` ## Output Parsers [Заголовок раздела «Output Parsers»](#output-parsers) ### Structured Output Parser [Заголовок раздела «Structured Output Parser»](#structured-output-parser) Получение JSON из LLM: ```plaintext Prompt: "Извлеки информацию из текста и верни JSON: { "name": "имя", "email": "email", "phone": "телефон" } Текст: {{ $json.text }}" Output (parsed): { "name": "Иван Петров", "email": "ivan@example.com", "phone": "+7 999 123 4567" } ``` ### Auto-fixing Parser [Заголовок раздела «Auto-fixing Parser»](#auto-fixing-parser) Автоматическое исправление невалидного JSON: ## Retrieval (Поиск) [Заголовок раздела «Retrieval (Поиск)»](#retrieval-поиск) ### Retriever Node [Заголовок раздела «Retriever Node»](#retriever-node) Поиск релевантных документов: ### Конфигурация [Заголовок раздела «Конфигурация»](#конфигурация) | Параметр | Описание | | ------------------- | ---------------------------------- | | **Top K** | Количество документов (default: 4) | | **Score Threshold** | Минимальная релевантность | ## Embeddings [Заголовок раздела «Embeddings»](#embeddings) ### OpenAI Embeddings [Заголовок раздела «OpenAI Embeddings»](#openai-embeddings) ```plaintext Model: text-embedding-3-small Dimensions: 1536 ``` ### Ollama Embeddings [Заголовок раздела «Ollama Embeddings»](#ollama-embeddings) ```plaintext Model: nomic-embed-text Base URL: http://localhost:11434 ``` Совет Для production с большими объёмами используйте локальные embeddings через Ollama. ## Vector Stores [Заголовок раздела «Vector Stores»](#vector-stores) ### Поддерживаемые [Заголовок раздела «Поддерживаемые»](#поддерживаемые) | Store | Описание | | ------------- | ------------------------ | | **Pinecone** | Managed облачный сервис | | **Qdrant** | Open-source, self-hosted | | **Supabase** | PostgreSQL + pgvector | | **Chroma** | Lightweight, embedded | | **In-Memory** | Для тестирования | ### Операции [Заголовок раздела «Операции»](#операции) | Операция | Описание | | ------------ | ------------------ | | **Insert** | Добавить документы | | **Get** | Получить по ID | | **Get Many** | Получить несколько | | **Search** | Векторный поиск | | **Delete** | Удалить документы | ## Document Loaders [Заголовок раздела «Document Loaders»](#document-loaders) ### Загрузка документов [Заголовок раздела «Загрузка документов»](#загрузка-документов) | Loader | Форматы | | ---------- | ---------------- | | **File** | TXT, PDF, DOCX | | **URL** | Web pages | | **GitHub** | Repositories | | **Notion** | Pages, databases | ### Text Splitter [Заголовок раздела «Text Splitter»](#text-splitter) Разбиение на chunks: | Параметр | Описание | | ----------------- | ----------------------------- | | **Chunk Size** | Размер фрагмента (tokens) | | **Chunk Overlap** | Перекрытие между фрагментами | | **Separator** | Разделитель (default: `\n\n`) | ```plaintext Original: 5000 tokens Chunk Size: 500 Overlap: 50 Result: 11 chunks ``` ## Построение RAG Pipeline [Заголовок раздела «Построение RAG Pipeline»](#построение-rag-pipeline) ### 1. Индексирование [Заголовок раздела «1. Индексирование»](#1-индексирование) ### 2. Поиск и генерация [Заголовок раздела «2. Поиск и генерация»](#2-поиск-и-генерация) ### Полный workflow [Заголовок раздела «Полный workflow»](#полный-workflow) ## Паттерны [Заголовок раздела «Паттерны»](#паттерны) ### Summarization Chain [Заголовок раздела «Summarization Chain»](#summarization-chain) ```plaintext Тип: Map-Reduce 1. Map: Summarize each chunk 2. Reduce: Combine summaries Input: 50 page document Output: 1 paragraph summary ``` ### Question Answering [Заголовок раздела «Question Answering»](#question-answering) ```plaintext Тип: Stuff 1. Retrieve relevant chunks 2. Stuff into context 3. Generate answer Prompt: "На основе контекста ответь на вопрос. Контекст: {{ $json.context }} Вопрос: {{ $json.question }} Ответ:" ``` ### Conversational Retrieval [Заголовок раздела «Conversational Retrieval»](#conversational-retrieval) ## Следующие шаги [Заголовок раздела «Следующие шаги»](#следующие-шаги) * [RAG workflows](/ai-mcp/rag/) — построение RAG систем * [AI Agent](/ai-mcp/ai-agent/) — автономные агенты * [MCP](/ai-mcp/mcp/) — Model Context Protocol # LLM модели в n8n > Полный справочник по языковым моделям, поддерживаемым в n8n через LangChain n8n поддерживает **20+ языковых моделей** через интеграцию с LangChain. Эта страница поможет выбрать подходящую модель для вашего проекта. ## Сравнение моделей [Заголовок раздела «Сравнение моделей»](#сравнение-моделей) ### Облачные модели [Заголовок раздела «Облачные модели»](#облачные-модели) | Модель | Провайдер | Контекст | Цена (input/1M) | Скорость | Качество | | --------------------- | --------- | -------- | --------------- | ------------- | -------- | | **GPT-4o** | OpenAI | 128K | $2.50 | Высокая | Отличное | | **GPT-4o-mini** | OpenAI | 128K | $0.15 | Очень высокая | Хорошее | | **Claude 3.5 Sonnet** | Anthropic | 200K | $3.00 | Высокая | Отличное | | **Claude 3 Haiku** | Anthropic | 200K | $0.25 | Очень высокая | Хорошее | | **Gemini 1.5 Pro** | Google | 1M | $1.25 | Высокая | Отличное | | **Gemini 1.5 Flash** | Google | 1M | $0.075 | Очень высокая | Хорошее | | **Mistral Large** | Mistral | 128K | $2.00 | Высокая | Отличное | | **Llama 3.1 70B** | Groq | 128K | $0.59 | Экстремальная | Хорошее | ### Локальные модели (Ollama) [Заголовок раздела «Локальные модели (Ollama)»](#локальные-модели-ollama) | Модель | Размер | RAM | Скорость | Качество | | ------------------ | ------ | ----- | --------- | -------------- | | **Llama 3.2 3B** | 2 GB | 4 GB | Быстрая | Базовое | | **Llama 3.2 11B** | 7 GB | 12 GB | Средняя | Хорошее | | **Mistral 7B** | 4 GB | 8 GB | Быстрая | Хорошее | | **Mixtral 8x7B** | 26 GB | 48 GB | Медленная | Отличное | | **Qwen 2.5 7B** | 4 GB | 8 GB | Быстрая | Хорошее | | **DeepSeek Coder** | 7 GB | 12 GB | Средняя | Отличное (код) | *** ## OpenAI [Заголовок раздела «OpenAI»](#openai) ### Настройка Credentials [Заголовок раздела «Настройка Credentials»](#настройка-credentials) 1. Получите API ключ на [platform.openai.com](https://platform.openai.com/api-keys) 2. В n8n: **Settings** → **Credentials** → **Add Credential** → **OpenAI API** 3. Вставьте ключ ### Доступные модели [Заголовок раздела «Доступные модели»](#доступные-модели) ```plaintext gpt-4o # Лучшая модель OpenAI gpt-4o-mini # Быстрая и дешёвая gpt-4-turbo # Предыдущее поколение gpt-3.5-turbo # Устаревшая, но дешёвая o1-preview # Модель с reasoning o1-mini # Быстрая reasoning модель ``` ### Рекомендации [Заголовок раздела «Рекомендации»](#рекомендации) Для чат-ботов **gpt-4o-mini** — баланс цены и качества Для сложных задач **gpt-4o** — максимальное качество Для кода **gpt-4o** или **o1-mini** для рассуждений Совет Используйте `gpt-4o-mini` для большинства задач — он в 10 раз дешевле `gpt-4o` при сравнимом качестве для простых задач. *** ## Anthropic (Claude) [Заголовок раздела «Anthropic (Claude)»](#anthropic-claude) ### Настройка Credentials [Заголовок раздела «Настройка Credentials»](#настройка-credentials-1) 1. Получите ключ на [console.anthropic.com](https://console.anthropic.com) 2. В n8n: **Credentials** → **Anthropic API** 3. Вставьте ключ ### Доступные модели [Заголовок раздела «Доступные модели»](#доступные-модели-1) ```plaintext claude-3-5-sonnet-latest # Лучшая модель для большинства задач claude-3-5-haiku-latest # Быстрая и дешёвая claude-3-opus-latest # Максимальное качество (дорогая) ``` ### Особенности Claude [Заголовок раздела «Особенности Claude»](#особенности-claude) * **Thinking mode** — модель показывает ход рассуждений * **200K контекст** — больше чем у OpenAI * **Лучше для длинных документов** и анализа ```javascript // Включение thinking mode в настройках модели: // Extended Thinking: true // Max Tokens to think: 10000 ``` Заметка Claude 3.5 Sonnet часто показывает лучшие результаты в программировании и анализе текстов по сравнению с GPT-4o. *** ## Google (Gemini) [Заголовок раздела «Google (Gemini)»](#google-gemini) ### Настройка Credentials [Заголовок раздела «Настройка Credentials»](#настройка-credentials-2) 1. Получите ключ на [aistudio.google.com](https://aistudio.google.com/apikey) 2. В n8n: **Credentials** → **Google AI API** 3. Вставьте ключ ### Доступные модели [Заголовок раздела «Доступные модели»](#доступные-модели-2) ```plaintext gemini-1.5-pro # Основная модель gemini-1.5-flash # Быстрая версия gemini-1.5-flash-8b # Самая быстрая gemini-2.0-flash # Новейшая (экспериментальная) ``` ### Преимущества Gemini [Заголовок раздела «Преимущества Gemini»](#преимущества-gemini) * **1 миллион токенов контекста** — уникальная возможность * **Multimodal** — работает с изображениями и видео * **Бесплатный tier** — до 60 запросов в минуту Совет Gemini 1.5 Pro с контекстом 1M токенов идеален для анализа длинных документов, книг или кодовых баз. *** ## Ollama (локальные модели) [Заголовок раздела «Ollama (локальные модели)»](#ollama-локальные-модели) ### Установка [Заголовок раздела «Установка»](#установка) * Linux ```bash curl -fsSL https://ollama.com/install.sh | sh ollama serve & ``` * macOS ```bash # Скачайте с https://ollama.com/download # Или через Homebrew: brew install ollama ollama serve ``` * Windows ```powershell # Скачайте installer с https://ollama.com/download # После установки запустите Ollama из меню ``` ### Загрузка моделей [Заголовок раздела «Загрузка моделей»](#загрузка-моделей) ```bash # Рекомендуемые модели: ollama pull llama3.2 # 3B, быстрая ollama pull llama3.1:8b # 8B, баланс ollama pull mistral # 7B, хорошее качество ollama pull qwen2.5:7b # 7B, отлично для русского ollama pull deepseek-coder # Для программирования ``` ### Настройка в n8n [Заголовок раздела «Настройка в n8n»](#настройка-в-n8n) 1. **Credentials** → **Ollama API** 2. Base URL: `http://localhost:11434` (или IP сервера) 3. В ноде выберите загруженную модель ### Когда использовать Ollama [Заголовок раздела «Когда использовать Ollama»](#когда-использовать-ollama) * Конфиденциальные данные (не уходят в облако) * Экономия на API запросах * Офлайн работа * Тестирование и разработка Осторожно Локальные модели требуют GPU для комфортной работы. На CPU крупные модели (>7B) будут работать медленно. *** ## Groq (быстрые inference) [Заголовок раздела «Groq (быстрые inference)»](#groq-быстрые-inference) Groq предоставляет **самый быстрый** inference для open-source моделей. ### Настройка [Заголовок раздела «Настройка»](#настройка) 1. Получите ключ на [console.groq.com](https://console.groq.com) 2. В n8n: **Credentials** → **Groq API** ### Доступные модели [Заголовок раздела «Доступные модели»](#доступные-модели-3) ```plaintext llama-3.3-70b-versatile # Лучшее качество llama-3.1-8b-instant # Самая быстрая mixtral-8x7b-32768 # Хороший баланс ``` ### Преимущества [Заголовок раздела «Преимущества»](#преимущества) * **Скорость**: до 700 токенов/сек (vs \~50 у OpenAI) * **Цена**: дешевле OpenAI в 3-5 раз * **Качество**: open-source модели уровня GPT-3.5 Совет Groq идеален для real-time приложений и чат-ботов, где важна скорость ответа. *** ## Mistral [Заголовок раздела «Mistral»](#mistral) ### Настройка [Заголовок раздела «Настройка»](#настройка-1) 1. Получите ключ на [console.mistral.ai](https://console.mistral.ai) 2. В n8n: **Credentials** → **Mistral Cloud API** ### Доступные модели [Заголовок раздела «Доступные модели»](#доступные-модели-4) ```plaintext mistral-large-latest # Топовая модель mistral-medium-latest # Баланс mistral-small-latest # Быстрая и дешёвая codestral-latest # Для программирования ``` ### Особенности [Заголовок раздела «Особенности»](#особенности) * Европейский провайдер (GDPR compliant) * Отличное качество для своей цены * Сильная поддержка кода *** ## Azure OpenAI [Заголовок раздела «Azure OpenAI»](#azure-openai) Для enterprise-клиентов с требованиями к compliance. ### Настройка [Заголовок раздела «Настройка»](#настройка-2) 1. Создайте ресурс Azure OpenAI в [portal.azure.com](https://portal.azure.com) 2. Получите endpoint и API key 3. В n8n: **Credentials** → **Azure OpenAI API** * Resource Name * API Key * API Version ### Преимущества [Заголовок раздела «Преимущества»](#преимущества-1) * SLA 99.9% * Данные остаются в вашем регионе * Enterprise security *** ## Выбор модели по задаче [Заголовок раздела «Выбор модели по задаче»](#выбор-модели-по-задаче) ### Чат-боты и ассистенты [Заголовок раздела «Чат-боты и ассистенты»](#чат-боты-и-ассистенты) | Приоритет | Рекомендация | | --------- | ------------------------- | | Качество | Claude 3.5 Sonnet, GPT-4o | | Баланс | GPT-4o-mini, Gemini Flash | | Скорость | Groq Llama 3.1 8B | | Бюджет | Ollama + Llama 3.2 | ### Программирование [Заголовок раздела «Программирование»](#программирование) | Задача | Рекомендация | | -------------------- | ------------------- | | Code review | Claude 3.5 Sonnet | | Генерация кода | GPT-4o, Codestral | | Дебаг | Claude 3.5, o1-mini | | Локальная разработка | DeepSeek Coder | ### Анализ документов [Заголовок раздела «Анализ документов»](#анализ-документов) | Размер документа | Рекомендация | | ---------------- | ----------------- | | До 50K токенов | GPT-4o-mini | | До 200K токенов | Claude 3.5 Sonnet | | До 1M токенов | Gemini 1.5 Pro | ### RAG и поиск [Заголовок раздела «RAG и поиск»](#rag-и-поиск) | Требование | Рекомендация | | ------------------ | ------------------ | | Качество ответов | Claude 3.5, GPT-4o | | Скорость | Groq, Gemini Flash | | Конфиденциальность | Ollama + Llama 3.1 | *** ## Лучшие практики [Заголовок раздела «Лучшие практики»](#лучшие-практики) ### 1. Начинайте с дешёвых моделей [Заголовок раздела «1. Начинайте с дешёвых моделей»](#1-начинайте-с-дешёвых-моделей) ```javascript // Сначала тестируйте с gpt-4o-mini // Переключайтесь на gpt-4o только если качество недостаточно ``` ### 2. Используйте fallback [Заголовок раздела «2. Используйте fallback»](#2-используйте-fallback) ```javascript // Если основная модель недоступна — переключение на резервную // В n8n: Error Workflow → другой AI Agent с Ollama ``` ### 3. Кэшируйте ответы [Заголовок раздела «3. Кэшируйте ответы»](#3-кэшируйте-ответы) ```javascript // Одинаковые запросы → одинаковые ответы // Храните результаты в Redis или базе данных ``` ### 4. Мониторьте расходы [Заголовок раздела «4. Мониторьте расходы»](#4-мониторьте-расходы) * OpenAI: [platform.openai.com/usage](https://platform.openai.com/usage) * Anthropic: [console.anthropic.com/usage](https://console.anthropic.com/settings/usage) * Установите limits на API ключах *** ## Смена модели [Заголовок раздела «Смена модели»](#смена-модели) Все LLM ноды в n8n имеют одинаковый интерфейс. Для смены модели: 1. Отключите текущую Model ноду 2. Добавьте новую (например, Anthropic вместо OpenAI) 3. Подключите к Agent/Chain 4. Настройте credentials Заметка Системные промпты и настройки Agent сохраняются — меняется только модель! # Model Context Protocol > Интеграция MCP серверов в n8n для расширения возможностей AI агентов ## Что такое MCP? [Заголовок раздела «Что такое MCP?»](#что-такое-mcp) **Model Context Protocol (MCP)** — это открытый протокол для подключения AI моделей к внешним источникам данных и инструментам. ## Преимущества MCP [Заголовок раздела «Преимущества MCP»](#преимущества-mcp) Стандартизация Единый протокол для всех интеграций Безопасность Контролируемый доступ к ресурсам Расширяемость Легко добавлять новые серверы Экосистема Большое сообщество и готовые серверы ## MCP в n8n [Заголовок раздела «MCP в n8n»](#mcp-в-n8n) ### MCP Client Tool [Заголовок раздела «MCP Client Tool»](#mcp-client-tool) Нода для подключения MCP серверов к AI Agent: ### Настройка [Заголовок раздела «Настройка»](#настройка) 1. **Добавьте AI Agent** Создайте AI Agent ноду с моделью 2. **Добавьте MCP Client Tool** Подключите к Tools входу агента 3. **Настройте подключение** Укажите способ запуска MCP сервера 4. **Протестируйте** Запустите агента с запросом ## Способы подключения [Заголовок раздела «Способы подключения»](#способы-подключения) ### SSE (Server-Sent Events) [Заголовок раздела «SSE (Server-Sent Events)»](#sse-server-sent-events) Для MCP серверов, работающих по HTTP: | Параметр | Описание | | ----------- | --------------------------------------------------- | | **SSE URL** | URL сервера (например, `http://localhost:3000/sse`) | | **API Key** | Ключ авторизации (если требуется) | ### STDIO (Standard I/O) [Заголовок раздела «STDIO (Standard I/O)»](#stdio-standard-io) Для локальных MCP серверов: | Параметр | Описание | | --------------- | ------------------------------------------------------------------ | | **Command** | Команда запуска (например, `npx`) | | **Arguments** | Аргументы (например, `-y @modelcontextprotocol/server-filesystem`) | | **Environment** | Переменные окружения | Совет STDIO подходит для локальных серверов. SSE — для удалённых и production. ## Популярные MCP серверы [Заголовок раздела «Популярные MCP серверы»](#популярные-mcp-серверы) ### Файловая система [Заголовок раздела «Файловая система»](#файловая-система) ```bash npx -y @modelcontextprotocol/server-filesystem /path/to/allowed/directory ``` Возможности: * Чтение файлов * Запись файлов * Листинг директорий * Поиск по содержимому ### PostgreSQL [Заголовок раздела «PostgreSQL»](#postgresql) ```bash npx -y @modelcontextprotocol/server-postgres postgresql://user:pass@host:5432/db ``` Возможности: * Выполнение SQL запросов * Описание схемы * Просмотр таблиц ### GitHub [Заголовок раздела «GitHub»](#github) ```bash npx -y @modelcontextprotocol/server-github ``` Требует: `GITHUB_PERSONAL_ACCESS_TOKEN` Возможности: * Работа с репозиториями * Issues и Pull Requests * Поиск кода ### Slack [Заголовок раздела «Slack»](#slack) ```bash npx -y @modelcontextprotocol/server-slack ``` Требует: `SLACK_BOT_TOKEN`, `SLACK_TEAM_ID` Возможности: * Отправка сообщений * Чтение каналов * Поиск ### Web Browser (Puppeteer) [Заголовок раздела «Web Browser (Puppeteer)»](#web-browser-puppeteer) ```bash npx -y @modelcontextprotocol/server-puppeteer ``` Возможности: * Навигация по страницам * Скриншоты * Извлечение контента ## Конфигурация в n8n [Заголовок раздела «Конфигурация в n8n»](#конфигурация-в-n8n) ### Пример: Filesystem Server [Заголовок раздела «Пример: Filesystem Server»](#пример-filesystem-server) ```plaintext Connection Type: STDIO Command: npx Arguments: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/documents"] ``` ### Пример: PostgreSQL Server [Заголовок раздела «Пример: PostgreSQL Server»](#пример-postgresql-server) ```plaintext Connection Type: STDIO Command: npx Arguments: ["-y", "@modelcontextprotocol/server-postgres"] Environment: DATABASE_URL: postgresql://user:pass@localhost:5432/mydb ``` ### Пример: SSE Server [Заголовок раздела «Пример: SSE Server»](#пример-sse-server) ```plaintext Connection Type: SSE URL: https://my-mcp-server.example.com/sse Headers: Authorization: Bearer my-api-key ``` ## Безопасность [Заголовок раздела «Безопасность»](#безопасность) ### Ограничение доступа [Заголовок раздела «Ограничение доступа»](#ограничение-доступа) * Указывайте минимально необходимые пути * Используйте read-only режим где возможно * Ограничивайте SQL операции ### Переменные окружения [Заголовок раздела «Переменные окружения»](#переменные-окружения) ```plaintext ❌ Не храните секреты в workflow ✅ Используйте переменные окружения n8n ``` ### Sandboxing [Заголовок раздела «Sandboxing»](#sandboxing) MCP серверы работают в отдельных процессах, но: * Filesystem сервер имеет доступ к указанным путям * Database сервер может выполнять любые SQL * Puppeteer сервер может посещать любые сайты ## Примеры workflows [Заголовок раздела «Примеры workflows»](#примеры-workflows) ### Документация Assistant [Заголовок раздела «Документация Assistant»](#документация-assistant) Агент читает документацию из файлов и отвечает на вопросы. ### Database Analyst [Заголовок раздела «Database Analyst»](#database-analyst) Агент анализирует данные, выполняя SQL запросы. ### Web Researcher [Заголовок раздела «Web Researcher»](#web-researcher) Агент собирает информацию из веб-страниц. ## Создание своего MCP сервера [Заголовок раздела «Создание своего MCP сервера»](#создание-своего-mcp-сервера) ### TypeScript SDK [Заголовок раздела «TypeScript SDK»](#typescript-sdk) ```typescript import { Server } from '@modelcontextprotocol/sdk/server'; const server = new Server({ name: 'my-server', version: '1.0.0' }); server.setRequestHandler('tools/list', async () => ({ tools: [{ name: 'my_tool', description: 'My custom tool', inputSchema: { type: 'object', properties: {} } }] })); server.setRequestHandler('tools/call', async (request) => { // Handle tool call return { content: [{ type: 'text', text: 'Result' }] }; }); ``` ### Python SDK [Заголовок раздела «Python SDK»](#python-sdk) ```python from mcp.server import Server server = Server("my-server") @server.list_tools() async def handle_list_tools(): return [ {"name": "my_tool", "description": "My custom tool"} ] @server.call_tool() async def handle_call_tool(name: str, arguments: dict): return {"content": [{"type": "text", "text": "Result"}]} ``` ## Ресурсы [Заголовок раздела «Ресурсы»](#ресурсы) Дополнительная документация по MCP: | Ресурс | Описание | | ----------------------------------------------------- | ------------------------------ | | [mcpdoc.ru](https://mcpdoc.ru) | Русскоязычная документация MCP | | [MCP Spec](https://spec.modelcontextprotocol.io) | Спецификация протокола | | [GitHub MCP](https://github.com/modelcontextprotocol) | Официальные серверы | ## Следующие шаги [Заголовок раздела «Следующие шаги»](#следующие-шаги) * [MCP серверы](/ai-mcp/mcp-servers/) — каталог популярных серверов * [RAG](/ai-mcp/rag/) — работа с документами * [AI Agent](/ai-mcp/ai-agent/) — создание агентов # MCP Inspector > Отладка и тестирование MCP серверов — официальный инструмент для разработки и диагностики ## Обзор [Заголовок раздела «Обзор»](#обзор) **MCP Inspector** — официальный инструмент для тестирования и отладки MCP серверов. Он позволяет интерактивно исследовать capabilities сервера, вызывать инструменты и диагностировать проблемы. Заметка MCP Inspector имеет **8,100+ stars** на GitHub и является основным инструментом для разработки MCP серверов. ## Архитектура [Заголовок раздела «Архитектура»](#архитектура) Inspector состоит из двух компонентов: ```plaintext ┌─────────────────────────────────────────────────────────┐ │ MCP Inspector │ ├─────────────────────────┬───────────────────────────────┤ │ MCPI (Client) │ MCPP (Proxy) │ │ React Web UI │ Node.js Server │ │ localhost:6274 │ localhost:6277 │ ├─────────────────────────┼───────────────────────────────┤ │ • Интерактивный UI │ • Протокольный мост │ │ • Просмотр tools │ • Управление транспортами │ │ • Вызов методов │ • Логирование сообщений │ │ • История запросов │ • Авторизация │ └─────────────────────────┴───────────────────────────────┘ │ v ┌─────────────────┐ │ MCP Server │ │ (ваш сервер) │ └─────────────────┘ ``` ## Требования [Заголовок раздела «Требования»](#требования) * **Node.js** >= 22.7.5 * Для некоторых серверов: Python / uvx ## Быстрый старт [Заголовок раздела «Быстрый старт»](#быстрый-старт) ### Базовый запуск [Заголовок раздела «Базовый запуск»](#базовый-запуск) ```bash # Запуск Inspector UI (откроется http://localhost:6274) npx @modelcontextprotocol/inspector # Запуск с конкретным сервером npx @modelcontextprotocol/inspector node build/index.js # Python сервер npx @modelcontextprotocol/inspector uvx mcp-server-fetch ``` ### Передача переменных окружения [Заголовок раздела «Передача переменных окружения»](#передача-переменных-окружения) ```bash # Одна переменная npx @modelcontextprotocol/inspector -e API_KEY=sk-xxx node server.js # Несколько переменных npx @modelcontextprotocol/inspector \ -e API_KEY=sk-xxx \ -e DEBUG=true \ python -m my_server ``` ### Кастомные порты [Заголовок раздела «Кастомные порты»](#кастомные-порты) ```bash # Изменить порты по умолчанию CLIENT_PORT=8080 SERVER_PORT=9000 npx @modelcontextprotocol/inspector node build/index.js ``` ## Web UI интерфейс [Заголовок раздела «Web UI интерфейс»](#web-ui-интерфейс) Resources Просмотр ресурсов сервера Tools Список и вызов инструментов Prompts Тестирование подсказок Logs JSON-RPC сообщения ### Вкладки интерфейса [Заголовок раздела «Вкладки интерфейса»](#вкладки-интерфейса) | Вкладка | Описание | | ----------------- | ----------------------------------- | | **Resources** | Список ресурсов, чтение содержимого | | **Tools** | Вызов инструментов с параметрами | | **Prompts** | Получение prompt с аргументами | | **Messages** | Полный лог JSON-RPC коммуникации | | **Notifications** | Server notifications | ## CLI режим [Заголовок раздела «CLI режим»](#cli-режим) Для автоматизации и скриптов используйте CLI режим: ### Получение списка tools [Заголовок раздела «Получение списка tools»](#получение-списка-tools) ```bash npx @modelcontextprotocol/inspector --cli node build/index.js \ --method tools/list ``` ### Вызов инструмента [Заголовок раздела «Вызов инструмента»](#вызов-инструмента) ```bash npx @modelcontextprotocol/inspector --cli node build/index.js \ --method tools/call \ --tool-name get_weather \ --tool-arg location=Moscow ``` ### Работа с ресурсами [Заголовок раздела «Работа с ресурсами»](#работа-с-ресурсами) ```bash # Список ресурсов npx @modelcontextprotocol/inspector --cli node build/index.js \ --method resources/list # Чтение ресурса npx @modelcontextprotocol/inspector --cli node build/index.js \ --method resources/read \ --resource-uri "file:///project/config.json" ``` ### Подключение к HTTP серверу [Заголовок раздела «Подключение к HTTP серверу»](#подключение-к-http-серверу) ```bash npx @modelcontextprotocol/inspector --cli https://my-server.example.com \ --transport http \ --method tools/list ``` ## Файл конфигурации [Заголовок раздела «Файл конфигурации»](#файл-конфигурации) Создайте `mcp.json` для сохранения настроек серверов: ```json { "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/docs"], "env": {} }, "fetch": { "command": "uvx", "args": ["mcp-server-fetch"] }, "remote-api": { "type": "sse", "url": "http://localhost:3000/sse" }, "http-server": { "type": "streamable-http", "url": "http://localhost:3001/mcp" } } } ``` Запуск с конфигурацией: ```bash # Запустить конкретный сервер из конфига npx @modelcontextprotocol/inspector --config mcp.json --server filesystem # Или выбрать в UI npx @modelcontextprotocol/inspector --config mcp.json ``` ## Docker [Заголовок раздела «Docker»](#docker) ### Запуск в контейнере [Заголовок раздела «Запуск в контейнере»](#запуск-в-контейнере) ```bash docker run --rm \ -p 127.0.0.1:6274:6274 \ -p 127.0.0.1:6277:6277 \ -e HOST=0.0.0.0 \ -e MCP_AUTO_OPEN_ENABLED=false \ ghcr.io/modelcontextprotocol/inspector:latest ``` ### Docker Compose [Заголовок раздела «Docker Compose»](#docker-compose) ```yaml version: "3.8" services: mcp-inspector: image: ghcr.io/modelcontextprotocol/inspector:latest ports: - "127.0.0.1:6274:6274" - "127.0.0.1:6277:6277" environment: - HOST=0.0.0.0 - MCP_AUTO_OPEN_ENABLED=false restart: unless-stopped ``` ### Тестирование локального сервера из Docker [Заголовок раздела «Тестирование локального сервера из Docker»](#тестирование-локального-сервера-из-docker) ```bash # Монтируем сервер и запускаем docker run --rm -it \ -p 6274:6274 \ -p 6277:6277 \ -v /path/to/server:/app/server \ -e HOST=0.0.0.0 \ ghcr.io/modelcontextprotocol/inspector:latest \ node /app/server/build/index.js ``` ## Транспорты [Заголовок раздела «Транспорты»](#транспорты) Inspector поддерживает все MCP транспорты: * stdio **По умолчанию** — запуск сервера как subprocess ```bash npx @modelcontextprotocol/inspector node server.js ``` Использует stdin/stdout для коммуникации. * SSE **Server-Sent Events** — для HTTP серверов ```bash npx @modelcontextprotocol/inspector --transport sse http://localhost:3000/sse ``` Осторожно SSE транспорт deprecated с версии 2025-03-26. Используйте Streamable HTTP. * Streamable HTTP **Рекомендуемый** HTTP транспорт ```bash npx @modelcontextprotocol/inspector --transport http http://localhost:3001/mcp ``` Современный транспорт с поддержкой сессий и OAuth. ## Конфигурация [Заголовок раздела «Конфигурация»](#конфигурация) ### Переменные окружения [Заголовок раздела «Переменные окружения»](#переменные-окружения) | Переменная | Описание | По умолчанию | | ------------------------------- | --------------------- | ------------ | | `CLIENT_PORT` | Порт Web UI | 6274 | | `SERVER_PORT` | Порт Proxy | 6277 | | `HOST` | Bind адрес | 127.0.0.1 | | `MCP_AUTO_OPEN_ENABLED` | Открывать браузер | true | | `MCP_SERVER_REQUEST_TIMEOUT` | Таймаут запроса (ms) | 300000 | | `MCP_REQUEST_MAX_TOTAL_TIMEOUT` | Макс. общий таймаут | 60000 | | `MCP_PROXY_FULL_ADDRESS` | Кастомный адрес proxy | "" | ### Отключение автооткрытия [Заголовок раздела «Отключение автооткрытия»](#отключение-автооткрытия) ```bash MCP_AUTO_OPEN_ENABLED=false npx @modelcontextprotocol/inspector node server.js ``` ## Безопасность [Заголовок раздела «Безопасность»](#безопасность) Осторожно Inspector содержит встроенные механизмы безопасности. Не отключайте их в production. ### Защитные механизмы [Заголовок раздела «Защитные механизмы»](#защитные-механизмы) 1. **Session Token** — генерируется при запуске, требуется для доступа 2. **Localhost Binding** — по умолчанию привязан к 127.0.0.1 3. **DNS Rebinding Protection** — валидация Origin заголовков 4. **CORS Policy** — ограничение cross-origin запросов ### Удалённый доступ [Заголовок раздела «Удалённый доступ»](#удалённый-доступ) Для доступа извне (только для разработки!): ```bash # Разрешить внешние подключения HOST=0.0.0.0 npx @modelcontextprotocol/inspector node server.js ``` Опасно Не открывайте Inspector для внешних подключений в production! Используйте VPN или SSH tunnel. ## Примеры использования [Заголовок раздела «Примеры использования»](#примеры-использования) ### Тестирование Filesystem сервера [Заголовок раздела «Тестирование Filesystem сервера»](#тестирование-filesystem-сервера) ```bash # Запуск npx @modelcontextprotocol/inspector \ npx -y @modelcontextprotocol/server-filesystem /home/user/docs # В UI: # 1. Перейти на вкладку Tools # 2. Выбрать list_directory # 3. Указать path: /home/user/docs # 4. Нажать Execute ``` ### Тестирование Git сервера [Заголовок раздела «Тестирование Git сервера»](#тестирование-git-сервера) ```bash npx @modelcontextprotocol/inspector \ uvx mcp-server-git --repository /path/to/repo # Доступные инструменты: # - git_status # - git_log # - git_diff ``` ### Тестирование Memory сервера [Заголовок раздела «Тестирование Memory сервера»](#тестирование-memory-сервера) ```bash npx @modelcontextprotocol/inspector \ -e MEMORY_FILE_PATH=/tmp/memory.jsonl \ npx -y @modelcontextprotocol/server-memory # Тест: # 1. tools/call → create_entities # 2. tools/call → read_graph ``` ### Отладка кастомного сервера [Заголовок раздела «Отладка кастомного сервера»](#отладка-кастомного-сервера) ```bash # Добавить отладочный вывод DEBUG=* npx @modelcontextprotocol/inspector node --inspect my-server.js # Просмотр всех JSON-RPC сообщений во вкладке Messages ``` ## Типичные проблемы [Заголовок раздела «Типичные проблемы»](#типичные-проблемы) ### Сервер не запускается [Заголовок раздела «Сервер не запускается»](#сервер-не-запускается) ```bash # Проверить команду напрямую node build/index.js # Проверить права на исполнение chmod +x server.js # Проверить зависимости npm install ``` ### Таймаут запросов [Заголовок раздела «Таймаут запросов»](#таймаут-запросов) ```bash # Увеличить таймаут MCP_SERVER_REQUEST_TIMEOUT=600000 npx @modelcontextprotocol/inspector ... ``` ### Порт занят [Заголовок раздела «Порт занят»](#порт-занят) ```bash # Использовать другие порты CLIENT_PORT=7000 SERVER_PORT=7001 npx @modelcontextprotocol/inspector ... ``` ### Проблемы с SSE [Заголовок раздела «Проблемы с SSE»](#проблемы-с-sse) text/event-stream ```bash # Проверить CORS на сервере # Убедиться что endpoint возвращает правильные заголовки: # Cache-Control: no-cache # Connection: keep-alive ``` ## IDE интеграции [Заголовок раздела «IDE интеграции»](#ide-интеграции) MCP Inspector работает совместно с IDE плагинами: ### JetBrains [Заголовок раздела «JetBrains»](#jetbrains) ```json { "mcpServers": { "jetbrains": { "command": "npx", "args": ["-y", "@jetbrains/mcp-proxy"] } } } ``` Поддерживаемые IDE: IntelliJ IDEA, PyCharm, WebStorm, PhpStorm, Rider, Android Studio. ### VS Code [Заголовок раздела «VS Code»](#vs-code) VS Code имеет встроенную поддержку MCP через GitHub Copilot расширение. ### Cursor / Windsurf [Заголовок раздела «Cursor / Windsurf»](#cursor--windsurf) Оба редактора поддерживают MCP нативно через конфигурацию в настройках. ## Best Practices [Заголовок раздела «Best Practices»](#best-practices) ### Разработка [Заголовок раздела «Разработка»](#разработка) 1. **Запускайте Inspector рядом с IDE** — быстрая итерация 2. **Используйте CLI для CI/CD** — автоматизация тестов 3. **Сохраняйте конфиги в mcp.json** — переиспользуемость 4. **Мониторьте Messages** — понимание протокола ### Отладка [Заголовок раздела «Отладка»](#отладка) 1. **Проверяйте capabilities** — что сервер объявляет 2. **Тестируйте edge cases** — пустые входы, большие данные 3. **Следите за ошибками** — JSON-RPC error codes 4. **Логируйте на сервере** — stderr для отладки ### Production [Заголовок раздела «Production»](#production) 1. **Не используйте Inspector в prod** — только для разработки 2. **Тестируйте с реальными данными** — до деплоя 3. **Документируйте tools** — описания и примеры 4. **Версионируйте API** — breaking changes ## Следующие шаги [Заголовок раздела «Следующие шаги»](#следующие-шаги) * [MCP SDK](/ai-mcp/mcp-sdk/) — создание своих серверов * [Официальные серверы](/ai-mcp/mcp-servers-official/) — готовые решения * [n8n MCP серверы](/ai-mcp/mcp-n8n-servers/) — интеграция с n8n # n8n MCP серверы > Интеграция n8n с Model Context Protocol — два подхода для управления workflows через AI ## Обзор [Заголовок раздела «Обзор»](#обзор) Для интеграции n8n с MCP доступны два community-решения с разными подходами: mcp-n8n-server Минималистичный, webhook-ориентированный **4 инструмента** | npm пакет | n8n Cloud n8n-mcp Полнофункциональный, CRUD-операции **14 инструментов** | Docker | Health checks ## Сравнение [Заголовок раздела «Сравнение»](#сравнение) | Характеристика | mcp-n8n-server | n8n-mcp | | --------------- | ------------------------------- | --------------- | | **Автор** | Ahmad Soliman | sonnd08 | | **Язык** | TypeScript | JavaScript | | **Инструменты** | 4 | 14 | | **npm пакет** | `@ahmad.soliman/mcp-n8n-server` | — | | **Docker** | — | Да | | **n8n Cloud** | Да (PROJECT\_ID) | — | | **Node.js** | >= 18 | >= 22 | | **Архитектура** | Монолитная | Модульная | | **Transport** | stdio | Streamable HTTP | *** ## mcp-n8n-server [Заголовок раздела «mcp-n8n-server»](#mcp-n8n-server) **GitHub:** [ahmadsoliman/mcp-n8n-server](https://github.com/ahmadsoliman/mcp-n8n-server) **npm:** `@ahmad.soliman/mcp-n8n-server` Легковесный MCP сервер для запуска n8n workflows через webhooks. ### Инструменты [Заголовок раздела «Инструменты»](#инструменты) | Инструмент | Описание | Параметры | | ------------------------ | ----------------------------- | ------------------ | | `list_workflows` | Получить все workflows | — | | `list_workflow_webhooks` | Получить webhooks из workflow | `id` (workflow ID) | | `call_webhook_get` | Вызвать webhook GET-запросом | `url` | | `call_webhook_post` | Вызвать webhook POST-запросом | `url`, `data` | ### Установка [Заголовок раздела «Установка»](#установка) ```bash # Глобальная установка npm install -g @ahmad.soliman/mcp-n8n-server # Или через npx (без установки) npx -y @ahmad.soliman/mcp-n8n-server ``` ### Переменные окружения [Заголовок раздела «Переменные окружения»](#переменные-окружения) ```env # URL n8n сервера (обязательно) N8N_HOST_URL=https://your-n8n-instance.com # API ключ (обязательно) N8N_API_KEY=your_api_key_here # Project ID для n8n Cloud (опционально) PROJECT_ID=your_project_id_here ``` ### Конфигурация Claude Desktop [Заголовок раздела «Конфигурация Claude Desktop»](#конфигурация-claude-desktop) ```json { "mcpServers": { "n8n": { "command": "npx", "args": ["-y", "@ahmad.soliman/mcp-n8n-server"], "env": { "N8N_HOST_URL": "https://your-n8n-instance.com", "N8N_API_KEY": "your_api_key", "PROJECT_ID": "" } } } } ``` ### Примеры использования [Заголовок раздела «Примеры использования»](#примеры-использования) **Получить список workflows:** ```plaintext Пользователь: "Покажи все мои n8n workflows" Claude: [вызывает list_workflows] ``` **Найти webhooks в workflow:** ```plaintext Пользователь: "Какие webhooks есть в workflow 'Order Processing'?" Claude: [вызывает list_workflow_webhooks с id workflow] ``` **Вызвать webhook с данными:** ```plaintext Пользователь: "Отправь заказ customer123 на обработку" Claude: [вызывает call_webhook_post с данными заказа] ``` ### Идеально для [Заголовок раздела «Идеально для»](#идеально-для) * Быстрого старта с n8n + AI * Запуска существующих workflows * Пользователей n8n Cloud * Webhook-центричных сценариев *** ## n8n-mcp [Заголовок раздела «n8n-mcp»](#n8n-mcp) **GitHub:** [sonnd08/n8n-mcp](https://github.com/sonnd08/n8n-mcp) Полнофункциональный MCP сервер с полным CRUD для n8n. ### Инструменты [Заголовок раздела «Инструменты»](#инструменты-1) #### Управление Workflows (8 инструментов) [Заголовок раздела «Управление Workflows (8 инструментов)»](#управление-workflows-8-инструментов) | Инструмент | Описание | Параметры | | --------------------- | ----------------------- | ----------------------------- | | `list_workflows` | Список всех workflows | `limit` (default: 50) | | `get_workflow` | Получить workflow по ID | `workflowId` (required) | | `create_workflow` | Создать новый workflow | `name`, `nodes` (required) | | `update_workflow` | Обновить workflow | `workflowId`, `name`, `nodes` | | `delete_workflow` | Удалить workflow | `workflowId` (required) | | `activate_workflow` | Активировать workflow | `workflowId` (required) | | `deactivate_workflow` | Деактивировать workflow | `workflowId` (required) | | `execute_workflow` | Запустить workflow | `workflowId`, `inputData` | #### Управление Executions (2 инструмента) [Заголовок раздела «Управление Executions (2 инструмента)»](#управление-executions-2-инструмента) | Инструмент | Описание | Параметры | | ----------------- | ----------------- | ------------------------------- | | `list_executions` | Список выполнений | `limit` (default: 10, max: 100) | | `get_execution` | Детали выполнения | `executionId` (required) | #### Управление Credentials (2 инструмента) [Заголовок раздела «Управление Credentials (2 инструмента)»](#управление-credentials-2-инструмента) | Инструмент | Описание | Параметры | | ------------------- | ------------------ | --------------------------------- | | `list_credentials` | Список credentials | `limit` (default: 50) | | `create_credential` | Создать credential | `name`, `type`, `data` (required) | #### Системные (2 инструмента) [Заголовок раздела «Системные (2 инструмента)»](#системные-2-инструмента) | Инструмент | Описание | Параметры | | ------------ | --------------------- | --------- | | `self_test` | Проверить подключение | — | | `list_nodes` | Список типов узлов | — | ### Установка [Заголовок раздела «Установка»](#установка-1) ```bash # Клонирование git clone https://github.com/sonnd08/n8n-mcp cd n8n-mcp # Установка зависимостей npm install # Конфигурация cp .env.example .env ``` ### Переменные окружения [Заголовок раздела «Переменные окружения»](#переменные-окружения-1) ```env # API ключ (обязательно) N8N_API_KEY=your_api_key_here # URL n8n сервера N8N_BASE_URL=http://localhost:5678 # Порт MCP сервера MCP_PORT=3001 ``` ### Запуск [Заголовок раздела «Запуск»](#запуск) ```bash # Стандартный запуск npm start # С debug выводом DEBUG=1 node index.js # Development режим npm run dev ``` ### Конфигурация Claude Desktop [Заголовок раздела «Конфигурация Claude Desktop»](#конфигурация-claude-desktop-1) ```json { "mcpServers": { "n8n-full": { "command": "node", "args": ["index.js"], "cwd": "/path/to/n8n-mcp", "env": { "N8N_BASE_URL": "http://localhost:5678", "N8N_API_KEY": "your-n8n-api-key" } } } } ``` ### Docker [Заголовок раздела «Docker»](#docker) **Dockerfile:** ```dockerfile FROM node:22-alpine WORKDIR /app COPY package*.json ./ RUN npm ci --only=production COPY . . EXPOSE 3001 CMD ["node", "index.js"] ``` **Docker Compose:** ```yaml version: '3.8' services: n8n-mcp: build: . container_name: n8n-mcp-server restart: unless-stopped ports: - "3001:3001" environment: - N8N_BASE_URL=http://n8n:5678 - N8N_API_KEY=${N8N_API_KEY} healthcheck: test: ["CMD", "wget", "--spider", "http://localhost:3001/health"] interval: 30s timeout: 10s retries: 3 ``` ### Примеры использования [Заголовок раздела «Примеры использования»](#примеры-использования-1) **Создание workflow через AI:** ```plaintext Пользователь: "Создай workflow для отправки email при получении webhook" Claude: [вызывает create_workflow] { "name": "Email on Webhook", "nodes": [ { "name": "Webhook Trigger", "type": "n8n-nodes-base.webhook", "position": [100, 200], "parameters": { "path": "email-trigger", "httpMethod": "POST" } }, { "name": "Send Email", "type": "n8n-nodes-base.emailSend", "position": [300, 200], "parameters": { "toEmail": "{{$json.email}}", "subject": "New webhook received" } } ] } ``` **Мониторинг выполнений:** ```plaintext Пользователь: "Покажи последние 5 выполнений workflows" Claude: [вызывает list_executions с limit: 5] ``` **Диагностика подключения:** ```plaintext Пользователь: "Проверь подключение к n8n" Claude: [вызывает self_test] Результат: { "success": true, "tests": { "list_workflows": "PASS", "get_workflow": "PASS", "list_executions": "PASS", "create_workflow": "PASS" }, "successRate": "100%" } ``` ### Идеально для [Заголовок раздела «Идеально для»](#идеально-для-1) * Полного управления n8n через AI * DevOps и автоматизации * Production deployments * Создания workflows из chat *** ## Выбор решения [Заголовок раздела «Выбор решения»](#выбор-решения) * mcp-n8n-server **Выбирайте если:** * Нужен быстрый старт * Используете n8n Cloud * Основная задача — запуск workflows через webhooks * Предпочитаете npm пакеты ```bash npx -y @ahmad.soliman/mcp-n8n-server ``` * n8n-mcp **Выбирайте если:** * Нужно полное управление workflows (CRUD) * Планируете production deployment * Хотите создавать workflows через AI * Нужны health checks и мониторинг ```bash git clone https://github.com/sonnd08/n8n-mcp cd n8n-mcp && npm install && npm start ``` ### Таблица выбора [Заголовок раздела «Таблица выбора»](#таблица-выбора) | Сценарий | Рекомендация | | ---------------------------- | -------------- | | Быстрый старт | mcp-n8n-server | | Полное управление | n8n-mcp | | n8n Cloud | mcp-n8n-server | | Docker deployment | n8n-mcp | | Webhook-центричные workflows | mcp-n8n-server | | Создание workflows через AI | n8n-mcp | | Production с мониторингом | n8n-mcp | *** ## Полная среда с Docker [Заголовок раздела «Полная среда с Docker»](#полная-среда-с-docker) Развёртывание n8n + MCP сервера вместе: ```yaml version: '3.8' services: n8n: image: n8nio/n8n container_name: n8n restart: unless-stopped ports: - "5678:5678" environment: - N8N_BASIC_AUTH_ACTIVE=true - N8N_BASIC_AUTH_USER=admin - N8N_BASIC_AUTH_PASSWORD=password - N8N_API_ENABLED=true volumes: - n8n_data:/home/node/.n8n n8n-mcp: build: ./n8n-mcp container_name: n8n-mcp-server restart: unless-stopped ports: - "3001:3001" environment: - N8N_BASE_URL=http://n8n:5678 - N8N_API_KEY=${N8N_API_KEY} depends_on: - n8n healthcheck: test: ["CMD", "curl", "-f", "http://localhost:3001/health"] interval: 30s timeout: 10s retries: 3 volumes: n8n_data: ``` ## Получение API ключа n8n [Заголовок раздела «Получение API ключа n8n»](#получение-api-ключа-n8n) 1. Откройте n8n Settings → API 2. Создайте новый API ключ 3. Скопируйте ключ и добавьте в переменные окружения Осторожно Храните API ключ безопасно! Не коммитьте `.env` файлы в репозиторий. ## Безопасность [Заголовок раздела «Безопасность»](#безопасность) ### Рекомендации [Заголовок раздела «Рекомендации»](#рекомендации) 1. **Ограничьте права API ключа** — используйте minimum необходимых разрешений 2. **Используйте HTTPS** — для remote n8n инстансов 3. **Network isolation** — разместите MCP сервер в той же сети что и n8n 4. **Логирование** — включите логи для аудита операций ### Sensitive workflows [Заголовок раздела «Sensitive workflows»](#sensitive-workflows) ```json { "mcpServers": { "n8n": { "env": { "N8N_API_KEY": "${N8N_API_KEY}" } } } } ``` Используйте переменные окружения вместо hardcoded значений. ## Troubleshooting [Заголовок раздела «Troubleshooting»](#troubleshooting) ### Ошибка подключения [Заголовок раздела «Ошибка подключения»](#ошибка-подключения) ```bash # Проверьте доступность n8n curl http://localhost:5678/healthz # Проверьте API ключ curl -H "X-N8N-API-KEY: your_key" http://localhost:5678/api/v1/workflows ``` ### Workflow не запускается [Заголовок раздела «Workflow не запускается»](#workflow-не-запускается) 1. Убедитесь что workflow активирован 2. Проверьте что webhook настроен правильно 3. Проверьте логи n8n ### MCP сервер не отвечает [Заголовок раздела «MCP сервер не отвечает»](#mcp-сервер-не-отвечает) ```bash # Для n8n-mcp — проверить health curl http://localhost:3001/health # Для mcp-n8n-server — проверить процесс ps aux | grep mcp-n8n-server ``` ## Следующие шаги [Заголовок раздела «Следующие шаги»](#следующие-шаги) * [Протокол MCP](/ai-mcp/mcp-protocol/) — основы протокола * [MCP SDK](/ai-mcp/mcp-sdk/) — создание своих серверов * [MCP Inspector](/ai-mcp/mcp-inspector/) — отладка серверов # Протокол MCP > Архитектура и спецификация Model Context Protocol — открытого стандарта для интеграции AI с внешними системами ## Обзор протокола [Заголовок раздела «Обзор протокола»](#обзор-протокола) **Model Context Protocol (MCP)** — это открытый стандарт для подключения AI-приложений к внешним источникам данных и инструментам. MCP можно представить как “USB-C порт для AI” — универсальный коннектор между любым AI-приложением и любым совместимым сервером. Заметка MCP разработан Anthropic и поддерживается сообществом. Спецификация доступна на [spec.modelcontextprotocol.io](https://spec.modelcontextprotocol.io) ## Архитектура Client-Host-Server [Заголовок раздела «Архитектура Client-Host-Server»](#архитектура-client-host-server) MCP использует трёхуровневую архитектуру: ### Компоненты [Заголовок раздела «Компоненты»](#компоненты) | Компонент | Роль | Примеры | | ---------- | ------------------------------------ | ------------------------------ | | **Host** | Контейнер и координатор клиентов | Claude Desktop, n8n, VS Code | | **Client** | Поддерживает соединение с сервером | Встроен в Host | | **Server** | Предоставляет контекст и возможности | Filesystem, PostgreSQL, GitHub | ### Host (Хост) [Заголовок раздела «Host (Хост)»](#host-хост) Хост-процесс выполняет: * Создание и управление клиентами * Контроль разрешений и жизненного цикла * Применение политик безопасности * Координацию AI/LLM интеграции * Агрегацию контекста от клиентов ### Client (Клиент) [Заголовок раздела «Client (Клиент)»](#client-клиент) Каждый клиент: * Устанавливает изолированную сессию с сервером * Выполняет обмен capabilities * Маршрутизирует JSON-RPC сообщения * Управляет подписками и уведомлениями * Поддерживает границы безопасности между серверами ### Server (Сервер) [Заголовок раздела «Server (Сервер)»](#server-сервер) Серверы предоставляют: * Resources (ресурсы) — данные для контекста * Tools (инструменты) — действия для AI * Prompts (подсказки) — шаблоны взаимодействия ## Три примитива MCP [Заголовок раздела «Три примитива MCP»](#три-примитива-mcp) Tools **Model-controlled** — LLM решает когда использовать Resources **Application-controlled** — приложение определяет использование Prompts **User-controlled** — требует явного вызова пользователем ### Tools (Инструменты) [Заголовок раздела «Tools (Инструменты)»](#tools-инструменты) Выполняемые функции, которые AI может вызывать: ```json { "name": "get_weather", "title": "Weather Information", "description": "Get current weather for a location", "inputSchema": { "type": "object", "properties": { "location": { "type": "string", "description": "City name or zip code" } }, "required": ["location"] } } ``` **Протокольные операции:** | Метод | Описание | | ------------ | -------------------------------------- | | `tools/list` | Получить список доступных инструментов | | `tools/call` | Вызвать инструмент с параметрами | ### Resources (Ресурсы) [Заголовок раздела «Resources (Ресурсы)»](#resources-ресурсы) Пассивные источники данных, предоставляющие контекст: ```json { "uri": "file:///project/src/main.rs", "name": "main.rs", "title": "Application Main File", "description": "Primary entry point", "mimeType": "text/x-rust" } ``` **Протокольные операции:** | Метод | Описание | | -------------------------- | ---------------------------------------- | | `resources/list` | Список доступных ресурсов | | `resources/templates/list` | Шаблоны ресурсов (параметризованные URI) | | `resources/read` | Получить содержимое ресурса | | `resources/subscribe` | Подписаться на изменения | **URI схемы:** * `file://` — файловая система * `https://` — веб-ресурсы * `git://` — Git репозитории * Кастомные схемы по RFC3986 ### Prompts (Подсказки) [Заголовок раздела «Prompts (Подсказки)»](#prompts-подсказки) Переиспользуемые шаблоны для взаимодействия с LLM: ```json { "name": "code_review", "title": "Request Code Review", "description": "Analyze code quality", "arguments": [ { "name": "code", "description": "The code to review", "required": true } ] } ``` **Протокольные операции:** | Метод | Описание | | -------------- | -------------------------------- | | `prompts/list` | Список доступных подсказок | | `prompts/get` | Получить подсказку с аргументами | ## Транспорты [Заголовок раздела «Транспорты»](#транспорты) MCP поддерживает несколько транспортных протоколов: * stdio **Standard I/O** — для локальных серверов ```plaintext Client запускает Server как subprocess Client ──stdin──> Server Client <──stdout── Server Client <──stderr── Server (logs) ``` **Использование:** * Локальные интеграции * CLI инструменты * Простое развёртывание * Streamable HTTP **HTTP + SSE** — для удалённых серверов (рекомендуемый) ```plaintext Client ──POST──> Server (JSON-RPC request) Server ──SSE──> Client (streaming responses) ``` **Особенности:** * Поддержка нескольких клиентов * Управление сессиями (`MCP-Session-Id`) * OAuth 2.1 авторизация * DNS Rebinding защита * SSE (deprecated) **Server-Sent Events** — устаревший Заменён на Streamable HTTP в версии 2025-03-26. Используйте только для совместимости с legacy системами. ### Сравнение транспортов [Заголовок раздела «Сравнение транспортов»](#сравнение-транспортов) | Характеристика | stdio | Streamable HTTP | | -------------- | -------------------- | ----------------- | | Развёртывание | Локальный subprocess | Удалённый сервис | | Клиенты | Один | Несколько | | Аутентификация | Env переменные | OAuth 2.1 | | Streaming | N/A | SSE (опционально) | | Сессии | Время жизни процесса | Явное управление | ## JSON-RPC 2.0 протокол [Заголовок раздела «JSON-RPC 2.0 протокол»](#json-rpc-20-протокол) MCP использует JSON-RPC 2.0 для обмена сообщениями: ### Request (Запрос) [Заголовок раздела «Request (Запрос)»](#request-запрос) ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {} } ``` ### Response (Ответ) [Заголовок раздела «Response (Ответ)»](#response-ответ) ```json { "jsonrpc": "2.0", "id": 1, "result": { "tools": [ { "name": "search", "description": "Search documents" } ] } } ``` ### Error (Ошибка) [Заголовок раздела «Error (Ошибка)»](#error-ошибка) ```json { "jsonrpc": "2.0", "id": 1, "error": { "code": -32602, "message": "Invalid params" } } ``` ### Notification (Уведомление) [Заголовок раздела «Notification (Уведомление)»](#notification-уведомление) Без `id`, не требует ответа: ```json { "jsonrpc": "2.0", "method": "notifications/tools/list_changed" } ``` ## Жизненный цикл соединения [Заголовок раздела «Жизненный цикл соединения»](#жизненный-цикл-соединения) ### 1. Инициализация [Заголовок раздела «1. Инициализация»](#1-инициализация) ```json // Client → Server { "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2025-11-25", "capabilities": { "sampling": {} }, "clientInfo": { "name": "MyClient", "version": "1.0" } } } // Server → Client { "jsonrpc": "2.0", "id": 1, "result": { "protocolVersion": "2025-11-25", "capabilities": { "tools": { "listChanged": true } }, "serverInfo": { "name": "MyServer", "version": "1.0" } } } // Client → Server (подтверждение) { "jsonrpc": "2.0", "method": "notifications/initialized" } ``` ### 2. Операции [Заголовок раздела «2. Операции»](#2-операции) После инициализации клиент и сервер обмениваются запросами согласно capabilities. ### 3. Завершение [Заголовок раздела «3. Завершение»](#3-завершение) * **stdio**: Закрытие stdin, SIGTERM, затем SIGKILL * **HTTP**: Закрытие соединений, DELETE сессии ## Capabilities (Возможности) [Заголовок раздела «Capabilities (Возможности)»](#capabilities-возможности) ### Capabilities клиента [Заголовок раздела «Capabilities клиента»](#capabilities-клиента) | Capability | Описание | | ------------- | -------------------------------------------- | | `roots` | Может предоставлять filesystem roots | | `sampling` | Поддерживает запросы на LLM completion | | `elicitation` | Поддерживает запросы на ввод от пользователя | ### Capabilities сервера [Заголовок раздела «Capabilities сервера»](#capabilities-сервера) | Capability | Описание | | ----------- | --------------------------------- | | `prompts` | Предоставляет шаблоны подсказок | | `resources` | Предоставляет ресурсы | | `tools` | Предоставляет инструменты | | `logging` | Отправляет структурированные логи | ## Расширенные возможности [Заголовок раздела «Расширенные возможности»](#расширенные-возможности) ### Sampling (Сэмплирование) [Заголовок раздела «Sampling (Сэмплирование)»](#sampling-сэмплирование) Серверы могут запрашивать LLM completions через клиента: ```json { "method": "sampling/createMessage", "params": { "messages": [ { "role": "user", "content": { "type": "text", "text": "Analyze this..." } } ], "maxTokens": 1000 } } ``` ### Elicitation (Запрос ввода) [Заголовок раздела «Elicitation (Запрос ввода)»](#elicitation-запрос-ввода) Серверы могут запрашивать информацию от пользователя: ```json { "method": "elicitation/create", "params": { "message": "Please confirm booking:", "schema": { "type": "object", "properties": { "confirm": { "type": "boolean" } } } } } ``` ### Progress (Прогресс) [Заголовок раздела «Progress (Прогресс)»](#progress-прогресс) Уведомления о прогрессе длительных операций: ```json { "method": "notifications/progress", "params": { "progressToken": "token-123", "progress": 50, "total": 100, "message": "Processing..." } } ``` ## OAuth 2.1 авторизация [Заголовок раздела «OAuth 2.1 авторизация»](#oauth-21-авторизация) Для HTTP транспорта MCP использует OAuth 2.1: 1. **Discovery** — `/.well-known/oauth-protected-resource` 2. **Authorization** — стандартный OAuth flow 3. **Token** — Bearer токен в каждом запросе ```http Authorization: Bearer MCP-Protocol-Version: 2025-11-25 ``` ## Безопасность [Заголовок раздела «Безопасность»](#безопасность) Осторожно Безопасность критически важна при работе с MCP. Серверы могут выполнять код, обращаться к файловой системе и внешним сервисам. ### Ключевые принципы [Заголовок раздела «Ключевые принципы»](#ключевые-принципы) 1. **Согласие пользователя** — явное одобрение для доступа к данным 2. **Минимальные права** — только необходимые разрешения 3. **Изоляция** — серверы не видят друг друга 4. **Валидация** — проверка всех входных данных ### Best Practices [Заголовок раздела «Best Practices»](#best-practices) **Для серверов:** * Валидируйте все входы * Реализуйте access control * Ограничивайте rate limits * Санитизируйте выводы **Для клиентов:** * Запрашивайте подтверждение пользователя * Показывайте параметры перед отправкой * Валидируйте результаты * Логируйте для аудита ## Версии протокола [Заголовок раздела «Версии протокола»](#версии-протокола) | Версия | Дата | Ключевые изменения | | ---------- | ---------- | ------------------------------------ | | 2025-11-25 | Current | Tasks, OAuth improvements, Icons | | 2025-06-18 | June 2025 | Elicitation, Security best practices | | 2025-03-26 | March 2025 | Authorization, Streamable HTTP | | 2024-11-05 | Initial | Core protocol, stdio, HTTP+SSE | ## Внешние ресурсы [Заголовок раздела «Внешние ресурсы»](#внешние-ресурсы) ### Официальная документация [Заголовок раздела «Официальная документация»](#официальная-документация) * [spec.modelcontextprotocol.io](https://spec.modelcontextprotocol.io) — спецификация протокола * [modelcontextprotocol.io](https://modelcontextprotocol.io) — официальный сайт * [GitHub: modelcontextprotocol](https://github.com/modelcontextprotocol) — исходный код и SDK * [MCP Registry](https://registry.modelcontextprotocol.io/) — каталог серверов ### Русскоязычная документация [Заголовок раздела «Русскоязычная документация»](#русскоязычная-документация) * [mcpdoc.ru](https://mcpdoc.ru/) — полная документация MCP на русском * [Протокол MCP](https://mcpdoc.ru/reference/protocol/) — детальное описание * [SDK по языкам](https://mcpdoc.ru/sdk/typescript/) — TypeScript, Python, Go, Rust и др. * [Каталог серверов](https://mcpdoc.ru/servers/overview/) — обзор официальных серверов * [Развёртывание](https://mcpdoc.ru/deployment/docker/) — Docker, Ubuntu, Windows ## Следующие шаги [Заголовок раздела «Следующие шаги»](#следующие-шаги) * [MCP SDK](/ai-mcp/mcp-sdk/) — разработка серверов * [Официальные серверы](/ai-mcp/mcp-servers-official/) — готовые решения * [MCP Inspector](/ai-mcp/mcp-inspector/) — отладка серверов # MCP SDK > Разработка MCP серверов на TypeScript, Python и C# — официальные SDK и примеры кода ## Обзор SDK [Заголовок раздела «Обзор SDK»](#обзор-sdk) Для разработки MCP серверов доступны официальные SDK на нескольких языках: TypeScript `@modelcontextprotocol/server` — 4,200+ stars Python `mcp` (FastMCP) — 3,800+ stars C# `ModelContextProtocol` — 2,800+ stars Совет Также доступны SDK для Go, Rust, Java, Kotlin, PHP, Ruby и Swift на [github.com/modelcontextprotocol](https://github.com/modelcontextprotocol) ## TypeScript SDK [Заголовок раздела «TypeScript SDK»](#typescript-sdk) ### Установка [Заголовок раздела «Установка»](#установка) ```bash # Для сервера npm install @modelcontextprotocol/server zod # Для клиента npm install @modelcontextprotocol/client zod ``` ### Структура [Заголовок раздела «Структура»](#структура) ```plaintext @modelcontextprotocol/server ├── McpServer - High-level API (рекомендуется) ├── Server - Low-level implementation ├── StdioServerTransport ├── StreamableHTTPServerTransport └── SSEServerTransport (deprecated) ``` ### Быстрый старт [Заголовок раздела «Быстрый старт»](#быстрый-старт) ```typescript import { McpServer } from '@modelcontextprotocol/server'; import { StdioServerTransport } from '@modelcontextprotocol/server/stdio'; import * as z from 'zod'; // Создание сервера const server = new McpServer({ name: 'my-mcp-server', version: '1.0.0' }); // Регистрация инструмента server.registerTool( 'greet', { title: 'Greeting Tool', description: 'Returns a greeting message', inputSchema: { name: z.string().describe('Name to greet') } }, async ({ name }) => ({ content: [{ type: 'text', text: `Hello, ${name}!` }] }) ); // Регистрация ресурса server.registerResource( 'config', 'config://app', { title: 'App Configuration', description: 'Application settings', mimeType: 'application/json' }, async (uri) => ({ contents: [{ uri: uri.href, text: JSON.stringify({ version: '1.0', debug: false }) }] }) ); // Регистрация prompt server.registerPrompt( 'code-review', { title: 'Code Review', description: 'Review code for best practices', argsSchema: { code: z.string().describe('Code to review'), language: z.string().optional() } }, ({ code, language }) => ({ messages: [{ role: 'user', content: { type: 'text', text: `Review this ${language || ''} code:\n\n${code}` } }] }) ); // Запуск с stdio транспортом const transport = new StdioServerTransport(); await server.connect(transport); ``` ### Streamable HTTP транспорт [Заголовок раздела «Streamable HTTP транспорт»](#streamable-http-транспорт) ```typescript import express from 'express'; import { randomUUID } from 'node:crypto'; import { StreamableHTTPServerTransport } from '@modelcontextprotocol/server'; const app = express(); app.use(express.json()); // Stateless режим (рекомендуется для production) app.post('/mcp', async (req, res) => { const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: () => randomUUID() }); await server.connect(transport); await transport.handleRequest(req, res, req.body); }); app.listen(3000, () => { console.log('MCP server running on http://localhost:3000/mcp'); }); ``` ### Структурированный вывод [Заголовок раздела «Структурированный вывод»](#структурированный-вывод) ```typescript server.registerTool( 'get_weather', { title: 'Weather Tool', description: 'Get weather data', inputSchema: { city: z.string() }, outputSchema: { temperature: z.number(), condition: z.string(), humidity: z.number() } }, async ({ city }) => { const data = await fetchWeather(city); return { content: [{ type: 'text', text: JSON.stringify(data) }], structuredContent: data // Типизированный вывод }; } ); ``` ## Python SDK [Заголовок раздела «Python SDK»](#python-sdk) ### Установка [Заголовок раздела «Установка»](#установка-1) ```bash # Рекомендуется uv uv add "mcp[cli]" # Или pip pip install "mcp[cli]" ``` ### FastMCP (High-level API) [Заголовок раздела «FastMCP (High-level API)»](#fastmcp-high-level-api) FastMCP — декоратор-ориентированный API для быстрой разработки: ```python from mcp.server.fastmcp import FastMCP # Создание сервера mcp = FastMCP("My MCP Server", json_response=True) # Регистрация инструмента @mcp.tool() def add(a: int, b: int) -> int: """Add two numbers together.""" return a + b # Регистрация ресурса с шаблоном URI @mcp.resource("greeting://{name}") def get_greeting(name: str) -> str: """Get a personalized greeting.""" return f"Hello, {name}!" # Регистрация prompt @mcp.prompt() def code_review(code: str, language: str = "python") -> str: """Generate a code review prompt.""" return f"Please review this {language} code:\n\n{code}" # Запуск if __name__ == "__main__": mcp.run(transport="stdio") # или "streamable-http" ``` ### Структурированный вывод с Pydantic [Заголовок раздела «Структурированный вывод с Pydantic»](#структурированный-вывод-с-pydantic) ```python from pydantic import BaseModel, Field from mcp.server.fastmcp import FastMCP mcp = FastMCP("Weather Service") class WeatherData(BaseModel): temperature: float = Field(description="Temperature in Celsius") humidity: float = Field(description="Humidity percentage") condition: str = Field(description="Weather condition") @mcp.tool() def get_weather(city: str) -> WeatherData: """Get current weather for a city.""" # Автоматическая генерация outputSchema из Pydantic модели return WeatherData( temperature=22.5, humidity=65.0, condition="Partly cloudy" ) ``` ### Context и прогресс [Заголовок раздела «Context и прогресс»](#context-и-прогресс) ```python from mcp.server.fastmcp import Context, FastMCP from mcp.server.session import ServerSession mcp = FastMCP("Progress Example") @mcp.tool() async def long_task( task_name: str, ctx: Context[ServerSession, None], steps: int = 5 ) -> str: """Execute a task with progress reporting.""" await ctx.info(f"Starting: {task_name}") for i in range(steps): progress = (i + 1) / steps await ctx.report_progress( progress=progress, total=1.0, message=f"Step {i + 1}/{steps}" ) return f"Task '{task_name}' completed" ``` ### Lifespan и зависимости [Заголовок раздела «Lifespan и зависимости»](#lifespan-и-зависимости) ```python from contextlib import asynccontextmanager from dataclasses import dataclass @dataclass class AppContext: db: Database @asynccontextmanager async def app_lifespan(server: FastMCP): """Initialize resources on startup, cleanup on shutdown.""" db = await Database.connect() try: yield AppContext(db=db) finally: await db.disconnect() mcp = FastMCP("Database App", lifespan=app_lifespan) @mcp.tool() def query_users(ctx: Context[ServerSession, AppContext]) -> list: """Query users from database.""" db = ctx.request_context.lifespan_context.db return db.query("SELECT * FROM users") ``` ## C# SDK [Заголовок раздела «C# SDK»](#c-sdk) ### Установка [Заголовок раздела «Установка»](#установка-2) ```bash # Основной пакет dotnet add package ModelContextProtocol --prerelease # ASP.NET Core (для HTTP) dotnet add package ModelContextProtocol.AspNetCore --prerelease ``` ### Console Application (stdio) [Заголовок раздела «Console Application (stdio)»](#console-application-stdio) ```csharp using Microsoft.Extensions.DependencyInjection; using Microsoft.Extensions.Hosting; using ModelContextProtocol.Server; using System.ComponentModel; var builder = Host.CreateApplicationBuilder(args); // Добавление MCP сервера builder.Services .AddMcpServer() .WithStdioServerTransport() .WithToolsFromAssembly(); await builder.Build().RunAsync(); // Определение инструмента через атрибуты [McpServerToolType] public static class MathTools { [McpServerTool] [Description("Add two numbers together")] public static int Add( [Description("First number")] int a, [Description("Second number")] int b) => a + b; [McpServerTool] [Description("Multiply two numbers")] public static int Multiply(int a, int b) => a * b; } ``` ### ASP.NET Core (HTTP) [Заголовок раздела «ASP.NET Core (HTTP)»](#aspnet-core-http) ```csharp using ModelContextProtocol.Server; using System.ComponentModel; var builder = WebApplication.CreateBuilder(args); // Добавление MCP с HTTP транспортом builder.Services.AddMcpServer() .WithHttpTransport() .WithToolsFromAssembly(); var app = builder.Build(); // Регистрация MCP endpoint app.MapMcp(); app.Run("http://localhost:3001"); [McpServerToolType] public class WeatherTools { [McpServerTool] [Description("Get weather forecast")] public static async Task GetForecast( HttpClient client, // Инъекция через DI [Description("City name")] string city) { var response = await client.GetStringAsync( $"https://api.weather.com/forecast?city={city}" ); return response; } } ``` ### Dependency Injection [Заголовок раздела «Dependency Injection»](#dependency-injection) ```csharp [McpServerToolType] public class DatabaseTools { private readonly ILogger _logger; private readonly IDbConnection _db; public DatabaseTools(ILogger logger, IDbConnection db) { _logger = logger; _db = db; } [McpServerTool] [Description("Execute SQL query")] public async Task Query(string sql) { _logger.LogInformation("Executing: {Sql}", sql); var result = await _db.QueryAsync(sql); return JsonSerializer.Serialize(result); } } ``` ### Prompts [Заголовок раздела «Prompts»](#prompts) ```csharp [McpServerPromptType] public static class CodePrompts { [McpServerPrompt] [Description("Generate a code review prompt")] public static ChatMessage ReviewCode( [Description("Code to review")] string code) => new(ChatRole.User, $"Please review this code:\n\n{code}"); } ``` ## Сравнение SDK [Заголовок раздела «Сравнение SDK»](#сравнение-sdk) | Аспект | TypeScript | Python | C# | | ------------------- | ---------------- | --------------------- | ----------------- | | **API стиль** | `registerTool()` | `@mcp.tool()` | `[McpServerTool]` | | **Схема входа** | Zod | Type hints / Pydantic | JSON Schema | | **DI** | Ручное | Через Context | Полная интеграция | | **Async** | `async/await` | `async/await` | `async/await` | | **HTTP фреймворк** | Express | Встроенный | ASP.NET Core | | **Package Manager** | npm | pip / uv | NuGet | ## Конфигурация для Claude Desktop [Заголовок раздела «Конфигурация для Claude Desktop»](#конфигурация-для-claude-desktop) * TypeScript ```json { "mcpServers": { "my-server": { "command": "node", "args": ["dist/index.js"] } } } ``` * Python ```json { "mcpServers": { "my-server": { "command": "python", "args": ["-m", "my_server"] } } } ``` * C# ```json { "mcpServers": { "my-server": { "command": "dotnet", "args": ["run", "--project", "MyServer.csproj"] } } } ``` ## Best Practices [Заголовок раздела «Best Practices»](#best-practices) ### Именование инструментов [Заголовок раздела «Именование инструментов»](#именование-инструментов) * Используйте `snake_case`: `get_weather`, `create_user` * Описательные имена: не `do`, а `execute_query` * Группировка через точки: `db.query`, `db.insert` ### Описания [Заголовок раздела «Описания»](#описания) * Краткие, но информативные * Указывайте формат входа/выхода * Упоминайте ограничения ### Обработка ошибок [Заголовок раздела «Обработка ошибок»](#обработка-ошибок) ```typescript server.registerTool('risky_operation', schema, async (args) => { try { const result = await performOperation(args); return { content: [{ type: 'text', text: JSON.stringify(result) }] }; } catch (error) { return { content: [{ type: 'text', text: `Error: ${error.message}` }], isError: true }; } }); ``` ### Валидация входа [Заголовок раздела «Валидация входа»](#валидация-входа) ```python @mcp.tool() def process_data(data: str, max_items: int = 100) -> str: """Process data with validation.""" if max_items < 1 or max_items > 1000: raise ValueError("max_items must be between 1 and 1000") # Обработка... return "Processed" ``` ## Дополнительные ресурсы [Заголовок раздела «Дополнительные ресурсы»](#дополнительные-ресурсы) * [mcpdoc.ru/sdk](https://mcpdoc.ru/sdk/typescript/) — детальная документация SDK на русском * [mcpdoc.ru/examples](https://mcpdoc.ru/examples/calculator/) — примеры серверов ## Следующие шаги [Заголовок раздела «Следующие шаги»](#следующие-шаги) * [Официальные серверы](/ai-mcp/mcp-servers-official/) — примеры реализации * [MCP Inspector](/ai-mcp/mcp-inspector/) — тестирование серверов * [Протокол MCP](/ai-mcp/mcp-protocol/) — спецификация # MCP серверы > Каталог популярных MCP серверов для интеграции с n8n ## Официальные серверы [Заголовок раздела «Официальные серверы»](#официальные-серверы) MCP серверы от Anthropic и партнёров. ### Данные и файлы [Заголовок раздела «Данные и файлы»](#данные-и-файлы) Filesystem Работа с локальными файлами и директориями Google Drive Доступ к файлам в Google Drive PostgreSQL Выполнение SQL запросов SQLite Локальные SQLite базы данных ### Сервисы и API [Заголовок раздела «Сервисы и API»](#сервисы-и-api) GitHub Репозитории, issues, pull requests GitLab GitLab API Slack Сообщения и каналы Linear Управление задачами ### Web и Browser [Заголовок раздела «Web и Browser»](#web-и-browser) Puppeteer Автоматизация браузера Playwright Альтернатива Puppeteer Fetch HTTP запросы Brave Search Веб-поиск ## Детали серверов [Заголовок раздела «Детали серверов»](#детали-серверов) ### Filesystem [Заголовок раздела «Filesystem»](#filesystem) Работа с файловой системой. **Установка:** ```bash npx -y @modelcontextprotocol/server-filesystem /path/to/directory ``` **Возможности:** | Tool | Описание | | ------------------ | ------------------- | | `read_file` | Чтение файла | | `write_file` | Запись в файл | | `list_directory` | Листинг директории | | `create_directory` | Создание директории | | `move_file` | Перемещение файла | | `search_files` | Поиск по имени | Осторожно Указывайте только те директории, к которым агент должен иметь доступ. ### PostgreSQL [Заголовок раздела «PostgreSQL»](#postgresql) SQL запросы к PostgreSQL. **Установка:** ```bash npx -y @modelcontextprotocol/server-postgres postgresql://user:pass@host:5432/db ``` **Возможности:** | Tool | Описание | | ---------------- | ---------------------- | | `query` | Выполнение SQL запроса | | `list_tables` | Список таблиц | | `describe_table` | Схема таблицы | **Пример использования:** ```plaintext User: "Покажи топ-10 пользователей по количеству заказов" Agent: Использую query tool... SQL: SELECT user_id, COUNT(*) as orders FROM orders GROUP BY user_id ORDER BY orders DESC LIMIT 10 ``` ### GitHub [Заголовок раздела «GitHub»](#github) Работа с GitHub через API. **Установка:** ```bash GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxx npx -y @modelcontextprotocol/server-github ``` **Возможности:** | Tool | Описание | | --------------------- | ------------------------- | | `search_repositories` | Поиск репозиториев | | `get_file_contents` | Получить содержимое файла | | `create_issue` | Создать issue | | `list_issues` | Список issues | | `create_pull_request` | Создать PR | ### Puppeteer [Заголовок раздела «Puppeteer»](#puppeteer) Автоматизация браузера для web scraping. **Установка:** ```bash npx -y @modelcontextprotocol/server-puppeteer ``` **Возможности:** | Tool | Описание | | ------------ | -------------------- | | `navigate` | Перейти на URL | | `screenshot` | Сделать скриншот | | `click` | Клик по элементу | | `type` | Ввод текста | | `evaluate` | Выполнить JavaScript | ### Slack [Заголовок раздела «Slack»](#slack) Работа со Slack workspace. **Установка:** ```bash SLACK_BOT_TOKEN=xoxb-xxx SLACK_TEAM_ID=T0000 npx -y @modelcontextprotocol/server-slack ``` **Возможности:** | Tool | Описание | | --------------------- | ------------------- | | `list_channels` | Список каналов | | `post_message` | Отправить сообщение | | `reply_to_thread` | Ответить в тред | | `get_channel_history` | История канала | ### Brave Search [Заголовок раздела «Brave Search»](#brave-search) Поиск в интернете через Brave API. **Установка:** ```bash BRAVE_API_KEY=xxx npx -y @anthropics/mcp-server-brave-search ``` **Возможности:** | Tool | Описание | | -------------- | --------------- | | `web_search` | Поиск в вебе | | `local_search` | Локальный поиск | ## Сообщество серверов [Заголовок раздела «Сообщество серверов»](#сообщество-серверов) ### Memory (sqlite-vec) [Заголовок раздела «Memory (sqlite-vec)»](#memory-sqlite-vec) Персистентная память для агентов. ```bash npx -y @anthropics/mcp-server-memory ``` ### Obsidian [Заголовок раздела «Obsidian»](#obsidian) Работа с Obsidian vault. ```bash npx -y @anthropics/mcp-server-obsidian /path/to/vault ``` ### Notion [Заголовок раздела «Notion»](#notion) Доступ к Notion workspace. ```bash NOTION_API_KEY=xxx npx -y @anthropics/mcp-server-notion ``` ### Google Maps [Заголовок раздела «Google Maps»](#google-maps) Геолокация и места. ```bash GOOGLE_MAPS_API_KEY=xxx npx -y @anthropics/mcp-server-google-maps ``` ## Настройка в n8n [Заголовок раздела «Настройка в n8n»](#настройка-в-n8n) ### STDIO подключение [Заголовок раздела «STDIO подключение»](#stdio-подключение) Для локальных серверов: ```plaintext Connection Type: STDIO Command: npx Arguments: ["-y", "@modelcontextprotocol/server-filesystem", "/data"] Environment Variables: NODE_OPTIONS: --max-old-space-size=4096 ``` ### SSE подключение [Заголовок раздела «SSE подключение»](#sse-подключение) Для удалённых серверов: ```plaintext Connection Type: SSE URL: https://mcp-server.example.com/sse Headers: Authorization: Bearer xxx ``` ## Создание своего сервера [Заголовок раздела «Создание своего сервера»](#создание-своего-сервера) ### Минимальный сервер (TypeScript) [Заголовок раздела «Минимальный сервер (TypeScript)»](#минимальный-сервер-typescript) ```typescript import { Server } from "@modelcontextprotocol/sdk/server/index.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; const server = new Server( { name: "my-server", version: "1.0.0" }, { capabilities: { tools: {} } } ); server.setRequestHandler("tools/list", async () => ({ tools: [{ name: "hello", description: "Says hello", inputSchema: { type: "object", properties: { name: { type: "string", description: "Name to greet" } }, required: ["name"] } }] })); server.setRequestHandler("tools/call", async (request) => { if (request.params.name === "hello") { const name = request.params.arguments?.name || "World"; return { content: [{ type: "text", text: `Hello, ${name}!` }] }; } throw new Error("Unknown tool"); }); const transport = new StdioServerTransport(); server.connect(transport); ``` ### Запуск [Заголовок раздела «Запуск»](#запуск) ```bash npx ts-node my-server.ts ``` ## Ресурсы [Заголовок раздела «Ресурсы»](#ресурсы) | Ресурс | Описание | | -------------------------------------------------------------- | --------------------------- | | [mcpdoc.ru](https://mcpdoc.ru) | Документация MCP на русском | | [MCP GitHub](https://github.com/modelcontextprotocol) | Официальные серверы | | [MCP Spec](https://spec.modelcontextprotocol.io) | Спецификация протокола | | [Awesome MCP](https://github.com/punkpeye/awesome-mcp-servers) | Каталог серверов | ## Следующие шаги [Заголовок раздела «Следующие шаги»](#следующие-шаги) * [MCP интеграция](/ai-mcp/mcp/) — настройка в n8n * [AI Agent](/ai-mcp/ai-agent/) — использование с агентами * [RAG](/ai-mcp/rag/) — системы поиска # Официальные MCP серверы > Каталог референсных MCP серверов от Anthropic — Filesystem, Git, Memory, Fetch и другие ## Обзор [Заголовок раздела «Обзор»](#обзор) Репозиторий [modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers) содержит **референсные реализации** MCP серверов, поддерживаемые Anthropic и MCP steering group. Заметка Эти серверы демонстрируют best practices и служат примерами для разработчиков. Community серверы публикуются в [MCP Server Registry](https://registry.modelcontextprotocol.io/). ## Каталог серверов [Заголовок раздела «Каталог серверов»](#каталог-серверов) Filesystem Безопасная работа с файлами Git Операции с репозиториями Memory Knowledge Graph память Fetch Получение веб-контента Sequential Thinking Структурированное мышление Time Работа с временем и таймзонами *** ## Filesystem Server [Заголовок раздела «Filesystem Server»](#filesystem-server) **Package:** `@modelcontextprotocol/server-filesystem` **Язык:** TypeScript Безопасные операции с файловой системой с контролем доступа. ### Инструменты [Заголовок раздела «Инструменты»](#инструменты) | Инструмент | Описание | Read-Only | | --------------------- | -------------------------- | --------- | | `read_text_file` | Чтение текстового файла | Да | | `read_media_file` | Чтение медиа (base64) | Да | | `read_multiple_files` | Чтение нескольких файлов | Да | | `write_file` | Создание/перезапись файла | Нет | | `edit_file` | Редактирование с diff | Нет | | `create_directory` | Создание директории | Нет | | `list_directory` | Содержимое директории | Да | | `move_file` | Перемещение/переименование | Нет | | `search_files` | Поиск по glob паттерну | Да | | `get_file_info` | Метаданные файла | Да | ### Конфигурация [Заголовок раздела «Конфигурация»](#конфигурация) * Claude Desktop ```json { "mcpServers": { "filesystem": { "command": "npx", "args": [ "-y", "@modelcontextprotocol/server-filesystem", "/Users/user/Documents", "/Users/user/Projects" ] } } } ``` * Docker ```json { "mcpServers": { "filesystem": { "command": "docker", "args": [ "run", "-i", "--rm", "--mount", "type=bind,src=/home/user/docs,dst=/docs", "mcp/filesystem", "/docs" ] } } } ``` Осторожно Указывайте только необходимые директории. Сервер имеет доступ к указанным путям. *** ## Git Server [Заголовок раздела «Git Server»](#git-server) **Package:** `mcp-server-git` **Язык:** Python Операции с Git репозиториями. ### Инструменты [Заголовок раздела «Инструменты»](#инструменты-1) | Инструмент | Описание | | ------------------- | --------------------------- | | `git_status` | Статус рабочего дерева | | `git_diff_unstaged` | Незафиксированные изменения | | `git_diff_staged` | Подготовленные изменения | | `git_diff` | Сравнение веток/коммитов | | `git_commit` | Создание коммита | | `git_add` | Добавление в staging | | `git_reset` | Сброс staging | | `git_log` | История коммитов | | `git_create_branch` | Создание ветки | | `git_checkout` | Переключение веток | | `git_show` | Содержимое коммита | | `git_branch` | Список веток | ### Конфигурация [Заголовок раздела «Конфигурация»](#конфигурация-1) ```json { "mcpServers": { "git": { "command": "uvx", "args": ["mcp-server-git", "--repository", "/path/to/repo"] } } } ``` *** ## Memory Server [Заголовок раздела «Memory Server»](#memory-server) **Package:** `@modelcontextprotocol/server-memory` **Язык:** TypeScript Персистентная память через Knowledge Graph. ### Концепции [Заголовок раздела «Концепции»](#концепции) * **Entities** — узлы графа (name, entityType, observations) * **Relations** — связи между узлами (from, to, relationType) * **Observations** — факты, привязанные к entities ### Инструменты [Заголовок раздела «Инструменты»](#инструменты-2) | Инструмент | Описание | | --------------------- | ------------------------ | | `create_entities` | Создание сущностей | | `create_relations` | Создание связей | | `add_observations` | Добавление фактов | | `delete_entities` | Удаление сущностей | | `delete_observations` | Удаление фактов | | `delete_relations` | Удаление связей | | `read_graph` | Чтение всего графа | | `search_nodes` | Поиск по запросу | | `open_nodes` | Получение узлов по имени | ### Конфигурация [Заголовок раздела «Конфигурация»](#конфигурация-2) ```json { "mcpServers": { "memory": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-memory"], "env": { "MEMORY_FILE_PATH": "/path/to/memory.jsonl" } } } } ``` ### Рекомендуемый System Prompt [Заголовок раздела «Рекомендуемый System Prompt»](#рекомендуемый-system-prompt) ```plaintext При каждом взаимодействии: 1. Идентификация пользователя — определите с кем общаетесь 2. Получение памяти — скажите "Вспоминаю..." и получите релевантную информацию 3. Сбор информации — будьте внимательны к новым данным: - Базовая информация (возраст, локация, работа) - Интересы и привычки - Предпочтения в общении - Цели и задачи - Связи с другими людьми 4. Обновление памяти — создавайте entities для людей, организаций, событий ``` *** ## Fetch Server [Заголовок раздела «Fetch Server»](#fetch-server) **Package:** `mcp-server-fetch` **Язык:** Python Получение веб-контента с конвертацией в markdown. ### Инструменты [Заголовок раздела «Инструменты»](#инструменты-3) **`fetch`** — получение URL с извлечением содержимого | Параметр | Описание | По умолчанию | | ------------- | ------------------------ | ------------ | | `url` | URL для загрузки | Обязательный | | `max_length` | Макс. символов | 5000 | | `start_index` | Начальный индекс | 0 | | `raw` | Без markdown конвертации | false | ### Prompts [Заголовок раздела «Prompts»](#prompts) **`fetch`** — prompt для загрузки URL ### Особенности [Заголовок раздела «Особенности»](#особенности) * **Readability** — извлечение основного контента * **Chunked reading** — постраничное чтение через `start_index` * **robots.txt** — соблюдение для автономных запросов * **Proxy** — поддержка прокси ### Конфигурация [Заголовок раздела «Конфигурация»](#конфигурация-3) * Стандартная ```json { "mcpServers": { "fetch": { "command": "uvx", "args": ["mcp-server-fetch"] } } } ``` * С опциями ```json { "mcpServers": { "fetch": { "command": "uvx", "args": [ "mcp-server-fetch", "--ignore-robots-txt", "--user-agent=MyBot/1.0" ] } } } ``` Осторожно Сервер может обращаться к локальным/внутренним IP. Учитывайте это при развёртывании. *** ## Sequential Thinking Server [Заголовок раздела «Sequential Thinking Server»](#sequential-thinking-server) **Package:** `@modelcontextprotocol/server-sequential-thinking` **Язык:** TypeScript Структурированное пошаговое мышление для сложных задач. ### Инструмент: `sequential_thinking` [Заголовок раздела «Инструмент: sequential\_thinking»](#инструмент-sequential_thinking) | Параметр | Тип | Описание | | ------------------- | ------- | -------------------------- | | `thought` | string | Текущий шаг мышления | | `nextThoughtNeeded` | boolean | Нужен ли следующий шаг | | `thoughtNumber` | integer | Номер текущей мысли | | `totalThoughts` | integer | Ожидаемое количество шагов | | `isRevision` | boolean | Пересмотр предыдущего шага | | `revisesThought` | integer | Какой шаг пересматривается | | `branchFromThought` | integer | Точка ветвления | | `branchId` | string | ID ветки | | `needsMoreThoughts` | boolean | Нужно больше шагов | ### Применение [Заголовок раздела «Применение»](#применение) * Декомпозиция сложных задач * Планирование с возможностью пересмотра * Анализ с коррекцией курса * Задачи с неясным объёмом * Фильтрация нерелевантной информации ### Особенности [Заголовок раздела «Особенности»](#особенности-1) * **Динамическая настройка** — увеличение/уменьшение шагов * **Ревизия** — пересмотр предыдущих мыслей * **Ветвление** — исследование альтернатив * **Выражение неопределённости** — признание unknown ### Конфигурация [Заголовок раздела «Конфигурация»](#конфигурация-4) ```json { "mcpServers": { "sequential-thinking": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"], "env": { "DISABLE_THOUGHT_LOGGING": "true" } } } } ``` *** ## Time Server [Заголовок раздела «Time Server»](#time-server) **Package:** `mcp-server-time` **Язык:** Python Работа с временем и таймзонами. ### Инструменты [Заголовок раздела «Инструменты»](#инструменты-4) **`get_current_time`** — текущее время в таймзоне ```json { "name": "get_current_time", "arguments": { "timezone": "Europe/Moscow" } } // Response { "timezone": "Europe/Moscow", "datetime": "2025-01-15T15:30:00+03:00", "is_dst": false } ``` **`convert_time`** — конвертация между таймзонами ```json { "name": "convert_time", "arguments": { "source_timezone": "America/New_York", "time": "09:00", "target_timezone": "Asia/Tokyo" } } ``` ### Конфигурация [Заголовок раздела «Конфигурация»](#конфигурация-5) ```json { "mcpServers": { "time": { "command": "uvx", "args": ["mcp-server-time", "--local-timezone=Europe/Moscow"] } } } ``` *** ## Everything Server (Reference) [Заголовок раздела «Everything Server (Reference)»](#everything-server-reference) **Package:** `@modelcontextprotocol/server-everything` **Язык:** TypeScript Тестовый сервер, демонстрирующий **все** возможности MCP. Совет Используйте для тестирования MCP клиентов и изучения возможностей протокола. ### Демонстрируемые возможности [Заголовок раздела «Демонстрируемые возможности»](#демонстрируемые-возможности) **Tools (15+):** * `echo` — эхо с Zod валидацией * `get-structured-content` — структурированный вывод * `trigger-long-running-operation` — progress notifications * `trigger-sampling-request` — sampling demo * `trigger-elicitation-request` — elicitation demo **Prompts (4):** * `simple-prompt` — статическое сообщение * `args-prompt` — prompt с аргументами * `completable-prompt` — автодополнение * `resource-prompt` — embedded resources **Resources:** * Динамические text/blob ресурсы * Статические документы * Session-scoped ресурсы ### Конфигурация [Заголовок раздела «Конфигурация»](#конфигурация-6) ```json { "mcpServers": { "everything": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-everything"] } } } ``` *** ## Архивные серверы [Заголовок раздела «Архивные серверы»](#архивные-серверы) Следующие серверы перемещены в [servers-archived](https://github.com/modelcontextprotocol/servers-archived): | Сервер | Описание | Статус | | ------------ | ------------------------ | ----------------------------------------------------------------------- | | Brave Search | Веб и локальный поиск | Заменён [официальным](https://github.com/brave/brave-search-mcp-server) | | GitHub | Работа с репозиториями | Архивирован | | PostgreSQL | Read-only доступ к БД | Архивирован | | Puppeteer | Браузерная автоматизация | Архивирован | | Slack | Управление каналами | Передан [Zencoder](https://github.com/zencoderai/slack-mcp-server) | | SQLite | Database + BI | Архивирован | *** ## Шаблоны установки [Заголовок раздела «Шаблоны установки»](#шаблоны-установки) ### NPX (TypeScript) [Заголовок раздела «NPX (TypeScript)»](#npx-typescript) ```bash npx -y @modelcontextprotocol/server- ``` ### UVX (Python) [Заголовок раздела «UVX (Python)»](#uvx-python) ```bash uvx mcp-server- ``` ### Docker [Заголовок раздела «Docker»](#docker) ```bash docker run -i --rm mcp/ ``` ### PIP [Заголовок раздела «PIP»](#pip) ```bash pip install mcp-server- python -m mcp_server_ ``` ## Дополнительные ресурсы [Заголовок раздела «Дополнительные ресурсы»](#дополнительные-ресурсы) * [mcpdoc.ru/servers](https://mcpdoc.ru/servers/overview/) — детальная документация серверов * [mcpdoc.ru/deployment](https://mcpdoc.ru/deployment/docker/) — развёртывание серверов ## Следующие шаги [Заголовок раздела «Следующие шаги»](#следующие-шаги) * [MCP Inspector](/ai-mcp/mcp-inspector/) — тестирование серверов * [MCP SDK](/ai-mcp/mcp-sdk/) — создание своих серверов * [n8n MCP серверы](/ai-mcp/mcp-n8n-servers/) — специфичные для n8n # AI в n8n > Обзор возможностей AI в n8n — агенты, LLM, память, инструменты ## AI возможности n8n [Заголовок раздела «AI возможности n8n»](#ai-возможности-n8n) n8n предоставляет нативную поддержку AI через специализированные ноды: AI Agent Автономные агенты с доступом к инструментам LLM Integration OpenAI, Anthropic, Google, Ollama, Mistral Memory Контекст и история диалогов RAG Retrieval-Augmented Generation с векторами ## Архитектура AI в n8n [Заголовок раздела «Архитектура AI в n8n»](#архитектура-ai-в-n8n) ## AI Ноды [Заголовок раздела «AI Ноды»](#ai-ноды) ### Основные [Заголовок раздела «Основные»](#основные) | Нода | Описание | | ------------------------ | ---------------------------- | | **AI Agent** | Автономный агент с reasoning | | **Basic LLM Chain** | Простой вызов LLM | | **Conversational Agent** | Чат с памятью | | **Tool Agent** | Агент с инструментами | ### Chat Models [Заголовок раздела «Chat Models»](#chat-models) | Нода | Провайдер | | ------------------------ | ------------------- | | **OpenAI Chat Model** | GPT-4, GPT-3.5 | | **Anthropic Chat Model** | Claude 3, Claude 2 | | **Google Gemini** | Gemini Pro | | **Ollama Chat Model** | Локальные модели | | **Mistral Cloud** | Mistral AI | | **Azure OpenAI** | Azure-hosted OpenAI | ### Memory [Заголовок раздела «Memory»](#memory) | Нода | Описание | | ------------------------ | -------------------------- | | **Buffer Memory** | Хранение в памяти процесса | | **Window Buffer Memory** | Скользящее окно сообщений | | **Postgres Chat Memory** | Хранение в PostgreSQL | | **Redis Chat Memory** | Хранение в Redis | | **Motorhead Memory** | Внешний memory server | ### Tools (Инструменты) [Заголовок раздела «Tools (Инструменты)»](#tools-инструменты) | Нода | Описание | | --------------------- | ------------------------- | | **Calculator** | Математические вычисления | | **Code Tool** | Выполнение кода | | **HTTP Request Tool** | API запросы | | **Workflow Tool** | Вызов другого workflow | | **MCP Client** | Model Context Protocol | ### Vector Stores [Заголовок раздела «Vector Stores»](#vector-stores) | Нода | Описание | | ------------- | --------------------- | | **Pinecone** | Облачный векторный DB | | **Qdrant** | Открытый векторный DB | | **Supabase** | PostgreSQL + pgvector | | **In-Memory** | Временное хранилище | ## Типы AI Workflows [Заголовок раздела «Типы AI Workflows»](#типы-ai-workflows) ### 1. Простой LLM Chain [Заголовок раздела «1. Простой LLM Chain»](#1-простой-llm-chain) Прямой запрос к LLM без агента. ### 2. Conversational Agent [Заголовок раздела «2. Conversational Agent»](#2-conversational-agent) Чат с сохранением контекста. ### 3. Tool Agent [Заголовок раздела «3. Tool Agent»](#3-tool-agent) Агент, использующий инструменты для ответа. ### 4. RAG Pipeline [Заголовок раздела «4. RAG Pipeline»](#4-rag-pipeline) Поиск по документам + генерация ответа. ## Подключение LLM [Заголовок раздела «Подключение LLM»](#подключение-llm) ### OpenAI [Заголовок раздела «OpenAI»](#openai) 1. Создайте API ключ на [platform.openai.com](https://platform.openai.com) 2. В n8n: **Credentials** → **Add Credential** → **OpenAI API** 3. Вставьте API Key ### Anthropic [Заголовок раздела «Anthropic»](#anthropic) 1. Создайте API ключ на [console.anthropic.com](https://console.anthropic.com) 2. В n8n: **Credentials** → **Add Credential** → **Anthropic API** 3. Вставьте API Key ### Ollama (Self-hosted) [Заголовок раздела «Ollama (Self-hosted)»](#ollama-self-hosted) 1. Установите [Ollama](https://ollama.ai) 2. Запустите модель: `ollama run llama3.2` 3. В n8n: укажите Base URL `http://localhost:11434` Совет Для production рекомендуется использовать Ollama для снижения затрат на API. ### VPS для n8n + AI Полный доступ к OpenAI, Claude, Gemini без блокировок ✓ Без VPN и прокси•✓ Оплата в рублях•✓ Готов за 5 минут [🇳🇱Нидерланды](/vps_vds_netherlands) [Максимальная скорость до EU API](/vps_vds_netherlands) [OpenAI, Anthropic, Google](/vps_vds_netherlands) [🇰🇿Казахстан](/vps-vds-kazakhstan) [Ближе к России, низкая задержка](/vps-vds-kazakhstan) [Все AI провайдеры доступны](/vps-vds-kazakhstan) Промокод для скидки:`648429339` API-запросы идут с IP сервера — провайдеры не блокируют ## Примеры использования [Заголовок раздела «Примеры использования»](#примеры-использования) ### Чат-бот с памятью [Заголовок раздела «Чат-бот с памятью»](#чат-бот-с-памятью) * Customer support бот * Персональный ассистент * FAQ система ### RAG системы [Заголовок раздела «RAG системы»](#rag-системы) * Поиск по документации * Корпоративный поиск * Анализ контрактов ### Автоматизация с AI [Заголовок раздела «Автоматизация с AI»](#автоматизация-с-ai) * Классификация писем * Генерация отчётов * Извлечение данных из текста ### Мультимодальные задачи [Заголовок раздела «Мультимодальные задачи»](#мультимодальные-задачи) * Анализ изображений * Транскрипция аудио * Генерация изображений ## Стоимость и лимиты [Заголовок раздела «Стоимость и лимиты»](#стоимость-и-лимиты) | Модель | Примерная стоимость | | --------------- | -------------------------------------- | | GPT-4 | $0.03/1K tokens input, $0.06/1K output | | GPT-3.5 | $0.0005/1K tokens | | Claude 3 Opus | $15/1M tokens input, $75/1M output | | Claude 3 Sonnet | $3/1M tokens input, $15/1M output | | Ollama | Бесплатно (self-hosted) | Осторожно Следите за использованием токенов. Добавляйте лимиты и мониторинг в production. ## Следующие шаги [Заголовок раздела «Следующие шаги»](#следующие-шаги) * [AI Agent](/ai-mcp/ai-agent/) — создание агентов * [LangChain](/ai-mcp/langchain/) — цепочки обработки * [RAG](/ai-mcp/rag/) — работа с документами * [MCP](/ai-mcp/mcp/) — Model Context Protocol # RAG Workflows > Построение систем Retrieval-Augmented Generation в n8n ## Что такое RAG? [Заголовок раздела «Что такое RAG?»](#что-такое-rag) **RAG (Retrieval-Augmented Generation)** — это паттерн, объединяющий поиск по документам с генерацией ответов через LLM. ## Преимущества RAG [Заголовок раздела «Преимущества RAG»](#преимущества-rag) * **Актуальность** — LLM получает свежую информацию * **Точность** — ответы основаны на реальных документах * **Источники** — можно указать откуда информация * **Стоимость** — меньше токенов чем fine-tuning ## Архитектура RAG в n8n [Заголовок раздела «Архитектура RAG в n8n»](#архитектура-rag-в-n8n) ### Фаза индексирования [Заголовок раздела «Фаза индексирования»](#фаза-индексирования) ### Фаза запроса [Заголовок раздела «Фаза запроса»](#фаза-запроса) ## Построение RAG Pipeline [Заголовок раздела «Построение RAG Pipeline»](#построение-rag-pipeline) ### Шаг 1: Загрузка документов [Заголовок раздела «Шаг 1: Загрузка документов»](#шаг-1-загрузка-документов) * Файлы Поддерживаемые форматы: * PDF * DOCX * TXT * Markdown * Web * API ### Шаг 2: Разбиение на chunks [Заголовок раздела «Шаг 2: Разбиение на chunks»](#шаг-2-разбиение-на-chunks) **Text Splitter** нода: | Параметр | Рекомендация | | ----------------- | --------------------- | | **Chunk Size** | 500-1000 tokens | | **Chunk Overlap** | 50-100 tokens | | **Separator** | `\n\n` для параграфов | Совет Меньшие chunks дают более точный поиск, но могут терять контекст. Экспериментируйте для вашего use case. ### Шаг 3: Создание embeddings [Заголовок раздела «Шаг 3: Создание embeddings»](#шаг-3-создание-embeddings) **Embeddings** нода: | Модель | Размерность | Качество | | ------------------------------- | ----------- | ------------------- | | OpenAI `text-embedding-3-small` | 1536 | Высокое | | OpenAI `text-embedding-3-large` | 3072 | Очень высокое | | Ollama `nomic-embed-text` | 768 | Хорошее (бесплатно) | ### Шаг 4: Сохранение в Vector Store [Заголовок раздела «Шаг 4: Сохранение в Vector Store»](#шаг-4-сохранение-в-vector-store) * Supabase ```sql -- Создание таблицы create table documents ( id bigserial primary key, content text, embedding vector(1536), metadata jsonb ); -- Создание индекса create index on documents using ivfflat (embedding vector_cosine_ops); ``` * Qdrant ```bash # Docker docker run -p 6333:6333 qdrant/qdrant ``` В n8n: URL `http://localhost:6333` * Pinecone ```plaintext API Key: ваш ключ Index: my-index Environment: us-east-1 ``` ### Шаг 5: Поиск [Заголовок раздела «Шаг 5: Поиск»](#шаг-5-поиск) **Vector Store Retriever**: | Параметр | Описание | | ------------------- | ----------------------------- | | **Top K** | Количество результатов (4-10) | | **Score Threshold** | Минимальный score (0.7-0.8) | ### Шаг 6: Генерация ответа [Заголовок раздела «Шаг 6: Генерация ответа»](#шаг-6-генерация-ответа) Prompt для LLM: ```plaintext Ты полезный ассистент. Отвечай на вопросы ТОЛЬКО на основе предоставленного контекста. Контекст: {{ $json.context }} Вопрос: {{ $json.question }} Правила: - Если ответа нет в контексте, скажи "Не найдено в документации" - Указывай источник информации - Отвечай кратко и по существу Ответ: ``` ## Полный workflow [Заголовок раздела «Полный workflow»](#полный-workflow) ### Индексирование [Заголовок раздела «Индексирование»](#индексирование) 1. **Trigger**: Manual или Schedule 2. **Load Documents**: Read Binary Files / HTTP Request 3. **Extract Text**: PDF, DOCX, или HTML node 4. **Split**: Text Splitter с overlap 5. **Embed**: OpenAI или Ollama Embeddings 6. **Store**: Vector Store Insert ### Запрос [Заголовок раздела «Запрос»](#запрос) 1. **Input**: Webhook или Manual 2. **Embed Query**: Тот же Embeddings model 3. **Search**: Vector Store Retriever 4. **Format Context**: Code node для форматирования 5. **Generate**: LLM Chain с контекстом 6. **Output**: Response ## Примеры [Заголовок раздела «Примеры»](#примеры) ### Документация Bot [Заголовок раздела «Документация Bot»](#документация-bot) Use case: Поддержка по документации продукта. ### Knowledge Base [Заголовок раздела «Knowledge Base»](#knowledge-base) Use case: Корпоративная база знаний. ### Legal Document Analysis [Заголовок раздела «Legal Document Analysis»](#legal-document-analysis) Use case: Анализ юридических документов. ## Оптимизация [Заголовок раздела «Оптимизация»](#оптимизация) ### Качество поиска [Заголовок раздела «Качество поиска»](#качество-поиска) | Метод | Описание | | ------------------- | --------------------------------------- | | **Hybrid Search** | Комбинация vector + keyword | | **Re-ranking** | Перераспределение результатов через LLM | | **Query Expansion** | Расширение запроса синонимами | ### Стоимость [Заголовок раздела «Стоимость»](#стоимость) | Оптимизация | Эффект | | ----------------------------- | -------------- | | Кэширование embeddings | -80% API calls | | Локальные embeddings (Ollama) | Бесплатно | | Batch processing | -50% стоимости | ### Latency [Заголовок раздела «Latency»](#latency) | Оптимизация | Эффект | | ------------------- | ------------------- | | ANN индексы (HNSW) | 10x быстрее поиска | | Streaming responses | Мгновенный feedback | | Pre-computed chunks | -2s на запрос | ## Паттерны [Заголовок раздела «Паттерны»](#паттерны) ### Parent-Child Chunking [Заголовок раздела «Parent-Child Chunking»](#parent-child-chunking) ```plaintext Parent chunk (большой контекст) → для LLM Child chunks (маленькие) → для поиска ``` ### Hierarchical RAG [Заголовок раздела «Hierarchical RAG»](#hierarchical-rag) ### Multi-Query RAG [Заголовок раздела «Multi-Query RAG»](#multi-query-rag) ## Следующие шаги [Заголовок раздела «Следующие шаги»](#следующие-шаги) * [AI Agent](/ai-mcp/ai-agent/) — агенты с RAG * [MCP](/ai-mcp/mcp/) — подключение данных через MCP * [LangChain](/ai-mcp/langchain/) — цепочки обработки # Туториал: Создаём AI агента > Пошаговое руководство по созданию первого AI агента в n8n с инструментами и памятью В этом туториале мы создадим **AI агента-помощника**, который умеет: * Отвечать на вопросы о погоде * Выполнять математические вычисления * Помнить контекст разговора **Время:** 20-30 минут **Уровень:** Начинающий **Требования:** Работающий n8n, API ключ OpenAI или Anthropic *** ## Шаг 1: Подготовка [Заголовок раздела «Шаг 1: Подготовка»](#шаг-1-подготовка) ### Получение API ключа [Заголовок раздела «Получение API ключа»](#получение-api-ключа) * OpenAI 1. Перейдите на [platform.openai.com](https://platform.openai.com) 2. Войдите или создайте аккаунт 3. Откройте **API Keys** → **Create new secret key** 4. Скопируйте ключ (он показывается только один раз!) * Anthropic 1. Перейдите на [console.anthropic.com](https://console.anthropic.com) 2. Войдите или создайте аккаунт 3. Откройте **API Keys** → **Create Key** 4. Скопируйте ключ * Ollama (бесплатно) ```bash # Установка на Linux/Mac curl -fsSL https://ollama.com/install.sh | sh # Запуск модели ollama run llama3.2 # Ollama будет доступен на http://localhost:11434 ``` ### Добавление Credentials в n8n [Заголовок раздела «Добавление Credentials в n8n»](#добавление-credentials-в-n8n) 1. Откройте n8n и перейдите в **Settings** → **Credentials** 2. Нажмите **Add Credential** 3. Выберите **OpenAI API** (или Anthropic/Ollama) 4. Введите ваш API ключ 5. Нажмите **Save** *** ## Шаг 2: Создание базового агента [Заголовок раздела «Шаг 2: Создание базового агента»](#шаг-2-создание-базового-агента) ### Добавляем ноды [Заголовок раздела «Добавляем ноды»](#добавляем-ноды) 1. **Создайте новый Workflow** * Нажмите **Add workflow** или используйте `Ctrl+N` 2. **Добавьте Chat Trigger** * Нажмите **+** → поиск “Chat Trigger” * Эта нода будет принимать сообщения пользователя 3. **Добавьте AI Agent** * Нажмите **+** → поиск “AI Agent” * Подключите выход Chat Trigger к входу AI Agent 4. **Добавьте Chat Model** * На AI Agent кликните на ”+” рядом с “Model” * Выберите **OpenAI Chat Model** (или другую модель) * Настройте: * **Credential**: выберите созданный ранее * **Model**: `gpt-4o-mini` (дешевле) или `gpt-4o` (умнее) ### Тестируем базового агента [Заголовок раздела «Тестируем базового агента»](#тестируем-базового-агента) 1. Нажмите **Chat** в правом нижнем углу 2. Напишите: “Привет! Кто ты?” 3. Агент должен ответить! Совет Если агент не отвечает, проверьте: * Credentials настроены правильно * На счету OpenAI есть баланс * Модель подключена к агенту (линия от Model к Agent) *** ## Шаг 3: Добавляем инструменты [Заголовок раздела «Шаг 3: Добавляем инструменты»](#шаг-3-добавляем-инструменты) Сейчас агент только отвечает на вопросы. Давайте дадим ему **инструменты**! ### Калькулятор [Заголовок раздела «Калькулятор»](#калькулятор) 1. На AI Agent кликните **+** рядом с “Tool” 2. Выберите **Calculator** 3. Инструмент автоматически подключится 4. Протестируйте в чате: ```plaintext Сколько будет 15% от 850? ``` Агент использует калькулятор и ответит: **127.5** ### HTTP Request (Погода) [Заголовок раздела «HTTP Request (Погода)»](#http-request-погода) 1. Добавьте ещё один Tool: **HTTP Request Tool** 2. Настройте: * **Name**: `get_weather` * **Description**: `Get current weather for a city. Returns temperature and conditions.` * **Method**: GET * **URL**: `https://wttr.in/{{ $fromAI('city') }}?format=j1` 3. В разделе **Tool Input Schema**: ```json { "type": "object", "properties": { "city": { "type": "string", "description": "City name in English, e.g. Moscow, London" } }, "required": ["city"] } ``` 4. Протестируйте: ```plaintext Какая погода в Москве? ``` Заметка **Как это работает:** Агент анализирует вопрос → понимает что нужна погода → вызывает `get_weather` с параметром `city=Moscow` → получает данные → формирует ответ на русском языке. *** ## Шаг 4: Добавляем память [Заголовок раздела «Шаг 4: Добавляем память»](#шаг-4-добавляем-память) Без памяти агент не помнит предыдущие сообщения. Добавим её! 1. На AI Agent кликните **+** рядом с “Memory” 2. Выберите **Window Buffer Memory** — это самый простой тип памяти, хранит последние N сообщений 3. Настройте **Context Window Length**: `10` (сообщений) 4. Протестируйте память — напишите “Меня зовут Алексей”, затем “Как меня зовут?” — агент должен помнить имя! ### Типы памяти [Заголовок раздела «Типы памяти»](#типы-памяти) | Тип | Описание | Когда использовать | | ------------------- | --------------------- | ------------------------------- | | **Window Buffer** | Последние N сообщений | Простые чат-боты | | **Buffer Memory** | Все сообщения | Короткие сессии | | **Redis Memory** | Хранение в Redis | Multi-instance, персистентность | | **Postgres Memory** | Хранение в БД | Enterprise, аналитика | *** ## Шаг 5: Настройка системного промпта [Заголовок раздела «Шаг 5: Настройка системного промпта»](#шаг-5-настройка-системного-промпта) Системный промпт определяет **личность** агента. 1. В настройках AI Agent найдите **System Message** 2. Введите промпт (пример ниже) 3. Сохраните и протестируйте **Пример системного промпта:** ```text Ты — дружелюбный ассистент на русском языке. Твои возможности: - Отвечать на вопросы - Выполнять математические вычисления (используй калькулятор) - Сообщать погоду в любом городе Правила: - Всегда отвечай на русском языке - Будь кратким, но информативным - Если не знаешь ответ — честно скажи об этом - Используй эмодзи для дружелюбности ``` *** ## Шаг 6: Финальная структура [Заголовок раздела «Шаг 6: Финальная структура»](#шаг-6-финальная-структура) Ваш workflow должен выглядеть так: ```plaintext ┌─────────────┐ ┌─────────────┐ │ Chat Trigger│────→│ AI Agent │ └─────────────┘ └──────┬──────┘ │ ┌────────────┼────────────┐ ↓ ↓ ↓ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │ Model │ │Calculator│ │ HTTP Request │ │(OpenAI) │ │ │ │ (Weather) │ └──────────┘ └──────────┘ └──────────────┘ │ ↓ ┌──────────────┐ │Window Buffer │ │ Memory │ └──────────────┘ ``` *** ## Шаг 7: Активация и тестирование [Заголовок раздела «Шаг 7: Активация и тестирование»](#шаг-7-активация-и-тестирование) 1. **Сохраните workflow** — нажмите `Ctrl+S` или кнопку Save 2. **Активируйте** — переключатель в правом верхнем углу → Active 3. **Протестируйте в чате** — отправьте сообщения и проверьте ответы агента **Пример диалога:** ```plaintext Привет! → Привет! Чем могу помочь? Сколько будет 234 * 567? → 234 × 567 = 132,678 Какая погода в Париже? → В Париже сейчас 18°C, облачно Напомни, что я спрашивал? → Вы спрашивали про умножение и погоду в Париже ``` *** ## Расширение агента [Заголовок раздела «Расширение агента»](#расширение-агента) ### Добавление MCP инструментов [Заголовок раздела «Добавление MCP инструментов»](#добавление-mcp-инструментов) Хотите дать агенту доступ к GitHub, базам данных или файловой системе? 1. Добавьте **MCP Client Tool** к агенту 2. Подключите к MCP серверу (например, GitHub) — запустите `npx @anthropic/mcp-server-github` 3. Агент получит доступ к репозиториям, issues, PR и т.д. [Подробнее о MCP ](/ai-mcp/mcp/)Подключение MCP серверов к n8n ### Добавление RAG [Заголовок раздела «Добавление RAG»](#добавление-rag) Хотите чтобы агент отвечал на вопросы по вашим документам? 1. Добавьте **Vector Store Tool** 2. Настройте Vector Store (Pinecone, Qdrant или In-Memory) 3. Загрузите документы через **Document Loader** 4. Агент будет искать релевантную информацию [RAG в n8n ](/ai-mcp/rag/)Retrieval Augmented Generation *** ## Полный JSON workflow [Заголовок раздела «Полный JSON workflow»](#полный-json-workflow) Нажмите чтобы раскрыть JSON ```json { "name": "AI Assistant Tutorial", "nodes": [ { "parameters": {}, "id": "chat-trigger", "name": "Chat Trigger", "type": "@n8n/n8n-nodes-langchain.chatTrigger", "position": [250, 300] }, { "parameters": { "options": { "systemMessage": "Ты — дружелюбный ассистент на русском языке.\n\nТвои возможности:\n- Отвечать на вопросы\n- Выполнять математические вычисления\n- Сообщать погоду в любом городе\n\nВсегда отвечай на русском языке." } }, "id": "ai-agent", "name": "AI Agent", "type": "@n8n/n8n-nodes-langchain.agent", "position": [500, 300] }, { "parameters": { "model": "gpt-4o-mini" }, "id": "openai-chat", "name": "OpenAI Chat Model", "type": "@n8n/n8n-nodes-langchain.lmChatOpenAi", "position": [500, 500] }, { "parameters": {}, "id": "calculator", "name": "Calculator", "type": "@n8n/n8n-nodes-langchain.toolCalculator", "position": [700, 500] }, { "parameters": { "contextWindowLength": 10 }, "id": "memory", "name": "Window Buffer Memory", "type": "@n8n/n8n-nodes-langchain.memoryBufferWindow", "position": [300, 500] } ], "connections": { "Chat Trigger": { "main": [[{"node": "AI Agent", "type": "main", "index": 0}]] }, "OpenAI Chat Model": { "ai_languageModel": [[{"node": "AI Agent", "type": "ai_languageModel", "index": 0}]] }, "Calculator": { "ai_tool": [[{"node": "AI Agent", "type": "ai_tool", "index": 0}]] }, "Window Buffer Memory": { "ai_memory": [[{"node": "AI Agent", "type": "ai_memory", "index": 0}]] } } } ``` *** ## Следующие шаги [Заголовок раздела «Следующие шаги»](#следующие-шаги) Добавить MCP Подключите внешние инструменты через [MCP](/ai-mcp/mcp/) Настроить RAG Обучите агента на ваших документах через [RAG](/ai-mcp/rag/) Изучить модели Сравните [LLM модели](/ai-mcp/langchain/) для вашего use case Troubleshooting Решение [частых проблем](/reference/troubleshooting/) # Code Node > Программирование в n8n — JavaScript и Python ## Обзор [Заголовок раздела «Обзор»](#обзор) Code Node позволяет выполнять произвольный код на JavaScript или Python. ## Режимы выполнения [Заголовок раздела «Режимы выполнения»](#режимы-выполнения) ### Run Once for All Items [Заголовок раздела «Run Once for All Items»](#run-once-for-all-items) Код выполняется один раз, получая все items: ```javascript const items = $input.all(); return items.map(item => ({ json: { ...item.json, processed: true } })); ``` ### Run Once for Each Item [Заголовок раздела «Run Once for Each Item»](#run-once-for-each-item) Код выполняется для каждого item отдельно: ```javascript const item = $input.item; return { json: { ...item.json, processed: true } }; ``` ## JavaScript [Заголовок раздела «JavaScript»](#javascript) ### Базовая структура [Заголовок раздела «Базовая структура»](#базовая-структура) ```javascript // Получить входные данные const items = $input.all(); // Обработка const results = []; for (const item of items) { results.push({ json: { original: item.json, modified: transform(item.json) } }); } // Вернуть результат return results; ``` ### Доступ к данным [Заголовок раздела «Доступ к данным»](#доступ-к-данным) ```javascript // Все items const items = $input.all(); // Первый item const first = $input.first(); // Последний item const last = $input.last(); // Данные из другой ноды const httpData = $('HTTP Request').all(); const firstHttpItem = $('HTTP Request').first(); // Переменные окружения const apiKey = $env.API_KEY; // Глобальные переменные const baseUrl = $vars.BASE_URL; // Информация о выполнении const executionId = $execution.id; const workflowName = $workflow.name; ``` ### Асинхронные операции [Заголовок раздела «Асинхронные операции»](#асинхронные-операции) ```javascript // Async/await поддерживается const response = await fetch('https://api.example.com/data'); const data = await response.json(); return [{ json: data }]; ``` ### External Libraries [Заголовок раздела «External Libraries»](#external-libraries) ```javascript // Встроенные библиотеки const moment = require('moment'); const _ = require('lodash'); const crypto = require('crypto'); // Использование const formatted = moment().format('YYYY-MM-DD'); const unique = _.uniq(items.map(i => i.json.name)); const hash = crypto.createHash('sha256').update('data').digest('hex'); ``` Совет Доступны: `lodash`, `moment`, `crypto`, `axios`, `cheerio` и другие встроенные модули Node.js. ### Работа с Binary [Заголовок раздела «Работа с Binary»](#работа-с-binary) ```javascript // Создание binary из строки const buffer = Buffer.from('Hello World'); return [{ json: { fileName: 'test.txt' }, binary: { data: await this.helpers.prepareBinaryData(buffer, 'test.txt') } }]; ``` ```javascript // Чтение binary const binaryData = items[0].binary.data; const buffer = await this.helpers.getBinaryDataBuffer(0, 'data'); const content = buffer.toString('utf8'); ``` ## Python [Заголовок раздела «Python»](#python) ### Базовая структура [Заголовок раздела «Базовая структура»](#базовая-структура-1) ```python # Получить входные данные items = _input.all() # Обработка results = [] for item in items: results.append({ 'json': { 'original': item['json'], 'processed': True } }) # Вернуть результат return results ``` ### Доступ к данным [Заголовок раздела «Доступ к данным»](#доступ-к-данным-1) ```python # Все items items = _input.all() # Первый item first = _input.first() # Данные из другой ноды http_data = _node['HTTP Request'].all() # Переменные окружения import os api_key = os.environ.get('API_KEY') ``` ### Библиотеки [Заголовок раздела «Библиотеки»](#библиотеки) ```python import json import datetime import re from collections import defaultdict # Использование data = json.loads(items[0]['json']['text']) now = datetime.datetime.now().isoformat() matches = re.findall(r'\d+', text) ``` Осторожно Python в n8n выполняется через pyodide (WebAssembly). Не все библиотеки доступны. ## Паттерны [Заголовок раздела «Паттерны»](#паттерны) ### Фильтрация [Заголовок раздела «Фильтрация»](#фильтрация) * JavaScript ```javascript const items = $input.all(); return items.filter(item => item.json.status === 'active' ); ``` * Python ```python items = _input.all() return [item for item in items if item['json']['status'] == 'active'] ``` ### Группировка [Заголовок раздела «Группировка»](#группировка) ```javascript const items = $input.all(); const grouped = items.reduce((acc, item) => { const key = item.json.category; if (!acc[key]) acc[key] = []; acc[key].push(item.json); return acc; }, {}); return Object.entries(grouped).map(([category, items]) => ({ json: { category, items, count: items.length } })); ``` ### Агрегация [Заголовок раздела «Агрегация»](#агрегация) ```javascript const items = $input.all(); const total = items.reduce((sum, item) => sum + item.json.amount, 0 ); const average = total / items.length; return [{ json: { total, average, count: items.length } }]; ``` ### Merge данных [Заголовок раздела «Merge данных»](#merge-данных) ```javascript // Объединение данных из двух нод const users = $('Get Users').all(); const orders = $('Get Orders').all(); return users.map(user => { const userOrders = orders.filter(o => o.json.userId === user.json.id ); return { json: { ...user.json, orders: userOrders.map(o => o.json), orderCount: userOrders.length } }; }); ``` ### HTTP запросы [Заголовок раздела «HTTP запросы»](#http-запросы) ```javascript const response = await fetch('https://api.example.com/data', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${$env.API_KEY}` }, body: JSON.stringify({ query: $json.query }) }); if (!response.ok) { throw new Error(`HTTP ${response.status}`); } const data = await response.json(); return [{ json: data }]; ``` ### Error handling [Заголовок раздела «Error handling»](#error-handling) ```javascript const items = $input.all(); const results = []; for (const item of items) { try { const processed = riskyOperation(item.json); results.push({ json: { success: true, data: processed } }); } catch (error) { results.push({ json: { success: false, error: error.message, original: item.json } }); } } return results; ``` ## Debugging [Заголовок раздела «Debugging»](#debugging) ### Console.log [Заголовок раздела «Console.log»](#consolelog) ```javascript console.log('Debug:', $json); console.log('Items count:', items.length); ``` Логи видны в деталях выполнения. ### Throw Error [Заголовок раздела «Throw Error»](#throw-error) ```javascript if (!$json.requiredField) { throw new Error('Required field is missing'); } ``` ## Performance [Заголовок раздела «Performance»](#performance) ### Batch processing [Заголовок раздела «Batch processing»](#batch-processing) ```javascript const BATCH_SIZE = 100; const items = $input.all(); const results = []; for (let i = 0; i < items.length; i += BATCH_SIZE) { const batch = items.slice(i, i + BATCH_SIZE); const batchResults = await processBatch(batch); results.push(...batchResults); } return results; ``` ### Parallel execution [Заголовок раздела «Parallel execution»](#parallel-execution) ```javascript const items = $input.all(); const results = await Promise.all( items.map(async item => { const data = await fetchData(item.json.id); return { json: data }; }) ); return results; ``` ## Следующие шаги [Заголовок раздела «Следующие шаги»](#следующие-шаги) * [Expressions](/code/expressions/) — динамические значения * [Трансформация данных](/concepts/transforming/) — паттерны * [Примеры](/code/examples/) — готовые решения # Expressions > Синтаксис и возможности expressions в n8n ## Синтаксис [Заголовок раздела «Синтаксис»](#синтаксис) Expressions заключаются в двойные фигурные скобки: ```javascript {{ выражение }} ``` ## Доступ к данным [Заголовок раздела «Доступ к данным»](#доступ-к-данным) ### Текущий item [Заголовок раздела «Текущий item»](#текущий-item) ```javascript // Поле верхнего уровня {{ $json.name }} // Вложенное поле {{ $json.user.email }} // Поле с дефисом {{ $json["field-name"] }} // Элемент массива {{ $json.items[0] }} ``` ### Binary данные [Заголовок раздела «Binary данные»](#binary-данные) ```javascript {{ $binary.data }} {{ $binary.data.fileName }} {{ $binary.data.mimeType }} {{ $binary.data.fileSize }} ``` ### Данные из других нод [Заголовок раздела «Данные из других нод»](#данные-из-других-нод) ```javascript // По имени ноды {{ $('HTTP Request').item.json.data }} // Все items из ноды {{ $('HTTP Request').all() }} // Первый item {{ $('HTTP Request').first().json }} // Последний item {{ $('HTTP Request').last().json }} // По индексу {{ $('HTTP Request').itemMatching(0).json }} ``` ## Методы $input [Заголовок раздела «Методы $input»](#методы-input) | Метод | Описание | | ---------------- | ---------------------------------- | | `$input.all()` | Все items | | `$input.first()` | Первый item | | `$input.last()` | Последний item | | `$input.item` | Текущий item (в Run Once for Each) | ## Специальные переменные [Заголовок раздела «Специальные переменные»](#специальные-переменные) | Переменная | Описание | Пример | | ---------------- | ------------------------------ | ---------------------- | | `$now` | Текущее время (Luxon DateTime) | `{{ $now.toISO() }}` | | `$today` | Сегодня (начало дня) | `{{ $today.toISO() }}` | | `$itemIndex` | Индекс текущего item | `{{ $itemIndex }}` | | `$runIndex` | Номер итерации в цикле | `{{ $runIndex }}` | | `$env` | Переменные окружения | `{{ $env.API_KEY }}` | | `$vars` | Глобальные переменные | `{{ $vars.BASE_URL }}` | | `$execution.id` | ID выполнения | `{{ $execution.id }}` | | `$workflow.id` | ID workflow | `{{ $workflow.id }}` | | `$workflow.name` | Имя workflow | `{{ $workflow.name }}` | ## Строковые методы [Заголовок раздела «Строковые методы»](#строковые-методы) ```javascript // Регистр {{ $json.name.toUpperCase() }} // "JOHN" {{ $json.name.toLowerCase() }} // "john" // Обрезка {{ $json.text.trim() }} // Убрать пробелы {{ $json.text.substring(0, 10) }} // Первые 10 символов {{ $json.text.slice(-5) }} // Последние 5 символов // Замена {{ $json.text.replace('old', 'new') }} {{ $json.text.replaceAll(' ', '_') }} // Разделение {{ $json.text.split(',') }} // ['a', 'b', 'c'] {{ $json.text.split(',')[0] }} // 'a' // Поиск {{ $json.text.includes('search') }} // true/false {{ $json.text.startsWith('Hello') }} {{ $json.text.endsWith('!') }} {{ $json.text.indexOf('find') }} // Индекс или -1 ``` ## Числовые методы [Заголовок раздела «Числовые методы»](#числовые-методы) ```javascript // Округление {{ $json.price.toFixed(2) }} // "99.50" {{ Math.round($json.value) }} // 100 {{ Math.floor($json.value) }} // 99 {{ Math.ceil($json.value) }} // 100 // Математика {{ Math.abs($json.num) }} // Модуль {{ Math.max(1, 2, 3) }} // 3 {{ Math.min(1, 2, 3) }} // 1 {{ Math.random() }} // 0-1 // Преобразование {{ parseInt($json.str) }} // String → Integer {{ parseFloat($json.str) }} // String → Float {{ Number($json.str) }} // String → Number ``` ## Массивы [Заголовок раздела «Массивы»](#массивы) ```javascript // Доступ {{ $json.items[0] }} // Первый элемент {{ $json.items.length }} // Длина // Методы {{ $json.items.join(', ') }} // "a, b, c" {{ $json.items.includes('a') }} // true/false {{ $json.items.indexOf('b') }} // Индекс // Трансформация (в Code Node) {{ $json.items.map(i => i.name) }} {{ $json.items.filter(i => i.active) }} {{ $json.items.find(i => i.id === 1) }} {{ $json.items.sort((a, b) => a - b) }} ``` ## Даты (Luxon) [Заголовок раздела «Даты (Luxon)»](#даты-luxon) n8n использует [Luxon](https://moment.github.io/luxon/) для работы с датами. ### Форматирование [Заголовок раздела «Форматирование»](#форматирование) ```javascript {{ $now.toFormat('dd.MM.yyyy') }} // "15.01.2025" {{ $now.toFormat('HH:mm:ss') }} // "14:30:00" {{ $now.toFormat('dd MMMM yyyy', { locale: 'ru' }) }} // "15 января 2025" {{ $now.toISO() }} // ISO формат {{ $now.toMillis() }} // Timestamp ``` ### Арифметика [Заголовок раздела «Арифметика»](#арифметика) ```javascript {{ $now.plus({ days: 1 }) }} // Завтра {{ $now.minus({ hours: 2 }) }} // 2 часа назад {{ $now.startOf('day') }} // Начало дня {{ $now.endOf('month') }} // Конец месяца ``` ### Сравнение [Заголовок раздела «Сравнение»](#сравнение) ```javascript {{ $now > DateTime.fromISO($json.date) }} {{ $now.diff(DateTime.fromISO($json.date), 'days').days }} ``` ### Timezone [Заголовок раздела «Timezone»](#timezone) ```javascript {{ $now.setZone('Europe/Moscow').toFormat('HH:mm') }} ``` ## Условная логика [Заголовок раздела «Условная логика»](#условная-логика) ### Тернарный оператор [Заголовок раздела «Тернарный оператор»](#тернарный-оператор) ```javascript {{ $json.status === 'active' ? 'Активен' : 'Неактивен' }} ``` ### Nullish coalescing [Заголовок раздела «Nullish coalescing»](#nullish-coalescing) ```javascript {{ $json.name ?? 'Без имени' }} // Если null/undefined {{ $json.count || 0 }} // Если falsy ``` ### Optional chaining [Заголовок раздела «Optional chaining»](#optional-chaining) ```javascript {{ $json.user?.address?.city }} // Безопасный доступ {{ $json.items?.[0]?.name }} // К элементу массива ``` ## JSON методы [Заголовок раздела «JSON методы»](#json-методы) ```javascript // Объект → Строка {{ JSON.stringify($json.data) }} {{ JSON.stringify($json.data, null, 2) }} // С форматированием // Строка → Объект {{ JSON.parse($json.jsonString) }} ``` ## Регулярные выражения [Заголовок раздела «Регулярные выражения»](#регулярные-выражения) ```javascript // Проверка {{ /^[a-z]+$/.test($json.value) }} // Поиск {{ $json.text.match(/\d+/g) }} // Все числа // Замена {{ $json.text.replace(/\s+/g, ' ') }} // Убрать лишние пробелы ``` ## Примеры [Заголовок раздела «Примеры»](#примеры) ### Форматирование телефона [Заголовок раздела «Форматирование телефона»](#форматирование-телефона) ```javascript {{ $json.phone.replace(/[^\d]/g, '').replace(/^7/, '+7 ') }} ``` ### Генерация ID [Заголовок раздела «Генерация ID»](#генерация-id) ```javascript {{ `${$now.toMillis()}-${Math.random().toString(36).substr(2, 9)}` }} ``` ### Безопасный доступ с default [Заголовок раздела «Безопасный доступ с default»](#безопасный-доступ-с-default) ```javascript {{ $json.user?.name || 'Anonymous' }} ``` ### Форматирование цены [Заголовок раздела «Форматирование цены»](#форматирование-цены) ```javascript {{ new Intl.NumberFormat('ru-RU', { style: 'currency', currency: 'RUB' }).format($json.price) }} ``` Совет Для сложных выражений лучше использовать Code Node — это улучшает читаемость и отладку. ## Следующие шаги [Заголовок раздела «Следующие шаги»](#следующие-шаги) * [Code Node](/code/code-node/) — полноценное программирование * [Примеры](/code/examples/) — готовые решения * [Структура данных](/concepts/data-structure/) — формат данных # Код в n8n > Обзор возможностей программирования в n8n ## Способы программирования [Заголовок раздела «Способы программирования»](#способы-программирования) Expressions Динамические значения в полях нод Code Node Полноценный JavaScript/Python код Function Item Обработка каждого item отдельно External Libraries Использование npm пакетов ## Когда что использовать [Заголовок раздела «Когда что использовать»](#когда-что-использовать) | Задача | Решение | | -------------------------- | ------------------------------ | | Динамическое значение поля | Expression | | Простое преобразование | Expression с методами | | Сложная логика | Code Node | | Обработка каждого item | Code Node или Function Item | | Внешние библиотеки | Code Node | | Математика | Expression или Calculator Tool | ## Expressions [Заголовок раздела «Expressions»](#expressions) Вставляются в любое поле через `{{ }}`: ```javascript // Доступ к данным {{ $json.name }} // Вызов методов {{ $json.name.toUpperCase() }} // Тернарный оператор {{ $json.age >= 18 ? 'adult' : 'minor' }} ``` ## Code Node [Заголовок раздела «Code Node»](#code-node) Полный контроль над данными: ```javascript // JavaScript const items = $input.all(); return items.map(item => ({ json: { ...item.json, processed: true } })); ``` ```python # Python items = _input.all() for item in items: item['json']['processed'] = True return items ``` ## Доступные объекты [Заголовок раздела «Доступные объекты»](#доступные-объекты) | Объект | Описание | | ------------ | ----------------------- | | `$input` | Входные данные | | `$json` | JSON текущего item | | `$binary` | Binary данные | | `$('Node')` | Данные из ноды по имени | | `$env` | Переменные окружения | | `$vars` | Глобальные переменные | | `$now` | Текущее время | | `$today` | Сегодняшняя дата | | `$itemIndex` | Индекс текущего item | ## Примеры [Заголовок раздела «Примеры»](#примеры) ### Форматирование данных [Заголовок раздела «Форматирование данных»](#форматирование-данных) ```javascript {{ $json.price.toFixed(2) }} // "99.00" {{ $json.name.trim().toLowerCase() }} // "john" {{ $json.date.format('DD.MM.YYYY') }} // "15.01.2025" ``` ### Условная логика [Заголовок раздела «Условная логика»](#условная-логика) ```javascript {{ $json.status === 'active' ? '✅' : '❌' }} {{ $json.items?.length || 0 }} {{ $json.name ?? 'Unknown' }} ``` ### Работа с массивами [Заголовок раздела «Работа с массивами»](#работа-с-массивами) ```javascript {{ $json.tags.join(', ') }} {{ $json.users.map(u => u.name) }} {{ $json.items.filter(i => i.price > 100) }} ``` ## Режимы Code Node [Заголовок раздела «Режимы Code Node»](#режимы-code-node) ### Run Once for All Items [Заголовок раздела «Run Once for All Items»](#run-once-for-all-items) ```javascript // Получить все items const items = $input.all(); // Обработать и вернуть return items.map(item => ({ json: transform(item.json) })); ``` ### Run Once for Each Item [Заголовок раздела «Run Once for Each Item»](#run-once-for-each-item) ```javascript // Получить текущий item const item = $input.item; // Вернуть один item return { json: transform(item.json) }; ``` ## Следующие шаги [Заголовок раздела «Следующие шаги»](#следующие-шаги) * [Expressions](/code/expressions/) — подробный синтаксис * [Code Node](/code/code-node/) — программирование * [Примеры](/code/examples/) — готовые решения # Структура данных > Формат данных в n8n — items, json, binary, метаданные ## Основа: Items [Заголовок раздела «Основа: Items»](#основа-items) В n8n данные передаются между нодами в виде **items** — массива объектов. ```json [ { "json": { "id": 1, "name": "John", "email": "john@example.com" } }, { "json": { "id": 2, "name": "Jane", "email": "jane@example.com" } } ] ``` ## Структура Item [Заголовок раздела «Структура Item»](#структура-item) Каждый item содержит: | Поле | Тип | Описание | | ------------ | ------ | ----------------------- | | `json` | Object | Основные данные | | `binary` | Object | Бинарные данные (файлы) | | `pairedItem` | Object | Связь с исходным item | ### JSON данные [Заголовок раздела «JSON данные»](#json-данные) Основной контейнер для данных: ```json { "json": { "любой_ключ": "любое_значение", "nested": { "object": true }, "array": [1, 2, 3] } } ``` ### Binary данные [Заголовок раздела «Binary данные»](#binary-данные) Для файлов и бинарных данных: ```json { "json": { "fileName": "image.png" }, "binary": { "data": { "data": "base64_encoded_content...", "mimeType": "image/png", "fileName": "image.png", "fileSize": 12345 } } } ``` ## Доступ к данным [Заголовок раздела «Доступ к данным»](#доступ-к-данным) ### Текущий item [Заголовок раздела «Текущий item»](#текущий-item) ```javascript // В Expression {{ $json.fieldName }} {{ $json.nested.value }} {{ $json["field-with-dash"] }} ``` ### Binary данные [Заголовок раздела «Binary данные»](#binary-данные-1) ```javascript // Получить binary данные {{ $binary.data }} // Метаданные файла {{ $binary.data.fileName }} {{ $binary.data.mimeType }} ``` ## Методы работы с items [Заголовок раздела «Методы работы с items»](#методы-работы-с-items) ### Input методы [Заголовок раздела «Input методы»](#input-методы) | Метод | Описание | | ---------------- | -------------- | | `$input.all()` | Все items | | `$input.first()` | Первый item | | `$input.last()` | Последний item | | `$input.item` | Текущий item | ### Примеры [Заголовок раздела «Примеры»](#примеры) * Expression ```javascript // Все items {{ $input.all() }} // Первый item {{ $input.first().json.name }} // Количество items {{ $input.all().length }} ``` * Code Node ```javascript // Получить все items const items = $input.all(); // Обработать каждый return items.map(item => ({ json: { ...item.json, processed: true } })); ``` ## Доступ к другим нодам [Заголовок раздела «Доступ к другим нодам»](#доступ-к-другим-нодам) ### По имени ноды [Заголовок раздела «По имени ноды»](#по-имени-ноды) ```javascript // Данные из конкретной ноды {{ $('HTTP Request').item.json.data }} // Все items из ноды {{ $('HTTP Request').all() }} // Первый item {{ $('HTTP Request').first().json }} ``` ### Методы ноды [Заголовок раздела «Методы ноды»](#методы-ноды) | Метод | Описание | | ------------------------------- | -------------------- | | `$('Node').all()` | Все items | | `$('Node').first()` | Первый item | | `$('Node').last()` | Последний item | | `$('Node').item` | Соответствующий item | | `$('Node').itemMatching(index)` | Item по индексу | Осторожно Метод `$('Node').item` работает только если количество items совпадает между нодами. ## Преобразование данных [Заголовок раздела «Преобразование данных»](#преобразование-данных) ### Изменение структуры [Заголовок раздела «Изменение структуры»](#изменение-структуры) ```javascript // В Code ноде const items = $input.all(); return items.map(item => ({ json: { // Переименование полей userId: item.json.id, fullName: item.json.name, // Добавление полей createdAt: new Date().toISOString(), // Вычисляемые поля isAdult: item.json.age >= 18 } })); ``` ### Фильтрация [Заголовок раздела «Фильтрация»](#фильтрация) ```javascript const items = $input.all(); return items.filter(item => item.json.status === 'active' ); ``` ### Агрегация [Заголовок раздела «Агрегация»](#агрегация) ```javascript const items = $input.all(); const total = items.reduce((sum, item) => sum + item.json.amount, 0 ); return [{ json: { total } }]; ``` ## Работа с массивами [Заголовок раздела «Работа с массивами»](#работа-с-массивами) ### Массив внутри item [Заголовок раздела «Массив внутри item»](#массив-внутри-item) ```json { "json": { "user": "John", "orders": [ { "id": 1, "total": 100 }, { "id": 2, "total": 200 } ] } } ``` ### Разворачивание (Split) [Заголовок раздела «Разворачивание (Split)»](#разворачивание-split) Нода **Split Out** разбивает массив на отдельные items: ```plaintext До: 1 item с массивом [a, b, c] После: 3 items: a, b, c ``` ### Сворачивание (Aggregate) [Заголовок раздела «Сворачивание (Aggregate)»](#сворачивание-aggregate) Нода **Aggregate** объединяет items в массив: ```plaintext До: 3 items: a, b, c После: 1 item с массивом [a, b, c] ``` ## Типы данных [Заголовок раздела «Типы данных»](#типы-данных) ### Примитивы [Заголовок раздела «Примитивы»](#примитивы) | Тип | Пример | | ------- | --------------- | | String | `"Hello"` | | Number | `42`, `3.14` | | Boolean | `true`, `false` | | Null | `null` | ### Сложные типы [Заголовок раздела «Сложные типы»](#сложные-типы) | Тип | Пример | | ------ | ------------------------ | | Object | `{ "key": "value" }` | | Array | `[1, 2, 3]` | | Date | `"2024-01-15T10:30:00Z"` | ### Проверка типов [Заголовок раздела «Проверка типов»](#проверка-типов) ```javascript // В Expression {{ typeof $json.value }} // В Code if (typeof item.json.value === 'string') { // ... } ``` ## Специальные переменные [Заголовок раздела «Специальные переменные»](#специальные-переменные) | Переменная | Описание | | ------------ | --------------------------- | | `$json` | JSON текущего item | | `$binary` | Binary данные текущего item | | `$itemIndex` | Индекс текущего item | | `$runIndex` | Номер выполнения в цикле | | `$now` | Текущее время (DateTime) | | `$today` | Сегодняшняя дата | ## Паттерны [Заголовок раздела «Паттерны»](#паттерны) ### Объединение данных из разных источников [Заголовок раздела «Объединение данных из разных источников»](#объединение-данных-из-разных-источников) ### Обогащение данных [Заголовок раздела «Обогащение данных»](#обогащение-данных) ```javascript // Добавить данные из lookup const users = $input.all(); const roles = $('Get Roles').all(); return users.map(user => { const role = roles.find(r => r.json.userId === user.json.id ); return { json: { ...user.json, role: role?.json.name || 'unknown' } }; }); ``` ## Следующие шаги [Заголовок раздела «Следующие шаги»](#следующие-шаги) * [Слияние данных](/concepts/merging/) — объединение потоков * [Трансформация](/concepts/transforming/) — преобразование данных * [Expressions](/code/expressions/) — работа с выражениями # Логика потоков > Условия, ветвление и управление потоком данных в n8n ## Управление потоком [Заголовок раздела «Управление потоком»](#управление-потоком) n8n предоставляет несколько способов управления потоком выполнения: ## IF (Условие) [Заголовок раздела «IF (Условие)»](#if-условие) Простое условное ветвление: true или false. ### Базовое использование [Заголовок раздела «Базовое использование»](#базовое-использование) | Параметр | Описание | | -------------- | -------------------------- | | **Conditions** | Одно или несколько условий | | **Combine** | AND (все) или OR (любое) | ### Типы условий [Заголовок раздела «Типы условий»](#типы-условий) * String ```plaintext {{ $json.status }} equals "active" {{ $json.name }} contains "John" {{ $json.email }} matches regex .*@gmail\.com ``` * Number ```plaintext {{ $json.age }} is greater than 18 {{ $json.price }} is less than or equal 100 {{ $json.count }} equals 0 ``` * Boolean ```plaintext {{ $json.isActive }} is true {{ $json.verified }} is false {{ $json.data }} exists ``` ### Пример: Проверка статуса [Заголовок раздела «Пример: Проверка статуса»](#пример-проверка-статуса) Настройка IF: ```plaintext Condition: {{ $json.statusCode }} equals 200 ``` ### Множественные условия [Заголовок раздела «Множественные условия»](#множественные-условия) ```plaintext Условие 1: {{ $json.status }} equals "active" AND Условие 2: {{ $json.age }} is greater than 18 ``` ## Switch (Переключатель) [Заголовок раздела «Switch (Переключатель)»](#switch-переключатель) Множественное ветвление по значению. ### Режимы работы [Заголовок раздела «Режимы работы»](#режимы-работы) | Режим | Описание | | -------------- | ------------------------------------ | | **Rules** | Набор правил с условиями | | **Expression** | Выражение, возвращающее номер выхода | ### Routing Rules [Заголовок раздела «Routing Rules»](#routing-rules) Настройка правил: ```plaintext Rule 1: {{ $json.type }} equals "email" → Output 0 Rule 2: {{ $json.type }} equals "sms" → Output 1 Rule 3: {{ $json.type }} equals "push" → Output 2 Fallback: Output 3 ``` ### Expression Mode [Заголовок раздела «Expression Mode»](#expression-mode) ```javascript // Возвращает индекс выхода (0, 1, 2, ...) switch($json.priority) { case 'high': return 0; case 'medium': return 1; default: return 2; } ``` ## Filter [Заголовок раздела «Filter»](#filter) Фильтрация items по условию. ### Пример: Только активные пользователи [Заголовок раздела «Пример: Только активные пользователи»](#пример-только-активные-пользователи) ```javascript // Условие фильтрации {{ $json.status }} equals "active" ``` Результат: Items, не соответствующие условию, отбрасываются. Совет Filter отличается от IF тем, что не создаёт второй выход — несоответствующие items просто удаляются. ## Remove Duplicates [Заголовок раздела «Remove Duplicates»](#remove-duplicates) Удаление дубликатов по полю. | Параметр | Описание | | ----------- | ---------------------- | | **Compare** | Поле для сравнения | | **Action** | Keep first / Keep last | Пример: ```plaintext Compare: {{ $json.email }} Action: Keep First Match ``` ## Limit [Заголовок раздела «Limit»](#limit) Ограничение количества items. | Параметр | Описание | | ------------- | ----------------------- | | **Max Items** | Максимальное количество | | **Keep** | First / Last items | ## Sort [Заголовок раздела «Sort»](#sort) Сортировка items. | Параметр | Описание | | ----------- | ---------------------- | | **Sort By** | Поле для сортировки | | **Order** | Ascending / Descending | | **Type** | String / Number / Date | ## Wait [Заголовок раздела «Wait»](#wait) Пауза в выполнении. ### Режимы ожидания [Заголовок раздела «Режимы ожидания»](#режимы-ожидания) | Режим | Описание | | ----------------------- | ---------------------------- | | **After Time Interval** | Пауза на время | | **At Specific Time** | Продолжить в указанное время | | **On Webhook Call** | Ждать webhook | | **On Form Submission** | Ждать заполнения формы | ### Пример: Rate Limiting [Заголовок раздела «Пример: Rate Limiting»](#пример-rate-limiting) ## No Operation (NoOp) [Заголовок раздела «No Operation (NoOp)»](#no-operation-noop) Нода-заглушка, не выполняющая действий. Использование: * Placeholder для будущей логики * Точка соединения нескольких веток * Комментарий к workflow ## Паттерны ветвления [Заголовок раздела «Паттерны ветвления»](#паттерны-ветвления) ### Параллельное выполнение [Заголовок раздела «Параллельное выполнение»](#параллельное-выполнение) Подключите несколько нод к одному выходу. ### Условное выполнение [Заголовок раздела «Условное выполнение»](#условное-выполнение) ### Fallback паттерн [Заголовок раздела «Fallback паттерн»](#fallback-паттерн) ## Лучшие практики [Заголовок раздела «Лучшие практики»](#лучшие-практики) 1. **Ясные имена условий** — называйте IF/Switch понятно: “Check Status”, “Route by Type” 2. **Минимум вложенности** — избегайте глубоких цепочек IF 3. **Default ветка** — всегда добавляйте fallback в Switch 4. **Логирование ветвлений** — добавляйте logging для отладки 5. **Документируйте логику** — используйте Sticky Notes ## Следующие шаги [Заголовок раздела «Следующие шаги»](#следующие-шаги) * [Структура данных](/concepts/data-structure/) — формат данных n8n * [Слияние данных](/concepts/merging/) — объединение потоков * [Циклы](/concepts/looping/) — итерация по данным # Циклы > Итерация по данным и циклическая обработка в n8n ## Автоматическая итерация [Заголовок раздела «Автоматическая итерация»](#автоматическая-итерация) По умолчанию n8n автоматически обрабатывает каждый item: Нода выполнится 3 раза — по одному для каждого item. Совет Большинство задач не требуют явных циклов — используйте автоматическую итерацию. ## Loop Over Items [Заголовок раздела «Loop Over Items»](#loop-over-items) Явный цикл с контролем итерации. ### Когда использовать [Заголовок раздела «Когда использовать»](#когда-использовать) * Обработка с паузами (rate limiting) * Batch processing * Условная остановка цикла * Отслеживание прогресса ### Настройка [Заголовок раздела «Настройка»](#настройка) | Параметр | Описание | | -------------- | ---------------------- | | **Batch Size** | Items за одну итерацию | | **Options** | Reset, Pause | ### Пример: Rate-limited API [Заголовок раздела «Пример: Rate-limited API»](#пример-rate-limited-api) 1. **Loop Over Items**: Batch Size = 1 2. **HTTP Request**: API вызов 3. **Wait**: 1 секунда 4. **Done**: Подключить выход “done” ## Split In Batches [Заголовок раздела «Split In Batches»](#split-in-batches) Разбиение на пакеты для параллельной обработки. ### Настройка [Заголовок раздела «Настройка»](#настройка-1) | Параметр | Описание | | -------------- | ------------- | | **Batch Size** | Размер пакета | ### Паттерн обработки [Заголовок раздела «Паттерн обработки»](#паттерн-обработки) ```javascript // В Code после Split In Batches const batch = $input.all(); // Обработка пакета const results = await Promise.all( batch.map(item => processItem(item)) ); return results; ``` ## Рекурсивные workflow [Заголовок раздела «Рекурсивные workflow»](#рекурсивные-workflow) Вызов workflow из самого себя для обработки иерархий. ### Execute Workflow (Self) [Заголовок раздела «Execute Workflow (Self)»](#execute-workflow-self) Осторожно Установите ограничение глубины, чтобы избежать бесконечной рекурсии. ### Пример: Обход дерева [Заголовок раздела «Пример: Обход дерева»](#пример-обход-дерева) ```javascript // Входные данные { "id": 1, "children": [ { "id": 2, "children": [] }, { "id": 3, "children": [ { "id": 4, "children": [] } ]} ] } ``` Workflow: 1. Получить текущий узел 2. Обработать узел 3. Для каждого child вызвать этот же workflow 4. Собрать результаты ## While-цикл через Loop [Заголовок раздела «While-цикл через Loop»](#while-цикл-через-loop) Цикл с условием выхода: ### Реализация [Заголовок раздела «Реализация»](#реализация) ```javascript // В Code ноде внутри цикла const currentItem = $input.first(); const shouldContinue = currentItem.json.hasMore; if (!shouldContinue) { // Завершить цикл return []; } // Продолжить return [currentItem]; ``` ## Pagination [Заголовок раздела «Pagination»](#pagination) Получение данных постранично. ### Встроенная пагинация [Заголовок раздела «Встроенная пагинация»](#встроенная-пагинация) HTTP Request поддерживает автоматическую пагинацию: | Параметр | Значение | | ------------------- | ------------------------------- | | **Pagination Mode** | Update a Parameter Each Request | | **Parameter** | `page` | | **Start Value** | 1 | | **Update** | +1 | ### Ручная пагинация [Заголовок раздела «Ручная пагинация»](#ручная-пагинация) ```javascript // В Code ноде const response = $input.first().json; const currentPage = $('Set Page').first().json.page; if (response.hasNextPage) { return [{ json: { page: currentPage + 1, data: response.data } }]; } // Пагинация завершена return [{ json: { done: true, allData: response.data }}]; ``` ## Performance Tips [Заголовок раздела «Performance Tips»](#performance-tips) ### Batch вместо поэлементной обработки [Заголовок раздела «Batch вместо поэлементной обработки»](#batch-вместо-поэлементной-обработки) ```javascript // ❌ Медленно items.forEach(async item => { await apiCall(item); }); // ✅ Быстро await apiCall(items); // Если API поддерживает batch ``` ### Параллельная обработка [Заголовок раздела «Параллельная обработка»](#параллельная-обработка) Используйте Split In Batches с оптимальным размером: * Маленькие batches: меньше памяти, больше overhead * Большие batches: больше памяти, меньше overhead * Оптимум: 50-100 items при batch API ### Ограничение параллелизма [Заголовок раздела «Ограничение параллелизма»](#ограничение-параллелизма) ```javascript // В Code ноде const CONCURRENT_LIMIT = 5; const items = $input.all(); const results = []; for (let i = 0; i < items.length; i += CONCURRENT_LIMIT) { const batch = items.slice(i, i + CONCURRENT_LIMIT); const batchResults = await Promise.all( batch.map(item => processItem(item)) ); results.push(...batchResults); } return results.map(r => ({ json: r })); ``` ## Паттерны [Заголовок раздела «Паттерны»](#паттерны) ### Retry с экспоненциальным backoff [Заголовок раздела «Retry с экспоненциальным backoff»](#retry-с-экспоненциальным-backoff) ```javascript const maxRetries = 3; let attempt = $input.first().json.attempt || 0; try { const result = await riskyOperation(); return [{ json: result }]; } catch (error) { if (attempt < maxRetries) { // Продолжить цикл с увеличенным attempt return [{ json: { attempt: attempt + 1, waitTime: Math.pow(2, attempt) * 1000 } }]; } throw error; } ``` ### Cursor-based пагинация [Заголовок раздела «Cursor-based пагинация»](#cursor-based-пагинация) ```javascript const response = $input.first().json; const cursor = response.nextCursor; if (cursor) { return [{ json: { cursor, accumulatedData: [ ...($json.accumulatedData || []), ...response.data ] } }]; } // Все данные получены return [{ json: { data: [...($json.accumulatedData || []), ...response.data] } }]; ``` ## Следующие шаги [Заголовок раздела «Следующие шаги»](#следующие-шаги) * [Трансформация данных](/concepts/transforming/) — преобразование * [Слияние данных](/concepts/merging/) — объединение потоков * [Code Node](/code/code-node/) — программирование в n8n # Слияние данных > Объединение данных из нескольких потоков в n8n ## Merge Node [Заголовок раздела «Merge Node»](#merge-node) Нода **Merge** объединяет данные из нескольких входов. ## Режимы слияния [Заголовок раздела «Режимы слияния»](#режимы-слияния) ### Append [Заголовок раздела «Append»](#append) Объединение всех items в один поток: ```plaintext Input 1: [A, B] Input 2: [C, D] ─────────────── Output: [A, B, C, D] ``` **Использование**: Собрать данные из разных источников в один список. ### Combine [Заголовок раздела «Combine»](#combine) Объединение по позиции (индексу): ```plaintext Input 1: [A1, A2, A3] Input 2: [B1, B2, B3] ──────────────────── Output: [A1+B1, A2+B2, A3+B3] ``` **Использование**: Добавить данные из одного источника к другому. Осторожно При разном количестве items лишние отбрасываются. Используйте опцию “Include Unpaired Items” для сохранения. ### Multiplex [Заголовок раздела «Multiplex»](#multiplex) Все возможные комбинации: ```plaintext Input 1: [A, B] Input 2: [1, 2] ────────────── Output: [A+1, A+2, B+1, B+2] ``` **Использование**: Создание всех комбинаций (например, продукты × регионы). ### Choose Branch [Заголовок раздела «Choose Branch»](#choose-branch) Выбор одного потока данных: | Опция | Описание | | --------------- | --------------------- | | **Output Type** | First non-empty / All | | **Priority** | Порядок приоритета | **Использование**: Fallback логика — использовать данные из первого успешного источника. ## Расширенные режимы Combine [Заголовок раздела «Расширенные режимы Combine»](#расширенные-режимы-combine) ### By Field [Заголовок раздела «By Field»](#by-field) Объединение по значению поля (аналог JOIN): ```plaintext Input 1: Input 2: ┌────┬───────┐ ┌────┬─────┐ │ id │ name │ │ id │ age │ ├────┼───────┤ ├────┼─────┤ │ 1 │ John │ │ 1 │ 30 │ │ 2 │ Jane │ │ 2 │ 25 │ └────┴───────┘ └────┴─────┘ Output (by field "id"): ┌────┬───────┬─────┐ │ id │ name │ age │ ├────┼───────┼─────┤ │ 1 │ John │ 30 │ │ 2 │ Jane │ 25 │ └────┴───────┴─────┘ ``` ### Настройка Join [Заголовок раздела «Настройка Join»](#настройка-join) | Параметр | Описание | | -------------------- | --------------------------- | | **Join Mode** | Inner / Left / Right / Full | | **Field to Match** | Поле для сопоставления | | **Output Data From** | Both / Input 1 / Input 2 | * Inner Join Только совпадающие записи из обоих источников. * Left Join Все записи из Input 1 + совпадения из Input 2. * Right Join Все записи из Input 2 + совпадения из Input 1. * Full Join Все записи из обоих источников. ## Примеры [Заголовок раздела «Примеры»](#примеры) ### Объединение данных из API [Заголовок раздела «Объединение данных из API»](#объединение-данных-из-api) Настройка: * Mode: **Combine** * Type: **By Field** * Field Input 1: `userId` * Field Input 2: `userId` ### Fallback при ошибке [Заголовок раздела «Fallback при ошибке»](#fallback-при-ошибке) Настройка Merge: * Mode: **Choose Branch** * Output Type: **First Non-Empty** ### Обогащение данных [Заголовок раздела «Обогащение данных»](#обогащение-данных) Последовательное обогащение: 1. Merge Products + Categories by `categoryId` 2. Merge результат + Prices by `productId` ## Compare Datasets [Заголовок раздела «Compare Datasets»](#compare-datasets) Сравнение двух наборов данных: | Режим | Описание | | ------------------ | ----------------------------- | | **Same** | Items, присутствующие в обоих | | **Different** | Items, различающиеся | | **Only in First** | Items только в первом наборе | | **Only in Second** | Items только во втором наборе | ### Пример: Синхронизация [Заголовок раздела «Пример: Синхронизация»](#пример-синхронизация) ## Aggregate Node [Заголовок раздела «Aggregate Node»](#aggregate-node) Агрегация items в один: ### Режимы агрегации [Заголовок раздела «Режимы агрегации»](#режимы-агрегации) | Режим | Результат | | --------------------- | ------------------------ | | **Individual Fields** | Выбранные поля в массивы | | **All Item Data** | Все данные в один массив | ### Пример: Сбор email’ов [Заголовок раздела «Пример: Сбор email’ов»](#пример-сбор-emailов) ```plaintext Input: [{email: "a@x.com"}, {email: "b@x.com"}, {email: "c@x.com"}] Aggregate by field "email": [{emails: ["a@x.com", "b@x.com", "c@x.com"]}] ``` ## Split Out Node [Заголовок раздела «Split Out Node»](#split-out-node) Разделение массива на отдельные items: ```plaintext Input: [{tags: ["a", "b", "c"]}] Split by field "tags": [{tags: "a"}, {tags: "b"}, {tags: "c"}] ``` ## Паттерны [Заголовок раздела «Паттерны»](#паттерны) ### Fan-out / Fan-in [Заголовок раздела «Fan-out / Fan-in»](#fan-out--fan-in) ### Lookup Table [Заголовок раздела «Lookup Table»](#lookup-table) ```javascript // В Code node после Merge const items = $input.all(); const lookup = $('Lookup Table').first().json; return items.map(item => ({ json: { ...item.json, categoryName: lookup[item.json.categoryId] || 'Unknown' } })); ``` ## Следующие шаги [Заголовок раздела «Следующие шаги»](#следующие-шаги) * [Циклы](/concepts/looping/) — итерация по данным * [Трансформация](/concepts/transforming/) — преобразование данных * [Логика потоков](/concepts/flow-logic/) — условия и ветвление # Трансформация данных > Преобразование и обработка данных в n8n ## Ноды для трансформации [Заголовок раздела «Ноды для трансформации»](#ноды-для-трансформации) | Нода | Назначение | | --------------- | ------------------------------ | | **Set** | Создание/изменение полей | | **Code** | Произвольная логика | | **Edit Fields** | Переименование, удаление полей | | **Date & Time** | Работа с датами | | **Crypto** | Хеширование, шифрование | | **HTML** | Парсинг HTML | | **JSON** | Конвертация JSON | ## Set Node [Заголовок раздела «Set Node»](#set-node) Универсальная нода для работы с данными. ### Режимы [Заголовок раздела «Режимы»](#режимы) | Режим | Описание | | ------------------ | --------------------- | | **Manual Mapping** | Ручное указание полей | | **JSON** | Ввод JSON напрямую | ### Manual Mapping [Заголовок раздела «Manual Mapping»](#manual-mapping) Добавление полей: | Параметр | Пример | | --------- | -------------------------------------------- | | **Name** | `fullName` | | **Value** | `{{ $json.firstName }} {{ $json.lastName }}` | ### Опции [Заголовок раздела «Опции»](#опции) | Опция | Описание | | --------------------------------- | -------------------------- | | **Keep Only Set** | Оставить только новые поля | | **Include Other Input Fields** | Сохранить существующие | | **Ignore Type Conversion Errors** | Игнорировать ошибки типов | ## Edit Fields Node [Заголовок раздела «Edit Fields Node»](#edit-fields-node) Переименование и удаление полей. ### Операции [Заголовок раздела «Операции»](#операции) * Rename ```plaintext oldFieldName → newFieldName user.name → userName ``` * Remove ```plaintext Удалить: password, secretKey ``` * Move ```plaintext data.user.name → userName ``` ## Code Node [Заголовок раздела «Code Node»](#code-node) Полный контроль через JavaScript/Python. ### JavaScript [Заголовок раздела «JavaScript»](#javascript) ```javascript // Трансформация данных const items = $input.all(); return items.map(item => ({ json: { // Преобразование полей id: item.json.id, name: item.json.name.toUpperCase(), email: item.json.email.toLowerCase(), // Вычисляемые поля createdAt: new Date().toISOString(), isActive: item.json.status === 'active', // Вложенные объекты metadata: { source: 'n8n', processedAt: Date.now() } } })); ``` ### Python [Заголовок раздела «Python»](#python) ```python items = _input.all() for item in items: # Трансформация item['json']['name'] = item['json']['name'].upper() item['json']['email'] = item['json']['email'].lower() item['json']['isActive'] = item['json']['status'] == 'active' return items ``` ## Типичные трансформации [Заголовок раздела «Типичные трансформации»](#типичные-трансформации) ### Преобразование типов [Заголовок раздела «Преобразование типов»](#преобразование-типов) ```javascript // String → Number const num = parseInt($json.value, 10); const float = parseFloat($json.price); // Number → String const str = $json.count.toString(); // String → Boolean const bool = $json.flag === 'true'; // String → Date const date = new Date($json.dateString); ``` ### Работа со строками [Заголовок раздела «Работа со строками»](#работа-со-строками) ```javascript // Обрезка пробелов const trimmed = $json.name.trim(); // Разделение const parts = $json.fullName.split(' '); const firstName = parts[0]; const lastName = parts[1]; // Объединение const fullAddress = `${$json.city}, ${$json.street}, ${$json.building}`; // Замена const cleaned = $json.phone.replace(/[^0-9]/g, ''); // Форматирование const padded = $json.id.toString().padStart(5, '0'); ``` ### Работа с массивами [Заголовок раздела «Работа с массивами»](#работа-с-массивами) ```javascript // Фильтрация const active = $json.users.filter(u => u.isActive); // Преобразование const names = $json.users.map(u => u.name); // Сортировка const sorted = $json.users.sort((a, b) => a.age - b.age); // Поиск const admin = $json.users.find(u => u.role === 'admin'); // Уникальные значения const unique = [...new Set($json.tags)]; // Группировка const byRole = $json.users.reduce((acc, user) => { (acc[user.role] = acc[user.role] || []).push(user); return acc; }, {}); ``` ### Работа с объектами [Заголовок раздела «Работа с объектами»](#работа-с-объектами) ```javascript // Извлечение ключей const keys = Object.keys($json.data); // Извлечение значений const values = Object.values($json.data); // Слияние объектов const merged = { ...$json.defaults, ...$json.overrides }; // Удаление полей const { password, ...safeData } = $json.user; // Переименование ключей const renamed = Object.fromEntries( Object.entries($json.data).map(([k, v]) => [k.toLowerCase(), v]) ); ``` ## Date & Time Node [Заголовок раздела «Date & Time Node»](#date--time-node) Работа с датами и временем. ### Операции [Заголовок раздела «Операции»](#операции-1) | Операция | Описание | | -------------------------- | ---------------------- | | **Calculate** | Добавить/вычесть время | | **Format** | Форматировать дату | | **Round** | Округлить до единицы | | **Get Time Between Dates** | Разница между датами | ### Форматирование [Заголовок раздела «Форматирование»](#форматирование) ```javascript // Expressions для дат {{ $json.date.format('YYYY-MM-DD') }} {{ $json.date.format('DD.MM.YYYY HH:mm') }} {{ $now.format('YYYY-MM-DD') }} ``` ### Часовые пояса [Заголовок раздела «Часовые пояса»](#часовые-пояса) ```javascript // Конвертация часового пояса {{ $json.date.setZone('Europe/Moscow').toISO() }} ``` ## JSON Node [Заголовок раздела «JSON Node»](#json-node) Конвертация между JSON и строкой. ### Parse [Заголовок раздела «Parse»](#parse) ```plaintext Input: '{"name": "John", "age": 30}' Output: { name: "John", age: 30 } ``` ### Stringify [Заголовок раздела «Stringify»](#stringify) ```plaintext Input: { name: "John", age: 30 } Output: '{"name":"John","age":30}' ``` ## HTML Node [Заголовок раздела «HTML Node»](#html-node) Извлечение данных из HTML. ### Extract [Заголовок раздела «Extract»](#extract) ```javascript // CSS selector selector: 'div.product h2' // Результат: массив текстов из найденных элементов // Атрибуты selector: 'a.link' attribute: 'href' ``` ## Crypto Node [Заголовок раздела «Crypto Node»](#crypto-node) Хеширование и шифрование. ### Операции [Заголовок раздела «Операции»](#операции-2) | Операция | Примеры | | ----------- | ------------------- | | **Hash** | MD5, SHA256, SHA512 | | **HMAC** | HMAC-SHA256 | | **Encrypt** | AES | | **Decrypt** | AES | ### Пример хеширования [Заголовок раздела «Пример хеширования»](#пример-хеширования) ```javascript // В Expression {{ $json.password.hash('sha256') }} // Или через ноду Crypto Action: Hash Type: SHA256 Value: {{ $json.password }} ``` ## Паттерны [Заголовок раздела «Паттерны»](#паттерны) ### Нормализация данных [Заголовок раздела «Нормализация данных»](#нормализация-данных) ```javascript // Привести к единому формату return $input.all().map(item => ({ json: { id: String(item.json.id || item.json.ID || item.json._id), name: (item.json.name || item.json.title || '').trim(), email: (item.json.email || '').toLowerCase().trim(), phone: (item.json.phone || '').replace(/\D/g, ''), createdAt: new Date(item.json.created_at || item.json.createdAt).toISOString() } })); ``` ### Валидация и очистка [Заголовок раздела «Валидация и очистка»](#валидация-и-очистка) ```javascript const items = $input.all(); return items .filter(item => { // Валидация const email = item.json.email; return email && email.includes('@'); }) .map(item => ({ json: { ...item.json, // Очистка phone: item.json.phone?.replace(/[^0-9+]/g, ''), name: item.json.name?.trim().replace(/\s+/g, ' ') } })); ``` ### Flatten вложенных структур [Заголовок раздела «Flatten вложенных структур»](#flatten-вложенных-структур) ```javascript // Из { user: { name: 'John', address: { city: 'NYC' }}} // В { user_name: 'John', user_address_city: 'NYC' } function flatten(obj, prefix = '') { return Object.keys(obj).reduce((acc, key) => { const pre = prefix.length ? `${prefix}_` : ''; if (typeof obj[key] === 'object' && obj[key] !== null && !Array.isArray(obj[key])) { Object.assign(acc, flatten(obj[key], pre + key)); } else { acc[pre + key] = obj[key]; } return acc; }, {}); } return [{ json: flatten($input.first().json) }]; ``` ## Следующие шаги [Заголовок раздела «Следующие шаги»](#следующие-шаги) * [Expressions](/code/expressions/) — выражения в n8n * [Code Node](/code/code-node/) — программирование * [Структура данных](/concepts/data-structure/) — формат данных # Ожидание (Waiting) > Пауза выполнения workflow с возобновлением по времени или событию **Waiting** позволяет приостановить выполнение workflow и возобновить его позже — по таймеру или при получении webhook. ## Зачем нужен Waiting [Заголовок раздела «Зачем нужен Waiting»](#зачем-нужен-waiting) | Сценарий | Описание | | -------------------------- | -------------------------------- | | **Rate limiting** | Задержка между API вызовами | | **Ожидание подтверждения** | Пауза до одобрения пользователем | | **Scheduled actions** | Отложенное выполнение | | **External events** | Ожидание внешнего события | *** ## Wait Node [Заголовок раздела «Wait Node»](#wait-node) Нода **Wait** приостанавливает выполнение workflow. ### Режимы работы [Заголовок раздела «Режимы работы»](#режимы-работы) * After time interval Возобновление через указанное время: ```plaintext ┌────────────┐ ┌────────────┐ ┌────────────┐ │ Trigger │───→│ Wait │───→│ Следующая │ │ │ │ (5 минут) │ │ нода │ └────────────┘ └────────────┘ └────────────┘ ``` **Настройки:** * **Amount**: число * **Unit**: секунды, минуты, часы, дни * At specified time Возобновление в конкретное время: ```javascript // Примеры: // - Завтра в 9:00 // - Через 3 дня // - В конкретную дату и время ``` **Настройки:** * **Resume at**: дата и время * On webhook call Возобновление при получении webhook: ```plaintext ┌────────────┐ ┌────────────┐ ┌────────────┐ │ Trigger │───→│ Wait │ ← hook ─│ External │ │ │ │ (webhook) │ │ System │ └────────────┘ └────────────┘ └────────────┘ │ ↓ ┌────────────┐ │ Следующая │ │ нода │ └────────────┘ ``` **Настройки:** * **Resume URL**: уникальный URL для возобновления *** ## Примеры использования [Заголовок раздела «Примеры использования»](#примеры-использования) ### Пример 1: Rate limiting [Заголовок раздела «Пример 1: Rate limiting»](#пример-1-rate-limiting) При работе с API с лимитами: ```plaintext ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ Get Data │───→│ Process │───→│ Wait │───→│ Next Batch │ │ │ │ │ │ (1 секунда)│ │ │ └────────────┘ └────────────┘ └────────────┘ └────────────┘ ``` Совет Для простых задержек между запросами используйте **Split In Batches** с параметром **Wait Between Batches**. ### Пример 2: Approval workflow [Заголовок раздела «Пример 2: Approval workflow»](#пример-2-approval-workflow) Отправка письма с ссылками на одобрение/отклонение: ```plaintext ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ Request │───→│ Send Email │───→│ Wait │───→│ Switch │ │ │ │ (с ссылками)│ │ (webhook) │ │(approve?) │ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │ ┌─────────┴─────────┐ ↓ ↓ ┌──────────┐ ┌──────────┐ │ Approved │ │ Rejected │ └──────────┘ └──────────┘ ``` **Email содержит:** ```plaintext Новый запрос на отпуск от {{ $json.employee }} [Одобрить]({{ $node.Wait.resumeUrl }}?action=approve) [Отклонить]({{ $node.Wait.resumeUrl }}?action=reject) ``` ### Пример 3: Scheduled reminder [Заголовок раздела «Пример 3: Scheduled reminder»](#пример-3-scheduled-reminder) Напоминание через определённое время: ```plaintext ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ Create │───→│ Slack │───→│ Wait │───→│ Slack │ │ Task │ │ (создано) │ │ (24 часа) │ │(напомнить) │ └────────────┘ └────────────┘ └────────────┘ └────────────┘ ``` ### Пример 4: Multi-step form [Заголовок раздела «Пример 4: Multi-step form»](#пример-4-multi-step-form) Сбор данных в несколько этапов: ```plaintext Step 1: Получить email ↓ [Wait for webhook] ← Пользователь заполняет форму ↓ Step 2: Получить контактные данные ↓ [Wait for webhook] ← Пользователь продолжает ↓ Step 3: Финализация ``` *** ## Webhook Resume URL [Заголовок раздела «Webhook Resume URL»](#webhook-resume-url) При использовании режима **On webhook call**, Wait нода предоставляет уникальный URL: ```javascript // Доступ к URL в выражениях: {{ $node.Wait.resumeUrl }} // Полный URL примерно такой: https://n8n.example.com/webhook-waiting/abc123-def456 ``` ### Передача данных через webhook [Заголовок раздела «Передача данных через webhook»](#передача-данных-через-webhook) Данные, отправленные на webhook, доступны в следующих нодах: ```bash # Пример вызова: curl -X POST "https://n8n.example.com/webhook-waiting/abc123" \ -H "Content-Type: application/json" \ -d '{"action": "approve", "comment": "OK"}' ``` ```javascript // В следующей ноде: {{ $json.action }} // "approve" {{ $json.comment }} // "OK" ``` *** ## Хранение состояния [Заголовок раздела «Хранение состояния»](#хранение-состояния) Осторожно Во время ожидания execution приостановлена, но **состояние сохранено** в базе данных. При перезапуске n8n ожидающие executions продолжат работу. ### Ограничения [Заголовок раздела «Ограничения»](#ограничения) | Ограничение | Описание | | ------------------ | ------------------------------------------- | | Максимальное время | Зависит от настроек (по умолчанию 365 дней) | | Память | Данные хранятся в БД, не в памяти | | Webhooks | URL валиден только пока execution ожидает | *** ## Настройки [Заголовок раздела «Настройки»](#настройки) ### Timeout [Заголовок раздела «Timeout»](#timeout) ```javascript // В переменных окружения: EXECUTIONS_TIMEOUT=3600 // Общий timeout (секунды) EXECUTIONS_TIMEOUT_MAX=86400 // Максимальный timeout ``` ### Limit Wait Time [Заголовок раздела «Limit Wait Time»](#limit-wait-time) В настройках Wait ноды можно установить максимальное время ожидания webhook: ```plaintext Limit Wait Time: 7 days ``` Если webhook не получен за это время — execution завершается с ошибкой. *** ## Best Practices [Заголовок раздела «Best Practices»](#best-practices) ### 1. Устанавливайте разумные лимиты [Заголовок раздела «1. Устанавливайте разумные лимиты»](#1-устанавливайте-разумные-лимиты) ```javascript // ✅ Хорошо: конкретный лимит Wait: 24 hours (max 7 days) // ❌ Плохо: бесконечное ожидание Wait: forever ``` ### 2. Информируйте пользователя [Заголовок раздела «2. Информируйте пользователя»](#2-информируйте-пользователя) При отправке approval ссылок: * Укажите deadline * Объясните последствия бездействия * Добавьте fallback (автоматическое отклонение) ### 3. Обрабатывайте timeout [Заголовок раздела «3. Обрабатывайте timeout»](#3-обрабатывайте-timeout) ```plaintext ┌────────────┐ ┌────────────┐ ┌────────────┐ │ Wait │───→│ Switch │───→│ Process │ │ (webhook) │ │ (timeout?) │ │ │ └────────────┘ └─────┬──────┘ └────────────┘ │ Timeout ↓ ┌────────────┐ │ Fallback │ └────────────┘ ``` ### 4. Используйте уникальные идентификаторы [Заголовок раздела «4. Используйте уникальные идентификаторы»](#4-используйте-уникальные-идентификаторы) При работе с webhooks добавляйте ID для отслеживания: ```javascript // В URL: {{ $node.Wait.resumeUrl }}?request_id={{ $json.id }} ``` *** ## Альтернативы [Заголовок раздела «Альтернативы»](#альтернативы) | Задача | Лучший выбор | | ----------------------- | ---------------------- | | Простая задержка | `Wait` с time interval | | Задержка между batch | `Split In Batches` | | Запуск по расписанию | `Schedule Trigger` | | Ожидание события | `Wait` с webhook | | Polling внешней системы | Loop + `Wait` + `IF` | *** ## Связанные темы [Заголовок раздела «Связанные темы»](#связанные-темы) Looping [Циклы](/concepts/looping/) — повторное выполнение Triggers [Триггеры](/integrations/triggers/) — запуск workflows Error Handling [Обработка ошибок](/workflows/error-handling/) — timeout errors # Docker > Развёртывание n8n через Docker и Docker Compose ## Быстрый старт [Заголовок раздела «Быстрый старт»](#быстрый-старт) ```bash docker run -it --rm \ --name n8n \ -p 5678:5678 \ -v n8n_data:/home/node/.n8n \ n8nio/n8n ``` Откройте ## Docker Compose [Заголовок раздела «Docker Compose»](#docker-compose) ### Базовая конфигурация [Заголовок раздела «Базовая конфигурация»](#базовая-конфигурация) docker-compose.yml ```yaml version: '3.8' services: n8n: image: n8nio/n8n restart: always ports: - "5678:5678" environment: - N8N_HOST=localhost - N8N_PORT=5678 - N8N_PROTOCOL=http - WEBHOOK_URL=http://localhost:5678/ volumes: - n8n_data:/home/node/.n8n volumes: n8n_data: ``` ### Production с PostgreSQL [Заголовок раздела «Production с PostgreSQL»](#production-с-postgresql) docker-compose.yml ```yaml version: '3.8' services: n8n: image: n8nio/n8n restart: always ports: - "5678:5678" environment: - DB_TYPE=postgresdb - DB_POSTGRESDB_HOST=postgres - DB_POSTGRESDB_PORT=5432 - DB_POSTGRESDB_DATABASE=n8n - DB_POSTGRESDB_USER=n8n - DB_POSTGRESDB_PASSWORD=${POSTGRES_PASSWORD} - N8N_HOST=${N8N_HOST} - N8N_PORT=5678 - N8N_PROTOCOL=https - WEBHOOK_URL=https://${N8N_HOST}/ - N8N_ENCRYPTION_KEY=${N8N_ENCRYPTION_KEY} volumes: - n8n_data:/home/node/.n8n depends_on: postgres: condition: service_healthy postgres: image: postgres:15 restart: always environment: - POSTGRES_USER=n8n - POSTGRES_PASSWORD=${POSTGRES_PASSWORD} - POSTGRES_DB=n8n volumes: - postgres_data:/var/lib/postgresql/data healthcheck: test: ["CMD-SHELL", "pg_isready -U n8n"] interval: 5s timeout: 5s retries: 5 volumes: n8n_data: postgres_data: ``` ### .env файл [Заголовок раздела «.env файл»](#env-файл) .env ```bash POSTGRES_PASSWORD=your_secure_password N8N_HOST=n8n.example.com N8N_ENCRYPTION_KEY=your_32_char_encryption_key_here ``` Осторожно Обязательно установите `N8N_ENCRYPTION_KEY` — он используется для шифрования credentials. Без него credentials будут потеряны при перезапуске. ## Запуск [Заголовок раздела «Запуск»](#запуск) 1. **Создайте файлы** `docker-compose.yml` и `.env` 2. **Запустите** ```bash docker-compose up -d ``` 3. **Проверьте логи** ```bash docker-compose logs -f n8n ``` 4. **Откройте** (или ваш домен) ## Обновление [Заголовок раздела «Обновление»](#обновление) ```bash # Остановить docker-compose down # Обновить образ docker-compose pull # Запустить docker-compose up -d ``` ## Volumes [Заголовок раздела «Volumes»](#volumes) | Volume | Содержимое | | --------------- | ------------------------------------------- | | `n8n_data` | Конфигурация, SQLite DB (если используется) | | `postgres_data` | Данные PostgreSQL | ### Бэкап [Заголовок раздела «Бэкап»](#бэкап) * SQLite ```bash # Бэкап docker run --rm -v n8n_data:/data -v $(pwd):/backup \ alpine tar czf /backup/n8n_backup.tar.gz /data # Восстановление docker run --rm -v n8n_data:/data -v $(pwd):/backup \ alpine tar xzf /backup/n8n_backup.tar.gz -C / ``` * PostgreSQL ```bash # Бэкап docker-compose exec postgres pg_dump -U n8n n8n > backup.sql # Восстановление cat backup.sql | docker-compose exec -T postgres psql -U n8n n8n ``` ## Reverse Proxy [Заголовок раздела «Reverse Proxy»](#reverse-proxy) ### nginx [Заголовок раздела «nginx»](#nginx) ```nginx server { listen 80; server_name n8n.example.com; return 301 https://$server_name$request_uri; } server { listen 443 ssl http2; server_name n8n.example.com; ssl_certificate /etc/letsencrypt/live/n8n.example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/n8n.example.com/privkey.pem; location / { proxy_pass http://localhost:5678; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; chunked_transfer_encoding off; proxy_buffering off; proxy_cache off; } } ``` ### Traefik [Заголовок раздела «Traefik»](#traefik) ```yaml # docker-compose.yml с Traefik services: n8n: image: n8nio/n8n labels: - "traefik.enable=true" - "traefik.http.routers.n8n.rule=Host(`n8n.example.com`)" - "traefik.http.routers.n8n.tls=true" - "traefik.http.routers.n8n.tls.certresolver=letsencrypt" - "traefik.http.services.n8n.loadbalancer.server.port=5678" # ... остальные настройки ``` ## Healthcheck [Заголовок раздела «Healthcheck»](#healthcheck) ```yaml services: n8n: # ... healthcheck: test: ["CMD", "wget", "-q", "--spider", "http://localhost:5678/healthz"] interval: 30s timeout: 10s retries: 3 start_period: 30s ``` ## Resource Limits [Заголовок раздела «Resource Limits»](#resource-limits) ```yaml services: n8n: # ... deploy: resources: limits: cpus: '2' memory: 4G reservations: cpus: '0.5' memory: 1G ``` ## Логирование [Заголовок раздела «Логирование»](#логирование) ```yaml services: n8n: # ... logging: driver: "json-file" options: max-size: "10m" max-file: "3" ``` #### Нужен сервер для n8n с доступом к AI? VPS в Нидерландах или Казахстане — полный доступ к OpenAI, Claude, Gemini. Оплата в рублях. [🇳🇱Нидерланды](/vps_vds_netherlands)[🇰🇿Казахстан](/vps-vds-kazakhstan) ## Следующие шаги [Заголовок раздела «Следующие шаги»](#следующие-шаги) * [Переменные окружения](/hosting/environment-variables/) — полный список * [Масштабирование](/hosting/scaling/) — queue mode * [Безопасность](/hosting/security/) — SSL и аутентификация # Переменные окружения > Конфигурация n8n через переменные окружения ## Основные [Заголовок раздела «Основные»](#основные) | Переменная | Описание | Default | | -------------- | --------------------- | ------------- | | `N8N_HOST` | Hostname для n8n | `localhost` | | `N8N_PORT` | Порт | `5678` | | `N8N_PROTOCOL` | Протокол (http/https) | `http` | | `N8N_PATH` | Base path | `/` | | `WEBHOOK_URL` | URL для webhooks | автоматически | ## База данных [Заголовок раздела «База данных»](#база-данных) ### SQLite (default) [Заголовок раздела «SQLite (default)»](#sqlite-default) | Переменная | Описание | | -------------------- | --------------- | | `DB_TYPE` | `sqlite` | | `DB_SQLITE_DATABASE` | Путь к файлу DB | ### PostgreSQL [Заголовок раздела «PostgreSQL»](#postgresql) | Переменная | Описание | | --------------------------------------- | -------------------- | | `DB_TYPE` | `postgresdb` | | `DB_POSTGRESDB_HOST` | Хост PostgreSQL | | `DB_POSTGRESDB_PORT` | Порт (default: 5432) | | `DB_POSTGRESDB_DATABASE` | Имя базы данных | | `DB_POSTGRESDB_USER` | Пользователь | | `DB_POSTGRESDB_PASSWORD` | Пароль | | `DB_POSTGRESDB_SSL_REJECT_UNAUTHORIZED` | Валидация SSL cert | ### MySQL [Заголовок раздела «MySQL»](#mysql) | Переменная | Описание | | --------------------- | -------------------- | | `DB_TYPE` | `mysqldb` | | `DB_MYSQLDB_HOST` | Хост MySQL | | `DB_MYSQLDB_PORT` | Порт (default: 3306) | | `DB_MYSQLDB_DATABASE` | Имя базы данных | | `DB_MYSQLDB_USER` | Пользователь | | `DB_MYSQLDB_PASSWORD` | Пароль | ## Безопасность [Заголовок раздела «Безопасность»](#безопасность) | Переменная | Описание | | -------------------------------- | ------------------------------------------ | | `N8N_ENCRYPTION_KEY` | Ключ шифрования credentials (32+ символов) | | `N8N_USER_MANAGEMENT_JWT_SECRET` | Secret для JWT токенов | | `N8N_BASIC_AUTH_ACTIVE` | Включить Basic Auth | | `N8N_BASIC_AUTH_USER` | Логин для Basic Auth | | `N8N_BASIC_AUTH_PASSWORD` | Пароль для Basic Auth | Осторожно `N8N_ENCRYPTION_KEY` обязателен для production. Без него credentials не сохранятся при перезапуске. ## Выполнение [Заголовок раздела «Выполнение»](#выполнение) | Переменная | Описание | Default | | ---------------------------------------- | ---------------------------- | --------------- | | `EXECUTIONS_MODE` | `regular` или `queue` | `regular` | | `EXECUTIONS_TIMEOUT` | Таймаут выполнения (секунды) | `-1` | | `EXECUTIONS_TIMEOUT_MAX` | Максимальный таймаут | `3600` | | `EXECUTIONS_DATA_SAVE_ON_ERROR` | Сохранять при ошибке | `all` | | `EXECUTIONS_DATA_SAVE_ON_SUCCESS` | Сохранять при успехе | `all` | | `EXECUTIONS_DATA_SAVE_ON_PROGRESS` | Сохранять прогресс | `false` | | `EXECUTIONS_DATA_SAVE_MANUAL_EXECUTIONS` | Сохранять manual | `true` | | `EXECUTIONS_DATA_PRUNE` | Автоочистка | `true` | | `EXECUTIONS_DATA_MAX_AGE` | Возраст для очистки (часы) | `336` (14 дней) | ## Queue Mode [Заголовок раздела «Queue Mode»](#queue-mode) | Переменная | Описание | | --------------------------- | ---------------------- | | `EXECUTIONS_MODE` | `queue` | | `QUEUE_BULL_REDIS_HOST` | Redis host | | `QUEUE_BULL_REDIS_PORT` | Redis port | | `QUEUE_BULL_REDIS_PASSWORD` | Redis password | | `QUEUE_BULL_REDIS_DB` | Redis DB number | | `QUEUE_HEALTH_CHECK_ACTIVE` | Health check для queue | ## Логирование [Заголовок раздела «Логирование»](#логирование) | Переменная | Описание | Default | | ----------------------- | ------------------------ | --------- | | `N8N_LOG_LEVEL` | error, warn, info, debug | `info` | | `N8N_LOG_OUTPUT` | console, file | `console` | | `N8N_LOG_FILE_LOCATION` | Путь к log файлу | | | `N8N_LOG_FILE_SIZE_MAX` | Макс размер файла | `16` (MB) | ## Workflows [Заголовок раздела «Workflows»](#workflows) | Переменная | Описание | | ------------------------------ | -------------------- | | `WORKFLOWS_DEFAULT_NAME` | Имя нового workflow | | `N8N_ONBOARDING_FLOW_DISABLED` | Отключить onboarding | | `N8N_WORKFLOW_TAGS_DISABLED` | Отключить теги | ## Email (SMTP) [Заголовок раздела «Email (SMTP)»](#email-smtp) | Переменная | Описание | | ----------------- | ----------------- | | `N8N_EMAIL_MODE` | `smtp` | | `N8N_SMTP_HOST` | SMTP сервер | | `N8N_SMTP_PORT` | Порт | | `N8N_SMTP_USER` | Пользователь | | `N8N_SMTP_PASS` | Пароль | | `N8N_SMTP_SENDER` | Email отправителя | | `N8N_SMTP_SSL` | Использовать SSL | ## Внешние сервисы [Заголовок раздела «Внешние сервисы»](#внешние-сервисы) | Переменная | Описание | | ------------------------------ | --------------------------- | | `N8N_METRICS` | Включить Prometheus metrics | | `N8N_METRICS_PREFIX` | Prefix для metrics | | `EXTERNAL_FRONTEND_HOOKS_URLS` | URL для frontend hooks | | `EXTERNAL_BACKEND_HOOKS_URLS` | URL для backend hooks | ## Ограничения [Заголовок раздела «Ограничения»](#ограничения) | Переменная | Описание | Default | | ----------------------------------- | --------------------- | --------- | | `N8N_PAYLOAD_SIZE_MAX` | Макс размер payload | `16` (MB) | | `N8N_HIRING_BANNER_ENABLED` | Баннер о найме | `true` | | `N8N_PERSONALIZATION_ENABLED` | Персонализация | `true` | | `N8N_VERSION_NOTIFICATIONS_ENABLED` | Уведомления о версиях | `true` | | `N8N_TEMPLATES_ENABLED` | Шаблоны | `true` | ## AI [Заголовок раздела «AI»](#ai) | Переменная | Описание | | ----------------------- | --------------------- | | `N8N_AI_ENABLED` | Включить AI фичи | | `N8N_AI_PROVIDER` | Провайдер AI (openai) | | `N8N_AI_OPENAI_API_KEY` | API ключ OpenAI | ## Пример .env [Заголовок раздела «Пример .env»](#пример-env) ```bash # Основные N8N_HOST=n8n.example.com N8N_PORT=5678 N8N_PROTOCOL=https WEBHOOK_URL=https://n8n.example.com/ # База данных DB_TYPE=postgresdb DB_POSTGRESDB_HOST=postgres DB_POSTGRESDB_PORT=5432 DB_POSTGRESDB_DATABASE=n8n DB_POSTGRESDB_USER=n8n DB_POSTGRESDB_PASSWORD=secure_password_here # Безопасность N8N_ENCRYPTION_KEY=32_char_encryption_key_here_xxx N8N_USER_MANAGEMENT_JWT_SECRET=another_secret_key_here # Выполнение EXECUTIONS_DATA_PRUNE=true EXECUTIONS_DATA_MAX_AGE=168 # Логирование N8N_LOG_LEVEL=info # Timezone GENERIC_TIMEZONE=Europe/Moscow ``` ## Переменные в Workflows [Заголовок раздела «Переменные в Workflows»](#переменные-в-workflows) ### Глобальные переменные [Заголовок раздела «Глобальные переменные»](#глобальные-переменные) В n8n UI: **Settings** → **Variables** Доступ в expressions: ```javascript {{ $vars.MY_VARIABLE }} ``` ### Переменные окружения в Expressions [Заголовок раздела «Переменные окружения в Expressions»](#переменные-окружения-в-expressions) ```javascript {{ $env.MY_ENV_VAR }} ``` Совет Используйте `$env` для секретов — они не сохраняются при экспорте workflow. ## Следующие шаги [Заголовок раздела «Следующие шаги»](#следующие-шаги) * [Docker](/hosting/docker/) — настройка контейнера * [Масштабирование](/hosting/scaling/) — queue mode * [Безопасность](/hosting/security/) — SSL и auth # Хостинг n8n > Способы развёртывания n8n — Docker, npm, облако ## Варианты хостинга [Заголовок раздела «Варианты хостинга»](#варианты-хостинга) Docker Рекомендуемый способ для production npm Для разработки и тестирования n8n Cloud Managed решение без инфраструктуры Kubernetes Для масштабируемых решений ## Сравнение [Заголовок раздела «Сравнение»](#сравнение) | Способ | Сложность | Масштабируемость | Стоимость | | ---------- | ----------- | ---------------- | --------- | | Docker | Средняя | Высокая | Низкая | | npm | Низкая | Низкая | Низкая | | n8n Cloud | Минимальная | Средняя | Средняя | | Kubernetes | Высокая | Очень высокая | Зависит | ## Требования [Заголовок раздела «Требования»](#требования) ### Минимальные [Заголовок раздела «Минимальные»](#минимальные) | Ресурс | Значение | | ------- | ---------------- | | CPU | 1 vCPU | | RAM | 1 GB | | Disk | 10 GB | | Node.js | 18.17+ (для npm) | ### Рекомендуемые (Production) [Заголовок раздела «Рекомендуемые (Production)»](#рекомендуемые-production) | Ресурс | Значение | | -------- | ---------- | | CPU | 2+ vCPU | | RAM | 4+ GB | | Disk | 50+ GB SSD | | Database | PostgreSQL | ## Архитектура [Заголовок раздела «Архитектура»](#архитектура) ### Standalone [Заголовок раздела «Standalone»](#standalone) ```plaintext ┌─────────────────┐ │ n8n │ │ (все-в-одном) │ │ SQLite DB │ └─────────────────┘ ``` Подходит для: тестирования, небольших нагрузок. ### Production [Заголовок раздела «Production»](#production) ```plaintext ┌─────────────────┐ ┌─────────────────┐ │ n8n │────▶│ PostgreSQL │ │ (web + worker) │ │ │ └─────────────────┘ └─────────────────┘ │ ▼ ┌─────────────────┐ │ Redis │ │ (queue) │ └─────────────────┘ ``` Подходит для: production, высокие нагрузки. ### Scaling (Queue Mode) [Заголовок раздела «Scaling (Queue Mode)»](#scaling-queue-mode) ```plaintext ┌─────────────────┐ │ Load Balancer │ └────────┬────────┘ │ ┌────┴────┐ ▼ ▼ ┌───────┐ ┌───────┐ │ n8n 1 │ │ n8n 2 │ (main) └───┬───┘ └───┬───┘ │ │ └────┬────┘ │ ┌────┴────┐ ▼ ▼ ┌───────┐ ┌───────┐ │Worker1│ │Worker2│ (workers) └───────┘ └───────┘ │ ┌────┴────┐ ▼ ▼ ┌───────┐ ┌───────┐ │ Postgres│ │ Redis │ └───────┘ └───────┘ ``` ## Выбор базы данных [Заголовок раздела «Выбор базы данных»](#выбор-базы-данных) ### SQLite (default) [Заголовок раздела «SQLite (default)»](#sqlite-default) ```plaintext ✅ Простая настройка ✅ Не требует отдельного сервиса ❌ Не масштабируется ❌ Ограничения на concurrent writes ``` ### PostgreSQL (рекомендуется) [Заголовок раздела «PostgreSQL (рекомендуется)»](#postgresql-рекомендуется) ```plaintext ✅ Масштабируется ✅ Надёжность ✅ Concurrent operations ❌ Требует настройки ``` ### MySQL (поддерживается) [Заголовок раздела «MySQL (поддерживается)»](#mysql-поддерживается) ```plaintext ✅ Популярная СУБД ✅ Знакомый многим ❌ Меньше функций чем PostgreSQL ``` ## Сетевые требования [Заголовок раздела «Сетевые требования»](#сетевые-требования) ### Порты [Заголовок раздела «Порты»](#порты) | Порт | Назначение | | ---- | ------------------------ | | 5678 | Web UI / API | | 5679 | Webhook (если отдельный) | ### SSL/TLS [Заголовок раздела «SSL/TLS»](#ssltls) Осторожно Для production обязательно настройте HTTPS через reverse proxy (nginx, Traefik, Caddy). ### VPS для n8n + AI Полный доступ к OpenAI, Claude, Gemini без блокировок ✓ Без VPN и прокси•✓ Оплата в рублях•✓ Готов за 5 минут [🇳🇱Нидерланды](/vps_vds_netherlands) [Максимальная скорость до EU API](/vps_vds_netherlands) [OpenAI, Anthropic, Google](/vps_vds_netherlands) [🇰🇿Казахстан](/vps-vds-kazakhstan) [Ближе к России, низкая задержка](/vps-vds-kazakhstan) [Все AI провайдеры доступны](/vps-vds-kazakhstan) Промокод для скидки:`648429339` API-запросы идут с IP сервера — провайдеры не блокируют ## Следующие шаги [Заголовок раздела «Следующие шаги»](#следующие-шаги) * [Docker](/hosting/docker/) — контейнеризация * [Переменные окружения](/hosting/environment-variables/) — конфигурация * [Масштабирование](/hosting/scaling/) — queue mode * [Безопасность](/hosting/security/) — SSL, auth # Масштабирование > Queue mode, workers и горизонтальное масштабирование n8n ## Queue Mode [Заголовок раздела «Queue Mode»](#queue-mode) Для высоких нагрузок n8n поддерживает **queue mode** с отдельными workers. ### Архитектура [Заголовок раздела «Архитектура»](#архитектура) ```plaintext ┌─────────────┐ │ Load │ │ Balancer │ └──────┬──────┘ │ ┌──────────────┼──────────────┐ │ │ │ ┌────▼────┐ ┌────▼────┐ ┌────▼────┐ │ Main 1 │ │ Main 2 │ │ Main 3 │ │ (web) │ │ (web) │ │ (web) │ └────┬────┘ └────┬────┘ └────┬────┘ │ │ │ └──────────────┼──────────────┘ │ ┌──────▼──────┐ │ Redis │ │ (queue) │ └──────┬──────┘ │ ┌──────────────┼──────────────┐ │ │ │ ┌────▼────┐ ┌────▼────┐ ┌────▼────┐ │Worker 1 │ │Worker 2 │ │Worker 3 │ └─────────┘ └─────────┘ └─────────┘ │ ┌──────▼──────┐ │ PostgreSQL │ └─────────────┘ ``` ### Компоненты [Заголовок раздела «Компоненты»](#компоненты) | Компонент | Роль | | -------------- | --------------------------------- | | **Main** | Web UI, API, управление workflows | | **Workers** | Выполнение workflows | | **Redis** | Очередь задач | | **PostgreSQL** | Хранение данных | ## Настройка Queue Mode [Заголовок раздела «Настройка Queue Mode»](#настройка-queue-mode) ### Docker Compose [Заголовок раздела «Docker Compose»](#docker-compose) ```yaml version: '3.8' services: # Main instance (web UI) n8n: image: n8nio/n8n restart: always ports: - "5678:5678" environment: - DB_TYPE=postgresdb - DB_POSTGRESDB_HOST=postgres - DB_POSTGRESDB_DATABASE=n8n - DB_POSTGRESDB_USER=n8n - DB_POSTGRESDB_PASSWORD=${POSTGRES_PASSWORD} - EXECUTIONS_MODE=queue - QUEUE_BULL_REDIS_HOST=redis - N8N_ENCRYPTION_KEY=${N8N_ENCRYPTION_KEY} volumes: - n8n_data:/home/node/.n8n depends_on: - postgres - redis # Worker instance n8n-worker: image: n8nio/n8n restart: always command: worker environment: - DB_TYPE=postgresdb - DB_POSTGRESDB_HOST=postgres - DB_POSTGRESDB_DATABASE=n8n - DB_POSTGRESDB_USER=n8n - DB_POSTGRESDB_PASSWORD=${POSTGRES_PASSWORD} - EXECUTIONS_MODE=queue - QUEUE_BULL_REDIS_HOST=redis - N8N_ENCRYPTION_KEY=${N8N_ENCRYPTION_KEY} volumes: - n8n_data:/home/node/.n8n depends_on: - postgres - redis - n8n postgres: image: postgres:15 restart: always environment: - POSTGRES_USER=n8n - POSTGRES_PASSWORD=${POSTGRES_PASSWORD} - POSTGRES_DB=n8n volumes: - postgres_data:/var/lib/postgresql/data redis: image: redis:7 restart: always volumes: - redis_data:/data volumes: n8n_data: postgres_data: redis_data: ``` ### Масштабирование Workers [Заголовок раздела «Масштабирование Workers»](#масштабирование-workers) ```bash # Запустить 3 worker'а docker-compose up -d --scale n8n-worker=3 ``` ## Переменные для Queue Mode [Заголовок раздела «Переменные для Queue Mode»](#переменные-для-queue-mode) | Переменная | Описание | | --------------------------- | -------------------------- | | `EXECUTIONS_MODE` | `queue` | | `QUEUE_BULL_REDIS_HOST` | Redis hostname | | `QUEUE_BULL_REDIS_PORT` | Redis port (default: 6379) | | `QUEUE_BULL_REDIS_PASSWORD` | Redis password | | `QUEUE_BULL_REDIS_DB` | Redis DB number | | `QUEUE_HEALTH_CHECK_ACTIVE` | Health check enabled | | `QUEUE_WORKER_TIMEOUT` | Timeout для jobs (ms) | ## Concurrency [Заголовок раздела «Concurrency»](#concurrency) ### Worker Concurrency [Заголовок раздела «Worker Concurrency»](#worker-concurrency) ```bash # Количество параллельных executions на worker N8N_CONCURRENCY_PRODUCTION_LIMIT=10 ``` ### Workflow Settings [Заголовок раздела «Workflow Settings»](#workflow-settings) В настройках каждого workflow: * **Concurrency Limit** — макс параллельных выполнений ## Webhooks в Queue Mode [Заголовок раздела «Webhooks в Queue Mode»](#webhooks-в-queue-mode) ### Отдельный Webhook Process [Заголовок раздела «Отдельный Webhook Process»](#отдельный-webhook-process) ```yaml services: n8n-webhook: image: n8nio/n8n restart: always command: webhook ports: - "5679:5678" environment: - EXECUTIONS_MODE=queue - QUEUE_BULL_REDIS_HOST=redis # ... остальные настройки ``` ### Разделение URL [Заголовок раздела «Разделение URL»](#разделение-url) ```bash # Web UI N8N_HOST=n8n.example.com # Webhooks WEBHOOK_URL=https://webhooks.example.com/ ``` ## Health Checks [Заголовок раздела «Health Checks»](#health-checks) ### Main Instance [Заголовок раздела «Main Instance»](#main-instance) ```bash curl http://localhost:5678/healthz ``` ### Worker [Заголовок раздела «Worker»](#worker) ```yaml n8n-worker: healthcheck: test: ["CMD", "n8n", "queue:status"] interval: 30s timeout: 10s retries: 3 ``` ### Redis [Заголовок раздела «Redis»](#redis) ```yaml redis: healthcheck: test: ["CMD", "redis-cli", "ping"] interval: 5s ``` ## Мониторинг [Заголовок раздела «Мониторинг»](#мониторинг) ### Prometheus Metrics [Заголовок раздела «Prometheus Metrics»](#prometheus-metrics) ```bash N8N_METRICS=true N8N_METRICS_PREFIX=n8n_ ``` Endpoint: `http://localhost:5678/metrics` ### Grafana Dashboard [Заголовок раздела «Grafana Dashboard»](#grafana-dashboard) Метрики включают: * `n8n_executions_total` * `n8n_workflow_active_count` * `n8n_queue_jobs_waiting` * `n8n_queue_jobs_active` ## Best Practices [Заголовок раздела «Best Practices»](#best-practices) ### 1. Изолируйте компоненты [Заголовок раздела «1. Изолируйте компоненты»](#1-изолируйте-компоненты) ```plaintext ✅ Отдельные контейнеры для main, worker, postgres, redis ❌ Всё в одном контейнере ``` ### 2. Достаточно памяти [Заголовок раздела «2. Достаточно памяти»](#2-достаточно-памяти) ```bash # Worker с большими данными deploy: resources: limits: memory: 4G ``` ### 3. Мониторинг очереди [Заголовок раздела «3. Мониторинг очереди»](#3-мониторинг-очереди) Следите за: * Waiting jobs — не должны расти постоянно * Failed jobs — исследуйте причины * Processing time — оптимизируйте долгие workflow ### 4. Graceful Shutdown [Заголовок раздела «4. Graceful Shutdown»](#4-graceful-shutdown) ```yaml n8n-worker: stop_grace_period: 30s ``` Совет Worker завершит текущее выполнение перед остановкой. ### 5. Retry Strategy [Заголовок раздела «5. Retry Strategy»](#5-retry-strategy) В workflow settings: * **Retry On Fail** — количество повторов * **Wait Between Tries** — пауза между попытками ## Kubernetes [Заголовок раздела «Kubernetes»](#kubernetes) ### Deployment Example [Заголовок раздела «Deployment Example»](#deployment-example) ```yaml apiVersion: apps/v1 kind: Deployment metadata: name: n8n-worker spec: replicas: 3 selector: matchLabels: app: n8n-worker template: metadata: labels: app: n8n-worker spec: containers: - name: n8n-worker image: n8nio/n8n command: ["n8n", "worker"] env: - name: EXECUTIONS_MODE value: "queue" # ... остальные переменные resources: limits: memory: "2Gi" cpu: "1000m" ``` ### HPA (Horizontal Pod Autoscaler) [Заголовок раздела «HPA (Horizontal Pod Autoscaler)»](#hpa-horizontal-pod-autoscaler) ```yaml apiVersion: autoscaling/v2 kind: HorizontalPodAutoscaler metadata: name: n8n-worker-hpa spec: scaleTargetRef: apiVersion: apps/v1 kind: Deployment name: n8n-worker minReplicas: 2 maxReplicas: 10 metrics: - type: Resource resource: name: cpu target: type: Utilization averageUtilization: 80 ``` ## Следующие шаги [Заголовок раздела «Следующие шаги»](#следующие-шаги) * [Безопасность](/hosting/security/) — SSL, auth * [Docker](/hosting/docker/) — базовая настройка * [Переменные окружения](/hosting/environment-variables/) — полный список # Безопасность > SSL, аутентификация и защита n8n в production ## Checklist безопасности [Заголовок раздела «Checklist безопасности»](#checklist-безопасности) * [ ] HTTPS включён * [ ] Encryption key установлен * [ ] Аутентификация настроена * [ ] Firewall настроен * [ ] Credentials зашифрованы * [ ] Регулярные бэкапы ## SSL/TLS [Заголовок раздела «SSL/TLS»](#ssltls) ### Let’s Encrypt + nginx [Заголовок раздела «Let’s Encrypt + nginx»](#lets-encrypt--nginx) 1. **Установите certbot** ```bash sudo apt install certbot python3-certbot-nginx ``` 2. **Получите сертификат** ```bash sudo certbot --nginx -d n8n.example.com ``` 3. **Настройте nginx** ```nginx server { listen 443 ssl http2; server_name n8n.example.com; ssl_certificate /etc/letsencrypt/live/n8n.example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/n8n.example.com/privkey.pem; # Современные SSL настройки ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256; ssl_prefer_server_ciphers off; # HSTS add_header Strict-Transport-Security "max-age=31536000" always; location / { proxy_pass http://localhost:5678; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } } ``` 4. **Автопродление** ```bash sudo certbot renew --dry-run ``` ### Cloudflare [Заголовок раздела «Cloudflare»](#cloudflare) Используйте Full (strict) SSL mode: 1. Cloudflare → Origin Server → SSL/TLS 2. Encryption mode: Full (strict) 3. Создайте Origin Certificate ## Encryption Key [Заголовок раздела «Encryption Key»](#encryption-key) Осторожно Без `N8N_ENCRYPTION_KEY` credentials не будут сохранены при перезапуске! ### Генерация ключа [Заголовок раздела «Генерация ключа»](#генерация-ключа) ```bash # Linux/Mac openssl rand -hex 32 # Или head -c 32 /dev/urandom | base64 ``` ### Установка [Заголовок раздела «Установка»](#установка) .env ```bash N8N_ENCRYPTION_KEY=your_32_char_key_here_xxxxxxxxxxxxxx ``` ## Аутентификация [Заголовок раздела «Аутентификация»](#аутентификация) ### User Management (рекомендуется) [Заголовок раздела «User Management (рекомендуется)»](#user-management-рекомендуется) Встроенная система пользователей: ```bash # Включена по умолчанию в новых версиях ``` Возможности: * Регистрация пользователей * Роли (owner, admin, member) * Приглашения по email ### Basic Auth (простой вариант) [Заголовок раздела «Basic Auth (простой вариант)»](#basic-auth-простой-вариант) ```bash N8N_BASIC_AUTH_ACTIVE=true N8N_BASIC_AUTH_USER=admin N8N_BASIC_AUTH_PASSWORD=secure_password ``` Совет Basic Auth проще, но User Management даёт больше контроля. ## RBAC (Role-Based Access) [Заголовок раздела «RBAC (Role-Based Access)»](#rbac-role-based-access) ### Роли [Заголовок раздела «Роли»](#роли) | Роль | Права | | ---------- | ------------------------------------ | | **Owner** | Полный доступ | | **Admin** | Управление пользователями, workflows | | **Member** | Работа с workflow (ограниченно) | ### Sharing Workflows [Заголовок раздела «Sharing Workflows»](#sharing-workflows) * Owner может шарить workflows * Member видит только shared workflows * Credentials шарятся отдельно ## Firewall [Заголовок раздела «Firewall»](#firewall) ### Правила iptables [Заголовок раздела «Правила iptables»](#правила-iptables) ```bash # Разрешить только HTTPS sudo iptables -A INPUT -p tcp --dport 443 -j ACCEPT sudo iptables -A INPUT -p tcp --dport 80 -j ACCEPT # Заблокировать прямой доступ к n8n sudo iptables -A INPUT -p tcp --dport 5678 -s 127.0.0.1 -j ACCEPT sudo iptables -A INPUT -p tcp --dport 5678 -j DROP ``` ### UFW [Заголовок раздела «UFW»](#ufw) ```bash sudo ufw allow 443/tcp sudo ufw allow 80/tcp sudo ufw deny 5678/tcp ``` ## Webhook Security [Заголовок раздела «Webhook Security»](#webhook-security) ### Authentication [Заголовок раздела «Authentication»](#authentication) В Webhook ноде: * **Header Auth** — проверка заголовка * **Basic Auth** — логин/пароль * **JWT** — валидация токена ### IP Whitelist [Заголовок раздела «IP Whitelist»](#ip-whitelist) Через nginx: ```nginx location /webhook/ { allow 1.2.3.4; # Allowed IP deny all; proxy_pass http://localhost:5678; } ``` ### Webhook URL Security [Заголовок раздела «Webhook URL Security»](#webhook-url-security) ```bash # Случайный path WEBHOOK_URL=https://n8n.example.com/webhook-xxxx-random-path/ ``` ## Credentials Security [Заголовок раздела «Credentials Security»](#credentials-security) ### Шифрование [Заголовок раздела «Шифрование»](#шифрование) Credentials шифруются с помощью `N8N_ENCRYPTION_KEY`: * AES-256-GCM * Ключ не покидает сервер ### Best Practices [Заголовок раздела «Best Practices»](#best-practices) 1. **Минимальные права** — создавайте API ключи с минимальными правами 2. **Ротация** — регулярно меняйте credentials 3. **Аудит** — отслеживайте использование ## Docker Security [Заголовок раздела «Docker Security»](#docker-security) ### Non-root User [Заголовок раздела «Non-root User»](#non-root-user) n8n уже работает под user `node`, но проверьте: ```yaml services: n8n: user: "1000:1000" security_opt: - no-new-privileges:true ``` ### Read-only Filesystem [Заголовок раздела «Read-only Filesystem»](#read-only-filesystem) ```yaml services: n8n: read_only: true tmpfs: - /tmp volumes: - n8n_data:/home/node/.n8n ``` ### Network Isolation [Заголовок раздела «Network Isolation»](#network-isolation) ```yaml networks: frontend: backend: services: n8n: networks: - frontend - backend postgres: networks: - backend # Только внутренняя сеть ``` ## Logging & Audit [Заголовок раздела «Logging & Audit»](#logging--audit) ### Логирование [Заголовок раздела «Логирование»](#логирование) ```bash N8N_LOG_LEVEL=info N8N_LOG_OUTPUT=file N8N_LOG_FILE_LOCATION=/var/log/n8n/n8n.log ``` ### Audit Log [Заголовок раздела «Audit Log»](#audit-log) Отслеживайте: * Логины пользователей * Изменения workflows * Создание credentials * Активации workflows ## Headers Security [Заголовок раздела «Headers Security»](#headers-security) ### nginx [Заголовок раздела «nginx»](#nginx) ```nginx # Security headers add_header X-Frame-Options "SAMEORIGIN" always; add_header X-Content-Type-Options "nosniff" always; add_header X-XSS-Protection "1; mode=block" always; add_header Referrer-Policy "strict-origin-when-cross-origin" always; add_header Content-Security-Policy "default-src 'self'" always; ``` ## Rate Limiting [Заголовок раздела «Rate Limiting»](#rate-limiting) ### nginx [Заголовок раздела «nginx»](#nginx-1) ```nginx # Rate limit zone limit_req_zone $binary_remote_addr zone=n8n:10m rate=10r/s; server { location / { limit_req zone=n8n burst=20 nodelay; proxy_pass http://localhost:5678; } } ``` ### Webhook Rate Limiting [Заголовок раздела «Webhook Rate Limiting»](#webhook-rate-limiting) ```nginx location /webhook/ { limit_req zone=n8n burst=5; proxy_pass http://localhost:5678; } ``` ## Backup Security [Заголовок раздела «Backup Security»](#backup-security) ### Шифрование бэкапов [Заголовок раздела «Шифрование бэкапов»](#шифрование-бэкапов) ```bash # Бэкап с шифрованием pg_dump -U n8n n8n | gzip | \ gpg --symmetric --cipher-algo AES256 > backup.sql.gz.gpg # Восстановление gpg --decrypt backup.sql.gz.gpg | gunzip | \ psql -U n8n n8n ``` ### Хранение бэкапов [Заголовок раздела «Хранение бэкапов»](#хранение-бэкапов) * Отдельное хранилище (S3, GCS) * Encryption at rest * Access logging ## Следующие шаги [Заголовок раздела «Следующие шаги»](#следующие-шаги) * [Docker](/hosting/docker/) — контейнеризация * [Масштабирование](/hosting/scaling/) — queue mode * [Переменные окружения](/hosting/environment-variables/) — конфигурация # Core Nodes > Основные ноды n8n — HTTP Request, Code, Set, IF, Merge ## HTTP Request [Заголовок раздела «HTTP Request»](#http-request) Универсальная нода для работы с любыми API. ### Основные параметры [Заголовок раздела «Основные параметры»](#основные-параметры) | Параметр | Описание | | ------------------------- | --------------- | | **Method** | HTTP метод | | **URL** | Endpoint URL | | **Authentication** | Тип авторизации | | **Send Query Parameters** | URL параметры | | **Send Headers** | HTTP заголовки | | **Send Body** | Тело запроса | ### Примеры [Заголовок раздела «Примеры»](#примеры) * GET ```plaintext Method: GET URL: https://api.example.com/users Query Parameters: - page: 1 - limit: 10 ``` * POST JSON ```plaintext Method: POST URL: https://api.example.com/users Body Content Type: JSON Body: { "name": "{{ $json.name }}", "email": "{{ $json.email }}" } ``` * Form Data ```plaintext Method: POST URL: https://api.example.com/upload Body Content Type: Form-Data Body Parameters: - file: {{ $binary.data }} - description: "My file" ``` ### Pagination [Заголовок раздела «Pagination»](#pagination) Автоматическая обработка пагинации: | Режим | Описание | | --------------------- | ----------------------------- | | **Update Parameter** | Увеличивать параметр (page++) | | **Response Contains** | Использовать cursor из ответа | ### Retry [Заголовок раздела «Retry»](#retry) * **Retry On Fail**: количество повторов * **Wait Between Tries**: пауза (мс) ## Code [Заголовок раздела «Code»](#code) Выполнение произвольного кода. ### JavaScript [Заголовок раздела «JavaScript»](#javascript) ```javascript // Доступ к данным const items = $input.all(); // Обработка const results = items.map(item => ({ json: { ...item.json, processed: true, timestamp: new Date().toISOString() } })); return results; ``` ### Python [Заголовок раздела «Python»](#python) ```python # Доступ к данным items = _input.all() # Обработка for item in items: item['json']['processed'] = True item['json']['timestamp'] = datetime.now().isoformat() return items ``` ### Доступные объекты [Заголовок раздела «Доступные объекты»](#доступные-объекты) | Объект | Описание | | ----------- | --------------------- | | `$input` | Входные данные | | `$json` | JSON текущего item | | `$binary` | Binary данные | | `$env` | Переменные окружения | | `$vars` | Глобальные переменные | | `$('Node')` | Данные из другой ноды | ### External Libraries [Заголовок раздела «External Libraries»](#external-libraries) Использование npm пакетов: ```javascript const moment = require('moment'); const _ = require('lodash'); return items.map(item => ({ json: { date: moment(item.json.date).format('DD.MM.YYYY'), sorted: _.sortBy(item.json.items, 'name') } })); ``` ## Set [Заголовок раздела «Set»](#set) Создание и модификация данных. ### Режимы [Заголовок раздела «Режимы»](#режимы) | Режим | Описание | | ------------------ | -------------------- | | **Manual Mapping** | Ручное задание полей | | **JSON** | Ввод JSON напрямую | ### Manual Mapping [Заголовок раздела «Manual Mapping»](#manual-mapping) ```plaintext Fields: - Name: fullName Value: {{ $json.firstName }} {{ $json.lastName }} - Name: createdAt Value: {{ $now.toISOString() }} Options: - Keep Only Set: false - Include Other Input Fields: true ``` ### JSON Mode [Заголовок раздела «JSON Mode»](#json-mode) ```json { "userId": "{{ $json.id }}", "status": "processed", "metadata": { "source": "n8n", "timestamp": "{{ $now }}" } } ``` ## IF [Заголовок раздела «IF»](#if) Условное ветвление. ### Условия [Заголовок раздела «Условия»](#условия) | Тип | Операторы | | ----------- | ----------------------------------------------- | | **String** | equals, contains, starts with, ends with, regex | | **Number** | =, !=, <, >, <=, >= | | **Boolean** | is true, is false | | **General** | exists, is empty, is not empty | ### Пример [Заголовок раздела «Пример»](#пример) ```plaintext Conditions: {{ $json.status }} equals "active" AND {{ $json.age }} is greater than 18 Combine: AND ``` ### Outputs [Заголовок раздела «Outputs»](#outputs) * **True branch**: условие выполнено * **False branch**: условие не выполнено ## Switch [Заголовок раздела «Switch»](#switch) Множественное ветвление. ### Rules Mode [Заголовок раздела «Rules Mode»](#rules-mode) ```plaintext Rules: 1. {{ $json.type }} equals "email" → Output 0 2. {{ $json.type }} equals "sms" → Output 1 3. {{ $json.type }} equals "push" → Output 2 Fallback: Output 3 ``` ### Expression Mode [Заголовок раздела «Expression Mode»](#expression-mode) ```javascript // Возвращает индекс выхода switch($json.priority) { case 'high': return 0; case 'medium': return 1; default: return 2; } ``` ## Merge [Заголовок раздела «Merge»](#merge) Объединение данных из нескольких входов. ### Режимы [Заголовок раздела «Режимы»](#режимы-1) | Режим | Описание | | ----------------- | --------------------- | | **Append** | Склеить items | | **Combine** | Объединить по индексу | | **Multiplex** | Все комбинации | | **Choose Branch** | Выбрать один поток | ### Combine by Field [Заголовок раздела «Combine by Field»](#combine-by-field) ```plaintext Mode: Combine Merge By: Fields Field Input 1: userId Field Input 2: id Join Mode: Inner Join ``` ## Split In Batches [Заголовок раздела «Split In Batches»](#split-in-batches) Разбиение на пакеты. ### Настройка [Заголовок раздела «Настройка»](#настройка) | Параметр | Описание | | -------------- | ----------------- | | **Batch Size** | Размер пакета | | **Options** | Reset on each run | ### Паттерн использования [Заголовок раздела «Паттерн использования»](#паттерн-использования) ## Loop Over Items [Заголовок раздела «Loop Over Items»](#loop-over-items) Явный цикл по items. ### Настройка [Заголовок раздела «Настройка»](#настройка-1) | Параметр | Описание | | -------------- | -------------------- | | **Batch Size** | Items за итерацию | | **Loop Count** | Ограничение итераций | ### Выходы [Заголовок раздела «Выходы»](#выходы) * **Loop**: следующая итерация * **Done**: цикл завершён ## Wait [Заголовок раздела «Wait»](#wait) Пауза в выполнении. ### Режимы [Заголовок раздела «Режимы»](#режимы-2) | Режим | Описание | | ----------------------- | ---------------------------- | | **After Time Interval** | Пауза на N секунд/минут | | **At Specific Time** | Продолжить в указанное время | | **On Webhook Call** | Ждать webhook | Совет Используйте Wait для rate-limiting API или ожидания внешних событий. ## Filter [Заголовок раздела «Filter»](#filter) Фильтрация items по условию. ```plaintext Condition: {{ $json.status }} equals "active" ``` Результат: только items с `status === "active"`. ## Remove Duplicates [Заголовок раздела «Remove Duplicates»](#remove-duplicates) Удаление дубликатов. | Параметр | Описание | | ----------- | ---------------------- | | **Compare** | Поле для сравнения | | **Action** | Keep first / Keep last | ## Sort [Заголовок раздела «Sort»](#sort) Сортировка items. | Параметр | Описание | | ----------- | ---------------------- | | **Sort By** | Поле сортировки | | **Order** | Ascending / Descending | | **Type** | String / Number / Date | ## Limit [Заголовок раздела «Limit»](#limit) Ограничение количества items. | Параметр | Описание | | ------------- | -------------- | | **Max Items** | Максимум items | | **Keep** | First / Last | ## Следующие шаги [Заголовок раздела «Следующие шаги»](#следующие-шаги) * [Triggers](/integrations/triggers/) — типы триггеров * [Интеграции](/integrations/overview/) — обзор сервисов * [Логика потоков](/concepts/flow-logic/) — ветвление # Интеграции > Обзор нод, триггеров и credentials в n8n ## 400+ интеграций [Заголовок раздела «400+ интеграций»](#400-интеграций) n8n поддерживает более 400 готовых интеграций с популярными сервисами. CRM Salesforce, HubSpot, Pipedrive, Zoho Базы данных PostgreSQL, MySQL, MongoDB, Redis Мессенджеры Slack, Telegram, Discord, WhatsApp Cloud AWS, Google Cloud, Azure ## Типы нод [Заголовок раздела «Типы нод»](#типы-нод) ### App Nodes [Заголовок раздела «App Nodes»](#app-nodes) Интеграции с конкретными сервисами: | Категория | Примеры | | ----------------- | ------------------------------- | | **Productivity** | Google Sheets, Notion, Airtable | | **Communication** | Slack, Email, Telegram | | **Development** | GitHub, GitLab, Jira | | **Marketing** | Mailchimp, SendGrid, HubSpot | | **Finance** | Stripe, PayPal, QuickBooks | | **Social** | Twitter, Facebook, LinkedIn | ### Core Nodes [Заголовок раздела «Core Nodes»](#core-nodes) Универсальные ноды для любых задач: | Нода | Описание | | -------------------- | ----------------------- | | **HTTP Request** | Запросы к любым API | | **Code** | JavaScript/Python код | | **Set** | Создание данных | | **IF** | Условное ветвление | | **Switch** | Множественное ветвление | | **Merge** | Объединение данных | | **Split In Batches** | Разбиение на пакеты | ### Trigger Nodes [Заголовок раздела «Trigger Nodes»](#trigger-nodes) Запускают workflow: | Триггер | Описание | | ---------------- | ------------------ | | **Webhook** | HTTP запросы | | **Schedule** | По расписанию | | **Manual** | Ручной запуск | | **App Triggers** | События в сервисах | ## Credentials [Заголовок раздела «Credentials»](#credentials) ### Типы авторизации [Заголовок раздела «Типы авторизации»](#типы-авторизации) | Тип | Примеры | | -------------- | --------------------- | | **API Key** | OpenAI, Anthropic | | **OAuth2** | Google, Slack, GitHub | | **Basic Auth** | Многие REST API | | **Token** | Telegram, Discord | ### Создание Credential [Заголовок раздела «Создание Credential»](#создание-credential) 1. **Settings** → **Credentials** → **Add Credential** 2. Выберите тип сервиса 3. Заполните данные 4. **Save** ### OAuth2 Flow [Заголовок раздела «OAuth2 Flow»](#oauth2-flow) 1. Создайте приложение в сервисе 2. Получите Client ID и Secret 3. Укажите Redirect URL: `https://n8n.example.com/rest/oauth2-credential/callback` 4. Авторизуйтесь через кнопку Connect ## Популярные интеграции [Заголовок раздела «Популярные интеграции»](#популярные-интеграции) ### Google [Заголовок раздела «Google»](#google) | Нода | Возможности | | ------------------- | ---------------------- | | **Google Sheets** | CRUD операции | | **Gmail** | Отправка, чтение писем | | **Google Drive** | Файловые операции | | **Google Calendar** | События | | **Google Docs** | Создание документов | ### Slack [Заголовок раздела «Slack»](#slack) | Операция | Описание | | ------------------ | ------------------- | | **Send Message** | Отправить сообщение | | **Update Message** | Обновить сообщение | | **Get Channel** | Информация о канале | | **File Upload** | Загрузка файлов | ### Telegram [Заголовок раздела «Telegram»](#telegram) | Операция | Описание | | ----------------- | --------------------- | | **Send Message** | Отправить сообщение | | **Send Photo** | Отправить изображение | | **Send Document** | Отправить файл | | **Get Updates** | Получить обновления | ### Базы данных [Заголовок раздела «Базы данных»](#базы-данных) | БД | Операции | | -------------- | --------------------------------------- | | **PostgreSQL** | Query, Insert, Update, Delete | | **MySQL** | Query, Insert, Update, Delete | | **MongoDB** | Find, Insert, Update, Delete, Aggregate | | **Redis** | Get, Set, Delete, Keys | ## HTTP Request [Заголовок раздела «HTTP Request»](#http-request) Универсальная нода для любых API. ### Методы [Заголовок раздела «Методы»](#методы) | Метод | Использование | | ---------- | -------------------- | | **GET** | Получение данных | | **POST** | Создание ресурса | | **PUT** | Полное обновление | | **PATCH** | Частичное обновление | | **DELETE** | Удаление | ### Аутентификация [Заголовок раздела «Аутентификация»](#аутентификация) * **None** — без авторизации * **Predefined Credential** — сохранённый credential * **Generic Credential** — базовая/API Key auth * **Custom** — своя схема в headers ### Pagination [Заголовок раздела «Pagination»](#pagination) Автоматическая пагинация: * **Update Parameter** — обновлять параметр (page) * **Use Response** — cursor из ответа * **Response Contains** — условие остановки ## Custom Nodes [Заголовок раздела «Custom Nodes»](#custom-nodes) ### Создание [Заголовок раздела «Создание»](#создание) 1. Установите n8n-node-dev: `npm i -g n8n-node-dev` 2. Создайте структуру: `n8n-node-dev new` 3. Разработайте ноду 4. Установите: `npm link` ### Публикация [Заголовок раздела «Публикация»](#публикация) ```bash # package.json { "name": "n8n-nodes-mynode", "n8n": { "nodes": ["dist/nodes/MyNode/MyNode.node.js"] } } ``` ## Community Nodes [Заголовок раздела «Community Nodes»](#community-nodes) ### Установка [Заголовок раздела «Установка»](#установка) ```bash # В Settings → Community Nodes npm: n8n-nodes-package-name ``` ### Популярные [Заголовок раздела «Популярные»](#популярные) | Package | Описание | | ----------------------------- | ------------------ | | `n8n-nodes-browserless` | Browser automation | | `n8n-nodes-puppeteer` | Puppeteer | | `n8n-nodes-text-manipulation` | Работа с текстом | ## Следующие шаги [Заголовок раздела «Следующие шаги»](#следующие-шаги) * [Core Nodes](/integrations/core-nodes/) — детальное описание * [Triggers](/integrations/triggers/) — типы триггеров * [HTTP Request](/integrations/core-nodes/http-request/) — работа с API # Triggers > Типы триггеров в n8n — Webhook, Schedule, App Triggers ## Обзор триггеров [Заголовок раздела «Обзор триггеров»](#обзор-триггеров) Триггеры запускают выполнение workflow. Без триггера workflow не может работать автоматически. | Тип | Использование | | ---------------- | ------------------ | | **Manual** | Ручной запуск | | **Webhook** | HTTP запросы | | **Schedule** | По расписанию | | **App Triggers** | События в сервисах | ## Manual Trigger [Заголовок раздела «Manual Trigger»](#manual-trigger) Простейший триггер для ручного запуска. ### Использование [Заголовок раздела «Использование»](#использование) * Тестирование workflow * Разовые задачи * Запуск через API ### Запуск через API [Заголовок раздела «Запуск через API»](#запуск-через-api) ```bash curl -X POST https://n8n.example.com/api/v1/workflows/123/execute \ -H "X-N8N-API-KEY: your-api-key" ``` ## Webhook [Заголовок раздела «Webhook»](#webhook) Запуск по HTTP запросу. ### Параметры [Заголовок раздела «Параметры»](#параметры) | Параметр | Описание | | ------------------ | ---------------------------- | | **HTTP Method** | GET, POST, PUT, DELETE, etc. | | **Path** | URL path | | **Authentication** | Способ авторизации | | **Response Mode** | Когда отвечать | ### URL формат [Заголовок раздела «URL формат»](#url-формат) ```plaintext Production: https://n8n.example.com/webhook/path Test: https://n8n.example.com/webhook-test/path ``` ### Authentication [Заголовок раздела «Authentication»](#authentication) * None Открытый доступ (не рекомендуется). * Basic Auth ```plaintext Authorization: Basic base64(user:password) ``` * Header Auth ```plaintext X-Custom-Header: secret-value ``` * JWT ```plaintext Authorization: Bearer jwt-token ``` ### Response Mode [Заголовок раздела «Response Mode»](#response-mode) | Режим | Описание | | ----------------------------------- | --------------------- | | **Immediately** | Ответ сразу (200 OK) | | **When Last Node Finishes** | Данные последней ноды | | **Using ‘Respond to Webhook’ Node** | Кастомный ответ | ### Respond to Webhook [Заголовок раздела «Respond to Webhook»](#respond-to-webhook) ```plaintext Response Code: 201 Response Body: {{ $json.result }} Response Headers: - Content-Type: application/json ``` ### Пример: GitHub Webhook [Заголовок раздела «Пример: GitHub Webhook»](#пример-github-webhook) ```plaintext Method: POST Path: /github-webhook Authentication: Header Auth Header Name: X-Hub-Signature-256 Header Value: sha256=... ``` ## Schedule Trigger [Заголовок раздела «Schedule Trigger»](#schedule-trigger) Запуск по расписанию. ### Интервалы [Заголовок раздела «Интервалы»](#интервалы) | Интервал | Пример | | ----------- | ---------------------- | | **Seconds** | Каждые 30 секунд | | **Minutes** | Каждые 5 минут | | **Hours** | Каждый час | | **Days** | Каждый день в 9:00 | | **Weeks** | По понедельникам | | **Months** | 1-го числа | | **Cron** | Произвольное выражение | ### Cron выражения [Заголовок раздела «Cron выражения»](#cron-выражения) ```plaintext * * * * * │ │ │ │ │ │ │ │ │ └── День недели (0-7, 0=Sun) │ │ │ └──── Месяц (1-12) │ │ └────── День месяца (1-31) │ └──────── Час (0-23) └────────── Минута (0-59) ``` ### Примеры Cron [Заголовок раздела «Примеры Cron»](#примеры-cron) | Cron | Описание | | -------------- | ------------------ | | `*/15 * * * *` | Каждые 15 минут | | `0 9 * * 1-5` | 9:00 по будням | | `0 0 1 * *` | Полночь 1-го числа | | `0 */2 * * *` | Каждые 2 часа | | `0 9,18 * * *` | 9:00 и 18:00 | ### Timezone [Заголовок раздела «Timezone»](#timezone) ```bash # В переменных окружения GENERIC_TIMEZONE=Europe/Moscow ``` Или в настройках workflow. Совет Всегда указывайте timezone для production workflows. ## App Triggers [Заголовок раздела «App Triggers»](#app-triggers) Триггеры от внешних сервисов. ### Polling vs Webhook [Заголовок раздела «Polling vs Webhook»](#polling-vs-webhook) | Тип | Описание | Пример | | ----------- | --------------------- | --------------- | | **Polling** | n8n проверяет сервис | Gmail, Airtable | | **Webhook** | Сервис уведомляет n8n | Slack, GitHub | ### Polling Settings [Заголовок раздела «Polling Settings»](#polling-settings) | Параметр | Описание | | -------------- | ---------------------------- | | **Poll Times** | Интервал проверки | | **Trigger On** | Что триггерит (new, updated) | ### Популярные App Triggers [Заголовок раздела «Популярные App Triggers»](#популярные-app-triggers) #### Gmail [Заголовок раздела «Gmail»](#gmail) ```plaintext Trigger: On new email Poll Times: Every minute Filters: - Label: Inbox - From: important@example.com ``` #### Slack [Заголовок раздела «Slack»](#slack) ```plaintext Trigger: On new message Events: - Message posted to channel - Mention - Direct message ``` #### GitHub [Заголовок раздела «GitHub»](#github) ```plaintext Trigger: On event Events: - Push - Pull Request - Issue - Star ``` #### Telegram [Заголовок раздела «Telegram»](#telegram) ```plaintext Trigger: On message Updates: - Message - Callback query - Inline query ``` ## Chat Trigger [Заголовок раздела «Chat Trigger»](#chat-trigger) Для AI чат-ботов. ### Режимы [Заголовок раздела «Режимы»](#режимы) | Режим | Описание | | ----------------- | --------------- | | **Embedded Chat** | Виджет на сайте | | **Hosted Chat** | Страница от n8n | ### Настройка [Заголовок раздела «Настройка»](#настройка) ```plaintext Authentication: None / Basic Auth Initial Messages: - "Привет! Чем могу помочь?" Input Placeholder: "Введите сообщение..." ``` ## Execute Workflow Trigger [Заголовок раздела «Execute Workflow Trigger»](#execute-workflow-trigger) Запуск от другого workflow. ### Использование [Заголовок раздела «Использование»](#использование-1) ### Параметры [Заголовок раздела «Параметры»](#параметры-1) | Параметр | Описание | | ------------------------- | ---------------- | | **Source** | Выбрать workflow | | **Wait for Sub-Workflow** | Ждать завершения | ## Error Trigger [Заголовок раздела «Error Trigger»](#error-trigger) Обработка ошибок. ### Настройка [Заголовок раздела «Настройка»](#настройка-1) 1. Создайте workflow с Error Trigger 2. В основном workflow: **Settings** → **Error Workflow** 3. Выберите созданный workflow ### Данные ошибки [Заголовок раздела «Данные ошибки»](#данные-ошибки) ```json { "execution": { "id": "123", "url": "https://n8n.../execution/123" }, "workflow": { "id": "456", "name": "My Workflow" }, "error": { "message": "Error message", "node": "HTTP Request" } } ``` ## Лучшие практики [Заголовок раздела «Лучшие практики»](#лучшие-практики) 1. **Безопасность Webhook** * Используйте authentication * Валидируйте входные данные * Ограничивайте IP (если возможно) 2. **Schedule надёжность** * Учитывайте timezone * Не планируйте на точное время (00:00) * Добавляйте buffer между задачами 3. **Polling эффективность** * Не проверяйте слишком часто * Используйте фильтры * Следите за API лимитами ## Следующие шаги [Заголовок раздела «Следующие шаги»](#следующие-шаги) * [Core Nodes](/integrations/core-nodes/) — основные ноды * [Интеграции](/integrations/overview/) — обзор сервисов * [Выполнение](/workflows/executions/) — запуск workflow # REST API > Справочник REST API n8n ## Аутентификация [Заголовок раздела «Аутентификация»](#аутентификация) ### API Key [Заголовок раздела «API Key»](#api-key) ```bash # Создание ключа: Settings → API → Create API Key curl -H "X-N8N-API-KEY: your-api-key" \ https://n8n.example.com/api/v1/workflows ``` ### Header [Заголовок раздела «Header»](#header) ```plaintext X-N8N-API-KEY: your-api-key ``` ## Workflows [Заголовок раздела «Workflows»](#workflows) ### Получить все workflows [Заголовок раздела «Получить все workflows»](#получить-все-workflows) ```bash GET /api/v1/workflows ``` Response: ```json { "data": [ { "id": "123", "name": "My Workflow", "active": true, "createdAt": "2025-01-15T10:00:00.000Z", "updatedAt": "2025-01-15T12:00:00.000Z" } ] } ``` ### Получить workflow по ID [Заголовок раздела «Получить workflow по ID»](#получить-workflow-по-id) ```bash GET /api/v1/workflows/{id} ``` ### Создать workflow [Заголовок раздела «Создать workflow»](#создать-workflow) ```bash POST /api/v1/workflows Content-Type: application/json { "name": "New Workflow", "nodes": [...], "connections": {...}, "settings": {...} } ``` ### Обновить workflow [Заголовок раздела «Обновить workflow»](#обновить-workflow) ```bash PUT /api/v1/workflows/{id} Content-Type: application/json { "name": "Updated Workflow", "nodes": [...], "connections": {...} } ``` ### Удалить workflow [Заголовок раздела «Удалить workflow»](#удалить-workflow) ```bash DELETE /api/v1/workflows/{id} ``` ### Активировать/деактивировать [Заголовок раздела «Активировать/деактивировать»](#активироватьдеактивировать) ```bash POST /api/v1/workflows/{id}/activate POST /api/v1/workflows/{id}/deactivate ``` ## Executions [Заголовок раздела «Executions»](#executions) ### Получить executions [Заголовок раздела «Получить executions»](#получить-executions) ```bash GET /api/v1/executions # С фильтрами GET /api/v1/executions?workflowId=123&status=success&limit=10 ``` Parameters: | Параметр | Описание | | ------------ | ----------------------- | | `workflowId` | ID workflow | | `status` | success, error, waiting | | `limit` | Количество (max 250) | ### Получить execution по ID [Заголовок раздела «Получить execution по ID»](#получить-execution-по-id) ```bash GET /api/v1/executions/{id} ``` ### Удалить execution [Заголовок раздела «Удалить execution»](#удалить-execution) ```bash DELETE /api/v1/executions/{id} ``` ## Запуск Workflow [Заголовок раздела «Запуск Workflow»](#запуск-workflow) ### Manual Execute [Заголовок раздела «Manual Execute»](#manual-execute) ```bash POST /api/v1/workflows/{id}/execute Content-Type: application/json { "workflowData": {...} // опционально } ``` Response: ```json { "data": { "executionId": "456" } } ``` ### Execute с данными [Заголовок раздела «Execute с данными»](#execute-с-данными) ```bash POST /api/v1/workflows/{id}/execute Content-Type: application/json { "workflowData": { "nodes": [...], "connections": {...} } } ``` ## Credentials [Заголовок раздела «Credentials»](#credentials) ### Получить credentials (без секретов) [Заголовок раздела «Получить credentials (без секретов)»](#получить-credentials-без-секретов) ```bash GET /api/v1/credentials ``` ### Создать credential [Заголовок раздела «Создать credential»](#создать-credential) ```bash POST /api/v1/credentials Content-Type: application/json { "name": "My API Key", "type": "httpHeaderAuth", "data": { "name": "Authorization", "value": "Bearer token" } } ``` ### Удалить credential [Заголовок раздела «Удалить credential»](#удалить-credential) ```bash DELETE /api/v1/credentials/{id} ``` Осторожно API не возвращает секретные данные credentials из соображений безопасности. ## Users (Enterprise) [Заголовок раздела «Users (Enterprise)»](#users-enterprise) ### Получить пользователей [Заголовок раздела «Получить пользователей»](#получить-пользователей) ```bash GET /api/v1/users ``` ### Создать пользователя [Заголовок раздела «Создать пользователя»](#создать-пользователя) ```bash POST /api/v1/users Content-Type: application/json { "email": "user@example.com", "firstName": "John", "lastName": "Doe", "role": "member" } ``` ## Tags [Заголовок раздела «Tags»](#tags) ### Получить теги [Заголовок раздела «Получить теги»](#получить-теги) ```bash GET /api/v1/tags ``` ### Создать тег [Заголовок раздела «Создать тег»](#создать-тег) ```bash POST /api/v1/tags Content-Type: application/json { "name": "production" } ``` ## Variables [Заголовок раздела «Variables»](#variables) ### Получить переменные [Заголовок раздела «Получить переменные»](#получить-переменные) ```bash GET /api/v1/variables ``` ### Создать переменную [Заголовок раздела «Создать переменную»](#создать-переменную) ```bash POST /api/v1/variables Content-Type: application/json { "key": "API_URL", "value": "https://api.example.com" } ``` ## Примеры использования [Заголовок раздела «Примеры использования»](#примеры-использования) ### Python [Заголовок раздела «Python»](#python) ```python import requests API_KEY = "your-api-key" BASE_URL = "https://n8n.example.com/api/v1" headers = { "X-N8N-API-KEY": API_KEY, "Content-Type": "application/json" } # Получить workflows response = requests.get(f"{BASE_URL}/workflows", headers=headers) workflows = response.json()["data"] # Запустить workflow response = requests.post( f"{BASE_URL}/workflows/123/execute", headers=headers ) execution_id = response.json()["data"]["executionId"] ``` ### JavaScript [Заголовок раздела «JavaScript»](#javascript) ```javascript const API_KEY = 'your-api-key'; const BASE_URL = 'https://n8n.example.com/api/v1'; async function getWorkflows() { const response = await fetch(`${BASE_URL}/workflows`, { headers: { 'X-N8N-API-KEY': API_KEY } }); return response.json(); } async function executeWorkflow(id) { const response = await fetch(`${BASE_URL}/workflows/${id}/execute`, { method: 'POST', headers: { 'X-N8N-API-KEY': API_KEY, 'Content-Type': 'application/json' } }); return response.json(); } ``` ### cURL [Заголовок раздела «cURL»](#curl) ```bash # Получить workflows curl -H "X-N8N-API-KEY: key" \ https://n8n.example.com/api/v1/workflows # Запустить workflow curl -X POST \ -H "X-N8N-API-KEY: key" \ -H "Content-Type: application/json" \ https://n8n.example.com/api/v1/workflows/123/execute # Создать workflow curl -X POST \ -H "X-N8N-API-KEY: key" \ -H "Content-Type: application/json" \ -d '{"name":"Test","nodes":[],"connections":{}}' \ https://n8n.example.com/api/v1/workflows ``` ## Rate Limits [Заголовок раздела «Rate Limits»](#rate-limits) | Endpoint | Limit | | -------- | ----------- | | Общий | 100 req/min | | Execute | 20 req/min | Совет При достижении лимита API возвращает `429 Too Many Requests`. ## Ошибки [Заголовок раздела «Ошибки»](#ошибки) | Код | Описание | | --- | ------------------------------- | | 400 | Bad Request | | 401 | Unauthorized (неверный API key) | | 404 | Not Found | | 429 | Rate Limit Exceeded | | 500 | Internal Server Error | ## Следующие шаги [Заголовок раздела «Следующие шаги»](#следующие-шаги) * [CLI команды](/reference/cli/) — командная строка * [Глоссарий](/reference/glossary/) — термины * [Переменные окружения](/hosting/environment-variables/) — конфигурация # CLI команды > Справочник команд n8n для командной строки ## Запуск [Заголовок раздела «Запуск»](#запуск) ### Основные команды [Заголовок раздела «Основные команды»](#основные-команды) ```bash # Запуск n8n n8n start # Запуск с указанием порта n8n start --port 5679 # Запуск в production режиме NODE_ENV=production n8n start ``` ### Worker (Queue Mode) [Заголовок раздела «Worker (Queue Mode)»](#worker-queue-mode) ```bash # Запуск worker'а n8n worker # С concurrency n8n worker --concurrency 10 ``` ### Webhook [Заголовок раздела «Webhook»](#webhook) ```bash # Отдельный процесс для webhooks n8n webhook ``` ## Export / Import [Заголовок раздела «Export / Import»](#export--import) ### Workflows [Заголовок раздела «Workflows»](#workflows) ```bash # Экспорт всех workflows n8n export:workflow --all # Экспорт в файл n8n export:workflow --all --output=workflows.json # Экспорт конкретного workflow n8n export:workflow --id=123 # Импорт из файла n8n import:workflow --input=workflow.json # Импорт с разделением n8n import:workflow --separate --input=workflows/ ``` ### Credentials [Заголовок раздела «Credentials»](#credentials) ```bash # Экспорт всех credentials n8n export:credentials --all # Экспорт с расшифровкой n8n export:credentials --all --decrypted # Импорт n8n import:credentials --input=credentials.json ``` Осторожно `--decrypted` экспортирует пароли в открытом виде. Используйте осторожно. ## Пользователи [Заголовок раздела «Пользователи»](#пользователи) ```bash # Сброс пароля владельца n8n user-management:reset # Информация о пользователях (Enterprise) n8n user-management:list ``` ## База данных [Заголовок раздела «База данных»](#база-данных) ```bash # Создание базы n8n db:create # Миграции n8n db:revert # Очистка executions n8n db:prune ``` ## Очередь [Заголовок раздела «Очередь»](#очередь) ```bash # Статус очереди n8n queue:status # Очистка очереди n8n queue:clear ``` ## License (Enterprise) [Заголовок раздела «License (Enterprise)»](#license-enterprise) ```bash # Активация лицензии n8n license:activate --activation-key=KEY # Информация о лицензии n8n license:info # Очистка лицензии n8n license:clear ``` ## Переменные окружения в CLI [Заголовок раздела «Переменные окружения в CLI»](#переменные-окружения-в-cli) ```bash # С переменными N8N_PORT=5679 N8N_PROTOCOL=https n8n start # Или через .env файл export $(cat .env | xargs) && n8n start ``` ## Docker команды [Заголовок раздела «Docker команды»](#docker-команды) ```bash # Запуск docker run -it --rm \ -p 5678:5678 \ -v n8n_data:/home/node/.n8n \ n8nio/n8n # Экспорт через Docker docker run -it --rm \ -v n8n_data:/home/node/.n8n \ -v $(pwd):/backup \ n8nio/n8n \ n8n export:workflow --all --output=/backup/workflows.json # Worker в Docker docker run -it --rm \ -v n8n_data:/home/node/.n8n \ n8nio/n8n \ n8n worker ``` ## Полезные флаги [Заголовок раздела «Полезные флаги»](#полезные-флаги) | Флаг | Описание | | ----------- | -------------------------- | | `--help` | Показать справку | | `--version` | Версия n8n | | `--tunnel` | Включить локальный туннель | ## Примеры [Заголовок раздела «Примеры»](#примеры) ### Backup script [Заголовок раздела «Backup script»](#backup-script) ```bash #!/bin/bash DATE=$(date +%Y%m%d) n8n export:workflow --all --output=/backup/workflows_$DATE.json n8n export:credentials --all --output=/backup/credentials_$DATE.json ``` ### Health check [Заголовок раздела «Health check»](#health-check) ```bash #!/bin/bash curl -sf http://localhost:5678/healthz > /dev/null if [ $? -ne 0 ]; then echo "n8n is not healthy" exit 1 fi ``` ## Следующие шаги [Заголовок раздела «Следующие шаги»](#следующие-шаги) * [API](/reference/api/) — REST API n8n * [Переменные окружения](/hosting/environment-variables/) — конфигурация * [Docker](/hosting/docker/) — контейнеризация # Часто задаваемые вопросы > Ответы на популярные вопросы о n8n, MCP и автоматизации с AI ## Общие вопросы о n8n [Заголовок раздела «Общие вопросы о n8n»](#общие-вопросы-о-n8n) ### Что такое n8n и чем он отличается от Zapier/Make? [Заголовок раздела «Что такое n8n и чем он отличается от Zapier/Make?»](#что-такое-n8n-и-чем-он-отличается-от-zapiermake) **n8n** — это платформа автоматизации с открытым исходным кодом. Ключевые отличия: | Параметр | n8n | Zapier | Make | | --------------- | --------------------------- | ------------- | ------------- | | Лицензия | Fair-code (можно self-host) | Проприетарная | Проприетарная | | Self-hosting | Да | Нет | Нет | | Код в workflows | JavaScript/Python | Нет | Ограниченно | | AI интеграция | 119+ LangChain нод | Базовая | Базовая | | MCP поддержка | Полная | Нет | Нет | | Цена | Бесплатно (self-host) | От $20/мес | От $9/мес | ### Какие требования для установки n8n? [Заголовок раздела «Какие требования для установки n8n?»](#какие-требования-для-установки-n8n) **Минимальные требования:** * Node.js 18.17+ или Docker * 2 GB RAM (4 GB рекомендуется) * 20 GB диск **Рекомендуемые требования для production:** * 4+ CPU cores * 8+ GB RAM * SSD диск * PostgreSQL (вместо SQLite) ### Как обновить n8n до последней версии? [Заголовок раздела «Как обновить n8n до последней версии?»](#как-обновить-n8n-до-последней-версии) ```bash # Docker docker pull n8nio/n8n:latest docker-compose down && docker-compose up -d # npm npm update -g n8n # Проверка версии n8n --version ``` *** ## AI и LangChain [Заголовок раздела «AI и LangChain»](#ai-и-langchain) ### Какие LLM модели поддерживает n8n? [Заголовок раздела «Какие LLM модели поддерживает n8n?»](#какие-llm-модели-поддерживает-n8n) n8n поддерживает **20+ моделей** через LangChain: **Облачные:** * OpenAI (GPT-4, GPT-4o, GPT-3.5) * Anthropic (Claude 3.5, Claude 3) * Google (Gemini Pro, Gemini Flash) * Mistral (Large, Medium, Small) * Groq (Llama, Mixtral) * DeepSeek * xAI Grok **Локальные:** * Ollama (любые модели) * LM Studio ### Что такое AI Agent и когда его использовать? [Заголовок раздела «Что такое AI Agent и когда его использовать?»](#что-такое-ai-agent-и-когда-его-использовать) **AI Agent** — это нода, которая использует LLM для принятия решений о том, какие инструменты вызывать. **Используйте Agent когда:** * Задача требует многошаговой логики * Нужно выбирать между несколькими действиями * Результат зависит от контекста разговора **Используйте Chain когда:** * Задача линейная (вопрос → ответ) * Не нужны внешние инструменты * Важна скорость и стоимость ### Как добавить память (Memory) в AI Agent? [Заголовок раздела «Как добавить память (Memory) в AI Agent?»](#как-добавить-память-memory-в-ai-agent) ```javascript // В настройках AI Agent ноды: // 1. Подключите Memory ноду к входу "Memory" // 2. Выберите тип памяти: // Buffer Memory — хранит последние N сообщений // Window Memory — скользящее окно сообщений // Redis Memory — персистентная память // Postgres Memory — для масштабирования ``` Совет Для чат-ботов используйте Window Memory с размером 10-20 сообщений. Для длинных разговоров — Redis или Postgres. *** ## MCP (Model Context Protocol) [Заголовок раздела «MCP (Model Context Protocol)»](#mcp-model-context-protocol) ### Что такое MCP и зачем он нужен? [Заголовок раздела «Что такое MCP и зачем он нужен?»](#что-такое-mcp-и-зачем-он-нужен) **MCP (Model Context Protocol)** — это открытый протокол для подключения AI моделей к внешним инструментам и данным. **Преимущества:** * Стандартный интерфейс для всех AI клиентов * Безопасный доступ к инструментам * OAuth аутентификация * Работает с Claude, n8n, VS Code и др. ### Как подключить MCP сервер к n8n? [Заголовок раздела «Как подключить MCP сервер к n8n?»](#как-подключить-mcp-сервер-к-n8n) 1. **Установите MCP сервер** (например, GitHub MCP): ```bash npx @anthropic/mcp-server-github ``` 2. **В n8n добавьте MCP Client ноду:** * Укажите URL сервера * Настройте аутентификацию (API Key или OAuth) * Выберите нужные tools 3. **Подключите к AI Agent:** * MCP Client как Tool input для Agent ### Как создать свой MCP сервер? [Заголовок раздела «Как создать свой MCP сервер?»](#как-создать-свой-mcp-сервер) ```typescript import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; const server = new McpServer({ name: "my-server", version: "1.0.0" }); // Регистрация tool server.tool("hello", "Say hello", { name: "string" }, async ({ name }) => `Hello, ${name}!` ); // Запуск const transport = new StdioServerTransport(); await server.connect(transport); ``` [Полный гайд по MCP SDK ](/ai-mcp/mcp-sdk/)Создание MCP серверов на TypeScript и Python *** ## Хостинг и развёртывание [Заголовок раздела «Хостинг и развёртывание»](#хостинг-и-развёртывание) ### Где лучше разместить n8n? [Заголовок раздела «Где лучше разместить n8n?»](#где-лучше-разместить-n8n) **Варианты размещения:** | Платформа | Плюсы | Минусы | | ------------------ | ----------------------- | ----------------------------- | | **Docker на VPS** | Полный контроль, дёшево | Требует DevOps знаний | | **n8n Cloud** | Готово к работе | Платно, данные у n8n | | **Railway/Render** | Простой деплой | Ограничения бесплатного плана | | **Kubernetes** | Масштабируемость | Сложность настройки | **Рекомендация для России:** VPS на Selectel, Timeweb или Yandex Cloud с Docker. ### Как настроить HTTPS для n8n? [Заголовок раздела «Как настроить HTTPS для n8n?»](#как-настроить-https-для-n8n) ```bash # С использованием Caddy (автоматический SSL) # Caddyfile: n8n.example.com { reverse_proxy localhost:5678 } # Или через nginx + certbot: sudo certbot --nginx -d n8n.example.com ``` ### Как масштабировать n8n? [Заголовок раздела «Как масштабировать n8n?»](#как-масштабировать-n8n) 1. **Включите Queue Mode:** ```bash # docker-compose.yml environment: - EXECUTIONS_MODE=queue - QUEUE_BULL_REDIS_HOST=redis ``` 2. **Добавьте worker’ы:** ```bash docker-compose up -d --scale worker=3 ``` 3. **Используйте PostgreSQL** вместо SQLite *** ## Безопасность [Заголовок раздела «Безопасность»](#безопасность) ### Как защитить n8n? [Заголовок раздела «Как защитить n8n?»](#как-защитить-n8n) **Обязательные меры:** * [ ] Настройте аутентификацию (`N8N_BASIC_AUTH_ACTIVE=true`) * [ ] Используйте HTTPS * [ ] Ограничьте доступ по IP (firewall) * [ ] Регулярно обновляйте **Дополнительные меры:** * [ ] Включите 2FA * [ ] Используйте API ключи вместо паролей * [ ] Настройте RBAC (ролевой доступ) * [ ] Логируйте все действия ### Как безопасно хранить API ключи? [Заголовок раздела «Как безопасно хранить API ключи?»](#как-безопасно-хранить-api-ключи) ```bash # Используйте переменные окружения: OPENAI_API_KEY=sk-xxx ANTHROPIC_API_KEY=sk-ant-xxx # В n8n используйте Credentials (не хардкодьте в workflows) ``` Осторожно Никогда не храните API ключи в JSON workflows. Они будут видны при экспорте! *** ## Интеграции [Заголовок раздела «Интеграции»](#интеграции) ### Какие триггеры поддерживает n8n? [Заголовок раздела «Какие триггеры поддерживает n8n?»](#какие-триггеры-поддерживает-n8n) **Типы триггеров:** * **Webhook** — HTTP запросы * **Schedule** — по расписанию (cron) * **Polling** — проверка изменений * **Event** — события от сервисов (Telegram, Slack и др.) * **Manual** — ручной запуск * **Chat** — сообщения в чат * **MCP Trigger** — вызовы через MCP ### Как отлаживать workflows? [Заголовок раздела «Как отлаживать workflows?»](#как-отлаживать-workflows) 1. **Используйте режим Manual execution** — пошаговый запуск 2. **Проверяйте данные** — кликните на ноду чтобы увидеть output 3. **Логирование** — добавьте Code ноду с `console.log()` 4. **Error Workflow** — настройте отдельный workflow для ошибок ### Почему workflow не запускается по расписанию? [Заголовок раздела «Почему workflow не запускается по расписанию?»](#почему-workflow-не-запускается-по-расписанию) **Проверьте:** 1. Workflow активирован (зелёный переключатель) 2. Timezone в настройках соответствует вашему 3. Cron выражение корректно 4. Нет ошибок в первой ноде *** ## Производительность [Заголовок раздела «Производительность»](#производительность) ### Workflow работает медленно. Что делать? [Заголовок раздела «Workflow работает медленно. Что делать?»](#workflow-работает-медленно-что-делать) **Оптимизации:** 1. **Используйте Split In Batches** для больших данных 2. **Включите Queue Mode** для параллельного выполнения 3. **Кэшируйте результаты** в Redis 4. **Уменьшите payload** — не передавайте лишние данные 5. **Используйте webhooks** вместо polling ### Какие лимиты у n8n? [Заголовок раздела «Какие лимиты у n8n?»](#какие-лимиты-у-n8n) | Параметр | Self-hosted | n8n Cloud (Pro) | | ---------------- | ------------- | --------------- | | Workflows | Неограничено | 100+ | | Executions | Неограничено | 50,000/мес | | Active workflows | Неограничено | 100+ | | Retention | Настраивается | 30 дней | *** ## Где получить помощь? [Заголовок раздела «Где получить помощь?»](#где-получить-помощь) Документация n8n [docs.n8n.io](https://docs.n8n.io) — официальная документация Community Forum [community.n8n.io](https://community.n8n.io) — форум сообщества Discord [n8n Discord](https://discord.gg/n8n) — чат сообщества GitHub [github.com/n8n-io/n8n](https://github.com/n8n-io/n8n) — исходный код # Глоссарий > Термины и определения в n8n ## A [Заголовок раздела «A»](#a) ### AI Agent [Заголовок раздела «AI Agent»](#ai-agent) Автономный агент, использующий LLM для принятия решений и инструменты для выполнения задач. ### App Node [Заголовок раздела «App Node»](#app-node) Нода для интеграции с конкретным сервисом (Slack, Google Sheets, etc.). ## B [Заголовок раздела «B»](#b) ### Binary Data [Заголовок раздела «Binary Data»](#binary-data) Бинарные данные (файлы, изображения) в n8n. Хранятся отдельно от JSON. ### Buffer Memory [Заголовок раздела «Buffer Memory»](#buffer-memory) Тип памяти AI агента, хранящий всю историю диалога. ## C [Заголовок раздела «C»](#c) ### Canvas [Заголовок раздела «Canvas»](#canvas) Рабочая область редактора n8n для построения workflows. ### Chain [Заголовок раздела «Chain»](#chain) Последовательность вызовов LLM в LangChain паттерне. ### Chat Model [Заголовок раздела «Chat Model»](#chat-model) Нода для подключения LLM (OpenAI, Anthropic, Ollama). ### Condition [Заголовок раздела «Condition»](#condition) Условие в ноде IF или Switch для ветвления логики. ### Connection [Заголовок раздела «Connection»](#connection) Связь между нодами, по которой передаются данные. ### Core Node [Заголовок раздела «Core Node»](#core-node) Универсальная нода n8n (HTTP Request, Code, Set, IF). ### Credential [Заголовок раздела «Credential»](#credential) Сохранённые учётные данные для подключения к сервисам. ## D [Заголовок раздела «D»](#d) ### Data Pinning [Заголовок раздела «Data Pinning»](#data-pinning) Фиксация тестовых данных на ноде для отладки. ### Deactivate [Заголовок раздела «Deactivate»](#deactivate) Отключение workflow от автоматического выполнения. ## E [Заголовок раздела «E»](#e) ### Embeddings [Заголовок раздела «Embeddings»](#embeddings) Векторные представления текста для семантического поиска. ### Error Trigger [Заголовок раздела «Error Trigger»](#error-trigger) Специальный триггер для обработки ошибок в workflows. ### Execution [Заголовок раздела «Execution»](#execution) Единичный запуск workflow. ### Expression [Заголовок раздела «Expression»](#expression) Динамическое значение в поле ноды: `{{ $json.field }}`. ## F [Заголовок раздела «F»](#f) ### Flow [Заголовок раздела «Flow»](#flow) Поток данных между нодами в workflow. ### Function Item [Заголовок раздела «Function Item»](#function-item) Режим Code Node для обработки каждого item отдельно. ## I [Заголовок раздела «I»](#i) ### Input [Заголовок раздела «Input»](#input) Входные данные ноды. ### Item [Заголовок раздела «Item»](#item) Единица данных в n8n — объект с полями `json` и `binary`. ## J [Заголовок раздела «J»](#j) ### JSON [Заголовок раздела «JSON»](#json) Формат данных в n8n. Каждый item содержит поле `json` с данными. ## L [Заголовок раздела «L»](#l) ### LangChain [Заголовок раздела «LangChain»](#langchain) Фреймворк для построения AI приложений. Концепции реализованы в n8n. ### LLM [Заголовок раздела «LLM»](#llm) Large Language Model — большая языковая модель (GPT, Claude, etc.). ### Loop [Заголовок раздела «Loop»](#loop) Цикл в workflow для итерации по данным. ## M [Заголовок раздела «M»](#m) ### Manual Trigger [Заголовок раздела «Manual Trigger»](#manual-trigger) Триггер для ручного запуска workflow. ### MCP [Заголовок раздела «MCP»](#mcp) Model Context Protocol — протокол для подключения AI к внешним данным. ### Memory [Заголовок раздела «Memory»](#memory) Компонент AI агента для хранения контекста диалога. ### Merge [Заголовок раздела «Merge»](#merge) Нода для объединения данных из нескольких источников. ## N [Заголовок раздела «N»](#n) ### Node [Заголовок раздела «Node»](#node) Узел workflow, выполняющий определённое действие. ### n8n Cloud [Заголовок раздела «n8n Cloud»](#n8n-cloud) Облачная версия n8n от Anthropic. ## O [Заголовок раздела «O»](#o) ### OAuth2 [Заголовок раздела «OAuth2»](#oauth2) Протокол авторизации, используемый многими сервисами. ### Output [Заголовок раздела «Output»](#output) Выходные данные ноды. ## P [Заголовок раздела «P»](#p) ### Pagination [Заголовок раздела «Pagination»](#pagination) Постраничное получение данных из API. ### Poll [Заголовок раздела «Poll»](#poll) Периодическая проверка сервиса на новые данные. ### Production Mode [Заголовок раздела «Production Mode»](#production-mode) Режим работы активированного workflow. ## Q [Заголовок раздела «Q»](#q) ### Queue Mode [Заголовок раздела «Queue Mode»](#queue-mode) Режим работы n8n с отдельными workers и Redis очередью. ## R [Заголовок раздела «R»](#r) ### RAG [Заголовок раздела «RAG»](#rag) Retrieval-Augmented Generation — поиск по документам + генерация ответа. ### Retriever [Заголовок раздела «Retriever»](#retriever) Компонент RAG для поиска релевантных документов. ### Retry [Заголовок раздела «Retry»](#retry) Повторная попытка выполнения при ошибке. ## S [Заголовок раздела «S»](#s) ### Schedule Trigger [Заголовок раздела «Schedule Trigger»](#schedule-trigger) Триггер для запуска workflow по расписанию. ### Split In Batches [Заголовок раздела «Split In Batches»](#split-in-batches) Нода для разбиения данных на пакеты. ### Sticky Note [Заголовок раздела «Sticky Note»](#sticky-note) Заметка на canvas для документирования workflow. ### Sub-workflow [Заголовок раздела «Sub-workflow»](#sub-workflow) Workflow, вызываемый из другого workflow. ## T [Заголовок раздела «T»](#t) ### Tag [Заголовок раздела «Tag»](#tag) Метка для организации workflows. ### Test Mode [Заголовок раздела «Test Mode»](#test-mode) Режим тестирования workflow с отображением данных. ### Tool [Заголовок раздела «Tool»](#tool) Инструмент AI агента (Calculator, HTTP, Code, MCP). ### Trigger [Заголовок раздела «Trigger»](#trigger) Нода, запускающая выполнение workflow. ## V [Заголовок раздела «V»](#v) ### Variable [Заголовок раздела «Variable»](#variable) Глобальная переменная в n8n (`$vars`). ### Vector Store [Заголовок раздела «Vector Store»](#vector-store) Хранилище векторных embeddings для RAG. ## W [Заголовок раздела «W»](#w) ### Wait [Заголовок раздела «Wait»](#wait) Нода для паузы выполнения. ### Webhook [Заголовок раздела «Webhook»](#webhook) HTTP endpoint для запуска workflow внешними сервисами. ### Window Memory [Заголовок раздела «Window Memory»](#window-memory) Тип памяти AI агента со скользящим окном сообщений. ### Worker [Заголовок раздела «Worker»](#worker) Процесс для выполнения workflows в Queue Mode. ### Workflow [Заголовок раздела «Workflow»](#workflow) Автоматизированный процесс из связанных нод. ## Следующие шаги [Заголовок раздела «Следующие шаги»](#следующие-шаги) * [CLI команды](/reference/cli/) — командная строка * [API](/reference/api/) — REST API * [Обзор workflows](/workflows/overview/) — основы # Горячие клавиши > Полный справочник клавиатурных сокращений n8n n8n предоставляет множество горячих клавиш для ускорения работы. Совет На Mac используйте **Cmd** вместо **Ctrl**. ## Управление Workflow [Заголовок раздела «Управление Workflow»](#управление-workflow) | Комбинация | Действие | | ------------------ | ----------------------------- | | `Ctrl + Alt + N` | Создать новый workflow | | `Ctrl + O` | Открыть workflow | | `Ctrl + S` | Сохранить workflow | | `Ctrl + Z` | Отменить последнее действие | | `Ctrl + Shift + Z` | Повторить отменённое действие | | `Ctrl + Enter` | Выполнить workflow | *** ## Работа с Canvas [Заголовок раздела «Работа с Canvas»](#работа-с-canvas) ### Перемещение холста [Заголовок раздела «Перемещение холста»](#перемещение-холста) | Комбинация | Действие | | ----------------------------- | ----------------------------- | | `Ctrl + ЛКМ` + перетаскивание | Перемещение области просмотра | | `Ctrl + СКМ` + перетаскивание | Перемещение области просмотра | | `Space` + перетаскивание | Перемещение области просмотра | | `СКМ` + перетаскивание | Перемещение области просмотра | | Два пальца (тачскрин) | Перемещение области просмотра | *ЛКМ = левая кнопка мыши, СКМ = средняя кнопка мыши* ### Масштабирование [Заголовок раздела «Масштабирование»](#масштабирование) | Комбинация | Действие | | -------------------- | ------------------------------------ | | `+` или `=` | Увеличить масштаб | | `-` или `_` | Уменьшить масштаб | | `0` | Сбросить масштаб (100%) | | `1` | Вписать workflow в область просмотра | | `Ctrl + Колесо мыши` | Плавное масштабирование | *** ## Работа с нодами [Заголовок раздела «Работа с нодами»](#работа-с-нодами) ### На холсте [Заголовок раздела «На холсте»](#на-холсте) | Комбинация | Действие | | ------------------------------------- | ------------------------------------ | | `Двойной клик` на ноде | Открыть настройки ноды | | `Ctrl + Двойной клик` на под-workflow | Открыть под-workflow в новой вкладке | | `Ctrl + A` | Выделить все ноды | | `Ctrl + V` | Вставить скопированные ноды | | `Shift + S` | Добавить Sticky Note | ### С выделенными нодами [Заголовок раздела «С выделенными нодами»](#с-выделенными-нодами) | Комбинация | Действие | | ---------- | --------------------------- | | `Ctrl + C` | Копировать | | `Ctrl + X` | Вырезать | | `Delete` | Удалить | | `D` | Деактивировать ноду | | `Enter` | Открыть настройки | | `F2` | Переименовать | | `P` | Закрепить данные (Pin data) | ### Навигация стрелками [Заголовок раздела «Навигация стрелками»](#навигация-стрелками) | Комбинация | Действие | | ------------------ | ------------------------------------ | | `↓` | Выбрать ноду ниже | | `↑` | Выбрать ноду выше | | `←` | Выбрать ноду слева | | `→` | Выбрать ноду справа | | `Shift + ←` | Выделить все ноды слева | | `Shift + →` | Выделить все ноды справа | | `Ctrl + Shift + O` | Открыть под-workflow в новой вкладке | *** ## Панель нод (Node Panel) [Заголовок раздела «Панель нод (Node Panel)»](#панель-нод-node-panel) | Комбинация | Действие | | ---------- | ----------------------- | | `Tab` | Открыть панель нод | | `Enter` | Вставить выбранную ноду | | `Escape` | Закрыть панель | ### В категориях [Заголовок раздела «В категориях»](#в-категориях) | Комбинация | Действие | | ---------- | --------------------------- | | `Enter` | Раскрыть/свернуть категорию | | `→` | Раскрыть категорию | | `←` | Свернуть категорию | *** ## Внутри нод [Заголовок раздела «Внутри нод»](#внутри-нод) | Комбинация | Действие | | ---------- | -------------------------------------------------- | | `=` | Переключить поле в режим выражений (в пустом поле) | *** ## Command Bar [Заголовок раздела «Command Bar»](#command-bar) **Command Bar** — универсальный поиск и быстрый доступ к действиям. | Комбинация | Действие | | ---------- | ------------------- | | `Ctrl + K` | Открыть Command Bar | Также можно кликнуть на иконку лупы на холсте. ### Доступные команды [Заголовок раздела «Доступные команды»](#доступные-команды) * Workflow * Add nodes — добавить ноды * Save — сохранить * Test — протестировать * Tidy up — выровнять ноды * Publish/Unpublish — опубликовать * Duplicate — дублировать * Import/Export — импорт/экспорт * Archive — архивировать * Delete — удалить * Навигация * Create workflow — создать workflow * Open workflow — открыть workflow * Create credentials — создать credentials * Open project — открыть проект * Recent resources — недавние ресурсы * Executions * Debug — отладка * Copy — копировать * Retry — повторить * Stop — остановить * Delete — удалить * Общее * Templates — шаблоны * Variables — переменные * Insights — аналитика * Settings — настройки * Help — помощь * Documentation — документация *** ## Шпаргалка [Заголовок раздела «Шпаргалка»](#шпаргалка) ```plaintext ┌─────────────────────────────────────────────────────────┐ │ ОСНОВНЫЕ СОЧЕТАНИЯ │ ├─────────────────────────────────────────────────────────┤ │ │ │ Ctrl+S Сохранить Ctrl+Z Отменить │ │ Ctrl+Enter Выполнить Ctrl+K Command Bar │ │ Tab Панель нод Ctrl+A Выделить все │ │ │ ├─────────────────────────────────────────────────────────┤ │ РАБОТА С НОДАМИ │ ├─────────────────────────────────────────────────────────┤ │ │ │ Ctrl+C Копировать Ctrl+V Вставить │ │ Delete Удалить D Деактивировать │ │ F2 Переименовать P Pin данные │ │ Enter Открыть Shift+S Sticky Note │ │ │ ├─────────────────────────────────────────────────────────┤ │ МАСШТАБ │ ├─────────────────────────────────────────────────────────┤ │ │ │ + Увеличить - Уменьшить │ │ 0 Сбросить (100%) 1 Вписать в окно │ │ Ctrl+Wheel Плавный зум │ │ │ └─────────────────────────────────────────────────────────┘ ``` *** ## Настройка горячих клавиш [Заголовок раздела «Настройка горячих клавиш»](#настройка-горячих-клавиш) Осторожно На данный момент n8n не поддерживает кастомизацию горячих клавиш. Используйте стандартные сочетания. Если вам нужны дополнительные сочетания, вы можете: 1. Использовать расширения браузера для ремаппинга клавиш 2. Предложить функцию на [GitHub Issues](https://github.com/n8n-io/n8n/issues) # 2025: Год прорывов n8n > От AI-революции до мажорной версии 2.0 — полная история развития платформы # 🚀 n8n в 2025 году [Заголовок раздела «🚀 n8n в 2025 году»](#-n8n-в-2025-году) **Год, который изменил автоматизацию навсегда** *** ## ✨ Главное за год [Заголовок раздела «✨ Главное за год»](#-главное-за-год) 🤖 AI Builder Скажи что нужно — получи готовый workflow. Магия! 🛡️ Версия 2.0 Enterprise-безопасность из коробки 💬 Chat Hub Все AI модели в одном чате 📊 Data Tables Своя база данных внутри n8n *** ## 📅 Таймлайн релизов [Заголовок раздела «📅 Таймлайн релизов»](#-таймлайн-релизов) ### 🎄 Декабрь 2025 [Заголовок раздела «🎄 Декабрь 2025»](#-декабрь-2025) v2.0.0 — Мажорный релиз **5 декабря** • [Смотреть на GitHub →](https://github.com/n8n-io/n8n/releases/tag/n8n%402.0.0) MAJORBreaking Changes Это не про новые фичи — это про **безопасность и стабильность**. n8n стал настоящей enterprise-платформой. **Что изменилось:** * 🔒 Код выполняется в изолированных контейнерах * 🚫 Доступ к переменным окружения закрыт по умолчанию * ⚠️ Опасные ноды отключены (ExecuteCommand, LocalFileTrigger) * 📝 Новая модель: **Save** = черновик, **Publish** = в продакшн Миграция обязательна! Проверь свои workflows через **Settings → Migration Report** перед обновлением. v2.1.6 — Time Saved Node **16 декабря** NEW NODE Теперь можно измерять, сколько времени экономят ваши автоматизации. Красивые графики в Insights! *** ### 🍂 Ноябрь 2025 [Заголовок раздела «🍂 Ноябрь 2025»](#-ноябрь-2025) v1.121.0 — Кастомные роли EnterpriseRBAC **Полный контроль над правами доступа:** * 👤 Создавай свои роли (Workflow Builder, Credential Manager…) * 🔐 CRUD-права на каждый ресурс * 🔄 SSO User Provisioning — роли из вашего IdP **Новая нода MCP Client** — подключайся к MCP серверам из любого места workflow, не только в AI Agent! v1.120.0 — Guardrails **3 ноября** • [Документация →](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-langchain.guardrails/) AI SafetyNEW NODE **Защита AI от всего плохого:** | Угроза | Защита | | ---------------------- | ------------ | | 🔓 Jailbreak попытки | Блокировка | | 🔞 NSFW контент | Фильтрация | | 👤 Персональные данные | Маскирование | | 🔑 API ключи в ответах | Обнаружение | **+ MCP на уровне инстанса** — один раз настроил, везде работает! *** ### 🎃 Октябрь 2025 [Заголовок раздела «🎃 Октябрь 2025»](#-октябрь-2025) v1.115.0 — AI Workflow Builder **6 октября** • [Попробовать →](https://docs.n8n.io/advanced-ai/ai-workflow-builder/) GAME CHANGERBeta ## 🪄 Пиши текстом — получай workflows! [Заголовок раздела «🪄 Пиши текстом — получай workflows!»](#-пиши-текстом--получай-workflows) ```plaintext "Каждый день в 9 утра проверяй новые заказы и отправляй их в Slack" ``` ↓ **Через 10 секунд** ↓ ```plaintext ✅ Schedule Trigger → настроен на 9:00 ✅ Google Sheets → подключён к таблице ✅ IF → фильтрует новые заказы ✅ Slack → отправляет сообщение ``` **Кредиты на генерацию:** * Trial: 20 кредитов * Starter: 50/месяц * Pro: 150/месяц Совет AI понимает все 543 ноды n8n, но может не знать особенности сторонних API. Всегда проверяй настройки! *** ### 🌻 Сентябрь 2025 [Заголовок раздела «🌻 Сентябрь 2025»](#-сентябрь-2025) v1.112.0 — Python Task Runner **24 сентября** PythonNative **Прощай, Pyodide! Привет, настоящий Python!** ```python # Теперь можно так: import pandas as pd import requests import numpy as np # Всё работает в изолированном sandbox df = pd.DataFrame(items) ``` v1.110.0 — Data Tables [Документация →](https://docs.n8n.io/data/data-tables/) Built-in DB100x Faster **Своя база данных прямо в n8n!** | Параметр | Значение | | ------------------ | ----------------------------------------- | | ⚡ Скорость вставки | **8ms** (vs секунды в Google Sheets) | | 💾 Лимит | 50 MB (Cloud), настраиваемо (Self-hosted) | | 📋 Типы данных | Numbers, Strings, Dates | **Идеально для:** * 📇 Своя CRM * 🤖 Контекст для AI * ⚙️ Конфиги workflows *** ### ☀️ Август 2025 [Заголовок раздела «☀️ Август 2025»](#️-август-2025) v1.107.0 — Workflow Diff **18 августа** DevOpsEnterprise **Видишь изменения перед деплоем:** ```diff 🟢 Добавлена нода "Slack Notification" ~ 🟠 Изменены настройки "HTTP Request" 🔴 Удалена нода "Debug Log" ``` Клик на ноду → JSON diff → точно знаешь что изменилось! v1.104.0 — Безлимитные workflows **4 августа** • [Подробнее →](https://blog.n8n.io/build-without-limits-everything-you-need-to-know-about-n8ns-new-pricing/) Pricing Revolution ## 🎉 Больше никаких лимитов на workflows! [Заголовок раздела «🎉 Больше никаких лимитов на workflows!»](#-больше-никаких-лимитов-на-workflows) **Было:** Платишь за количество workflows **Стало:** Платишь за executions (реальное использование) **Новый Self-hosted Business план:** * ✅ SSO, SAML, LDAP * ✅ Git version control * ✅ Разные environments * ✅ 6 shared projects *** ### 🌴 Июль 2025 [Заголовок раздела «🌴 Июль 2025»](#-июль-2025) v1.100.0 — Chat Streaming **14 июля** Real-timeUX **AI отвечает по словам, а не целым блоком!** Как в ChatGPT — видишь ответ по мере генерации. Быстрее, приятнее, современнее. v1.101.0 — Respond to Chat **28 июля** Human-in-the-Loop **Многошаговые разговоры в одном execution:** ```plaintext Бот: Как вас зовут? → Пользователь: Алексей Бот: Какой у вас вопрос? → Пользователь: Про доставку Бот: Создаю тикет... ``` Идеально для форм, опросов, согласований! *** ## 💬 Что говорят пользователи [Заголовок раздела «💬 Что говорят пользователи»](#-что-говорят-пользователи) 👍 Нравится **«Швейцарский нож автоматизации»** Гибкость: визуальный редактор ИЛИ код — выбирай что удобнее. **«AI Builder — магия для новичков»** За секунды генерирует рабочие workflows. Экономит часы на изучение нод. **«Data Tables в 100 раз быстрее Sheets»** 8ms vs секунды. Разница огромная для больших объёмов. 👎 Критикуют **«Сложнее чем Zapier»** Мощь требует времени на изучение. Не для совсем новичков. **«Лучшие фичи за paywall»** SSO, папки, кастомные роли — только в платных планах. **«AI Builder не знает все API»** Структуру делает отлично, но детали нод часто надо править руками. *** ## 📊 Год в цифрах [Заголовок раздела «📊 Год в цифрах»](#-год-в-цифрах) 100+ Релизов за год 543 Нод в библиотеке 400+ Интеграций 70+ AI/LLM нод *** ## 🔮 Что дальше? [Заголовок раздела «🔮 Что дальше?»](#-что-дальше) Январь 2026 **Autosave** — больше никаких потерянных изменений 2026 год **1-2 мажорных релиза** — ускоренный цикл разработки *** ## 🔗 Полезные ссылки [Заголовок раздела «🔗 Полезные ссылки»](#-полезные-ссылки) [📦 GitHub Releases ](https://github.com/n8n-io/n8n/releases)Все релизы n8n [📋 Release Notes ](https://docs.n8n.io/release-notes/)Официальные заметки [💬 Community ](https://community.n8n.io/)Форум сообщества [📝 Blog ](https://blog.n8n.io/)Новости и туториалы *** ### 🎉 2025 был невероятным годом для n8n! [Заголовок раздела «🎉 2025 был невероятным годом для n8n!»](#-2025-был-невероятным-годом-для-n8n) **От текста к workflow за секунды • Безопасность по умолчанию • AI везде** # Решение проблем > Диагностика и исправление распространённых ошибок в n8n ## Проблемы запуска [Заголовок раздела «Проблемы запуска»](#проблемы-запуска) ### n8n не запускается [Заголовок раздела «n8n не запускается»](#n8n-не-запускается) 1. **Проверьте логи:** ```bash # Docker docker logs n8n # npm n8n start --tunnel 2>&1 | tee n8n.log ``` 2. **Проверьте порт:** ```bash # Занят ли порт 5678? lsof -i :5678 # или netstat -tlnp | grep 5678 ``` 3. **Проверьте права доступа:** ```bash ls -la ~/.n8n/ # Должны быть права на чтение/запись ``` 4. **Проверьте переменные окружения:** ```bash env | grep N8N ``` **Частые причины:** * Порт 5678 уже занят * Нет прав на директорию `~/.n8n/` * Несовместимая версия Node.js (нужна 18.17+) * Повреждённая база данных ### Ошибка “Database is locked” (SQLite) [Заголовок раздела «Ошибка “Database is locked” (SQLite)»](#ошибка-database-is-locked-sqlite) ```bash # Остановите все процессы n8n pkill -f n8n # Удалите lock файл rm ~/.n8n/database.sqlite-journal # Перезапустите n8n start ``` Совет Для production используйте PostgreSQL вместо SQLite — он не имеет проблем с блокировками. ### Ошибка “ENOSPC: no space left on device” [Заголовок раздела «Ошибка “ENOSPC: no space left on device”»](#ошибка-enospc-no-space-left-on-device) ```bash # Проверьте место на диске df -h # Очистите старые executions n8n execute --cleanup # Или через API curl -X POST http://localhost:5678/rest/executions/delete \ -H "X-N8N-API-KEY: your-api-key" \ -d '{"deleteBefore": "2024-01-01"}' ``` *** ## Проблемы с Workflows [Заголовок раздела «Проблемы с Workflows»](#проблемы-с-workflows) ### Workflow не запускается по расписанию [Заголовок раздела «Workflow не запускается по расписанию»](#workflow-не-запускается-по-расписанию) 1. **Проверьте активацию:** * Workflow должен быть активирован (зелёный переключатель) * В заголовке должно быть “Active” 2. **Проверьте timezone:** ```bash # В docker-compose.yml: environment: - GENERIC_TIMEZONE=Europe/Moscow - TZ=Europe/Moscow ``` 3. **Проверьте cron выражение:** * `0 9 * * *` — каждый день в 9:00 * `*/5 * * * *` — каждые 5 минут * Используйте [crontab.guru](https://crontab.guru) для проверки 4. **Проверьте логи:** ```bash docker logs n8n 2>&1 | grep -i schedule ``` ### Webhook не работает [Заголовок раздела «Webhook не работает»](#webhook-не-работает) **Симптомы:** 404 или timeout при обращении к webhook * Проверка URL ```bash # Правильный формат URL: # Production: https://n8n.example.com/webhook/abc123 # Test: https://n8n.example.com/webhook-test/abc123 # Проверьте доступность: curl -v https://n8n.example.com/webhook/abc123 ``` * Настройки ```bash # docker-compose.yml environment: - WEBHOOK_URL=https://n8n.example.com/ - N8N_HOST=n8n.example.com - N8N_PROTOCOL=https ``` **Чек-лист:** * [ ] Workflow активирован * [ ] URL содержит правильный webhook ID * [ ] Firewall разрешает входящие соединения * [ ] Настроен reverse proxy (nginx/Caddy) * [ ] SSL сертификат валиден ### Ошибка “The execution was stopped at node X” [Заголовок раздела «Ошибка “The execution was stopped at node X”»](#ошибка-the-execution-was-stopped-at-node-x) **Причины:** 1. **Timeout** — нода работала слишком долго 2. **Ошибка в данных** — неправильный формат input 3. **Лимит памяти** — слишком большой payload **Решения:** ```javascript // Увеличьте timeout (в переменных окружения) EXECUTIONS_TIMEOUT=3600 // 1 час EXECUTIONS_TIMEOUT_MAX=7200 // 2 часа // Или в ноде HTTP Request: // Settings → Timeout → увеличьте значение ``` *** ## Проблемы с AI и LangChain [Заголовок раздела «Проблемы с AI и LangChain»](#проблемы-с-ai-и-langchain) ### Ошибка “Rate limit exceeded” (OpenAI/Anthropic) [Заголовок раздела «Ошибка “Rate limit exceeded” (OpenAI/Anthropic)»](#ошибка-rate-limit-exceeded-openaianthropic) ```javascript // Добавьте задержку между запросами: // В Code ноде перед AI: await new Promise(r => setTimeout(r, 1000)); // 1 секунда // Или используйте Split In Batches с задержкой ``` **Рекомендации:** * Увеличьте лимиты в dashboard провайдера * Используйте кэширование ответов * Разбивайте большие запросы на части ### AI Agent не использует tools [Заголовок раздела «AI Agent не использует tools»](#ai-agent-не-использует-tools) **Проверьте:** 1. **Tools подключены к Agent:** * Линия от Tool ноды должна идти к входу “Tool” Agent’а 2. **Описание tool понятно LLM:** ```javascript // Хорошо: "Search for products in the database by name or category" // Плохо: "Search" ``` 3. **Input schema корректна:** ```json { "type": "object", "properties": { "query": { "type": "string", "description": "Search query" } }, "required": ["query"] } ``` ### Ошибка “Context length exceeded” [Заголовок раздела «Ошибка “Context length exceeded”»](#ошибка-context-length-exceeded) ```javascript // Уменьшите размер входных данных: // 1. Используйте Text Splitter для длинных документов // 2. Summarization Chain для сжатия текста // 3. Ограничьте историю чата: // В Memory ноде: // Window Memory → k = 10 // только последние 10 сообщений ``` ### MCP сервер не подключается [Заголовок раздела «MCP сервер не подключается»](#mcp-сервер-не-подключается) 1. **Проверьте доступность сервера:** ```bash # Локальный сервер curl http://localhost:3000/health # Или проверьте процесс ps aux | grep mcp ``` 2. **Проверьте аутентификацию:** * API Key должен быть в Credentials * Для OAuth — проверьте token expiration 3. **Проверьте транспорт:** ```bash # stdio для локальных серверов: npx @anthropic/mcp-server-github # HTTP для удалённых: # URL должен быть доступен ``` 4. **Посмотрите логи MCP сервера:** ```bash # Запустите с debug DEBUG=* npx @anthropic/mcp-server-github 2>&1 ``` *** ## Проблемы с данными [Заголовок раздела «Проблемы с данными»](#проблемы-с-данными) ### Ошибка “Cannot read property ‘X’ of undefined” [Заголовок раздела «Ошибка “Cannot read property ‘X’ of undefined”»](#ошибка-cannot-read-property-x-of-undefined) ```javascript // Данные не существуют на предыдущей ноде // Решение 1: Проверка существования if ($json.data?.property) { return $json.data.property; } // Решение 2: Значение по умолчанию const value = $json.data?.property ?? "default"; // Решение 3: Optional chaining в выражениях {{ $json.data?.items?.[0]?.name ?? "No name" }} ``` ### Данные теряются между нодами [Заголовок раздела «Данные теряются между нодами»](#данные-теряются-между-нодами) **Причины:** 1. Нода не передаёт данные (empty output) 2. Неправильное соединение нод 3. Фильтр отсеивает все данные **Диагностика:** * Кликните на каждую ноду и проверьте Input/Output * Проверьте количество items: `{{ $items.length }}` ### Большой JSON вызывает ошибку [Заголовок раздела «Большой JSON вызывает ошибку»](#большой-json-вызывает-ошибку) ```javascript // Увеличьте лимит payload // В переменных окружения: N8N_PAYLOAD_SIZE_MAX=64 // MB // Или обрабатывайте данные частями: // Split In Batches → Batch Size: 100 ``` *** ## Проблемы с базой данных [Заголовок раздела «Проблемы с базой данных»](#проблемы-с-базой-данных) ### Не подключается к PostgreSQL [Заголовок раздела «Не подключается к PostgreSQL»](#не-подключается-к-postgresql) ```bash # Проверьте строку подключения: DATABASE_URL=postgres://user:password@host:5432/n8n # Проверьте доступность: psql -h host -U user -d n8n -c "SELECT 1" # Проверьте firewall: telnet host 5432 ``` **Частые ошибки:** * `ECONNREFUSED` — PostgreSQL не запущен или неправильный host * `authentication failed` — неверный пароль * `database "n8n" does not exist` — создайте базу данных ### Миграция с SQLite на PostgreSQL [Заголовок раздела «Миграция с SQLite на PostgreSQL»](#миграция-с-sqlite-на-postgresql) ```bash # 1. Экспортируйте workflows n8n export:workflow --all --output=workflows.json # 2. Экспортируйте credentials n8n export:credentials --all --output=credentials.json # 3. Настройте PostgreSQL export DATABASE_TYPE=postgresdb export DATABASE_URL=postgres://user:pass@host:5432/n8n # 4. Запустите n8n (создаст схему) n8n start # 5. Импортируйте данные n8n import:workflow --input=workflows.json n8n import:credentials --input=credentials.json ``` *** ## Проблемы производительности [Заголовок раздела «Проблемы производительности»](#проблемы-производительности) ### Высокое потребление памяти [Заголовок раздела «Высокое потребление памяти»](#высокое-потребление-памяти) ```bash # Проверьте использование памяти docker stats n8n # Ограничьте память в docker-compose.yml: services: n8n: deploy: resources: limits: memory: 2G ``` **Оптимизации:** * Включите Queue Mode для распределения нагрузки * Уменьшите `EXECUTIONS_DATA_SAVE_MANUAL_EXECUTIONS` * Очищайте старые executions ### Медленные executions [Заголовок раздела «Медленные executions»](#медленные-executions) ```bash # Включите профилирование N8N_LOG_LEVEL=debug # Проверьте узкие места: # 1. HTTP запросы — добавьте timeout # 2. Большие данные — используйте batching # 3. Последовательные запросы — параллелизуйте ``` *** ## Docker проблемы [Заголовок раздела «Docker проблемы»](#docker-проблемы) ### Container перезапускается [Заголовок раздела «Container перезапускается»](#container-перезапускается) ```bash # Проверьте логи docker logs n8n --tail 100 # Частые причины: # - OOM (Out of Memory) # - Ошибка подключения к БД # - Неправильные переменные окружения ``` ### Volumes не сохраняются [Заголовок раздела «Volumes не сохраняются»](#volumes-не-сохраняются) ```yaml # docker-compose.yml — правильная настройка: volumes: - n8n_data:/home/node/.n8n volumes: n8n_data: driver: local ``` Осторожно Не используйте bind mounts с неправильными правами. Данные n8n должны принадлежать пользователю с UID 1000. *** ## Логирование и отладка [Заголовок раздела «Логирование и отладка»](#логирование-и-отладка) ### Включение подробных логов [Заголовок раздела «Включение подробных логов»](#включение-подробных-логов) ```bash # Переменные окружения: N8N_LOG_LEVEL=debug # debug, info, warn, error N8N_LOG_OUTPUT=console,file N8N_LOG_FILE_LOCATION=/logs/n8n.log # Для Docker: docker logs -f n8n 2>&1 | tee n8n-debug.log ``` ### Отладка в Code ноде [Заголовок раздела «Отладка в Code ноде»](#отладка-в-code-ноде) ```javascript // Логирование console.log('Debug:', JSON.stringify($json, null, 2)); // Проверка типов console.log('Type:', typeof $json.value); // Вывод всех доступных данных console.log('Items:', $items.length); console.log('Node:', $node.name); console.log('Execution:', $execution.id); ``` *** ## Получение помощи [Заголовок раздела «Получение помощи»](#получение-помощи) Если проблема не решена: 1. **Соберите информацию:** * Версия n8n: `n8n --version` * Логи с ошибкой * Скриншот workflow (без credentials!) * Шаги воспроизведения 2. **Проверьте известные issues:** * [GitHub Issues](https://github.com/n8n-io/n8n/issues) 3. **Задайте вопрос:** * [Community Forum](https://community.n8n.io/) * [Discord](https://discord.gg/n8n) # Интерфейс редактора > Обзор интерфейса n8n — canvas, панели, навигация и настройки ## Обзор интерфейса [Заголовок раздела «Обзор интерфейса»](#обзор-интерфейса) Редактор n8n состоит из нескольких ключевых областей: ```plaintext ┌─────────────────────────────────────────────────────────────┐ │ [Logo] Workflows ▼ │ Workflow Name │ [Test] [Save] │ ├─────────────────────────────────────────────────────────────┤ │ │ │ │ Left │ Canvas │ │ Panel │ (область workflow) │ │ │ │ │ │ │ ├─────────┴───────────────────────────────────────────────────┤ │ Execution Panel │ └─────────────────────────────────────────────────────────────┘ ``` ## Canvas (Холст) [Заголовок раздела «Canvas (Холст)»](#canvas-холст) Основная рабочая область для построения workflow. ### Навигация [Заголовок раздела «Навигация»](#навигация) | Действие | Способ | | ----------------- | ------------------------------ | | Перемещение | Зажать пробел + перетаскивание | | Масштаб | Колесо мыши или Ctrl +/- | | Центрировать | Двойной клик на пустом месте | | Выделение области | Shift + перетаскивание | ### Работа с нодами [Заголовок раздела «Работа с нодами»](#работа-с-нодами) | Действие | Способ | | ------------- | -------------------- | | Добавить ноду | Кнопка + или Tab | | Переместить | Перетаскивание | | Копировать | Ctrl + C | | Вставить | Ctrl + V | | Дублировать | Ctrl + D | | Удалить | Delete или Backspace | ## Панель нод [Заголовок раздела «Панель нод»](#панель-нод) Открывается по кнопке **+** или клавише **Tab**. ### Категории нод [Заголовок раздела «Категории нод»](#категории-нод) | Категория | Описание | | ------------ | -------------------------------------------- | | **Triggers** | Запускают workflow (Webhook, Schedule, etc.) | | **Core** | Базовые операции (HTTP, Code, Set, IF) | | **Actions** | Интеграции (Google, Slack, GitHub) | | **AI** | Ноды для AI (Agent, LLM, Memory) | ### Поиск нод [Заголовок раздела «Поиск нод»](#поиск-нод) Начните вводить название ноды в поле поиска: * `http` → HTTP Request * `if` → IF (условие) * `slack` → Slack * `agent` → AI Agent ## Панель настроек ноды [Заголовок раздела «Панель настроек ноды»](#панель-настроек-ноды) Появляется при клике на ноду. ### Вкладки [Заголовок раздела «Вкладки»](#вкладки) | Вкладка | Описание | | -------------- | ------------------------ | | **Parameters** | Основные настройки ноды | | **Settings** | Дополнительные параметры | | **Input** | Входящие данные | | **Output** | Исходящие данные | ### Режимы ввода [Заголовок раздела «Режимы ввода»](#режимы-ввода) * **Fixed** — статическое значение * **Expression** — динамическое выражение (например, `{{ $json.name }}`) Совет Для переключения в режим Expression нажмите на иконку fx справа от поля. ## Панель выполнения [Заголовок раздела «Панель выполнения»](#панель-выполнения) Показывает результаты запуска workflow. ### Состояния выполнения [Заголовок раздела «Состояния выполнения»](#состояния-выполнения) | Иконка | Состояние | | ------ | -------------- | | 🟢 | Успешно | | 🔴 | Ошибка | | 🟡 | Выполняется | | ⚪ | Не выполнялось | ### Просмотр данных [Заголовок раздела «Просмотр данных»](#просмотр-данных) После выполнения кликните на ноду, чтобы увидеть: * **Input** — данные на входе * **Output** — данные на выходе * **Schema** — структура данных ## Левая панель [Заголовок раздела «Левая панель»](#левая-панель) ### Меню [Заголовок раздела «Меню»](#меню) | Пункт | Описание | | --------------- | ----------------------------- | | **Workflows** | Список всех workflow | | **Templates** | Готовые шаблоны | | **Credentials** | Учётные данные для интеграций | | **Variables** | Глобальные переменные | | **Executions** | История выполнений | ## Верхняя панель [Заголовок раздела «Верхняя панель»](#верхняя-панель) ### Элементы управления [Заголовок раздела «Элементы управления»](#элементы-управления) | Элемент | Описание | | ----------------- | -------------------------------------- | | **Workflow name** | Название (кликните для редактирования) | | **Test workflow** | Запустить весь workflow | | **Save** | Сохранить изменения | | **Share** | Поделиться workflow | | **…** | Дополнительные действия | ## Горячие клавиши [Заголовок раздела «Горячие клавиши»](#горячие-клавиши) ### Общие [Заголовок раздела «Общие»](#общие) | Клавиша | Действие | | ------------------ | ------------------ | | `Ctrl + S` | Сохранить workflow | | `Ctrl + Enter` | Запустить workflow | | `Ctrl + Z` | Отменить | | `Ctrl + Shift + Z` | Повторить | | `Tab` | Открыть панель нод | | `Esc` | Закрыть панели | ### Ноды [Заголовок раздела «Ноды»](#ноды) | Клавиша | Действие | | ---------- | ----------------- | | `Ctrl + A` | Выделить все ноды | | `Ctrl + C` | Копировать | | `Ctrl + V` | Вставить | | `Ctrl + D` | Дублировать | | `Delete` | Удалить | | `F2` | Переименовать | ### Навигация [Заголовок раздела «Навигация»](#навигация-1) | Клавиша | Действие | | -------------- | --------------------- | | `Ctrl + +` | Увеличить масштаб | | `Ctrl + -` | Уменьшить масштаб | | `Ctrl + 0` | Сбросить масштаб | | `Space + Drag` | Перемещение по canvas | ## Настройки workflow [Заголовок раздела «Настройки workflow»](#настройки-workflow) Откройте через **…** → **Settings**: | Настройка | Описание | | --------------------------- | ---------------------------------- | | **Error Workflow** | Workflow для обработки ошибок | | **Timezone** | Часовой пояс | | **Save Execution Progress** | Сохранять промежуточные результаты | | **Timeout** | Максимальное время выполнения | ## Следующие шаги [Заголовок раздела «Следующие шаги»](#следующие-шаги) * [Создание workflows](/workflows/create/) — подробное руководство * [Компоненты workflow](/workflows/components/) — ноды и соединения * [Выполнение](/workflows/executions/) — режимы запуска # Путь обучения > Рекомендуемый порядок изучения n8n — от новичка до эксперта ## Уровень 1: Основы [Заголовок раздела «Уровень 1: Основы»](#уровень-1-основы) 1. **Установка и запуск** * [Быстрый старт](/start/quickstart/) — установка через Docker * [Интерфейс редактора](/start/interface/) — навигация и горячие клавиши 2. **Первый workflow** * [Создание workflow](/workflows/create/) — добавление нод * [Компоненты](/workflows/components/) — триггеры, ноды, соединения 3. **Базовые ноды** * Manual Trigger — ручной запуск * HTTP Request — запросы к API * Set — создание данных **Результат:** Вы можете создавать простые workflow для получения данных из API. ## Уровень 2: Продвинутые концепции [Заголовок раздела «Уровень 2: Продвинутые концепции»](#уровень-2-продвинутые-концепции) 1. **Логика потоков** * [Условия (IF/Switch)](/concepts/flow-logic/) — ветвление логики * [Циклы](/concepts/looping/) — обработка массивов * [Слияние данных](/concepts/merging/) — объединение потоков 2. **Работа с данными** * [Структура данных](/concepts/data-structure/) — формат n8n * [Трансформация](/concepts/transforming/) — преобразование данных * [Expressions](/code/expressions/) — динамические значения 3. **Интеграции** * Credentials — настройка доступов * Webhook — внешние вызовы * Schedule Trigger — запуск по расписанию **Результат:** Вы можете создавать сложные автоматизации с условиями и обработкой данных. ## Уровень 3: AI и автоматизация [Заголовок раздела «Уровень 3: AI и автоматизация»](#уровень-3-ai-и-автоматизация) 1. **AI Agent** * [Обзор AI](/ai-mcp/overview/) — возможности AI в n8n * [AI Agent](/ai-mcp/ai-agent/) — создание агентов * [LangChain](/ai-mcp/langchain/) — цепочки обработки 2. **RAG и векторы** * [RAG workflows](/ai-mcp/rag/) — работа с документами * Vector stores — хранение embeddings 3. **MCP интеграция** * [Model Context Protocol](/ai-mcp/mcp/) — подключение серверов * [MCP серверы](/ai-mcp/mcp-servers/) — каталог серверов **Результат:** Вы можете создавать AI-powered автоматизации с агентами и RAG. ## Уровень 4: Production [Заголовок раздела «Уровень 4: Production»](#уровень-4-production) 1. **Хостинг** * [Docker](/hosting/docker/) — контейнеризация * [Переменные окружения](/hosting/environment-variables/) — конфигурация * [Масштабирование](/hosting/scaling/) — queue mode 2. **Безопасность** * [SSL](/hosting/security/) — настройка HTTPS * Credentials — безопасное хранение * RBAC — управление доступом 3. **Мониторинг** * Логирование * Обработка ошибок * Алерты **Результат:** Вы можете развернуть n8n в production с мониторингом и безопасностью. ## Рекомендуемые проекты [Заголовок раздела «Рекомендуемые проекты»](#рекомендуемые-проекты) ### Для начинающих [Заголовок раздела «Для начинающих»](#для-начинающих) RSS → Telegram Отправка новостей из RSS в Telegram канал Form → Google Sheets Сбор данных из форм в таблицу ### Средний уровень [Заголовок раздела «Средний уровень»](#средний-уровень) CRM Sync Синхронизация данных между CRM системами E-commerce Автоматизация заказов и уведомлений ### Продвинутый уровень [Заголовок раздела «Продвинутый уровень»](#продвинутый-уровень) AI Support Bot Чат-бот с RAG и историей Data Pipeline ETL процессы с трансформацией ## Ресурсы для обучения [Заголовок раздела «Ресурсы для обучения»](#ресурсы-для-обучения) ### Официальные [Заголовок раздела «Официальные»](#официальные) | Ресурс | Описание | | -------------------------------------------- | ------------------------ | | [docs.n8n.io](https://docs.n8n.io) | Официальная документация | | [community.n8n.io](https://community.n8n.io) | Форум сообщества | | [n8n.io/workflows](https://n8n.io/workflows) | Библиотека шаблонов | ### Видео [Заголовок раздела «Видео»](#видео) | Канал | Тематика | | ---------------- | ---------------------- | | n8n YouTube | Официальные туториалы | | Community videos | Кейсы от пользователей | ## Чеклист навыков [Заголовок раздела «Чеклист навыков»](#чеклист-навыков) ### Основы [Заголовок раздела «Основы»](#основы) * [ ] Установка и запуск n8n * [ ] Создание workflow с Manual Trigger * [ ] Использование HTTP Request * [ ] Работа с Set и данными ### Средний уровень [Заголовок раздела «Средний уровень»](#средний-уровень-1) * [ ] Условия (IF) и ветвление * [ ] Циклы и обработка массивов * [ ] Webhook и внешние вызовы * [ ] Expressions и Code node ### Продвинутый [Заголовок раздела «Продвинутый»](#продвинутый) * [ ] AI Agent и LangChain * [ ] RAG с Vector stores * [ ] MCP интеграция * [ ] Production deployment ## Следующие шаги [Заголовок раздела «Следующие шаги»](#следующие-шаги) Начните с [Быстрого старта](/start/quickstart/) и следуйте рекомендованному пути обучения. # Быстрый старт > Установите n8n и создайте первый workflow за 5 минут ## Способы запуска n8n [Заголовок раздела «Способы запуска n8n»](#способы-запуска-n8n) Docker Рекомендуемый способ — изолированная среда, простое обновление npm Для разработчиков — глобальная установка через Node.js n8n Cloud Облачная версия — без настройки инфраструктуры ## Установка через Docker [Заголовок раздела «Установка через Docker»](#установка-через-docker) 1. **Установите Docker** Скачайте [Docker Desktop](https://www.docker.com/products/docker-desktop/) для вашей ОС. 2. **Запустите n8n** ```bash docker run -it --rm \ --name n8n \ -p 5678:5678 \ -v n8n_data:/home/node/.n8n \ n8nio/n8n ``` 3. **Откройте интерфейс** Перейдите на 4. **Создайте аккаунт** Укажите email и пароль для первого пользователя. Совет Флаг `-v n8n_data:/home/node/.n8n` сохраняет данные между перезапусками контейнера. ## Установка через npm [Заголовок раздела «Установка через npm»](#установка-через-npm) ```bash # Установка глобально npm install n8n -g # Запуск n8n start ``` Осторожно Требуется Node.js версии 18.17 или выше. ## Создание первого workflow [Заголовок раздела «Создание первого workflow»](#создание-первого-workflow) 1. **Нажмите “Add workflow”** В левом меню выберите “Workflows” → “Add workflow” 2. **Добавьте триггер** Нажмите ”+” и выберите **Manual Trigger** — для ручного запуска 3. **Добавьте действие** Нажмите ”+” справа от триггера и выберите ноду: * **HTTP Request** — для API запросов * **Set** — для создания данных * **Code** — для JavaScript/Python кода 4. **Настройте ноду** Кликните на ноду и заполните параметры 5. **Запустите workflow** Нажмите кнопку “Test workflow” или Ctrl+Enter ## Пример: Получение данных из API [Заголовок раздела «Пример: Получение данных из API»](#пример-получение-данных-из-api) ### Настройка HTTP Request [Заголовок раздела «Настройка HTTP Request»](#настройка-http-request) | Параметр | Значение | | -------------- | ------------------------------------- | | Method | GET | | URL | `https://api.github.com/users/n8n-io` | | Authentication | None | ### Результат [Заголовок раздела «Результат»](#результат) ```json { "login": "n8n-io", "name": "n8n - Workflow Automation", "public_repos": 42, "followers": 10000 } ``` ## Интерфейс редактора [Заголовок раздела «Интерфейс редактора»](#интерфейс-редактора) ### Основные элементы [Заголовок раздела «Основные элементы»](#основные-элементы) | Элемент | Описание | | ------------------- | -------------------------------- | | **Canvas** | Область для построения workflow | | **Node panel** | Панель добавления нод (кнопка +) | | **Sidebar** | Настройки выбранной ноды | | **Execution panel** | Результаты выполнения | ### Горячие клавиши [Заголовок раздела «Горячие клавиши»](#горячие-клавиши) | Клавиша | Действие | | -------------- | ------------------ | | `Ctrl + Enter` | Запустить workflow | | `Ctrl + S` | Сохранить | | `Tab` | Открыть панель нод | | `Ctrl + A` | Выделить все ноды | | `Delete` | Удалить выбранное | ## Docker Compose (продакшен) [Заголовок раздела «Docker Compose (продакшен)»](#docker-compose-продакшен) Для production используйте PostgreSQL вместо SQLite: docker-compose.yml ```yaml version: '3.8' services: n8n: image: n8nio/n8n restart: always ports: - "5678:5678" environment: - DB_TYPE=postgresdb - DB_POSTGRESDB_HOST=postgres - DB_POSTGRESDB_DATABASE=n8n - DB_POSTGRESDB_USER=n8n - DB_POSTGRESDB_PASSWORD=n8n - N8N_BASIC_AUTH_ACTIVE=true - N8N_BASIC_AUTH_USER=admin - N8N_BASIC_AUTH_PASSWORD=admin volumes: - n8n_data:/home/node/.n8n depends_on: - postgres postgres: image: postgres:15 restart: always environment: - POSTGRES_USER=n8n - POSTGRES_PASSWORD=n8n - POSTGRES_DB=n8n volumes: - postgres_data:/var/lib/postgresql/data volumes: n8n_data: postgres_data: ``` Запуск: ```bash docker-compose up -d ``` VPS для AI:[🇳🇱Нидерланды](/vps_vds_netherlands)|[🇰🇿Казахстан](/vps-vds-kazakhstan) ## Следующие шаги [Заголовок раздела «Следующие шаги»](#следующие-шаги) * [Понимание workflows](/workflows/overview/) — компоненты и структура * [Логика потоков](/concepts/flow-logic/) — условия, циклы, ветвления * [AI Agent](/ai-mcp/ai-agent/) — создание AI агентов * [Переменные окружения](/hosting/environment-variables/) — настройка n8n # Компоненты Workflow > Детальное описание всех компонентов workflow — ноды, соединения, триггеры ## Структура Workflow [Заголовок раздела «Структура Workflow»](#структура-workflow) Каждый workflow состоит из: ## Триггеры [Заголовок раздела «Триггеры»](#триггеры) Триггеры запускают выполнение workflow. Без триггера workflow не может работать автоматически. ### Manual Trigger [Заголовок раздела «Manual Trigger»](#manual-trigger) Простейший триггер для ручного запуска. ```plaintext Использование: Тестирование, разовые задачи Параметры: Нет ``` ### Schedule Trigger [Заголовок раздела «Schedule Trigger»](#schedule-trigger) Запуск по расписанию (cron). | Параметр | Описание | | --------------------- | --------------------------------- | | **Trigger Interval** | Минуты, часы, дни, недели, месяцы | | **Trigger at Hour** | Час запуска | | **Trigger at Minute** | Минута запуска | Примеры cron: ```plaintext */15 * * * * — каждые 15 минут 0 9 * * 1-5 — в 9:00 по будням 0 0 1 * * — первого числа каждого месяца ``` ### Webhook [Заголовок раздела «Webhook»](#webhook) Запуск по HTTP-запросу. | Параметр | Описание | | ------------------ | ------------------------------------- | | **HTTP Method** | GET, POST, PUT, DELETE, etc. | | **Path** | URL path (например, `/my-webhook`) | | **Authentication** | None, Basic Auth, Header Auth | | **Response Mode** | Immediately, Last Node, Response Node | Совет Webhook URL формируется как: `https://your-n8n.com/webhook/path` ### App Triggers [Заголовок раздела «App Triggers»](#app-triggers) Триггеры интегрированных сервисов: | Сервис | Триггеры | | ---------- | ------------------------- | | **Gmail** | New Email | | **Slack** | New Message, Mention | | **GitHub** | Push, Pull Request, Issue | | **Stripe** | Payment, Subscription | ## Ноды [Заголовок раздела «Ноды»](#ноды) ### Core Nodes [Заголовок раздела «Core Nodes»](#core-nodes) HTTP Request Запросы к любым API Code JavaScript или Python код Set Создание и изменение данных Function JavaScript функции (legacy) ### HTTP Request [Заголовок раздела «HTTP Request»](#http-request) Универсальная нода для API-запросов. | Параметр | Описание | | -------------------- | -------------------------------------------- | | **Method** | GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS | | **URL** | Адрес API endpoint | | **Authentication** | Тип авторизации | | **Headers** | HTTP заголовки | | **Query Parameters** | URL параметры | | **Body** | Тело запроса (для POST/PUT/PATCH) | ### Code [Заголовок раздела «Code»](#code) Выполнение произвольного кода. ```javascript // JavaScript пример const items = $input.all(); return items.map(item => ({ json: { ...item.json, processed: true, timestamp: new Date().toISOString() } })); ``` ```python # Python пример items = _input.all() for item in items: item['json']['processed'] = True return items ``` ### Set [Заголовок раздела «Set»](#set) Создание и модификация данных. | Режим | Описание | | ------------------------------ | ------------------------------ | | **Manual Mapping** | Указание полей вручную | | **JSON** | Ввод JSON напрямую | | **Keep Only Set** | Оставить только указанные поля | | **Include Other Input Fields** | Добавить к существующим | ### Логические ноды [Заголовок раздела «Логические ноды»](#логические-ноды) #### IF [Заголовок раздела «IF»](#if) Условное ветвление (true/false). ```javascript // Условие {{ $json.status }} равно "active" ``` #### Switch [Заголовок раздела «Switch»](#switch) Множественное ветвление. ```javascript // Routing rules {{ $json.type }} === "email" → Output 1 {{ $json.type }} === "sms" → Output 2 {{ $json.type }} === "push" → Output 3 Default → Output 4 ``` #### Merge [Заголовок раздела «Merge»](#merge) Объединение нескольких потоков. | Режим | Описание | | ----------------- | ---------------------- | | **Append** | Добавить items в конец | | **Combine** | Объединить по индексу | | **Multiplex** | Все комбинации | | **Choose Branch** | Выбрать один поток | ### Цикловые ноды [Заголовок раздела «Цикловые ноды»](#цикловые-ноды) #### Loop Over Items [Заголовок раздела «Loop Over Items»](#loop-over-items) Итерация по массиву с возможностью паузы. | Параметр | Описание | | -------------- | ---------------------------- | | **Batch Size** | Количество items за итерацию | | **Options** | Reset, Start Index | #### Split In Batches [Заголовок раздела «Split In Batches»](#split-in-batches) Разбиение на пакеты для обработки. ## Соединения [Заголовок раздела «Соединения»](#соединения) ### Основные соединения (Main) [Заголовок раздела «Основные соединения (Main)»](#основные-соединения-main) Передают данные между нодами: ```plaintext Node A (output) ──────► Node B (input) ``` ### Error соединения [Заголовок раздела «Error соединения»](#error-соединения) Обрабатывают ошибки: ```plaintext Node A (error) ──────► Error Handler ``` Осторожно Error соединения доступны только при включённом **Continue on Fail** в настройках ноды. ### AI соединения [Заголовок раздела «AI соединения»](#ai-соединения) Специальные соединения для AI нод: | Тип | Назначение | | --------------------- | ------------------------ | | **ai\_languageModel** | Подключение LLM | | **ai\_memory** | Подключение памяти | | **ai\_tool** | Подключение инструментов | | **ai\_outputParser** | Парсер ответов | ## Credentials [Заголовок раздела «Credentials»](#credentials) Credentials хранят учётные данные для подключения к сервисам. ### Типы авторизации [Заголовок раздела «Типы авторизации»](#типы-авторизации) | Тип | Описание | | --------------- | --------------------- | | **API Key** | Ключ API | | **OAuth2** | OAuth 2.0 авторизация | | **Basic Auth** | Логин/пароль | | **Header Auth** | Токен в заголовке | ### Создание Credential [Заголовок раздела «Создание Credential»](#создание-credential) 1. **Settings** → **Credentials** → **Add Credential** 2. Выберите тип сервиса 3. Введите данные авторизации 4. **Save** ### Использование [Заголовок раздела «Использование»](#использование) В ноде выберите credential из списка: ```plaintext Authentication: Predefined Credential Type Credential: My API Key ``` ### Безопасность [Заголовок раздела «Безопасность»](#безопасность) * Credentials шифруются в базе данных * Доступ можно ограничить по пользователям * Используйте переменные окружения для production ## Переменные [Заголовок раздела «Переменные»](#переменные) ### Глобальные переменные [Заголовок раздела «Глобальные переменные»](#глобальные-переменные) Настраиваются в **Settings** → **Variables**: ```javascript {{ $vars.API_URL }} {{ $vars.MAX_RETRIES }} ``` ### Переменные окружения [Заголовок раздела «Переменные окружения»](#переменные-окружения) Доступны через `$env`: ```javascript {{ $env.MY_API_KEY }} ``` Совет Переменные окружения безопаснее — они не сохраняются в workflow JSON при экспорте. ## Sticky Notes [Заголовок раздела «Sticky Notes»](#sticky-notes) Документируйте workflow с помощью заметок: * **Правый клик** → **Add Sticky Note** * Поддержка Markdown * Цветовое кодирование * Размещение за нодами ## Следующие шаги [Заголовок раздела «Следующие шаги»](#следующие-шаги) * [Выполнение workflow](/workflows/executions/) — запуск и мониторинг * [Логика потоков](/concepts/flow-logic/) — условия и ветвление * [Структура данных](/concepts/data-structure/) — формат данных n8n # Создание Workflow > Пошаговое руководство по созданию workflow в n8n ## Создание нового workflow [Заголовок раздела «Создание нового workflow»](#создание-нового-workflow) 1. **Откройте редактор** В левом меню выберите **Workflows** → **Add workflow** 2. **Назовите workflow** Кликните на “My workflow” в верхней панели и введите описательное название 3. **Добавьте триггер** Нажмите **+** или клавишу **Tab**, выберите триггер для запуска 4. **Добавьте ноды** Кликните на **+** справа от триггера, добавьте нужные ноды 5. **Настройте соединения** Перетащите выход одной ноды на вход другой 6. **Тестируйте** Нажмите **Test workflow** или `Ctrl + Enter` 7. **Сохраните** Нажмите **Save** или `Ctrl + S` ## Добавление нод [Заголовок раздела «Добавление нод»](#добавление-нод) ### Способы добавления [Заголовок раздела «Способы добавления»](#способы-добавления) | Способ | Действие | | -------------- | ------------------------ | | Кнопка + | Клик на + справа от ноды | | Tab | Открытие панели нод | | Перетаскивание | Drag & drop из панели | | Копирование | Ctrl + C / Ctrl + V | ### Поиск нод [Заголовок раздела «Поиск нод»](#поиск-нод) В панели нод начните вводить: * Название ноды: `http`, `slack`, `if` * Категорию: `trigger`, `ai`, `core` * Действие: `send email`, `get users` ## Соединение нод [Заголовок раздела «Соединение нод»](#соединение-нод) ### Типы соединений [Заголовок раздела «Типы соединений»](#типы-соединений) | Тип | Описание | | --------- | --------------------------- | | **Main** | Основной поток данных | | **Error** | Поток при ошибке | | **AI** | Для AI нод (модели, память) | ### Множественные выходы [Заголовок раздела «Множественные выходы»](#множественные-выходы) Некоторые ноды имеют несколько выходов: ## Настройка нод [Заголовок раздела «Настройка нод»](#настройка-нод) ### Панель параметров [Заголовок раздела «Панель параметров»](#панель-параметров) Кликните на ноду, чтобы открыть настройки: | Вкладка | Содержимое | | -------------- | -------------------------------- | | **Parameters** | Основные настройки | | **Settings** | Дополнительные опции | | **Input** | Входящие данные (после запуска) | | **Output** | Исходящие данные (после запуска) | ### Режимы ввода значений [Заголовок раздела «Режимы ввода значений»](#режимы-ввода-значений) * Fixed ```plaintext Статическое значение: https://api.example.com ``` * Expression ```javascript {{ $json.url }} {{ $('Previous Node').item.json.id }} ``` Совет Для переключения в режим Expression нажмите на иконку **fx** справа от поля ввода. ## Пример: API → Обработка → Отправка [Заголовок раздела «Пример: API → Обработка → Отправка»](#пример-api--обработка--отправка) ### Шаг 1: Триггер [Заголовок раздела «Шаг 1: Триггер»](#шаг-1-триггер) Добавьте **Schedule Trigger**: * **Trigger Interval**: Hours * **Hours Between Triggers**: 1 ### Шаг 2: Получение данных [Заголовок раздела «Шаг 2: Получение данных»](#шаг-2-получение-данных) Добавьте **HTTP Request**: | Параметр | Значение | | -------------- | ------------------------------- | | Method | GET | | URL | `https://api.example.com/users` | | Authentication | None (или выберите credential) | ### Шаг 3: Фильтрация [Заголовок раздела «Шаг 3: Фильтрация»](#шаг-3-фильтрация) Добавьте **IF**: * **Condition**: `{{ $json.status }}` равно `active` ### Шаг 4: Отправка [Заголовок раздела «Шаг 4: Отправка»](#шаг-4-отправка) Добавьте **Slack** (для активных пользователей): * **Resource**: Message * **Operation**: Send * **Channel**: `#notifications` * **Text**: `New active user: {{ $json.name }}` ## Работа с данными между нодами [Заголовок раздела «Работа с данными между нодами»](#работа-с-данными-между-нодами) ### Доступ к данным предыдущей ноды [Заголовок раздела «Доступ к данным предыдущей ноды»](#доступ-к-данным-предыдущей-ноды) ```javascript // Текущий item {{ $json.fieldName }} // Все items {{ $input.all() }} // Первый item {{ $input.first() }} ``` ### Доступ к данным конкретной ноды [Заголовок раздела «Доступ к данным конкретной ноды»](#доступ-к-данным-конкретной-ноды) ```javascript // По имени ноды {{ $('HTTP Request').item.json.data }} // Все items из ноды {{ $('HTTP Request').all() }} ``` ### Переменные окружения [Заголовок раздела «Переменные окружения»](#переменные-окружения) ```javascript {{ $env.API_KEY }} ``` ## Организация сложных workflow [Заголовок раздела «Организация сложных workflow»](#организация-сложных-workflow) ### Sticky Notes [Заголовок раздела «Sticky Notes»](#sticky-notes) Добавляйте заметки для документирования: 1. Правый клик на canvas 2. Выберите **Add Sticky Note** 3. Напишите пояснение ### Группировка нод [Заголовок раздела «Группировка нод»](#группировка-нод) Визуально группируйте связанные ноды: 1. Выделите ноды (`Shift + клик`) 2. Добавьте Sticky Note под ними 3. Используйте цвет для разделения ### Sub-workflows [Заголовок раздела «Sub-workflows»](#sub-workflows) Для сложной логики используйте Execute Workflow: ## Отладка [Заголовок раздела «Отладка»](#отладка) ### Просмотр данных [Заголовок раздела «Просмотр данных»](#просмотр-данных) После выполнения кликните на ноду: * **Table** — табличный вид * **JSON** — сырой JSON * **Schema** — структура данных ### Пошаговое выполнение [Заголовок раздела «Пошаговое выполнение»](#пошаговое-выполнение) 1. Кликните на ноду правой кнопкой 2. Выберите **Execute Node** 3. Проверьте результат ### Pinned Data [Заголовок раздела «Pinned Data»](#pinned-data) Фиксируйте тестовые данные: 1. Выполните ноду 2. Кликните **Pin** на данных 3. Данные будут использоваться при следующих тестах Осторожно Pinned data работают только в тестовом режиме. В production используются реальные данные. ## Сохранение и экспорт [Заголовок раздела «Сохранение и экспорт»](#сохранение-и-экспорт) ### Автосохранение [Заголовок раздела «Автосохранение»](#автосохранение) n8n автоматически сохраняет изменения. Для принудительного сохранения: `Ctrl + S` ### Экспорт в JSON [Заголовок раздела «Экспорт в JSON»](#экспорт-в-json) 1. Откройте меню workflow (**…**) 2. Выберите **Download** 3. Сохраните JSON файл ### Импорт [Заголовок раздела «Импорт»](#импорт) 1. **Workflows** → **Add workflow** 2. Меню **…** → **Import from File** 3. Выберите JSON файл ## Следующие шаги [Заголовок раздела «Следующие шаги»](#следующие-шаги) * [Компоненты workflow](/workflows/components/) — детальный разбор * [Выполнение](/workflows/executions/) — режимы запуска * [Логика потоков](/concepts/flow-logic/) — условия и ветвление # Обработка ошибок > Настройка Error Workflows и graceful error handling в n8n При разработке workflow важно предусмотреть обработку ошибок. **Error Workflow** позволяет контролировать реакцию n8n на сбои выполнения. ## Типы ошибок [Заголовок раздела «Типы ошибок»](#типы-ошибок) | Тип | Описание | Пример | | -------------------- | ------------------------- | ----------------------------- | | **Node Error** | Ошибка в конкретной ноде | Неправильные credentials | | **Trigger Error** | Ошибка в триггере | Webhook недоступен | | **Memory Error** | Нехватка памяти | Обработка больших файлов | | **Timeout** | Превышение лимита времени | Долгий API запрос | | **Validation Error** | Неверные данные | Отсутствует обязательное поле | *** ## Создание Error Workflow [Заголовок раздела «Создание Error Workflow»](#создание-error-workflow) Error Workflow запускается при сбое любого workflow, к которому он привязан. 1. Создайте новый workflow 2. Добавьте ноду **Error Trigger** как первую 3. Добавьте ноды для обработки ошибок (email, Slack и т.д.) 4. Сохраните workflow (например, “Error Handler”) 5. Привяжите к другим workflows ### Привязка Error Workflow [Заголовок раздела «Привязка Error Workflow»](#привязка-error-workflow) 1. Откройте workflow, для которого нужна обработка ошибок 2. **Options** → **Settings** 3. В поле **Error workflow** выберите созданный Error Handler 4. Сохраните Совет Один Error Workflow можно использовать для нескольких workflows. *** ## Данные об ошибке [Заголовок раздела «Данные об ошибке»](#данные-об-ошибке) Error Trigger получает подробную информацию о сбое: ### Стандартная ошибка выполнения [Заголовок раздела «Стандартная ошибка выполнения»](#стандартная-ошибка-выполнения) ```json [ { "execution": { "id": "231", "url": "https://n8n.example.com/execution/231", "retryOf": "34", "error": { "message": "Example Error Message", "stack": "Stacktrace..." }, "lastNodeExecuted": "HTTP Request", "mode": "manual" }, "workflow": { "id": "1", "name": "My Workflow" } } ] ``` ### Поля данных [Заголовок раздела «Поля данных»](#поля-данных) | Поле | Описание | Доступность | | ---------------------------- | --------------------------- | ------------------- | | `execution.id` | ID выполнения | Если сохранено в БД | | `execution.url` | Ссылка на выполнение | Если сохранено в БД | | `execution.retryOf` | ID оригинального выполнения | Только для retry | | `execution.error.message` | Текст ошибки | Всегда | | `execution.error.stack` | Stack trace | Всегда | | `execution.lastNodeExecuted` | Нода с ошибкой | Всегда | | `execution.mode` | Режим запуска | Всегда | | `workflow.id` | ID workflow | Всегда | | `workflow.name` | Название workflow | Всегда | ### Ошибка в триггере [Заголовок раздела «Ошибка в триггере»](#ошибка-в-триггере) Если ошибка произошла в **триггере** (не в обычной ноде), структура данных отличается: ```json { "trigger": { "error": { "name": "WorkflowActivationError", "message": "Connection refused", "cause": { "message": "ECONNREFUSED", "stack": "..." }, "timestamp": 1654609328787, "node": { ... } }, "mode": "trigger" }, "workflow": { "id": "1", "name": "My Workflow" } } ``` *** ## Примеры Error Workflows [Заголовок раздела «Примеры Error Workflows»](#примеры-error-workflows) ### Уведомление в Slack [Заголовок раздела «Уведомление в Slack»](#уведомление-в-slack) ```plaintext ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ Error Trigger│───→│ Set │───→│ Slack │ │ │ │ (формат msg) │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ ``` **Сообщение в Slack:** ```plaintext :warning: *Ошибка в workflow* *Workflow:* {{ $json.workflow.name }} *Нода:* {{ $json.execution.lastNodeExecuted }} *Ошибка:* {{ $json.execution.error.message }} *Ссылка:* {{ $json.execution.url }} ``` ### Email уведомление [Заголовок раздела «Email уведомление»](#email-уведомление) ```plaintext ┌──────────────┐ ┌──────────────┐ │ Error Trigger│───→│ Gmail │ │ │ │ Send Email │ └──────────────┘ └──────────────┘ ``` ### Логирование в базу данных [Заголовок раздела «Логирование в базу данных»](#логирование-в-базу-данных) ```plaintext ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ Error Trigger│───→│ Code │───→│ PostgreSQL │ │ │ │ (parse data) │ │ Insert Row │ └──────────────┘ └──────────────┘ └──────────────┘ ``` ```javascript // Code нода для подготовки данных: return [{ json: { workflow_id: $json.workflow.id, workflow_name: $json.workflow.name, error_message: $json.execution.error?.message || $json.trigger?.error?.message, failed_node: $json.execution?.lastNodeExecuted || 'Trigger', execution_id: $json.execution?.id || null, timestamp: new Date().toISOString() } }]; ``` *** ## Принудительная ошибка: Stop And Error [Заголовок раздела «Принудительная ошибка: Stop And Error»](#принудительная-ошибка-stop-and-error) Нода **Stop And Error** позволяет принудительно завершить workflow с ошибкой при определённых условиях. ### Когда использовать [Заголовок раздела «Когда использовать»](#когда-использовать) * Валидация входных данных * Проверка бизнес-правил * Защита от некорректных состояний ### Пример: Валидация заказа [Заголовок раздела «Пример: Валидация заказа»](#пример-валидация-заказа) ```plaintext ┌────────────┐ ┌────────────┐ ┌────────────┐ │ Webhook │───→│ IF │───→│ Обработка │ │ (заказ) │ │(amount>0?) │ │ заказа │ └────────────┘ └─────┬──────┘ └────────────┘ │ Нет ↓ ┌────────────────┐ │ Stop And Error │ │ "Сумма должна │ │ быть > 0" │ └────────────────┘ ``` *** ## Порядок выполнения веток [Заголовок раздела «Порядок выполнения веток»](#порядок-выполнения-веток) Заметка В n8n 1.0+ ветки выполняются **последовательно** сверху вниз (ранее — параллельно). ### Изменение порядка [Заголовок раздела «Изменение порядка»](#изменение-порядка) 1. **Options** → **Settings** 2. Найдите настройку **Execution Order** 3. Выберите нужный режим При одинаковой высоте веток — сначала выполняется левая. *** ## Retry (Повторные попытки) [Заголовок раздела «Retry (Повторные попытки)»](#retry-повторные-попытки) ### Автоматический retry [Заголовок раздела «Автоматический retry»](#автоматический-retry) В настройках HTTP Request и некоторых других нод: ```plaintext Settings → Retry On Fail: true Settings → Max Tries: 3 Settings → Wait Between Tries: 1000ms ``` ### Ручной retry [Заголовок раздела «Ручной retry»](#ручной-retry) 1. Откройте **Executions** 2. Найдите failed execution 3. Нажмите **Retry** * Retry with same data Повторяет с теми же входными данными * Retry with new data Повторяет с обновлёнными данными (если триггер получает новые) *** ## Исследование ошибок [Заголовок раздела «Исследование ошибок»](#исследование-ошибок) ### Способы анализа [Заголовок раздела «Способы анализа»](#способы-анализа) 1. **Executions** — просмотр всех выполнений 2. **Log streaming** — отправка логов во внешние системы 3. **Error Workflow** — кастомная обработка ### Загрузка данных из прошлых выполнений [Заголовок раздела «Загрузка данных из прошлых выполнений»](#загрузка-данных-из-прошлых-выполнений) 1. Откройте workflow 2. Найдите failed execution 3. **Load data from previous execution** 4. Отладьте проблему Совет Доступно на n8n Cloud и зарегистрированных Community планах. *** ## Best Practices [Заголовок раздела «Best Practices»](#best-practices) ### 1. Всегда настраивайте Error Workflow [Заголовок раздела «1. Всегда настраивайте Error Workflow»](#1-всегда-настраивайте-error-workflow) ```plaintext ┌─────────────────────────────────────────────┐ │ Продакшн Workflow │ │ │ │ Settings: │ │ ├─ Error workflow: Error Handler │ │ └─ Save failed executions: Yes │ │ │ └─────────────────────────────────────────────┘ ``` ### 2. Используйте информативные сообщения [Заголовок раздела «2. Используйте информативные сообщения»](#2-используйте-информативные-сообщения) ```javascript // ❌ Плохо throw new Error("Error"); // ✅ Хорошо throw new Error(`Заказ ${orderId}: товар ${productId} отсутствует на складе`); ``` ### 3. Разделяйте критичные и некритичные ошибки [Заголовок раздела «3. Разделяйте критичные и некритичные ошибки»](#3-разделяйте-критичные-и-некритичные-ошибки) ```plaintext ┌──────────────┐ ┌──────────────┐ │ Error Trigger│───→│ Switch │ └──────────────┘ └──────┬───────┘ │ ┌────────────────┼────────────────┐ ↓ ↓ ↓ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ Critical │ │ Warning │ │ Info │ │ (PagerD) │ │ (Slack) │ │ (Log) │ └──────────┘ └──────────┘ └──────────┘ ``` ### 4. Включайте контекст [Заголовок раздела «4. Включайте контекст»](#4-включайте-контекст) В сообщениях об ошибках указывайте: * Какой workflow упал * На какой ноде * Какие данные обрабатывались * Ссылку на execution *** ## Связанные темы [Заголовок раздела «Связанные темы»](#связанные-темы) Troubleshooting [Решение проблем](/reference/troubleshooting/) — типичные ошибки Executions [Выполнение workflows](/workflows/executions/) — история запусков Логи [Logging](/hosting/environment-variables/) — настройка логирования # Примеры Workflows > Готовые примеры n8n workflows для различных сценариев автоматизации Коллекция готовых workflows для быстрого старта. Каждый пример можно импортировать в n8n. ## AI и Чат-боты [Заголовок раздела «AI и Чат-боты»](#ai-и-чат-боты) ### Telegram бот с AI [Заголовок раздела «Telegram бот с AI»](#telegram-бот-с-ai) Бот отвечает на вопросы пользователей с помощью GPT-4o. ```plaintext ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ Telegram │───→│ AI Agent │───→│ Telegram │ │ Trigger │ │ (GPT-4o) │ │ Send Message│ └──────────────┘ └──────────────┘ └──────────────┘ ``` JSON для импорта ```json { "name": "Telegram AI Bot", "nodes": [ { "parameters": { "updates": ["message"] }, "name": "Telegram Trigger", "type": "n8n-nodes-base.telegramTrigger", "position": [250, 300] }, { "parameters": { "options": { "systemMessage": "Ты — полезный ассистент. Отвечай кратко и по делу на русском языке." } }, "name": "AI Agent", "type": "@n8n/n8n-nodes-langchain.agent", "position": [500, 300] }, { "parameters": { "chatId": "={{ $('Telegram Trigger').item.json.message.chat.id }}", "text": "={{ $json.output }}" }, "name": "Telegram", "type": "n8n-nodes-base.telegram", "position": [750, 300] }, { "parameters": { "model": "gpt-4o-mini" }, "name": "OpenAI Chat Model", "type": "@n8n/n8n-nodes-langchain.lmChatOpenAi", "position": [500, 500] } ], "connections": { "Telegram Trigger": { "main": [[{"node": "AI Agent", "type": "main", "index": 0}]] }, "AI Agent": { "main": [[{"node": "Telegram", "type": "main", "index": 0}]] }, "OpenAI Chat Model": { "ai_languageModel": [[{"node": "AI Agent", "type": "ai_languageModel", "index": 0}]] } } } ``` **Требования:** * Telegram Bot Token (получить у @BotFather) * OpenAI API Key *** ### Чат-бот с RAG (ответы по документам) [Заголовок раздела «Чат-бот с RAG (ответы по документам)»](#чат-бот-с-rag-ответы-по-документам) Бот отвечает на вопросы, используя ваши документы. ```plaintext ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ Chat Trigger │───→│ AI Agent │───→│ Send Response│ └──────────────┘ └──────┬───────┘ └──────────────┘ │ ┌──────┴───────┐ │ Vector Store │ │ Tool │ └──────┬───────┘ │ ┌──────┴───────┐ │ Pinecone │ │ Vector Store │ └──────────────┘ ``` 1. **Загрузите документы** в Vector Store 2. **Настройте AI Agent** с Vector Store Tool 3. **Агент ищет** релевантные документы и отвечает на основе них [Подробнее о RAG ](/ai-mcp/rag/)Настройка Retrieval Augmented Generation *** ## Обработка данных [Заголовок раздела «Обработка данных»](#обработка-данных) ### Парсинг email и создание задач [Заголовок раздела «Парсинг email и создание задач»](#парсинг-email-и-создание-задач) Автоматическое создание задач в Notion из писем. ```plaintext ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ Gmail │───→│ AI Agent │───→│ IF │───→│ Notion │ │ Trigger │ │ (Classify) │ │ (is_task?) │ │ Create Page │ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ ``` **Логика:** 1. Получаем новое письмо 2. AI классифицирует: это задача или нет? 3. Если задача — создаём страницу в Notion ```javascript // Промпт для классификации: // "Проанализируй email и определи: // 1. Это задача? (true/false) // 2. Приоритет (high/medium/low) // 3. Краткое описание задачи" ``` *** ### ETL: Google Sheets → PostgreSQL [Заголовок раздела «ETL: Google Sheets → PostgreSQL»](#etl-google-sheets--postgresql) Синхронизация данных из таблицы в базу данных. ```plaintext ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ Schedule │───→│ Google Sheets│───→│ Code │───→│ PostgreSQL │ │ (hourly) │ │ Get Rows │ │ (Transform) │ │ Insert │ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ ``` ```javascript // Code нода для трансформации: return items.map(item => ({ json: { id: item.json.ID, name: item.json.Name.trim(), email: item.json.Email.toLowerCase(), created_at: new Date().toISOString() } })); ``` *** ### Обогащение данных через API [Заголовок раздела «Обогащение данных через API»](#обогащение-данных-через-api) Получение дополнительной информации о компаниях. ```plaintext ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ Webhook │───→│ Split Batches│───→│ HTTP Request │───→│ Merge │ │ │ │ (size: 10) │ │ (Company API)│ │ │ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ ``` Совет Используйте **Split In Batches** чтобы не превысить rate limits API. *** ## Мониторинг и уведомления [Заголовок раздела «Мониторинг и уведомления»](#мониторинг-и-уведомления) ### Мониторинг сайта [Заголовок раздела «Мониторинг сайта»](#мониторинг-сайта) Проверка доступности сайта и уведомление в Slack. ```plaintext ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ Schedule │───→│ HTTP Request │───→│ IF │───→│ Slack │ │ (5 min) │ │ (GET site) │ │ (status!=200)│ │ Message │ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ ``` ```javascript // Условие в IF ноде: {{ $json.statusCode !== 200 }} // Сообщение в Slack: :warning: Сайт {{ $('HTTP Request').params.url }} недоступен! Статус: {{ $json.statusCode }} Время: {{ $now.toISO() }} ``` *** ### GitHub → Slack уведомления [Заголовок раздела «GitHub → Slack уведомления»](#github--slack-уведомления) Уведомления о новых issues и PR. ```plaintext ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ GitHub │───→│ Switch │───→│ Slack │ │ Trigger │ │ (event type) │ │ (channel) │ └──────────────┘ └──────────────┘ └──────────────┘ ``` **События для отслеживания:** * `issues.opened` — новый issue * `pull_request.opened` — новый PR * `push` — новые коммиты * `release.published` — новый релиз *** ## Интеграция с MCP [Заголовок раздела «Интеграция с MCP»](#интеграция-с-mcp) ### AI Agent с GitHub MCP [Заголовок раздела «AI Agent с GitHub MCP»](#ai-agent-с-github-mcp) Агент с доступом к репозиториям GitHub. ```plaintext ┌──────────────┐ ┌──────────────┐ │ Chat Trigger │───→│ AI Agent │ └──────────────┘ └──────┬───────┘ │ ┌────────────┼────────────┐ ↓ ↓ ↓ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ Model │ │MCP Client│ │ Memory │ │(Claude) │ │ (GitHub) │ │ │ └──────────┘ └──────────┘ └──────────┘ ``` **Возможности:** * “Покажи последние issues в репозитории X” * “Создай issue с описанием Y” * “Найди все PR от пользователя Z” [Настройка MCP ](/ai-mcp/mcp/)Подключение MCP серверов к n8n *** ### Multi-tool Agent [Заголовок раздела «Multi-tool Agent»](#multi-tool-agent) Агент с несколькими инструментами. ```plaintext ┌──────────────┐ ┌────────────────────────────────────┐ │ Chat Trigger │───→│ AI Agent │ └──────────────┘ └─────────────────┬──────────────────┘ │ ┌─────────────┬───────────────┼───────────────┬─────────────┐ ↓ ↓ ↓ ↓ ↓ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ │Calculator │ │HTTP Tool │ │MCP GitHub │ │MCP Files │ │Workflow │ │ │ │(Weather) │ │ │ │ │ │ Tool │ └───────────┘ └───────────┘ └───────────┘ └───────────┘ └───────────┘ ``` **Промпт:** ```text Ты — универсальный ассистент с доступом к: - Калькулятору для математических расчётов - API погоды для информации о погоде - GitHub для работы с репозиториями - Файловой системе для работы с файлами - Другим n8n workflows для сложных операций Выбирай подходящий инструмент для каждой задачи. ``` *** ## Scheduled Jobs [Заголовок раздела «Scheduled Jobs»](#scheduled-jobs) ### Ежедневный отчёт [Заголовок раздела «Ежедневный отчёт»](#ежедневный-отчёт) Автоматическая отправка отчёта по расписанию. ```plaintext ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ Schedule │───→│ PostgreSQL │───→│ AI Agent │───→│ Email │ │ (9:00 AM) │ │ (Get data) │ │ (Summarize) │ │ (Send) │ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ ``` ```javascript // Cron для ежедневного запуска в 9:00 по Москве: 0 9 * * * // Промпт для AI: // "Создай краткий отчёт по данным: // - Ключевые метрики // - Изменения за день // - Рекомендации" ``` *** ### Очистка старых данных [Заголовок раздела «Очистка старых данных»](#очистка-старых-данных) Автоматическое удаление устаревших записей. ```plaintext ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ Schedule │───→│ PostgreSQL │───→│ Slack │ │ (weekly) │ │ (DELETE) │ │ (Notify) │ └──────────────┘ └──────────────┘ └──────────────┘ ``` ```sql -- SQL запрос: DELETE FROM logs WHERE created_at < NOW() - INTERVAL '30 days' RETURNING count(*); ``` *** ## Полезные паттерны [Заголовок раздела «Полезные паттерны»](#полезные-паттерны) ### Error Handling [Заголовок раздела «Error Handling»](#error-handling) ```plaintext ┌──────────────┐ │ Workflow │ └──────┬───────┘ │ ├── Success ──→ [Продолжение] │ └── Error ────→ ┌──────────────┐ ┌──────────────┐ │ Set Error │───→│ Slack │ │ Data │ │ (Alert) │ └──────────────┘ └──────────────┘ ``` ### Retry Logic [Заголовок раздела «Retry Logic»](#retry-logic) ```javascript // В HTTP Request ноде: // Settings → Retry On Fail: true // Settings → Max Tries: 3 // Settings → Wait Between Tries: 1000ms ``` ### Conditional Branching [Заголовок раздела «Conditional Branching»](#conditional-branching) ```plaintext ┌─── Условие A ───→ [Действие A] │ ┌──────────────┐ │ │ Switch │──────┼─── Условие B ───→ [Действие B] └──────────────┘ │ │ └─── Default ─────→ [Действие C] ``` *** ## Где найти больше примеров [Заголовок раздела «Где найти больше примеров»](#где-найти-больше-примеров) n8n Templates [n8n.io/workflows](https://n8n.io/workflows/) — 1000+ готовых workflows Community [community.n8n.io](https://community.n8n.io/) — примеры от сообщества GitHub [github.com/n8n-io](https://github.com/n8n-io) — официальные примеры *** ## Импорт Workflow [Заголовок раздела «Импорт Workflow»](#импорт-workflow) 1. Скопируйте JSON workflow 2. В n8n нажмите **+** → **Import from URL or JSON** 3. Вставьте JSON 4. Настройте Credentials 5. Активируйте workflow Осторожно После импорта всегда проверяйте и настраивайте Credentials — они не экспортируются из соображений безопасности. # Выполнение Workflow > Режимы выполнения, история, мониторинг и обработка ошибок ## Режимы выполнения [Заголовок раздела «Режимы выполнения»](#режимы-выполнения) ### Test Mode [Заголовок раздела «Test Mode»](#test-mode) Ручной запуск для отладки: * **Ctrl + Enter** или кнопка **Test workflow** * Данные видны на каждом шаге * Не записывается в историю (если не настроено) * Триггеры игнорируются (кроме Manual) ### Production Mode [Заголовок раздела «Production Mode»](#production-mode) Автоматическое выполнение активированного workflow: * Переключатель **Active** в правом верхнем углу * Триггеры работают автоматически * Записывается в историю выполнений * Учитывается в лимитах (для Cloud) ## Выполнение отдельных нод [Заголовок раздела «Выполнение отдельных нод»](#выполнение-отдельных-нод) ### Execute Node [Заголовок раздела «Execute Node»](#execute-node) Запуск конкретной ноды: 1. Кликните правой кнопкой на ноду 2. Выберите **Execute Node** 3. Нода выполнится с данными от предыдущих нод ### Test Step [Заголовок раздела «Test Step»](#test-step) Пошаговое выполнение: 1. Кликните на ноду 2. Нажмите **Test step** в панели 3. Просмотрите результат 4. Перейдите к следующей ноде ## История выполнений [Заголовок раздела «История выполнений»](#история-выполнений) ### Просмотр истории [Заголовок раздела «Просмотр истории»](#просмотр-истории) **Левое меню** → **Executions** | Столбец | Описание | | ------------ | ------------------------------------- | | **Status** | Успех (🟢), Ошибка (🔴), Running (🟡) | | **Started** | Время начала | | **Workflow** | Название workflow | | **Mode** | Test/Production | | **Duration** | Длительность выполнения | ### Фильтрация [Заголовок раздела «Фильтрация»](#фильтрация) Фильтры для поиска выполнений: * **Status**: Success, Error, Running * **Workflow**: Конкретный workflow * **Date range**: Период времени ### Детали выполнения [Заголовок раздела «Детали выполнения»](#детали-выполнения) Кликните на выполнение для просмотра: * Данные на каждой ноде * Время выполнения каждого шага * Ошибки с stack trace * Возможность повторного запуска ## Retry (Повторный запуск) [Заголовок раздела «Retry (Повторный запуск)»](#retry-повторный-запуск) ### Автоматический retry [Заголовок раздела «Автоматический retry»](#автоматический-retry) В настройках ноды (**Settings** → **On Error**): | Опция | Описание | | --------------------------------- | ------------------------------- | | **Stop Workflow** | Остановить при ошибке (default) | | **Continue** | Продолжить, вернуть ошибку | | **Continue (using error output)** | Направить в Error output | ### Ручной retry [Заголовок раздела «Ручной retry»](#ручной-retry) 1. Откройте **Executions** 2. Найдите неудачное выполнение 3. Кликните **Retry** 4. Выберите: с начала или с точки ошибки ## Обработка ошибок [Заголовок раздела «Обработка ошибок»](#обработка-ошибок) ### Error Trigger [Заголовок раздела «Error Trigger»](#error-trigger) Создайте отдельный workflow для обработки ошибок: Настройка: 1. Создайте новый workflow 2. Добавьте **Error Trigger** 3. В основном workflow: **Settings** → **Error Workflow** → выберите ### Error Output [Заголовок раздела «Error Output»](#error-output) Направление ошибок в отдельную ветку: Настройка: 1. В ноде: **Settings** → **On Error** → **Continue (using error output)** 2. Подключите Error output к обработчику ### Try/Catch паттерн [Заголовок раздела «Try/Catch паттерн»](#trycatch-паттерн) В Code ноде: ```javascript try { // Опасная операция const result = await someOperation(); return [{ json: { success: true, data: result } }]; } catch (error) { return [{ json: { success: false, error: error.message } }]; } ``` ## Мониторинг [Заголовок раздела «Мониторинг»](#мониторинг) ### Execution Data [Заголовок раздела «Execution Data»](#execution-data) Настройка хранения данных: **Settings** → **Workflow Settings**: | Настройка | Описание | | ------------------------------ | ------------------------------ | | **Save Execution Progress** | Сохранять промежуточные данные | | **Save Manual Executions** | Сохранять тестовые запуски | | **Save Successful Executions** | Сохранять успешные | | **Save Failed Executions** | Сохранять неудачные | ### Timeout [Заголовок раздела «Timeout»](#timeout) Ограничение времени выполнения: * **Workflow Settings** → **Timeout After** * Значение в секундах * Workflow прервётся по истечении Осторожно При timeout данные могут быть потеряны. Используйте checkpoint’ы для длительных операций. ## Оптимизация производительности [Заголовок раздела «Оптимизация производительности»](#оптимизация-производительности) ### Batch Processing [Заголовок раздела «Batch Processing»](#batch-processing) Обрабатывайте данные пакетами: ### Параллельное выполнение [Заголовок раздела «Параллельное выполнение»](#параллельное-выполнение) Настройка в **Settings** → **Execute Once**: * **OFF**: Каждый item обрабатывается параллельно * **ON**: Нода выполняется один раз для всех items ### Wait ноды [Заголовок раздела «Wait ноды»](#wait-ноды) Добавляйте паузы для rate-limited API: | Параметр | Значение | | --------------- | ------------------- | | **Resume** | After Time Interval | | **Wait Amount** | 1 | | **Wait Unit** | Seconds | ## Webhooks [Заголовок раздела «Webhooks»](#webhooks) ### Webhook Response [Заголовок раздела «Webhook Response»](#webhook-response) Настройка ответа webhook: * Immediately ```plaintext Ответ сразу после получения запроса HTTP 200 OK ``` * Last Node ```plaintext Ответ с данными последней ноды ``` * Response Node ```plaintext Ответ из специальной Respond to Webhook ноды ``` ### Respond to Webhook [Заголовок раздела «Respond to Webhook»](#respond-to-webhook) Кастомный ответ: | Параметр | Описание | | -------------------- | ------------------------------ | | **Response Code** | HTTP код (200, 201, 400, etc.) | | **Response Body** | Тело ответа (JSON, text) | | **Response Headers** | HTTP заголовки | ## Логирование [Заголовок раздела «Логирование»](#логирование) ### Console Output [Заголовок раздела «Console Output»](#console-output) В Code ноде: ```javascript console.log('Debug info:', data); console.error('Error:', error); ``` Логи видны в: * Execution details * Docker logs (self-hosted) * n8n logs ### Custom Logging [Заголовок раздела «Custom Logging»](#custom-logging) Отправка в внешние системы: ## Следующие шаги [Заголовок раздела «Следующие шаги»](#следующие-шаги) * [Логика потоков](/concepts/flow-logic/) — условия и ветвление * [Обработка ошибок](/concepts/error-handling/) — паттерны обработки * [Хостинг](/hosting/overview/) — настройка для production # Обзор Workflows > Понимание workflow в n8n — структура, компоненты и принципы работы ## Что такое Workflow? [Заголовок раздела «Что такое Workflow?»](#что-такое-workflow) **Workflow** — это автоматизированный процесс, состоящий из связанных между собой нод (узлов). Каждая нода выполняет определённую задачу: получает данные, преобразует их, отправляет в другие системы. ## Основные компоненты [Заголовок раздела «Основные компоненты»](#основные-компоненты) Триггеры Запускают workflow — по расписанию, по webhook, вручную Ноды Выполняют действия — запросы, преобразования, отправка данных Соединения Связывают ноды и передают данные между ними Credentials Хранят учётные данные для подключения к сервисам ## Типы нод [Заголовок раздела «Типы нод»](#типы-нод) ### Триггеры (Triggers) [Заголовок раздела «Триггеры (Triggers)»](#триггеры-triggers) Запускают выполнение workflow: | Триггер | Описание | | -------------------- | -------------------------------------- | | **Manual Trigger** | Ручной запуск кнопкой | | **Schedule Trigger** | Запуск по расписанию (cron) | | **Webhook** | Запуск по HTTP-запросу | | **App Triggers** | Триггеры сервисов (Gmail, Slack, etc.) | ### Основные ноды (Core Nodes) [Заголовок раздела «Основные ноды (Core Nodes)»](#основные-ноды-core-nodes) | Нода | Описание | | ------------------- | ------------------------- | | **HTTP Request** | Запросы к API | | **Code** | JavaScript/Python код | | **Set** | Создание/изменение данных | | **IF** | Условное ветвление | | **Switch** | Множественное ветвление | | **Merge** | Объединение потоков | | **Loop Over Items** | Цикл по элементам | ### AI ноды [Заголовок раздела «AI ноды»](#ai-ноды) | Нода | Описание | | ---------------- | ------------------------------------------- | | **AI Agent** | Автономный AI агент с инструментами | | **Chat Model** | Подключение LLM (OpenAI, Anthropic, Ollama) | | **Memory** | Память для контекста диалога | | **Vector Store** | Хранение embeddings для RAG | ## Поток данных [Заголовок раздела «Поток данных»](#поток-данных) Данные в n8n передаются между нодами в виде **items** — массива объектов JSON. ```json [ { "json": { "name": "John", "email": "john@example.com" } }, { "json": { "name": "Jane", "email": "jane@example.com" } } ] ``` Совет Каждый item обрабатывается независимо. Если входящие данные содержат 10 items, следующая нода выполнится 10 раз (если не указано иное). ## Режимы выполнения [Заголовок раздела «Режимы выполнения»](#режимы-выполнения) ### Test Mode (Тестовый) [Заголовок раздела «Test Mode (Тестовый)»](#test-mode-тестовый) * Запуск кнопкой “Test workflow” * Видны данные на каждом шаге * Не учитываются в лимитах выполнений ### Production Mode (Продакшен) [Заголовок раздела «Production Mode (Продакшен)»](#production-mode-продакшен) * Активируется переключателем “Active” * Триггеры работают автоматически * Логируется в истории выполнений ## Состояния workflow [Заголовок раздела «Состояния workflow»](#состояния-workflow) | Состояние | Описание | | ------------ | -------------------------- | | **Draft** | Черновик, не активен | | **Active** | Активен, триггеры работают | | **Inactive** | Деактивирован | | **Error** | Есть ошибки в настройках | ## Версионирование [Заголовок раздела «Версионирование»](#версионирование) n8n поддерживает версии workflow: * Автоматическое сохранение при изменениях * История версий для отката * Экспорт/импорт в JSON формате ## Организация workflow [Заголовок раздела «Организация workflow»](#организация-workflow) ### Теги [Заголовок раздела «Теги»](#теги) Группируйте workflow по тегам: * `production` — боевые процессы * `development` — в разработке * `integration` — интеграции с сервисами ### Папки [Заголовок раздела «Папки»](#папки) В Enterprise версии доступны папки для организации. ## Лучшие практики [Заголовок раздела «Лучшие практики»](#лучшие-практики) 1. **Называйте понятно** — используйте описательные имена 2. **Добавляйте Sticky Notes** — документируйте сложную логику 3. **Используйте Sub-workflows** — разбивайте сложные процессы 4. **Тестируйте поэтапно** — проверяйте каждую ноду отдельно 5. **Обрабатывайте ошибки** — добавляйте Error Trigger ## Следующие шаги [Заголовок раздела «Следующие шаги»](#следующие-шаги) * [Создание workflow](/workflows/create/) — пошаговое руководство * [Компоненты](/workflows/components/) — детальный разбор * [Выполнение](/workflows/executions/) — запуск и мониторинг # Под-workflows (Sub-workflows) > Создание модульных workflows с вызовом одного workflow из другого Под-workflows позволяют вызывать один workflow из другого. Это делает ваши автоматизации **модульными** и помогает избежать проблем с памятью при обработке больших объёмов данных. Совет Выполнение под-workflows **не учитывается** в лимитах вашего тарифа на количество executions или активных workflows. ## Зачем использовать под-workflows [Заголовок раздела «Зачем использовать под-workflows»](#зачем-использовать-под-workflows) | Преимущество | Описание | | --------------------------- | ----------------------------------------------------------- | | **Модульность** | Разбивайте сложную логику на переиспользуемые блоки | | **Память** | Избегайте ошибок памяти при больших workflows | | **Повторное использование** | Один под-workflow можно вызывать из нескольких родительских | | **Организация** | Чистая структура проекта | | **Тестирование** | Легче тестировать отдельные части | *** ## Создание под-workflow [Заголовок раздела «Создание под-workflow»](#создание-под-workflow) 1. Создайте новый workflow 2. Добавьте триггер **Execute Sub-workflow Trigger** (или “When Executed by Another Workflow”) 3. Настройте режим входных данных (Input data mode) 4. Добавьте остальные ноды для логики под-workflow 5. Сохраните workflow ### Режимы входных данных [Заголовок раздела «Режимы входных данных»](#режимы-входных-данных) | Режим | Описание | Когда использовать | | ----------------------- | ----------------------------- | ---------------------------------- | | **Define using fields** | Определите поля и типы данных | Строгая типизация, автоподстановка | | **Define using JSON** | Пример JSON структуры | Сложные объекты | | **Accept all data** | Принимает любые данные | Гибкость, но без валидации | ```json // Пример JSON схемы для "Define using JSON": { "customer_id": "12345", "email": "user@example.com", "order_total": 150.00 } ``` ### Настройка доступа [Заголовок раздела «Настройка доступа»](#настройка-доступа) По умолчанию под-workflow может вызывать только владелец. Для изменения: 1. Откройте **Options** → **Settings** 2. Найдите **This workflow can be called by** 3. Выберите нужный уровень доступа *** ## Вызов под-workflow [Заголовок раздела «Вызов под-workflow»](#вызов-под-workflow) 1. Откройте родительский workflow 2. Добавьте ноду **Execute Sub-workflow** 3. Выберите способ указания под-workflow 4. Заполните требуемые входные данные 5. Сохраните и запустите ### Способы указания под-workflow [Заголовок раздела «Способы указания под-workflow»](#способы-указания-под-workflow) | Способ | Описание | | ------------- | ------------------------------- | | **From list** | Выбор из списка ваших workflows | | **By ID** | Указание ID workflow | | **By URL** | URL до workflow | | **From file** | Загрузка из локального файла | | **Parameter** | JSON workflow как параметр | Заметка **Как найти ID workflow:** ID — это буквенно-цифровая строка в конце URL вашего workflow. Например: `https://n8n.example.com/workflow/abc123` → ID = `abc123` *** ## Как данные передаются между workflows [Заголовок раздела «Как данные передаются между workflows»](#как-данные-передаются-между-workflows) ```plaintext ┌─────────────────────────────────────────────────────────────┐ │ Родительский Workflow │ │ │ │ ┌────────────┐ ┌───────────────────┐ ┌────────────┐ │ │ │ Trigger │───→│ Execute Sub- │───→│ Следующая │ │ │ │ │ │ workflow │ │ нода │ │ │ └────────────┘ └─────────┬─────────┘ └────────────┘ │ │ │ │ └──────────────────────────────┼───────────────────────────────┘ │ ↓ Данные отправляются ┌─────────────────────────────────────────────────────────────┐ │ Под-Workflow │ │ │ │ ┌───────────────────┐ ┌────────────┐ ┌────────────┐ │ │ │ Execute Sub- │───→│ Обработка │───→│ Последняя │ │ │ │ workflow Trigger │ │ │ │ нода │ │ │ └───────────────────┘ └────────────┘ └─────┬──────┘ │ │ │ │ └────────────────────────────────────────────────────┼─────────┘ │ ↑ Результат возвращается ``` **Процесс:** 1. Execute Sub-workflow отправляет данные в триггер под-workflow 2. Под-workflow обрабатывает данные 3. **Последняя нода** под-workflow возвращает результат 4. Результат появляется на выходе Execute Sub-workflow *** ## Создание под-workflow из существующего [Заголовок раздела «Создание под-workflow из существующего»](#создание-под-workflow-из-существующего) ### Метод 1: Через ноду Execute Sub-workflow [Заголовок раздела «Метод 1: Через ноду Execute Sub-workflow»](#метод-1-через-ноду-execute-sub-workflow) 1. Добавьте Execute Sub-workflow в родительский workflow 2. Выберите **Database** → **From list** 3. Нажмите **Create a sub-workflow** 4. n8n создаст новый workflow с триггером ### Метод 2: Выделение нод [Заголовок раздела «Метод 2: Выделение нод»](#метод-2-выделение-нод) 1. Выделите ноды, которые хотите вынести 2. Правый клик → **Convert to sub-workflow** 3. n8n автоматически: * Создаст новый под-workflow * Заменит ноды на Execute Sub-workflow * Настроит входные/выходные данные *** ## Навигация между workflows [Заголовок раздела «Навигация между workflows»](#навигация-между-workflows) При выполнении workflow можно переключаться между родителем и под-workflow: * В **Execute Sub-workflow** ноде — ссылка **View sub-execution** * В под-workflow — ссылка на родительский execution Это упрощает отладку и понимание потока данных. *** ## Примеры использования [Заголовок раздела «Примеры использования»](#примеры-использования) ### Пример 1: Обработка заказов [Заголовок раздела «Пример 1: Обработка заказов»](#пример-1-обработка-заказов) ```plaintext Родительский workflow: ┌────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ Webhook │───→│ Execute Sub- │───→│ Execute Sub- │ │ (заказ) │ │ workflow │ │ workflow │ └────────────┘ │ (валидация) │ │ (уведомления) │ └─────────────────┘ └─────────────────┘ Под-workflow "Валидация": - Проверка наличия товара - Валидация адреса - Расчёт доставки Под-workflow "Уведомления": - Email клиенту - Slack команде - SMS при VIP заказе ``` ### Пример 2: ETL пайплайн [Заголовок раздела «Пример 2: ETL пайплайн»](#пример-2-etl-пайплайн) ```plaintext Родительский workflow (оркестратор): ┌────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ Schedule │───→│ Loop Over Items │───→│ Execute Sub- │ │ (ежечасно) │ │ (источники) │ │ workflow │ └────────────┘ └─────────────────┘ │ (ETL для │ │ источника) │ └─────────────────┘ Под-workflow "ETL": 1. Extract — получить данные из источника 2. Transform — преобразовать в нужный формат 3. Load — записать в целевую БД ``` ### Пример 3: AI с несколькими моделями [Заголовок раздела «Пример 3: AI с несколькими моделями»](#пример-3-ai-с-несколькими-моделями) ```json // Под-workflow для каждой AI модели: // - gpt4-processor // - claude-processor // - gemini-processor // Родительский workflow выбирает модель: { "model": "gpt4", "prompt": "Проанализируй текст..." } ``` *** ## Best Practices [Заголовок раздела «Best Practices»](#best-practices) ### Именование [Заголовок раздела «Именование»](#именование) ```plaintext ✅ Хорошо: - [SUB] Email Notifications - [SUB] Data Validation - Order Processing / Validate Order ❌ Плохо: - Workflow 1 - Test - Untitled ``` ### Документирование [Заголовок раздела «Документирование»](#документирование) Используйте **Sticky Notes** в начале под-workflow: * Описание назначения * Ожидаемые входные данные * Возвращаемый результат * Автор и дата создания ### Обработка ошибок [Заголовок раздела «Обработка ошибок»](#обработка-ошибок) ```plaintext Родительский workflow: ┌────────────────┐ │ Execute Sub- │ │ workflow │ └───────┬────────┘ │ ┌────┴────┐ ↓ ↓ Success Error ───→ [Error Handler] ``` Настройте Error Workflow для под-workflows отдельно. *** ## Ограничения [Заголовок раздела «Ограничения»](#ограничения) Осторожно **Важные ограничения:** * Под-workflow **не должен содержать ошибок** — иначе родитель не сможет его вызвать * Для загрузки данных из предыдущих выполнений нужен Cloud или зарегистрированный Community план * Рекурсивные вызовы (workflow вызывает сам себя) возможны, но требуют осторожности с лимитами *** ## Отладка [Заголовок раздела «Отладка»](#отладка) ### Загрузка данных в под-workflow [Заголовок раздела «Загрузка данных в под-workflow»](#загрузка-данных-в-под-workflow) 1. Создайте под-workflow с триггером 2. Установите **Input data mode** в **Accept all data** 3. В настройках: **Save successful production executions** = Save 4. Запустите родительский workflow 5. Откройте под-workflow → загрузите данные из previous execution 6. Закрепите данные (Pin) для дальнейшей разработки ### Типичные проблемы [Заголовок раздела «Типичные проблемы»](#типичные-проблемы) | Проблема | Решение | | -------------------- | ------------------------------------- | | ”Workflow not found” | Проверьте ID и права доступа | | ”Invalid input” | Сверьте схему данных | | Пустой результат | Проверьте последнюю ноду под-workflow | | Timeout | Увеличьте лимит или оптимизируйте | *** ## Связанные темы [Заголовок раздела «Связанные темы»](#связанные-темы) Error Handling [Обработка ошибок](/workflows/error-handling/) в workflows Executions [Выполнение workflows](/workflows/executions/) и отладка Примеры [Примеры workflows](/workflows/examples/) с под-workflows