Binary data в n8n: файлы, вложения, filesystem, database и S3 без падений

Обновлено: 2026-05-29

Binary data — это любые файлы, которые проходят через workflow: PDF, изображения, аудио, Excel, архивы, вложения писем, скачанные документы, файлы из Telegram или webhook. В небольших сценариях это незаметно, но в production именно binary data часто приводит к падению по памяти, переполнению диска и огромным backup.

Главное правило: файл не должен бесконечно путешествовать по workflow без необходимости. n8n должен получить файл, извлечь или передать его, сохранить в нужное место и дальше работать с metadata: ссылкой, hash, размером, типом, внешним ID.

Какие режимы хранения использовать

Режим	Когда подходит	Риск
`default`	только маленькие тесты и старые конфигурации	файлы могут съедать память процесса
`filesystem`	один n8n main без queue mode или простой Docker Compose	нужен стабильный volume и backup файлов
`database`	queue mode, где workers должны видеть binary data одинаково	PostgreSQL растёт быстрее
`s3`	крупные файлы и внешнее объектное хранилище	нужна лицензия/поддержка и lifecycle policy

Для большинства небольших self-hosted инстансов лучше начинать с filesystem. Для queue mode нельзя просто положиться на локальную папку одного контейнера: worker может не увидеть файл. В таком случае используйте database или продуманное внешнее хранилище.

Настройка filesystem mode

services:
  n8n:
    image: n8nio/n8n:latest
    environment:
      - N8N_DEFAULT_BINARY_DATA_MODE=filesystem
      - N8N_BINARY_DATA_STORAGE_PATH=/home/node/.n8n/binaryData
      - EXECUTIONS_DATA_PRUNE=true
      - EXECUTIONS_DATA_MAX_AGE=336
    volumes:
      - n8n_data:/home/node/.n8n

После включения проверьте, что volume реально сохраняется между перезапусками. Нельзя хранить binary data внутри одноразового слоя контейнера: при пересоздании контейнера файлы исчезнут, а старые executions начнут показывать ошибки.

Настройка для queue mode

В queue mode main и workers выполняют разные части системы. Если binary data лежит только на файловой системе одного контейнера, другой контейнер может не найти файл. Практичный вариант — database mode:

services:
  n8n:
    environment:
      - EXECUTIONS_MODE=queue
      - N8N_DEFAULT_BINARY_DATA_MODE=database
  n8n-worker:
    command: worker --concurrency=5
    environment:
      - EXECUTIONS_MODE=queue
      - N8N_DEFAULT_BINARY_DATA_MODE=database

Минус очевиден: база станет больше. Поэтому для файловых workflow нужны pruning, лимит размера входящих файлов и вынос бизнес-файлов в Drive, S3, MinIO, Nextcloud или Яндекс Диск.

S3/external storage: когда нужно

Объектное хранилище полезно, когда файлов много, они большие, а n8n должен оставаться оркестратором. В такой архитектуре n8n не хранит “всё навсегда”, а записывает файл в bucket, получает ключ объекта и передаёт его дальше.

N8N_DEFAULT_BINARY_DATA_MODE=s3
N8N_EXTERNAL_STORAGE_S3_HOST=s3.example.ru
N8N_EXTERNAL_STORAGE_S3_BUCKET_NAME=n8n-binary
N8N_EXTERNAL_STORAGE_S3_BUCKET_REGION=ru-1
N8N_EXTERNAL_STORAGE_S3_ACCESS_KEY=...
N8N_EXTERNAL_STORAGE_S3_ACCESS_SECRET=...

Обязательно настройте lifecycle policy на bucket. Иначе вы просто перенесёте переполнение диска из VPS в объектное хранилище и получите растущий счёт.

Как проектировать workflow с файлами

Принять файл через Webhook, Telegram, Gmail, Drive или HTTP Request.
Проверить размер, MIME type и источник.
Сохранить файл во внешнее хранилище или оставить только на время обработки.
Извлечь нужный текст/таблицу/metadata.
Удалить лишние binary-поля перед дальнейшей обработкой.
В CRM или таблицу записать ссылку, hash и статус обработки.

