N8n binary file

N8n Binary File: Архитектура, Работа и Управление

N8n — это инструмент для автоматизации рабочих процессов с открытым исходным кодом, который использует подход, основанный на узлах (нодах). В контексте N8n понятие «binary file» (бинарный файл) относится к файлам, содержащим данные в нетекстовом формате, которые обрабатываются и передаются между узлами в рамках workflow. Это могут быть изображения, PDF-документы, аудиозаписи, видео, архивы, исполняемые файлы и любые другие данные, представленные в двоичной форме. Понимание работы с бинарными файлами критически важно для создания сложных автоматизаций, включающих обработку медиа, генерацию отчетов или интеграцию с файловыми хранилищами.

Архитектура обработки бинарных данных в N8n

N8n обрабатывает все данные, включая бинарные, через концепцию «items» (элементов). Каждый элемент представляет собой объект JSON, который может содержать как текстовые поля, так и ссылки на бинарные данные. Сами бинарные данные не хранятся непосредственно в теле элемента JSON для эффективности и производительности. Вместо этого N8n использует систему бинарного менеджера (Binary Data Manager).

Когда узел (например, «Read Binary Files» или «HTTP Request») получает бинарный файл, происходит следующее:

• Бинарные данные загружаются в память или временное хранилище.
• Бинарный менеджер присваивает этим данным уникальный идентификатор (например, b7771c38-89a1-4a67-b18e-5e3c6b8bdcb2).
• В элемент данных добавляется специальное поле binary, которое содержит этот идентификатор, имя файла, тип MIME и размер данных.
• Сами байты файла управляются бинарным менеджером отдельно от основного потока JSON.

Ключевые узлы для работы с бинарными файлами

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

Узел «Read Binary Files»

Считывает файлы из локальной файловой системы сервера N8n. Важно: узел имеет доступ только к тем директориям, которые разрешены в конфигурации N8n (переменная EXECUTIONS_DATA_SAVE_PATH и другие настройки безопасности).

Узел «HTTP Request»

Чаще всего используется для загрузки бинарных файлов из внешних источников. При настройке запроса необходимо установить параметр «Response Format» в значение «File». Это указывает узлу интерпретировать ответ как бинарный файл и создать соответствующую запись в поле binary выходного элемента.

Узел «Write Binary Files»

Выполняет обратную операцию — сохраняет бинарные данные, полученные из предыдущих узлов, в файл на диске сервера N8n. Требует указания имени файла и пути для сохранения.

Узлы для облачных хранилищ

Узлы для Nextcloud, S3, Google Drive, Dropbox и других сервисов могут как загружать, так и скачивать бинарные файлы, интегрируя облачные хранилища в workflow.

Формат данных и поле BINARY

Элемент данных, содержащий бинарный файл, имеет следующую структуру:

• json: Объект, содержащий текстовые/числовые данные (например, метаданные файла).
• binary: Объект, ключами в котором являются имена бинарных свойств (например, data). Каждое свойство содержит объект с метаданными файла.

Пример структуры элемента:

{
  "json": {
    "fileName": "report.pdf"
  },
  "binary": {
    "data": {
      "id": "b7771c38-89a1-4a67-b18e-5e3c6b8bdcb2",
      "fileName": "report.pdf",
      "fileExtension": "pdf",
      "mimeType": "application/pdf",
      "fileSize": 24576
    }
  }
}

Конфигурация и управление бинарными данными

Поведение бинарного менеджера настраивается через переменные окружения в файле .env или конфигурации контейнера/сервера.

Переменная окружения	Описание	Значение по умолчанию
EXECUTIONS_DATA_SAVE_PATH	Директория для хранения временных данных исполнений, включая бинарные файлы.	~/.n8n
N8N_DEFAULT_BINARY_DATA_MODE	Режим хранения бинарных данных. filesystem (по умолчанию) или memory.	filesystem
N8N_MAX_BINARY_DATA_SIZE	Максимальный размер (в МБ) бинарных данных, которые будут храниться в памяти. Превышение приведет к использованию файловой системы.	10240 (10 ГБ)
N8N_PERSISTED_BINARY_DATA_TTL	Время жизни (в минутах) сохраненных бинарных данных после завершения workflow. Установите в 0 для отключения автоматической очистки.	60
N8N_BINARY_DATA_STORAGE_PATH	Путь для хранения бинарных данных, если режим filesystem активен.	~/.n8n/binaryData

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

