first commit

2026-05-04 16:54:53 +07:00
commit 49b389ed53
20 changed files with 4977 additions and 0 deletions
@@ -0,0 +1,167 @@
+# 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 при старте |
+
+---
+
+## Быстрый старт
+
+```bash
+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 ищет их на хосте.
+
+```bash
+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
+
+> (Опционально) Дать права
+```sh
+sudo chmod 777 /home/bbr/portainer/data/compose
+```
+
+### Документация
+
+- [Установка Docker Compose](https://docs.n8n.io/hosting/installation/server-setups/docker-compose/)
+- [Stacks in Portainer](https://docs.portainer.io/user/docker/stacks/add)
+- [Git repository deployment](https://docs.portainer.io/user/docker/stacks/add#option-3-git-repository)
+
+---
+
+## Встроенные 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](https://docs.n8n.io/api/authentication/)
+- [n8n CLI commands](https://docs.n8n.io/hosting/cli-commands/)
+- [Автоимпорт workflows](https://docs.n8n.io/hosting/cli-commands/#import-workflows-and-credentials)
+
+---
+
+## Политика хранения данных
+
+| Что | Лимит |
+|---|---|
+| Данные выполнений | 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](https://docs.n8n.io/hosting/scaling/execution-data/)
+- [Executions environment variables](https://docs.n8n.io/hosting/configuration/environment-variables/executions/)
+- [Workflow history](https://docs.n8n.io/workflows/history/)
+- [Логирование](https://docs.n8n.io/hosting/logging-monitoring/logging/)
+- [Environment Variables (все)](https://docs.n8n.io/hosting/configuration/environment-variables/)
+- [Task Runners](https://docs.n8n.io/hosting/configuration/task-runners/)
+- [Queue mode](https://docs.n8n.io/hosting/scaling/queue-mode/)
+- [Мониторинг n8n](https://docs.n8n.io/hosting/logging-monitoring/monitoring/)
+- [Prometheus](https://docs.n8n.io/hosting/configuration/configuration-examples/prometheus/)
+- [Аудит безопасности](https://docs.n8n.io/hosting/securing/security-audit/)