Если workflow отправляет файл в AI/OCR, не передавайте туда весь архив или длинную цепочку вложений. Сначала нормализуйте документ, ограничьте размер и разберите тип файла.

Права и папки

После обновлений Docker или переезда частая проблема — n8n не может записать файл в binaryData. Проверьте владельца volume и права:

docker compose exec n8n sh -lc 'id && ls -la /home/node/.n8n && ls -la /home/node/.n8n/binaryData || true'

Если директория принадлежит root или старому UID, контейнер может падать или выдавать file is not writable. Исправляйте права аккуратно, предварительно сделав backup volume.

Ошибки, которые легко перепутать

Ошибка	Что проверить
binary data missing	не удалён ли файл pruning-ом, доступен ли volume, не сменился ли режим хранения
file is not writable	права на папку, пользователь контейнера, read-only volume
workflow падает по памяти	не используется ли memory/default mode для больших файлов
backup огромный	не хранятся ли файлы в PostgreSQL или volume без политики очистки

Минимальный smoke-test

curl -X POST "https://n8n.example.ru/webhook/file-test" \
  -F "file=@./test.pdf" \
  -F "source=manual-test"

В workflow проверьте: файл принят, размер виден, путь/ключ сохранён, после перезапуска контейнера execution всё ещё может прочитать binary data, а pruning не удаляет свежие файлы.

Операционный runbook для self-hosted ¶

Для темы «Binary data в n8n» важно разделять настройку и эксплуатацию. Настройка отвечает на вопрос “запустилось ли”, эксплуатация — “сможем ли мы восстановиться, обновиться и расследовать инцидент без потери credentials и execution history”.

Перед изменениями проверьте бэкап базы, значение N8N_ENCRYPTION_KEY, состояние volume, логи web-процесса и worker-процесса. Главный риск — получить уверенный, но непроверенный ответ модели, сломанный JSON или дорогой цикл retry.

Слой	Что зафиксировать	Зачем
Вход	нормализованный prompt, контекст, список источников, версия промпта и ожидаемый JSON-ответ	позволяет повторить проблему без доступа к production-секретам
Контроль	validation_error_rate, token_cost, fallback_usage, human_review_rate, source_coverage	показывает деградацию раньше, чем пользователи начинают писать в поддержку
Безопасность	получить уверенный, но непроверенный ответ модели, сломанный JSON или дорогой цикл retry	снижает риск скрытых дублей, утечки данных и неконтролируемых write-действий
Готовность	есть тест на happy path, пустой вход, повтор и сбой внешнего сервиса для «Binary data в n8n»	делает статью пригодной для runbook, а не только для чтения

Пример безопасного входного контракта ¶

{
  "request_id": "req_demo_001",
  "prompt_version": "2026-05-29",
  "input": "краткое нормализованное сообщение пользователя",
  "allowed_actions": ["read", "draft", "classify"],
  "forbidden_actions": ["send_without_review", "change_payment"],
  "expected_output": {
    "intent": "technical|support|sales|unknown",
    "confidence": 0.0,
    "needs_human_review": true,
    "sources": []
  }
}

Критерий готовности ¶

есть свежий backup базы и проверено значение N8N_ENCRYPTION_KEY
web, worker, queue и database используют согласованные переменные окружения
после изменения проверены логи, healthcheck и запуск критичных workflow
записан rollback-план с командами и ответственным

Связанные материалы

Ответы на частые вопросы

Какой режим binary data выбрать для n8n?

Для простого одиночного Docker-инстанса чаще подходит filesystem. Для queue mode безопаснее database или внешнее хранилище, потому что workers должны видеть те же данные.

Почему n8n падает при обработке PDF или вложений?

Часто файл хранится или копируется в памяти. Нужно включить подходящий binary data mode, ограничить размер файлов и не передавать binary-поле через все ноды без необходимости.

Нужно ли включать S3 для binary data?

S3 полезен при большом количестве файлов, но требует правильной настройки bucket, lifecycle policy и совместимости. Для небольшого проекта filesystem может быть проще.