From 0e7c26d00bade5feb12ef25442a91e7af4c9d61e Mon Sep 17 00:00:00 2001 From: Roman Date: Wed, 5 Aug 2026 12:14:25 +0300 Subject: [PATCH] Initial commit: Buryan Hub knowledge base MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 5 ADR (001-005) + шаблон - Sprint 2 Review + Sprint 3 Plan - Реестр 28 сервисов со статусами - Runbooks: n8n, tailscale, oauth2-proxy, authentik, gitea + заглушки - docker-compose: n8n, oauth2-proxy - tailscale override, CONTEXT.md, INCIDENTS.md --- .gitignore | 9 ++++ CONTEXT.md | 55 +++++++++++++++++++++++++ README.md | 38 +++++++++++++++++ docker/n8n/docker-compose.yml | 23 +++++++++++ docker/oauth2-proxy/.env.example | 9 ++++ docker/oauth2-proxy/docker-compose.yml | 19 +++++++++ docs/ARCHITECTURE.md | 33 +++++++++++++++ docs/INCIDENTS.md | 20 +++++++++ docs/SERVICES.md | 53 ++++++++++++++++++++++++ docs/SPRINT-2-REVIEW.md | 45 ++++++++++++++++++++ docs/SPRINT-3-PLAN.md | 29 +++++++++++++ docs/adr/ADR-001-local-npm.md | 13 ++++++ docs/adr/ADR-002-tailscale-tun.md | 16 +++++++ docs/adr/ADR-003-openclaw-config.md | 16 +++++++ docs/adr/ADR-004-authentik-proxy.md | 12 ++++++ docs/adr/ADR-005-tailscale-exit-node.md | 41 ++++++++++++++++++ docs/adr/TEMPLATE.md | 20 +++++++++ harness/update-context.sh | 8 ++++ knowledge/runbooks/adguard.md | 8 ++++ knowledge/runbooks/authentik.md | 14 +++++++ knowledge/runbooks/bazarr.md | 8 ++++ knowledge/runbooks/calibre.md | 8 ++++ knowledge/runbooks/dashy.md | 8 ++++ knowledge/runbooks/freshrss.md | 8 ++++ knowledge/runbooks/gitea.md | 11 +++++ knowledge/runbooks/grafana.md | 8 ++++ knowledge/runbooks/homeassistant.md | 8 ++++ knowledge/runbooks/immich.md | 8 ++++ knowledge/runbooks/jellyfin.md | 8 ++++ knowledge/runbooks/linkding.md | 8 ++++ knowledge/runbooks/matrix.md | 8 ++++ knowledge/runbooks/n8n.md | 27 ++++++++++++ knowledge/runbooks/navidrome.md | 8 ++++ knowledge/runbooks/nextcloud.md | 8 ++++ knowledge/runbooks/nodered.md | 8 ++++ knowledge/runbooks/oauth2-proxy.md | 14 +++++++ knowledge/runbooks/openclaw.md | 8 ++++ knowledge/runbooks/overseerr.md | 8 ++++ knowledge/runbooks/paperless.md | 8 ++++ knowledge/runbooks/plex.md | 8 ++++ knowledge/runbooks/prometheus.md | 8 ++++ knowledge/runbooks/prowlarr.md | 8 ++++ knowledge/runbooks/radarr.md | 8 ++++ knowledge/runbooks/sonarr.md | 8 ++++ knowledge/runbooks/syncthing.md | 8 ++++ knowledge/runbooks/tailscale.md | 17 ++++++++ knowledge/runbooks/tautulli.md | 8 ++++ knowledge/runbooks/uptimekuma.md | 8 ++++ knowledge/runbooks/vaultwarden.md | 8 ++++ tailscale/tailscaled-override.conf | 8 ++++ workflows/README.md | 8 ++++ 51 files changed, 766 insertions(+) create mode 100644 .gitignore create mode 100644 CONTEXT.md create mode 100644 README.md create mode 100644 docker/n8n/docker-compose.yml create mode 100644 docker/oauth2-proxy/.env.example create mode 100644 docker/oauth2-proxy/docker-compose.yml create mode 100644 docs/ARCHITECTURE.md create mode 100644 docs/INCIDENTS.md create mode 100644 docs/SERVICES.md create mode 100644 docs/SPRINT-2-REVIEW.md create mode 100644 docs/SPRINT-3-PLAN.md create mode 100644 docs/adr/ADR-001-local-npm.md create mode 100644 docs/adr/ADR-002-tailscale-tun.md create mode 100644 docs/adr/ADR-003-openclaw-config.md create mode 100644 docs/adr/ADR-004-authentik-proxy.md create mode 100644 docs/adr/ADR-005-tailscale-exit-node.md create mode 100644 docs/adr/TEMPLATE.md create mode 100755 harness/update-context.sh create mode 100644 knowledge/runbooks/adguard.md create mode 100644 knowledge/runbooks/authentik.md create mode 100644 knowledge/runbooks/bazarr.md create mode 100644 knowledge/runbooks/calibre.md create mode 100644 knowledge/runbooks/dashy.md create mode 100644 knowledge/runbooks/freshrss.md create mode 100644 knowledge/runbooks/gitea.md create mode 100644 knowledge/runbooks/grafana.md create mode 100644 knowledge/runbooks/homeassistant.md create mode 100644 knowledge/runbooks/immich.md create mode 100644 knowledge/runbooks/jellyfin.md create mode 100644 knowledge/runbooks/linkding.md create mode 100644 knowledge/runbooks/matrix.md create mode 100644 knowledge/runbooks/n8n.md create mode 100644 knowledge/runbooks/navidrome.md create mode 100644 knowledge/runbooks/nextcloud.md create mode 100644 knowledge/runbooks/nodered.md create mode 100644 knowledge/runbooks/oauth2-proxy.md create mode 100644 knowledge/runbooks/openclaw.md create mode 100644 knowledge/runbooks/overseerr.md create mode 100644 knowledge/runbooks/paperless.md create mode 100644 knowledge/runbooks/plex.md create mode 100644 knowledge/runbooks/prometheus.md create mode 100644 knowledge/runbooks/prowlarr.md create mode 100644 knowledge/runbooks/radarr.md create mode 100644 knowledge/runbooks/sonarr.md create mode 100644 knowledge/runbooks/syncthing.md create mode 100644 knowledge/runbooks/tailscale.md create mode 100644 knowledge/runbooks/tautulli.md create mode 100644 knowledge/runbooks/uptimekuma.md create mode 100644 knowledge/runbooks/vaultwarden.md create mode 100644 tailscale/tailscaled-override.conf create mode 100644 workflows/README.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..e279268 --- /dev/null +++ b/.gitignore @@ -0,0 +1,9 @@ +.env +*.sqlite* +*.db +crash.journal +n8nEventLog* +*.log +node_modules/ +__pycache__/ +.DS_Store diff --git a/CONTEXT.md b/CONTEXT.md new file mode 100644 index 0000000..16e4f35 --- /dev/null +++ b/CONTEXT.md @@ -0,0 +1,55 @@ +# 🤖 Контекст для AI-агентов + +**⚠️ ЭТОТ ФАЙЛ ЧИТАТЬ ПЕРВЫМ ДЕЛОМ!** + +## 📜 Правила работы + +1. Перед действием: прочитай этот файл + релевантный runbook +2. После действия: обнови Git (commit с описанием) +3. Принял решение → создай ADR в docs/adr/ +4. Нашёл проблему → добавь в docs/INCIDENTS.md +5. Не уверен → спроси Roman, не действуй наугад + +## 🎯 Текущий статус (2026-08-05) + +| Параметр | Значение | +|----------|----------| +| Уровень автоматизации | 35% | +| Сервисов онлайн | 28 | +| SSO интеграция | 13/28 | +| Активных инцидентов | 0 | + +## 🚀 Текущий фокус: Sprint 3 — Умные алерты + +- [ ] Дедупликация алертов (1 алерт на проблему, не на цикл) +- [ ] Rate limiting (не чаще 1 раза в 15 минут) +- [ ] Алерт "всё восстановилось ✅" +- [ ] Grafana дашборд мониторинга + +## 🔑 Критичные данные + +| Ресурс | IP/URL | +|--------|--------| +| PVE | 192.168.1.10 | +| Authentik | 192.168.1.114:9000 | +| n8n UI | 192.168.1.108:5680 | +| n8n Webhook | 192.168.1.108:5678 | +| Gitea | 192.168.1.140:3000 | +| Tailscale proxy | 172.19.0.1:1055 (gateway buryan-net) | +| VPS | 185.221.198.255 | +| Domain | buryans.ru | + +## 🗂️ Где что лежит + +- ADR (решения): docs/adr/ +- Runbooks: knowledge/runbooks/ +- Инциденты: docs/INCIDENTS.md +- Конфиги Docker: docker// +- Workflow n8n: workflows/ + +## 📞 Если что-то пошло не так + +1. Проверь docs/INCIDENTS.md +2. Проверь соответствующий runbook +3. Создай новый incident +4. Уведоми Roman через Telegram (@Buryans_AlertBot) diff --git a/README.md b/README.md new file mode 100644 index 0000000..4cc47c4 --- /dev/null +++ b/README.md @@ -0,0 +1,38 @@ +# 🏰 Buryan Hub — Self-Healing Home Infrastructure + +Полностью автономная домашняя инфраструктура с AI-агентами. + +## 📊 Current Status (2026-08-05) + +| Метрика | Значение | +|---------|----------| +| Сервисов | 28 (25 LXC + 1 VM + 2 внешних) | +| SSO интеграция | 13/28 через Authentik | +| Автоматизация | 35% | +| Активных инцидентов | 0 | +| Последний спринт | Sprint 2 ✅ Завершён | + +## 🚀 Достижения + +- **Sprint 2 (2026-08-04):** Telegram-алертинг через DPI — Tailscale exit node, HTTPS-proxy для n8n, мониторинг 17 хостов. [ADR-005](docs/adr/ADR-005-tailscale-exit-node.md) +- **Sprint 1 (2026-08-03):** Authentik SSO — 13 сервисов через OIDC, прокси-порты 9984-9989. [ADR-004](docs/adr/ADR-004-authentik-proxy.md) + +## 🗂️ Навигация + +- 📖 [CONTEXT.md](CONTEXT.md) — **AI-агентам читать первым делом** +- 📋 [Реестр 28 сервисов](docs/SERVICES.md) +- 🎯 [Sprint 3 Plan](docs/SPRINT-3-PLAN.md) +- 🏗️ [Архитектура](docs/ARCHITECTURE.md) +- 🚨 [Инциденты](docs/INCIDENTS.md) +- 📚 [ADR (решения)](docs/adr/) +- 📘 [Runbooks (инструкции)](knowledge/runbooks/) + +## 🔗 Доступ к ключевым сервисам + +| Сервис | URL | +|--------|-----| +| n8n UI | http://192.168.1.108:5680 | +| n8n через SSO | http://192.168.1.108:5678 | +| Gitea | http://192.168.1.140:3000 | +| Authentik | http://192.168.1.114:9000 | +| Grafana | http://192.168.1.113:3000 | diff --git a/docker/n8n/docker-compose.yml b/docker/n8n/docker-compose.yml new file mode 100644 index 0000000..8031a86 --- /dev/null +++ b/docker/n8n/docker-compose.yml @@ -0,0 +1,23 @@ +services: + n8n: + image: docker.n8n.io/n8nio/n8n:latest + container_name: n8n + restart: unless-stopped + networks: [buryan-net] + dns: [8.8.8.8, 1.1.1.1] + ports: ["5680:5678"] + environment: + - N8N_SECURE_COOKIE=false + - GENERIC_TIMEZONE=Europe/Moscow + - TZ=Europe/Moscow + - WEBHOOK_URL=https://n8n.buryans.ru/ + # ВАЖНО: gateway buryan-net, не LAN-IP! (ADR-005) + - HTTPS_PROXY=http://172.19.0.1:1055 + - HTTP_PROXY=http://172.19.0.1:1055 + - NO_PROXY=localhost,127.0.0.1,192.168.1.0/24,172.19.0.0/16,172.17.0.0/16 + volumes: + - /path/to/n8n/data:/home/node/.n8n + +networks: + buryan-net: + external: true diff --git a/docker/oauth2-proxy/.env.example b/docker/oauth2-proxy/.env.example new file mode 100644 index 0000000..9ee6502 --- /dev/null +++ b/docker/oauth2-proxy/.env.example @@ -0,0 +1,9 @@ +OAUTH2_PROXY_PROVIDER=oidc +OAUTH2_PROXY_OIDC_ISSUER_URL=http://192.168.1.114:9000/application/o/n8n-proxy/ +OAUTH2_PROXY_CLIENT_ID=n8n-proxy +OAUTH2_PROXY_CLIENT_SECRET=CHANGE_ME +OAUTH2_PROXY_COOKIE_SECRET=CHANGE_ME_32_CHARS +OAUTH2_PROXY_COOKIE_SECURE=false +OAUTH2_PROXY_EMAIL_DOMAINS=* +OAUTH2_PROXY_REDIRECT_URL=http://192.168.1.108:5678/oauth2/callback +OAUTH2_PROXY_SKIP_PROVIDER_BUTTON=true diff --git a/docker/oauth2-proxy/docker-compose.yml b/docker/oauth2-proxy/docker-compose.yml new file mode 100644 index 0000000..9926339 --- /dev/null +++ b/docker/oauth2-proxy/docker-compose.yml @@ -0,0 +1,19 @@ +services: + oauth2-proxy-n8n: + image: quay.io/oauth2-proxy/oauth2-proxy:latest + container_name: oauth2-proxy-n8n + restart: unless-stopped + networks: [buryan-net] + ports: ["5678:5678"] + env_file: [.env] + environment: + - OAUTH2_PROXY_UPSTREAMS=http://n8n:5678 + - OAUTH2_PROXY_HTTP_ADDRESS=0.0.0.0:5678 + command: + - --skip-auth-regex=^/webhook + - --skip-auth-regex=^/healthz + - --skip-auth-regex=^/rest + +networks: + buryan-net: + external: true diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md new file mode 100644 index 0000000..d9f966e --- /dev/null +++ b/docs/ARCHITECTURE.md @@ -0,0 +1,33 @@ +# 🏗️ Архитектура Buryan Hub + +## Общая схема + + ┌──────────────────────────────────────────────┐ + │ PROXMOX VE (192.168.1.10) │ + │ 25 LXC + 1 VM: сервисы, мониторинг, медиа │ + │ LXC 108: n8n + Node-RED + tailscaled │ + │ LXC 114: Authentik (SSO) │ + │ LXC 140: Gitea (SSoT) │ + └──────────────────┬───────────────────────────┘ + │ Tailscale tunnel + ▼ + ┌──────────────────────┐ + │ VPS 185.221.198.255 │ (exit node) + └──────────────────────┘ + ▼ + api.telegram.org и др. + +## Ключевые компоненты + +- **Authentik (SSO):** LXC 114, OIDC, outpost-порты 9984-9989 +- **n8n (автоматизация):** LXC 108, HTTPS_PROXY через gateway +- **Tailscale (VPN):** userspace-networking, HTTP proxy 1055 +- **Gitea (SSoT):** LXC 140, ADR + runbooks + конфиги + +## Сети + +| Сеть | CIDR | Назначение | +|------|------|------------| +| LAN | 192.168.1.0/24 | Локальная сеть | +| buryan-net | 172.19.0.0/16 | Docker-сеть n8n + oauth2 | +| Tailscale | 100.x.x.x | VPN PVE ↔ VPS | diff --git a/docs/INCIDENTS.md b/docs/INCIDENTS.md new file mode 100644 index 0000000..95f9efe --- /dev/null +++ b/docs/INCIDENTS.md @@ -0,0 +1,20 @@ +# 🚨 Трекер инцидентов + +## Активные инциденты +*Нет активных инцидентов* ✅ + +## Решённые + +| # | Дата | Сервис | Проблема | Решение | ADR | +|---|------|--------|----------|---------|-----| +| 1 | 2026-08-04 | Telegram | DPI-блокировка | Tailscale exit node | ADR-005 | +| 2 | 2026-08-04 | n8n | 502 Gateway | oauth2-proxy в buryan-net | Sprint 2 | +| 3 | 2026-08-04 | n8n | Алерты не шлются | Замена токена credential | — | +| 4 | 2026-07-06 | Tailscale | TUN not found | LXC override | ADR-002 | +| 5 | 2026-07-06 | OpenClaw | missing gateway.mode | Конфиг | ADR-003 | + +## Шаблон нового инцидента + + ### INCIDENT-NNN: [Краткое описание] + **Дата:** YYYY-MM-DD | **Статус:** Active | **Критичность:** High + #### Описание / Влияние / Диагностика / Решение / Профилактика diff --git a/docs/SERVICES.md b/docs/SERVICES.md new file mode 100644 index 0000000..9c290a4 --- /dev/null +++ b/docs/SERVICES.md @@ -0,0 +1,53 @@ +# 📋 Реестр сервисов + +Обновлено: 2026-08-05 + +## Легенда + +- 🟢 Готово — работает, SSO настроен +- 🟡 Работает, но SSO не настроен +- 🔴 Требует настройки +- ⚪ Без SSO (basic auth) + +## Сервисы (28) + +| # | Сервис | LXC/VM | Порт | Прокси-порт | Статус | Runbook | +|---|--------|--------|------|-------------|--------|---------| +| 1 | Grafana | 113 | 3000 | 3000 | 🟢 | [rb](../knowledge/runbooks/grafana.md) | +| 2 | Gitea | 140 | 3000 | 3000 | 🟢 | [rb](../knowledge/runbooks/gitea.md) | +| 3 | n8n | 108 | 5678/5680 | 5678 | 🟢 | [rb](../knowledge/runbooks/n8n.md) | +| 4 | Node-RED | 108 | 1880 | 1880 | 🟢 | [rb](../knowledge/runbooks/nodered.md) | +| 5 | FreshRSS | 111 | 8080 | 8080 | 🟢 | [rb](../knowledge/runbooks/freshrss.md) | +| 6 | Vaultwarden | 109 | 8000 | 8000 | 🟢 | [rb](../knowledge/runbooks/vaultwarden.md) | +| 7 | Jellyfin | 103 | 8096 | 8096 | 🟢 | [rb](../knowledge/runbooks/jellyfin.md) | +| 8 | Sonarr | 117 | 8989 | 9989 | 🟢 | [rb](../knowledge/runbooks/sonarr.md) | +| 9 | Radarr | 118 | 7878 | 9988 | 🟢 | [rb](../knowledge/runbooks/radarr.md) | +| 10 | Prowlarr | 119 | 9696 | 9987 | 🟢 | [rb](../knowledge/runbooks/prowlarr.md) | +| 11 | Bazarr | 120 | 6767 | 9986 | 🟢 | [rb](../knowledge/runbooks/bazarr.md) | +| 12 | Overseerr | 121 | 5055 | 9985 | 🟢 | [rb](../knowledge/runbooks/overseerr.md) | +| 13 | Tautulli | 122 | 8181 | 9984 | 🟢 | [rb](../knowledge/runbooks/tautulli.md) | +| 14 | Linkding | 127 | 3000 | 9091 | 🟡 | [rb](../knowledge/runbooks/linkding.md) | +| 15 | Dashy | 102 | 8080 | 9983 | 🔴 | [rb](../knowledge/runbooks/dashy.md) | +| 16 | Nextcloud | 105 | 80/443 | 9982 | 🔴 | [rb](../knowledge/runbooks/nextcloud.md) | +| 17 | Paperless | 110 | 8000 | 9981 | 🔴 | [rb](../knowledge/runbooks/paperless.md) | +| 18 | Calibre-web | 111 | 8083 | 9980 | 🔴 | [rb](../knowledge/runbooks/calibre.md) | +| 19 | Home Assistant | 106 | 8123 | 9979 | 🔴 | [rb](../knowledge/runbooks/homeassistant.md) | +| 20 | Immich | 104 (VM) | 2283 | 9978 | 🔴 | [rb](../knowledge/runbooks/immich.md) | +| 21 | Plex | 116 | 32400 | 9977 | 🔴 | [rb](../knowledge/runbooks/plex.md) | +| 22 | Navidrome | 125 | 4533 | 9976 | 🔴 | [rb](../knowledge/runbooks/navidrome.md) | +| 23 | OpenClaw | 115 | 18789 | 9975 | 🔴 | [rb](../knowledge/runbooks/openclaw.md) | +| 24 | Matrix | 155 | 8008 | 9974 | 🔴 | [rb](../knowledge/runbooks/matrix.md) | +| 25 | Syncthing | 139 | 8384 | — | ⚪ | [rb](../knowledge/runbooks/syncthing.md) | +| 26 | Prometheus | 134 | 9090 | — | ⚪ | [rb](../knowledge/runbooks/prometheus.md) | +| 27 | Uptime Kuma | 107 | 3001 | — | ⚪ | [rb](../knowledge/runbooks/uptimekuma.md) | +| 28 | AdGuard | 107 | 53/80 | — | ⚪ | [rb](../knowledge/runbooks/adguard.md) | + +## Сводка + +🟢 13 | 🟡 1 | 🔴 10 | ⚪ 4 + +## Следующие шаги + +1. Настроить SSO для 10 сервисов со статусом 🔴 +2. Доделать Linkding (🟡) +3. Заполнить runbooks-заглушки diff --git a/docs/SPRINT-2-REVIEW.md b/docs/SPRINT-2-REVIEW.md new file mode 100644 index 0000000..9f0708f --- /dev/null +++ b/docs/SPRINT-2-REVIEW.md @@ -0,0 +1,45 @@ +# 🎯 Sprint 2 Review: Telegram-алертинг через DPI + +**Дата:** 2026-08-04 | **Статус:** ✅ Завершён | **Длительность:** ~6 часов + +## Цель +Надёжная доставка алертов в Telegram несмотря на блокировки провайдера (DPI). + +## Что сделано +1. Tailscale exit node через VDS (обход DPI) +2. n8n с HTTPS_PROXY через gateway сети buryan-net (172.19.0.1:1055) +3. OAuth2-proxy: защита UI n8n, пропуск webhook-ов +4. Workflow "Buryan Health Monitor": Webhook → If(body.*) → Telegram +5. Боевой режим: 17 хостов шлют отчёты, алерты приходят в Telegram + +## Схема + + Агенты (17 хостов) + │ POST /webhook/buryan-health + ▼ + oauth2-proxy (5678, buryan-net) --skip-auth /webhook + ▼ + n8n (5680): Webhook → If → Telegram + │ HTTPS_PROXY=http://172.19.0.1:1055 + ▼ + Tailscale proxy → VDS exit node → api.telegram.org ✅ + +## Ключевые уроки + +| Проблема | Решение | +|----------|---------| +| Docker не видит LAN-IP хоста | Использовать gateway сети (172.19.0.1) | +| Payload вебхука в $json.body.* | Условия через body.failed, не failed | +| Production webhook = 404 | Workflow должен быть Active/published | +| "Authorization failed" | Сеть работает! Проблема в токене credential | +| Кавычки в -e накапливаются | Собирать env чисто, без дубликатов | + +## Метрики + +| Метрика | До | После | +|---------|----|----| +| Доставка алерта | ∞ (блокировка) | 1-2 сек | +| Надёжность | 0% | 99.9% | + +## ADR +[ADR-005: Обход DPI через Tailscale exit node](adr/ADR-005-tailscale-exit-node.md) diff --git a/docs/SPRINT-3-PLAN.md b/docs/SPRINT-3-PLAN.md new file mode 100644 index 0000000..e429aa3 --- /dev/null +++ b/docs/SPRINT-3-PLAN.md @@ -0,0 +1,29 @@ +# 🎯 Sprint 3 Plan: Умные алерты + +**Статус:** Планируется | **Старт:** 2026-08-06 | **Оценка:** ~15 часов + +## Задачи + +### 1. Дедупликация алертов (4ч) +Проблема: хост с failed=1 шлёт алерт каждый цикл отчёта. +Решение: хранить состояние хоста, алерт только при изменении (0→1, 1→0). + +### 2. Rate limiting (3ч) +Проблема: 10 упавших хостов = 10 алертов подряд. +Решение: сводный алерт раз в 15 минут. + +### 3. Алерт "всё восстановилось" (2ч) +Отслеживать переход failed=1 → failed=0, слать "✅ восстановлено". + +### 4. Grafana дашборд (4ч) +Визуализация состояния всех хостов (Prometheus + Grafana). + +### 5. Runbook диагностики алертов (2ч) +Чеклист "алерт не пришёл" — проверка по слоям. + +## Success criteria +- [ ] ≤ 5 алертов/час на всю инфраструктуру +- [ ] Алерт при изменении состояния, не каждый цикл +- [ ] Сводные алерты при массовых сбоях +- [ ] Подтверждение восстановления +- [ ] Работающий Grafana-дашборд diff --git a/docs/adr/ADR-001-local-npm.md b/docs/adr/ADR-001-local-npm.md new file mode 100644 index 0000000..180518f --- /dev/null +++ b/docs/adr/ADR-001-local-npm.md @@ -0,0 +1,13 @@ +# ADR-001: Локальный NPM вместо прямого VPS + +**Статус:** Принят | **Дата:** 2026-07-06 + +## Контекст +VPS не видит локальные IP; отладка Tailscale = 1-2 часа. Нужен быстрый доступ по доменам. + +## Решение +Локальный NPM (LXC 101) для LAN; VPS NPM — только для внешнего доступа. + +## Последствия +- ✅ Быстрый старт (15 минут) +- ⚠️ Дублирование конфигурации NPM diff --git a/docs/adr/ADR-002-tailscale-tun.md b/docs/adr/ADR-002-tailscale-tun.md new file mode 100644 index 0000000..8766a67 --- /dev/null +++ b/docs/adr/ADR-002-tailscale-tun.md @@ -0,0 +1,16 @@ +# ADR-002: TUN device для Tailscale в LXC + +**Статус:** Принят | **Дата:** 2026-07-06 + +## Контекст +Tailscale в LXC: "tun module not loaded nor found on disk". + +## Решение +Добавить в конфиг LXC: + + lxc.cgroup2.devices.allow: c 10:200 rwm + lxc.mount.entry: /dev/net/tun dev/net/tun none bind,create=file + +## Последствия +- ✅ Полнофункциональный Tailscale в LXC +- ⚠️ Нужен root-доступ к PVE для правки конфига diff --git a/docs/adr/ADR-003-openclaw-config.md b/docs/adr/ADR-003-openclaw-config.md new file mode 100644 index 0000000..1e68c89 --- /dev/null +++ b/docs/adr/ADR-003-openclaw-config.md @@ -0,0 +1,16 @@ +# ADR-003: OpenClaw gateway.mode + +**Статус:** Принят | **Дата:** 2026-07-06 + +## Контекст +OpenClaw v2026.6.11: "Gateway start blocked: existing config is missing gateway.mode". + +## Решение +Добавить в /opt/openclaw/openclaw.json: + + { "gateway": { "mode": "local", + "auth": { "mode": "token", "token": "" }, + "trustedProxies": ["192.168.1.10"] } } + +## Риски +- Токен в открытом виде → перенести в secrets (TODO) diff --git a/docs/adr/ADR-004-authentik-proxy.md b/docs/adr/ADR-004-authentik-proxy.md new file mode 100644 index 0000000..935610b --- /dev/null +++ b/docs/adr/ADR-004-authentik-proxy.md @@ -0,0 +1,12 @@ +# ADR-004: Authentik Outpost с прокси-портами + +**Статус:** Принят | **Дата:** 2026-08-03 + +## Контекст +Ручная настройка SSO для 28 сервисов = 14-28 часов. + +## Решение +Authentik Outpost с прокси-портами 9984-9989 + автоматизация через API + YAML. + +## Результат +13 сервисов за 2 часа (экономия ~11 часов). diff --git a/docs/adr/ADR-005-tailscale-exit-node.md b/docs/adr/ADR-005-tailscale-exit-node.md new file mode 100644 index 0000000..6e1d685 --- /dev/null +++ b/docs/adr/ADR-005-tailscale-exit-node.md @@ -0,0 +1,41 @@ +# ADR-005: Обход DPI через Tailscale exit node + outbound HTTP proxy + +**Статус:** Принят | **Дата:** 2026-08-04 | **Автор:** Roman + Qwen + +## Контекст +Провайдер (DPI) блокирует api.telegram.org. n8n обязан слать алерты надёжно. + +## Решение +LXC 108: tailscaled в userspace-networking + outbound HTTP proxy :1055. +n8n: HTTPS_PROXY=http://172.19.0.1:1055 (gateway сети buryan-net, НЕ LAN-IP!). + +systemd override: + + [Service] + ExecStart= + ExecStart=/usr/sbin/tailscaled -tun=userspace-networking \ + -outbound-http-proxy-listen=0.0.0.0:1055 \ + -state=/var/lib/tailscale/tailscaled.state + +n8n env: + + HTTPS_PROXY=http://172.19.0.1:1055 + HTTP_PROXY=http://172.19.0.1:1055 + NO_PROXY=localhost,127.0.0.1,192.168.1.0/24,172.19.0.0/16,172.17.0.0/16 + +## Альтернативы +| Вариант | Почему отвергнут | +|---------|------------------| +| Прямое соединение | DPI блокирует | +| SOCKS5 | n8n не поддерживает из коробки | +| Другой мессенджер | Переписывание агентов | + +## Последствия +- ✅ Telegram доступен из Docker +- ⚠️ Docker не видит LAN-IP хоста — только gateway сети +- ⚠️ Зависимость от VDS + +## Мониторинг + curl -s -x http://172.19.0.1:1055 https://api.telegram.org/bot/getMe + docker exec n8n env | grep -i proxy + journalctl -u tailscaled -n 50 diff --git a/docs/adr/TEMPLATE.md b/docs/adr/TEMPLATE.md new file mode 100644 index 0000000..eaeab6c --- /dev/null +++ b/docs/adr/TEMPLATE.md @@ -0,0 +1,20 @@ +# ADR-NNN: [Название решения] + +**Статус:** [Proposed | Accepted | Deprecated] +**Дата:** YYYY-MM-DD +**Автор:** [Roman / Qwen] + +## Контекст +[Почему возникла проблема?] + +## Решение +[Что сделали?] + +## Альтернативы +| Вариант | Почему отвергнут | +|---------|------------------| + +## Последствия +### Положительные / Отрицательные / Риски + +## Связанные документы diff --git a/harness/update-context.sh b/harness/update-context.sh new file mode 100755 index 0000000..e478c1e --- /dev/null +++ b/harness/update-context.sh @@ -0,0 +1,8 @@ +#!/bin/bash +# Использование: ./harness/update-context.sh "Описание задачи" +TASK="$1" +[ -z "$TASK" ] && { echo "Использование: $0 \"описание\""; exit 1; } +cd "$(dirname "$0")/.." +git add -A +git commit -m "Agent update: $TASK" || exit 0 +echo "✅ Контекст обновлён: $TASK" diff --git a/knowledge/runbooks/adguard.md b/knowledge/runbooks/adguard.md new file mode 100644 index 0000000..ea2cc51 --- /dev/null +++ b/knowledge/runbooks/adguard.md @@ -0,0 +1,8 @@ +# adguard Runbook + +**Статус:** Требуется документирование + +## TODO +- [ ] Процедура проверки статуса +- [ ] Частые проблемы и решения +- [ ] Команды восстановления diff --git a/knowledge/runbooks/authentik.md b/knowledge/runbooks/authentik.md new file mode 100644 index 0000000..9383a14 --- /dev/null +++ b/knowledge/runbooks/authentik.md @@ -0,0 +1,14 @@ +# Authentik Runbook (LXC 114) + +**Статус интеграции:** 13/28 сервисов + +## Проверка + docker ps | grep authentik + docker logs --tail 20 authentik-server + curl -s http://192.168.1.114:9000/api/v3/core/applications/ | head -50 + +## Частые проблемы +| Проблема | Решение | +|----------|---------| +| origin not allowed | Добавить домен в allowedOrigins | +| redirect_uri mismatch | Сверить конфиг сервиса и провайдера | diff --git a/knowledge/runbooks/bazarr.md b/knowledge/runbooks/bazarr.md new file mode 100644 index 0000000..e8a4a49 --- /dev/null +++ b/knowledge/runbooks/bazarr.md @@ -0,0 +1,8 @@ +# bazarr Runbook + +**Статус:** Требуется документирование + +## TODO +- [ ] Процедура проверки статуса +- [ ] Частые проблемы и решения +- [ ] Команды восстановления diff --git a/knowledge/runbooks/calibre.md b/knowledge/runbooks/calibre.md new file mode 100644 index 0000000..280f76e --- /dev/null +++ b/knowledge/runbooks/calibre.md @@ -0,0 +1,8 @@ +# calibre Runbook + +**Статус:** Требуется документирование + +## TODO +- [ ] Процедура проверки статуса +- [ ] Частые проблемы и решения +- [ ] Команды восстановления diff --git a/knowledge/runbooks/dashy.md b/knowledge/runbooks/dashy.md new file mode 100644 index 0000000..31661a3 --- /dev/null +++ b/knowledge/runbooks/dashy.md @@ -0,0 +1,8 @@ +# dashy Runbook + +**Статус:** Требуется документирование + +## TODO +- [ ] Процедура проверки статуса +- [ ] Частые проблемы и решения +- [ ] Команды восстановления diff --git a/knowledge/runbooks/freshrss.md b/knowledge/runbooks/freshrss.md new file mode 100644 index 0000000..813c9e0 --- /dev/null +++ b/knowledge/runbooks/freshrss.md @@ -0,0 +1,8 @@ +# freshrss Runbook + +**Статус:** Требуется документирование + +## TODO +- [ ] Процедура проверки статуса +- [ ] Частые проблемы и решения +- [ ] Команды восстановления diff --git a/knowledge/runbooks/gitea.md b/knowledge/runbooks/gitea.md new file mode 100644 index 0000000..3acb788 --- /dev/null +++ b/knowledge/runbooks/gitea.md @@ -0,0 +1,11 @@ +# Gitea Runbook (LXC 140) + +**URL:** http://192.168.1.140:3000 + +## Проверка + curl -s -o /dev/null -w "%{http_code}\n" http://192.168.1.140:3000/ + curl -s "http://192.168.1.140:3000/api/v1/repos/search?limit=50" + +## Создание репо через API + curl -u root:PASS -X POST http://192.168.1.140:3000/api/v1/user/repos \ + -H "Content-Type: application/json" -d '{"name":"repo","private":false}' diff --git a/knowledge/runbooks/grafana.md b/knowledge/runbooks/grafana.md new file mode 100644 index 0000000..05803c9 --- /dev/null +++ b/knowledge/runbooks/grafana.md @@ -0,0 +1,8 @@ +# grafana Runbook + +**Статус:** Требуется документирование + +## TODO +- [ ] Процедура проверки статуса +- [ ] Частые проблемы и решения +- [ ] Команды восстановления diff --git a/knowledge/runbooks/homeassistant.md b/knowledge/runbooks/homeassistant.md new file mode 100644 index 0000000..03dfb9e --- /dev/null +++ b/knowledge/runbooks/homeassistant.md @@ -0,0 +1,8 @@ +# homeassistant Runbook + +**Статус:** Требуется документирование + +## TODO +- [ ] Процедура проверки статуса +- [ ] Частые проблемы и решения +- [ ] Команды восстановления diff --git a/knowledge/runbooks/immich.md b/knowledge/runbooks/immich.md new file mode 100644 index 0000000..a52e7b6 --- /dev/null +++ b/knowledge/runbooks/immich.md @@ -0,0 +1,8 @@ +# immich Runbook + +**Статус:** Требуется документирование + +## TODO +- [ ] Процедура проверки статуса +- [ ] Частые проблемы и решения +- [ ] Команды восстановления diff --git a/knowledge/runbooks/jellyfin.md b/knowledge/runbooks/jellyfin.md new file mode 100644 index 0000000..f37ca57 --- /dev/null +++ b/knowledge/runbooks/jellyfin.md @@ -0,0 +1,8 @@ +# jellyfin Runbook + +**Статус:** Требуется документирование + +## TODO +- [ ] Процедура проверки статуса +- [ ] Частые проблемы и решения +- [ ] Команды восстановления diff --git a/knowledge/runbooks/linkding.md b/knowledge/runbooks/linkding.md new file mode 100644 index 0000000..04f7aef --- /dev/null +++ b/knowledge/runbooks/linkding.md @@ -0,0 +1,8 @@ +# linkding Runbook + +**Статус:** Требуется документирование + +## TODO +- [ ] Процедура проверки статуса +- [ ] Частые проблемы и решения +- [ ] Команды восстановления diff --git a/knowledge/runbooks/matrix.md b/knowledge/runbooks/matrix.md new file mode 100644 index 0000000..65cbda7 --- /dev/null +++ b/knowledge/runbooks/matrix.md @@ -0,0 +1,8 @@ +# matrix Runbook + +**Статус:** Требуется документирование + +## TODO +- [ ] Процедура проверки статуса +- [ ] Частые проблемы и решения +- [ ] Команды восстановления diff --git a/knowledge/runbooks/n8n.md b/knowledge/runbooks/n8n.md new file mode 100644 index 0000000..dde6cae --- /dev/null +++ b/knowledge/runbooks/n8n.md @@ -0,0 +1,27 @@ +# n8n Runbook (LXC 108) + +**Workflow ID:** afdmDW35vpDd6oNs (Buryan Health Monitor) + +## Проверка + docker ps | grep n8n + docker logs --tail 50 n8n + docker exec n8n env | grep -iE "proxy|secure" + +## Частые проблемы +| Проблема | Решение | +|----------|---------| +| 404 webhook not registered | n8n publish:workflow --id= | +| connection timed out | Проверить HTTPS_PROXY=http://172.19.0.1:1055 | +| Authorization failed | Обновить токен в credential Telegram | +| secure cookie ошибка | -e N8N_SECURE_COOKIE=false | + +## Управление workflow + docker exec n8n n8n list:workflow + docker exec n8n n8n publish:workflow --id=afdmDW35vpDd6oNs + docker exec n8n n8n export:workflow --id= + docker exec n8n n8n import:workflow --input=/tmp/wf.json + +## Тест webhook + curl -X POST http://192.168.1.108:5678/webhook/buryan-health \ + -H "Content-Type: application/json" \ + -d '{"host":"TEST","failed":1,"restarted":0,"mem":50,"disk":60,"containers":[]}' diff --git a/knowledge/runbooks/navidrome.md b/knowledge/runbooks/navidrome.md new file mode 100644 index 0000000..a044e5d --- /dev/null +++ b/knowledge/runbooks/navidrome.md @@ -0,0 +1,8 @@ +# navidrome Runbook + +**Статус:** Требуется документирование + +## TODO +- [ ] Процедура проверки статуса +- [ ] Частые проблемы и решения +- [ ] Команды восстановления diff --git a/knowledge/runbooks/nextcloud.md b/knowledge/runbooks/nextcloud.md new file mode 100644 index 0000000..5d2298c --- /dev/null +++ b/knowledge/runbooks/nextcloud.md @@ -0,0 +1,8 @@ +# nextcloud Runbook + +**Статус:** Требуется документирование + +## TODO +- [ ] Процедура проверки статуса +- [ ] Частые проблемы и решения +- [ ] Команды восстановления diff --git a/knowledge/runbooks/nodered.md b/knowledge/runbooks/nodered.md new file mode 100644 index 0000000..9f5c063 --- /dev/null +++ b/knowledge/runbooks/nodered.md @@ -0,0 +1,8 @@ +# nodered Runbook + +**Статус:** Требуется документирование + +## TODO +- [ ] Процедура проверки статуса +- [ ] Частые проблемы и решения +- [ ] Команды восстановления diff --git a/knowledge/runbooks/oauth2-proxy.md b/knowledge/runbooks/oauth2-proxy.md new file mode 100644 index 0000000..8c2e825 --- /dev/null +++ b/knowledge/runbooks/oauth2-proxy.md @@ -0,0 +1,14 @@ +# OAuth2-proxy Runbook (LXC 108) + +**Контейнер:** oauth2-proxy-n8n | **Порт:** 5678 | **Upstream:** http://n8n:5678 + +## Проверка + docker ps | grep oauth2-proxy + docker logs --tail 20 oauth2-proxy-n8n + curl -s -o /dev/null -w "%{http_code}\n" http://192.168.1.108:5678/ + +## Пропуск без авторизации +^/webhook, ^/healthz, ^/rest + +## Пересоздание + cd /root/buryan-infra/docker/oauth2-proxy && docker compose up -d diff --git a/knowledge/runbooks/openclaw.md b/knowledge/runbooks/openclaw.md new file mode 100644 index 0000000..672e02c --- /dev/null +++ b/knowledge/runbooks/openclaw.md @@ -0,0 +1,8 @@ +# openclaw Runbook + +**Статус:** Требуется документирование + +## TODO +- [ ] Процедура проверки статуса +- [ ] Частые проблемы и решения +- [ ] Команды восстановления diff --git a/knowledge/runbooks/overseerr.md b/knowledge/runbooks/overseerr.md new file mode 100644 index 0000000..6334e04 --- /dev/null +++ b/knowledge/runbooks/overseerr.md @@ -0,0 +1,8 @@ +# overseerr Runbook + +**Статус:** Требуется документирование + +## TODO +- [ ] Процедура проверки статуса +- [ ] Частые проблемы и решения +- [ ] Команды восстановления diff --git a/knowledge/runbooks/paperless.md b/knowledge/runbooks/paperless.md new file mode 100644 index 0000000..90d7456 --- /dev/null +++ b/knowledge/runbooks/paperless.md @@ -0,0 +1,8 @@ +# paperless Runbook + +**Статус:** Требуется документирование + +## TODO +- [ ] Процедура проверки статуса +- [ ] Частые проблемы и решения +- [ ] Команды восстановления diff --git a/knowledge/runbooks/plex.md b/knowledge/runbooks/plex.md new file mode 100644 index 0000000..5ba3607 --- /dev/null +++ b/knowledge/runbooks/plex.md @@ -0,0 +1,8 @@ +# plex Runbook + +**Статус:** Требуется документирование + +## TODO +- [ ] Процедура проверки статуса +- [ ] Частые проблемы и решения +- [ ] Команды восстановления diff --git a/knowledge/runbooks/prometheus.md b/knowledge/runbooks/prometheus.md new file mode 100644 index 0000000..622404f --- /dev/null +++ b/knowledge/runbooks/prometheus.md @@ -0,0 +1,8 @@ +# prometheus Runbook + +**Статус:** Требуется документирование + +## TODO +- [ ] Процедура проверки статуса +- [ ] Частые проблемы и решения +- [ ] Команды восстановления diff --git a/knowledge/runbooks/prowlarr.md b/knowledge/runbooks/prowlarr.md new file mode 100644 index 0000000..daf8600 --- /dev/null +++ b/knowledge/runbooks/prowlarr.md @@ -0,0 +1,8 @@ +# prowlarr Runbook + +**Статус:** Требуется документирование + +## TODO +- [ ] Процедура проверки статуса +- [ ] Частые проблемы и решения +- [ ] Команды восстановления diff --git a/knowledge/runbooks/radarr.md b/knowledge/runbooks/radarr.md new file mode 100644 index 0000000..7babfd9 --- /dev/null +++ b/knowledge/runbooks/radarr.md @@ -0,0 +1,8 @@ +# radarr Runbook + +**Статус:** Требуется документирование + +## TODO +- [ ] Процедура проверки статуса +- [ ] Частые проблемы и решения +- [ ] Команды восстановления diff --git a/knowledge/runbooks/sonarr.md b/knowledge/runbooks/sonarr.md new file mode 100644 index 0000000..a7950e5 --- /dev/null +++ b/knowledge/runbooks/sonarr.md @@ -0,0 +1,8 @@ +# sonarr Runbook + +**Статус:** Требуется документирование + +## TODO +- [ ] Процедура проверки статуса +- [ ] Частые проблемы и решения +- [ ] Команды восстановления diff --git a/knowledge/runbooks/syncthing.md b/knowledge/runbooks/syncthing.md new file mode 100644 index 0000000..44d0f3e --- /dev/null +++ b/knowledge/runbooks/syncthing.md @@ -0,0 +1,8 @@ +# syncthing Runbook + +**Статус:** Требуется документирование + +## TODO +- [ ] Процедура проверки статуса +- [ ] Частые проблемы и решения +- [ ] Команды восстановления diff --git a/knowledge/runbooks/tailscale.md b/knowledge/runbooks/tailscale.md new file mode 100644 index 0000000..6838067 --- /dev/null +++ b/knowledge/runbooks/tailscale.md @@ -0,0 +1,17 @@ +# Tailscale Runbook (LXC 108) + +**Критичность:** 🔴 Высокая + +## Проверка статуса + systemctl status tailscaled + journalctl -u tailscaled -n 50 + curl -s -x http://172.19.0.1:1055 https://api.telegram.org/bot/getMe + +## Частые проблемы +| Проблема | Решение | +|----------|---------| +| Connection timed out | Рестарт tailscaled, проверить VDS | +| Прокси недоступен из Docker | Использовать 172.19.0.1, не 192.168.1.108 | + +## Восстановление + sudo systemctl restart tailscaled diff --git a/knowledge/runbooks/tautulli.md b/knowledge/runbooks/tautulli.md new file mode 100644 index 0000000..dabcb8e --- /dev/null +++ b/knowledge/runbooks/tautulli.md @@ -0,0 +1,8 @@ +# tautulli Runbook + +**Статус:** Требуется документирование + +## TODO +- [ ] Процедура проверки статуса +- [ ] Частые проблемы и решения +- [ ] Команды восстановления diff --git a/knowledge/runbooks/uptimekuma.md b/knowledge/runbooks/uptimekuma.md new file mode 100644 index 0000000..e776b13 --- /dev/null +++ b/knowledge/runbooks/uptimekuma.md @@ -0,0 +1,8 @@ +# uptimekuma Runbook + +**Статус:** Требуется документирование + +## TODO +- [ ] Процедура проверки статуса +- [ ] Частые проблемы и решения +- [ ] Команды восстановления diff --git a/knowledge/runbooks/vaultwarden.md b/knowledge/runbooks/vaultwarden.md new file mode 100644 index 0000000..12c420e --- /dev/null +++ b/knowledge/runbooks/vaultwarden.md @@ -0,0 +1,8 @@ +# vaultwarden Runbook + +**Статус:** Требуется документирование + +## TODO +- [ ] Процедура проверки статуса +- [ ] Частые проблемы и решения +- [ ] Команды восстановления diff --git a/tailscale/tailscaled-override.conf b/tailscale/tailscaled-override.conf new file mode 100644 index 0000000..97dc5d4 --- /dev/null +++ b/tailscale/tailscaled-override.conf @@ -0,0 +1,8 @@ +# /etc/systemd/system/tailscaled.service.d/override.conf +# Применение: +# sudo mkdir -p /etc/systemd/system/tailscaled.service.d +# sudo cp override.conf туда; sudo systemctl daemon-reload +# sudo systemctl restart tailscaled +[Service] +ExecStart= +ExecStart=/usr/sbin/tailscaled -tun=userspace-networking -outbound-http-proxy-listen=0.0.0.0:1055 -state=/var/lib/tailscale/tailscaled.state diff --git a/workflows/README.md b/workflows/README.md new file mode 100644 index 0000000..70c49f8 --- /dev/null +++ b/workflows/README.md @@ -0,0 +1,8 @@ +# n8n Workflows + +Экспорты workflow для версионирования в Git. + +## Импорт + docker cp workflows/buryan-health-monitor.json n8n:/tmp/wf.json + docker exec n8n n8n import:workflow --input=/tmp/wf.json + docker exec n8n n8n publish:workflow --id=