Task runners в n8n: Python, JavaScript, изоляция Code node и безопасный запуск ¶

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

Code node — мощная вещь: можно трансформировать items, чистить данные, готовить payload, работать с JSON и писать Python/JavaScript. Но именно пользовательский код чаще всего становится риском: он может зависнуть, съесть память, случайно вывести секрет или выполнить слишком тяжёлую операцию. Task runners нужны, чтобы выполнение кода было отделено от основного процесса n8n.

В production лучше использовать внешний runner-процесс, а не полагаться на внутренний режим. Тогда main instance остаётся редактором и оркестратором, а пользовательский код исполняется отдельно.

Что делает task runner ¶

n8n main / worker → task broker → task runner → результат обратно в execution

Runner получает задачу от n8n, исполняет код и возвращает результат. Для команды эксплуатации это важная граница: можно ограничить ресурсы runner, обновлять его отдельно и не давать пользовательскому коду ломать основной контейнер.

Когда task runners действительно нужны ¶

Минимальная схема Docker Compose ¶

Названия переменных могут меняться между версиями n8n, поэтому сверяйте их с документацией вашей версии. Смысл настройки такой: включить task runners, указать broker, общий auth token и отдельный runner-сервис.

services:
  n8n:
    image: n8nio/n8n:latest
    environment:
      N8N_RUNNERS_ENABLED: "true"
      N8N_RUNNERS_MODE: external
      N8N_RUNNERS_AUTH_TOKEN: ${N8N_RUNNERS_AUTH_TOKEN}
      N8N_RUNNERS_BROKER_LISTEN_ADDRESS: 0.0.0.0
    ports:
      - "5678:5678"
    restart: unless-stopped

  n8n-runner:
    image: n8nio/runners:latest
    environment:
      N8N_RUNNERS_AUTH_TOKEN: ${N8N_RUNNERS_AUTH_TOKEN}
      N8N_RUNNERS_TASK_BROKER_URI: http://n8n:5679
    depends_on:
      - n8n
    restart: unless-stopped

Не публикуйте broker port наружу. Он должен быть доступен runner внутри Docker network или Kubernetes pod/network, а не всему интернету.

Как писать Code node под runner ¶

• Не делайте бесконечные циклы. У каждого workflow должен быть лимит items и понятный timeout.
• Не храните секреты в коде. Берите токены из credentials или env, но не выводите их в лог.
• Возвращайте массив items в ожидаемом формате, не меняйте структуру хаотично.
• Для тяжёлой обработки файлов лучше сохранять файл в S3/MinIO и передавать ссылку/metadata.
• Пишите малые функции: normalize, validate, map, enrich. Не превращайте Code node в микросервис.

Smoke-test для JavaScript ¶

return items.map((item, index) => ({
  json: {
    ...item.json,
    normalized_at: new Date().toISOString(),
    row_number: index + 1
  }
}));

После запуска проверьте логи runner и execution data. Если код выполнился, но output пустой, проблема чаще в формате возвращаемых items, а не в runner.

Smoke-test для Python ¶

from datetime import datetime

for item in items:
    item["json"]["normalized_at"] = datetime.utcnow().isoformat() + "Z"
    item["json"]["source"] = item["json"].get("source", "n8n")

return items

Python особенно чувствителен к версии n8n и режиму runner. Если Python не стартует, не лечите это случайными пакетами в main container: проверьте, как именно ваша версия n8n поддерживает Python Code node и runners.

Безопасность ¶

Типовые ошибки ¶

• Runner не подключается. Проверьте token, broker URI, Docker network и доступность порта broker.
• Code node работает локально, но падает в production. Сравните версии n8n и runner, режим исполнения и доступные зависимости.
• Execution зависает. Ограничьте batch size, уберите тяжёлую обработку из одного запуска, проверьте логи runner.
• Output потерял items. Проверьте, что Code node возвращает массив items, а не один объект.

Связанные инструкции ¶

• Code node: JavaScript и Python
• Execute Command и безопасность
• n8n в Kubernetes и Helm
• Queue mode и workers

docker compose ps
docker compose logs --tail=200 n8n
docker compose logs --tail=200 n8n-worker
printenv | grep -E 'N8N_|WEBHOOK_|DB_|QUEUE_'
# перед изменениями: backup базы + проверка N8N_ENCRYPTION_KEY