ADR-003: egress policy engine + PG17 migration + AI automation vision

2026-09-12 09:00:15 +00:00
parent 2fcb5f3a4e
commit 2b96acedc7
1 changed files with 116 additions and 0 deletions
--- a/ADR-003-egress-pg17-automation.md
+++ b/ADR-003-egress-pg17-automation.md
@@ -0,0 +1,116 @@
+# ADR-003: Egress Policy Engine, PostgreSQL 17 и AI-автоматизация инфраструктуры
+
+**Статус:** Принято | **Дата:** 2026-09-11 | **Спринт:** 9
+
+## Контекст
+
+1. **Telegram API заблокирован в РФ** — n8n не мог отправлять уведомления о сбоях мониторинга.
+2. **n8n v2.38+ требует Postgres 17+** — на CT 151 был Postgres 14.23.
+3. **БД были размазаны** — SQLite в n8n, Postgres на CT 151, временный Docker-postgres17.
+4. **Отсутствие актуальной документации** — ADR-001/002 устарели, новые решения не зафиксированы.
+5. **Crash-loop смежных сервисов** — headscale падал с 9 сентября из-за рассинхрона пароля БД и конфига.
+
+## Решение
+
+### Слой 1. Egress Policy Engine
+
+    n8n (CT 108, Docker)
+      -> http_proxy/https_proxy = http://192.168.1.10:10888
+    sing-box (PVE, 0.0.0.0:10888, iptables ACCEPT)
+      -> rule: domain_suffix telegram.org -> vps-egress
+      -> rule: ip_is_private / buryans.ru -> direct
+    Tailscale (100.x.x.x)
+    tinyproxy (VPS buryan-edge, 100.78.31.42:8888)
+      -> api.telegram.org (Амстердам)
+
+**Правила реализации:**
+- Node.js читает ТОЛЬКО lowercase proxy-переменные: в compose обязательны оба регистра (6 переменных: HTTP_PROXY+http_proxy, HTTPS_PROXY+https_proxy, NO_PROXY+no_proxy).
+- CT 108 работает в Tailscale userspace-networking: контейнеры ходят в tailnet только через LAN-IP PVE (192.168.1.10), где sing-box имеет kernel-доступ к tailnet.
+- oauth2-proxy с OAUTH2_PROXY_SKIP_AUTH_ROUTES=^/webhook — без этого webhook-и режутся SSO (302 вместо 200).
+
+### Слой 2. Централизованная БД (CT 151)
+
+- **Миграция:** PostgreSQL 14.23 -> 17.11 через pg_upgradecluster --link.
+- **Кластер 14 оставлен на порту 5433** как rollback на 7 дней.
+- **Pre-upgrade:** pg_dumpall + точечные дампы критичных БД.
+- **Обязательные пакеты:** postgresql-17-pgvector (для immich), postgis при использовании.
+- **Рабочая БД:** n8n_central (владелец Roman Buryan, 4 workflow, 2 credentials).
+- **Архив:** БД n8n (история executions до миграции).
+- **Cold-backup:** SQLite database.sqlite (99M), /opt/postgres17-data, JSON-экспорты.
+
+### Слой 3. AI-Driven Infrastructure Automation (видение)
+
+**Наблюдение спринта 9:** AI-ассистент за ~15 запросов:
+- Составил полную карту инфраструктуры (27 LXC, Docker-стеки, systemd-сервисы, матрица БД)
+- Выполнил миграцию мажорной версии БД с pg_upgrade
+- Восстановил данные из 4 разных источников
+- Диагностировал и починил crash-loop headscale (37 часов простоя)
+- Освободил диск CT 110 (95% -> 81%)
+
+**Roadmap автоматизации:**
+
+| Спринт | Задача | Результат |
+|---|---|---|
+| **10** | AI-аудит инфраструктуры | Cron-обход всех CT -> отчёт-снимок в Gitea, детект дрейфа |
+| **11** | Auto-ADR | AI сравнивает снимки, сам предлагает ADR/PR; человек ревьюит |
+| **12** | Self-healing runbooks | Типовые аварии чинятся по runbook; новый фикс -> новый документ |
+| **13** | Predictive migrations | Мониторинг EOL, предложение окна миграции ДО аварии |
+| **14** | Шаблонный деплой | compose + oauth2-proxy + БД + backup одной командой |
+
+**Принципы безопасности:**
+- AI работает read-only + proposals; write-действия только после human approve.
+- Любая деструктивная операция начинается с бэкапа (правило спринта 9).
+- Все изменения фиксируются в Gitea (infra-as-docs).
+- Секреты ротируются регулярно, токены имеют минимальные scopes.
+
+## Последствия
+
+**Плюсы:**
+- Единая БД и бэкап-политика
+- Обход блокировок Telegram через VPS
+- Воспроизводимость всех операций
+- Экономия 10+ часов ручного аудита в месяц
+- Документация как код
+
+**Риски:**
+- VPS как single point of failure egress (митигация: резервный VPS)
+- AI-ошибки (митигация: human review, бэкапы, rollback-кластер PG14)
+- Рост числа токенов/секретов (митигация: ротация, vault-решение в Sprint 14)
+
+## Триггеры пересмотра ADR
+
+- n8n v3.x (требует Postgres 18+)
+- Блокировка IP VPS провайдером
+- Предоставление AI write-прав (тогда нужен новый ADR с контуром контроля)
+- Стоимость VPS превышает экономию от автоматизации
+
+## Runbook: ключевые уроки спринта 9
+
+1. **Экран setup n8n** = пустая таблица user, а не потеря данных. CLI-импорт не создаёт владельца.
+2. **pg_upgradecluster**, а не ручной pg_upgrade: Debian держит конфиги в /etc/postgresql/<ver>/main/.
+3. **Pre-upgrade checks** требуют ВСЕ расширения новой версии (pgvector, postgis).
+4. **COPY TO ломает JSON-экспорт** (экранирование обратных слешей); использовать psql -tAc "::text" или base64.
+5. **pct push читает файл с PVE-хоста**: сначала pct pull с исходного CT.
+6. **Дубли env в compose**: последнее значение побеждает. Не восстанавливать бэкапы вслепую.
+7. **Crash-loop сервиса** = сверить пароль в его конфиге с ролью БД (кейс headscale: 37 часов простоя).
+8. **no space left on device** в Docker = docker system prune -af --volumes + image prune.
+9. **paperless-ngx v3.x** использует /init как entrypoint, runworker устарел -> full-stack /init.
+
+## Приложение: Компоненты инфраструктуры
+
+| Компонент | Версия | Расположение | Порт |
+|---|---|---|---|
+| n8n | 2.38.7 | CT 108 (Docker) | 5680 |
+| postgres | 17.11 | CT 151 (systemd) | 5432 |
+| sing-box | 1.9.7 | PVE Host | 10888 |
+| tinyproxy | latest | VPS (100.78.31.42) | 8888 |
+| oauth2-proxy | latest | CT 108 (Docker) | 5678 |
+| headscale | latest | CT 201 (systemd) | 8080, 9090 |
+| paperless-ngx | 3.1.3 | CT 110 (Docker) | 8000 |
+| NPM | latest | VPS (193.233.210.184) | 81, 80, 443 |
+
+---
+
+**Автор:** AI Assistant + Roman Buryan
+**Дата создания:** 11 сентября 2026
+**Последнее обновление:** 12 сентября 2026