Пример 1: Загрузка изображения и сохранение в Google Drive

1. Узел «HTTP Request» загружает изображение по URL. Параметр «Response Format» = «File».
2. Узел «Google Drive» (действие: «Upload») получает выходные данные предыдущего узла. В поле «File Path / Binary Data» выбирается бинарное свойство (например, data).
3. При выполнении workflow изображение будет загружено напрямую из источника в указанную папку Google Drive.

Пример 2: Обработка вложений из электронной почты

1. Узел «Email Trigger» (IMAP) получает письмо с вложением.
2. Вложение автоматически становится доступным как бинарное свойство в выходном элементе.
3. Последующий узел (например, «Extract From File») может извлечь текст из PDF или «Code» узел может обработать данные с помощью пользовательской логики.

Оптимизация и устранение неполадок

Работа с большими бинарными файлами требует внимания к настройкам и логике workflow.

• Производительность: Для обработки больших файлов (видео, образы дисков) убедитесь, что на сервере достаточно дискового пространства в пути, указанном в EXECUTIONS_DATA_SAVE_PATH. Рассмотрите возможность использования режима memory для часто используемых файлов небольшого размера.
• Очистка данных: Настройте N8N_PERSISTED_BINARY_DATA_TTL для автоматического удаления временных файлов. В противном случае они будут накапливаться.
• Распространенные ошибки:
  • «Binary data not found» — возникает, если узел ожидает бинарные данные, но предыдущий узел не передал их. Проверьте настройку «Response Format» в узле HTTP Request.
  • Превышение лимита памяти — при обработке множества крупных файлов одновременно. Увеличьте значение N8N_MAX_BINARY_DATA_SIZE или оптимизируйте workflow для последовательной, а не параллельной обработки.

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

Где физически хранятся бинарные файлы во время выполнения workflow?

По умолчанию они хранятся в поддиректории binaryData/ внутри пути, заданного переменной EXECUTIONS_DATA_SAVE_PATH (обычно ~/.n8n). Файлы сохраняются под своими UUID-именами. N8n управляет их жизненным циклом автоматически.

Можно ли передать бинарный файл между узлами в виде base64-строки?

Да, но это не рекомендуется для больших файлов, так как увеличивает объем обрабатываемых данных на 33% и нагружает парсер JSON. Однако некоторые узлы или API могут требовать ввод в формате base64. Для преобразования можно использовать узел «Code», который имеет доступ к бинарным данным через объект $binary и может конвертировать их в строку base64 с помощью getBinaryDataBuffer().

Как ограничить размер загружаемых бинарных файлов?

Непосредственно в интерфейсе N8n такой глобальной настройки нет. Ограничения можно задать на уровне:

1. Обратного прокси (например, Nginx) с помощью директивы client_max_body_size.
2. В коде узла «HTTP Request», проверяя свойство fileSize в поле binary и добавляя условную логику.
3. Настройкой переменной окружения N8N_MAX_BINARY_DATA_SIZE, которая определяет порог для хранения в памяти.

Почему узел «HTTP Request» возвращает бинарные данные в виде «мусора» в JSON-поле?

Это происходит, если параметр «Response Format» установлен в «JSON» или «Auto». Когда сервер возвращает бинарный файл (например, изображение), его содержимое не является валидным JSON, и N8n пытается его интерпретировать как текст. Всегда устанавливайте «Response Format» в значение «File» для загрузки файлов.

Как удалить бинарные данные вручную?

Автоматическая очистка происходит по истечении TTL. Для ручной очистки:

1. Остановите N8n.
2. Удалите содержимое директорий binaryData/ и executionData/ внутри рабочей директории N8n.
3. Запустите N8n заново. Не удаляйте эти папки, только их содержимое.

Можно ли использовать бинарные данные в пользовательских узлах?

Да, при разработке собственных узлов вы можете объявить свойство как бинарное, используя displayOptions. В методе execute() вы можете получить доступ к бинарным данным текущего элемента через this.getBinaryDataStream(itemIndex, propertyName) для работы с потоком (stream) данных или использовать другие методы из BinaryDataManager.