n8n_stack/README.md

n8n Docker Stack

Self-hosted n8n с PostgreSQL, Redis, Task Runners, Prometheus и Grafana — готовый production-стек с минимальными усилиями на настройку

Зачем

• Изоляция — отключена телеметрия, шаблоны и внешние запросы к n8n.io
• Производительность — queue mode с workers, внешний task runner для JS и Python
• Надёжность — PostgreSQL вместо SQLite, Redis как брокер очередей
• Наблюдаемость — Prometheus + Grafana с готовым дашбордом
• Воспроизводимость — автоимпорт workflows и credentials при каждом старте
• Контроль версий — встроенные workflows для экспорта и коммита в git

---

Сервисы

Сервис	Порт	Описание
n8n	5678	Основной сервер
n8n-worker-1	—	Worker для queue mode
n8n-runner-1	—	Внешний раннер JS + Python
postgres	5433	База данных
redis (Valkey)	—	Очередь Bull
prometheus	9090	Сбор метрик
grafana	3000	Дашборды
fix-permissions	—	Однократная правка прав (uid 1000)
n8n-import	—	Автоимпорт workflows и credentials при старте

---

Быстрый старт

cp .env.example .env
# Заполнить .env

docker compose up -d

Стек запускается без .env — все переменные имеют дефолты в docker-compose.yml.

---

Деплой через Portainer

Portainer позволяет управлять стеком через UI без прямого доступа к серверу.

Важно: деплой через «URL» (одиночная ссылка на compose-файл) не работает — Portainer не скачивает вспомогательные файлы (prometheus.yml, grafana/ и т.д.). Использовать только Repository.

Требования

Portainer должен быть запущен так, чтобы путь к данным на хосте и внутри контейнера совпадал. Иначе Docker Engine не найдёт файлы клонированного репозитория — Portainer передаёт ему свои внутренние пути, а Docker ищет их на хосте.

docker stop portainer && docker rm portainer

PORTAINER_DATA="$HOME/portainer/data"
mkdir -p "$PORTAINER_DATA"

docker run -d \
  -p 9443:9443 \
  --name portainer \
  --restart=always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v "$PORTAINER_DATA":"$PORTAINER_DATA" \
  portainer/portainer-ce:latest \
  --data "$PORTAINER_DATA"

Флаг --data указывает Portainer хранить данные по тому же пути, что смонтирован с хоста — пути совпадают, Docker Engine находит файлы.

Шаги

1. Stacks → Add stack → Repository
2. Repository URL: адрес репозитория
3. Compose path: docker-compose.yml
4. Добавить переменные окружения или указать путь к .env Важно правильно настроить WEBHOOK_URL

# URL для вебхуков (адрес, по которому n8n доступен снаружи)
WEBHOOK_URL=http://YOUR_SERVER_IP:5678

⚠️ Важно: Если указан неверный адрес, то Form Data и вебхуки не будут работать

5. Deploy the stack

(Опционально) Дать права

sudo chmod 777 /home/bbr/portainer/data/compose

Документация

• Установка Docker Compose
• Stacks in Portainer
• Git repository deployment

---

Встроенные workflows

В n8n/backup/workflows/ лежат служебные workflow, которые импортируются автоматически при каждом старте.

Файл	Назначение
Backup_Workflows.json	Экспорт всех workflow в n8n/shared/
Backup_Сredentials.json	Экспорт всех credentials в n8n/shared/
Git_Commit_Workflows.json	Коммит экспортированных файлов в git
Git_Pull_Workflows.json	Pull изменений из git-репозитория

Настройка credentials

Встроенные workflows обращаются к API локального n8n. Для работы необходимо:

1. Сгенерировать API ключ: n8n → Settings → API → Create an API key
2. Создать credentials типа n8n API:
   • URL: http://n8n:5678/api/v1
   • API Key: ключ из шага 1
3. Сохранить credentials в файл n8n/backup/credentials/n8n_local.json

Защита credentials от перезаписи

n8n CLI не имеет встроенного --skipExisting для импорта credentials. Скрипт реализует это через маркер-файлы в n8n_storage volume (/home/node/.n8n/imported/).

Тип	Поведение при повторном деплое
Credentials	Импортируются один раз, затем пропускаются
Workflows	Перезаписываются всегда

Принудительный переимпорт — задать FORCE_IMPORT=true в env сервиса n8n-import.

Для добавления своих workflow при старте — положить JSON в n8n/backup/workflows/ или n8n/backup/credentials/.

Документация

• n8n Public API / Authentication
• n8n CLI commands
• Автоимпорт workflows

---

Политика хранения данных

Что	Лимит
Данные выполнений	7 дней / 5 000 записей
История версий workflow	30 дней
Логи n8n (файлы)	10 файлов × 20 MB = ~200 MB
Логи Docker (все сервисы)	3–5 файлов × 5–10 MB на сервис
Prometheus TSDB	15 дней / 1 GB
Redis	256 MB max (LRU)

Бинарные данные в n8n/shared/ автоматически не очищаются — при активном использовании нод Read/Write Files настроить очистку по расписанию.

Документация

• Execution data — pruning и retention
• Executions environment variables
• Workflow history
• Логирование
• Environment Variables (все)
• Task Runners
• Queue mode
• Мониторинг n8n
• Prometheus
• Аудит безопасности