maps: fix — репо-папки как обычные файлы (было submodule/gitlink), 45 MAP.md теперь в репо

2026-07-12 20:21:49 +03:00
parent 7faebe0a06
commit 4bfad7475f
90 changed files with 2217 additions and 45 deletions
@@ -0,0 +1,105 @@
+# cascade
+
+## Назначение
+
+Рабочая папка проекта **каскадного VPN** `RU → FI → {NL | DE}` + WireGuard site-to-site слой на 40–50 сотрудников. На 80% это документация/runbook'и (Markdown), на 20% — код management-слоя: node-agent (FastAPI/mTLS), Telegram-боты (aiogram), подписочный endpoint, панель мониторинга mesh, action-API для перезагрузок, скрипты оркестрации mesh и baseline-диагностики. Точка истины по архитектуре — `cascade-vpn-architecture.md`. Секреты в код/память не кладутся.
+
+- Основной язык: **Python** (16 файлов) + **Shell** (27 файлов) + **JSX/React** (3 файла).
+- Суммарный LOC по коду (py/js/jsx/sh/sql/bat/ps1): **≈6 261**.
+- Всего файлов в репо: 224 (большинство — `.md`).
+
+## Архитектура
+
+```mermaid
+graph TD
+  subgraph docs["Документация (runbooks/ knowledge/ deploy/*.md)"]
+    ARCH[cascade-vpn-architecture.md<br/>точка истины]
+    RB[runbooks/ phase-0..5]
+    KN[knowledge/ NODES, MEMORY, loc-*]
+  end
+
+  subgraph mgmt["code/ — management слой"]
+    AGENT[agent.py<br/>FastAPI node-agent :8443]
+    BOTM[code/bot.py<br/>MGMT-бот aiogram]
+    SUB[sub.py<br/>subscription :sub]
+    CADDY[caddy/ Caddyfile mTLS]
+    WG[wg/ конфиги+new_wg_client.sh]
+  end
+
+  subgraph client["bot/ — клиентский бот"]
+    BOTC[bot.py<br/>/start /key /stats /revoke /admin]
+  end
+
+  subgraph panel["deploy/panel-api + mesh-status"]
+    PAPI[panel-api.py<br/>BaseHTTPServer /api/*]
+    PNOT[panel-notifier.py timer]
+    MESHUI[mesh-status/*.jsx<br/>React панели]
+  end
+
+  subgraph ops["deploy/scripts + action-api + ats"]
+    AAPI[action-api.py<br/>/reboot challenge]
+    MESH[mesh.sh + merge-*.py<br/>state-producer, zabbix]
+    ATS[ats-security/ f2b attack-map]
+  end
+
+  ARCH --> mgmt
+  RB --> mgmt
+  BOTM -->|HTTP mTLS| AGENT
+  AGENT --> WG
+  AGENT --> CADDY
+  BOTC -->|выдача ключей| SUB
+  BOTC --> WG
+  PAPI --> MESH
+  MESHUI -->|fetch| PAPI
+  PNOT --> PAPI
+  MESH --> KN
+  AAPI --> AGENT
+```
+
+## Entry-points / маршруты
+
+| Метод | Путь | Файл | Назначение |
+|---|---|---|---|
+| GET | `/status` | code/agent.py:46 | метрики + состояние x-ui |
+| POST | `/xray/restart` | code/agent.py:66 | перезапуск x-ui |
+| GET | `/cascade/test` | code/agent.py:72 | e2e-тест каскада с ноды |
+| GET | `/conf/summary` | code/agent.py:94 | обзор XRay-config для сверки |
+| GET | `/wg/peers` | code/agent.py:120 | MGMT: список peer'ов WG |
+| POST | `/wg/add_peer` | code/agent.py:144 | MGMT: добавить peer (+QR) |
+| POST | `/wg/revoke_peer` | code/agent.py:155 | MGMT: удалить peer |
+| GET | `/wg/office_status` | code/agent.py:180 | MGMT: ping офиса через wg0/wg1 |
+| GET | `/sub/{token}` | code/sub.py:45 | подписка (subscription URL) |
+| GET | `/health` | code/sub.py:77 | healthcheck |
+| GET | `/api/whoami`,`/state`,`/users` | deploy/panel-api/panel-api.py:229-237 | панель: контекст/состояние/юзеры |
+| POST | `/users` (`/api` prefix) | deploy/panel-api/panel-api.py:252 | панель: мутация юзеров |
+| GET | `/health` | deploy/action-api/action-api.py:277 | action-API healthcheck |
+| POST | `/reboot/challenge`,`/reboot` | deploy/action-api/action-api.py:297-302 | защищённая перезагрузка ноды |
+| TG-cmd | `/start /key /stats /revoke /admin /help` | bot/bot.py:144-260 | клиентский бот выдачи VPN |
+| TG-cmd | `/status /restart /test /wg_status /wg_add /wg_office` | code/bot.py:78-219 | MGMT-бот (проксирует agent.py) |
+
+## Ключевые цепочки вызовов
+
+1. **Выдача клиенту VPN**: TG `/key` (bot/bot.py) → генерит UUID/конфиг → отдаёт subscription-ссылку `sub.servaki.online/sub/{token}` (sub.py) → клиент подтягивает конфиг.
+2. **Добавление WG-peer**: MGMT-бот `/wg_add` (code/bot.py) → HTTP mTLS через Caddy → `POST /wg/add_peer` (agent.py) → `new_wg_client.sh` генерит ключи → возврат conf+QR.
+3. **Проверка каскада**: MGMT-бот `/test` → `GET /cascade/test` (agent.py) → outbound-тест RU→FI→exit → отчёт в Telegram.
+4. **Mesh-мониторинг**: `state-producer.sh`/`mesh.sh` собирают `state.json` → `merge-health.py`/`merge-config.py` мёржат → `panel-api.py /api/state` → React `mesh-status/*.jsx` рендерит + `panel-notifier.py` шлёт алерты.
+5. **Удалённая перезагрузка ноды**: оператор → `POST /reboot/challenge` → подпись → `POST /reboot` (action-api.py) → систем-reboot ноды.
+
+## Тех-долг
+
+_Пометка: всё ниже — **предположение** по эвристике (grep, без реального call-graph). Точность — через codebase-memory-mcp._
+
+- **Дубли ботов**: `code/bot.py` (MGMT) и `bot/bot.py` (клиентский) — разные роли, но много общего кода aiogram/setup; кандидат на общий модуль.
+- **Версионные дубли UI**: `mesh-status/SmartHomeMesh.jsx` (735) vs `SmartHomeMesh.v2.jsx` (939) — вероятно v1 мёртв (dead-code кандидат). `MeshStatus.jsx` (311) — возможно предшественник.
+- **Дубли merge-скриптов**: `merge-health.py` присутствует в `deploy/scripts/` и `mesh-status/` — дивергенция копий.
+- **Дубли имён**: `run.sh`, `state.json`, `README.md`, `SKILL.md` в нескольких каталогах — конфиг разбросан.
+- **Одиночные утилиты без явных входящих ссылок** (dead-code кандидаты): `gen_links.py`, `ats-security/attack-map.py|digest.py|make-html.py`, `scripts/generate-uuids.sh` — упоминаются лишь в паре md; проверить, живые ли.
+- **Смешение кода и доков**: ~200 `.md` рядом с кодом усложняет навигацию; напрашивается вынос кода в отдельный подпакет.
+
+## TODO для Лилии (codebase-memory-mcp)
+
+- Построить **точный call-graph** для `code/agent.py` ↔ `code/bot.py` (какие эндпоинты реально дёргаются ботом) и `mesh-status/*.jsx` → `panel-api.py`.
+- Подтвердить **dead-code**: `SmartHomeMesh.jsx` (v1), `MeshStatus.jsx`, `gen_links.py`, `ats-security/*`, `generate-uuids.sh` — есть ли живые вызовы/деплой-ссылки.
+- Разрешить **дубли** `merge-health.py` (две копии) — какая канонична.
+- Разметить **cross-service links**: поддомены servaki.online (finik/ru1/ru2/ru3/de/ee*/gate/wg/sub/panel/zabbix/grafana/ha/matrix/n8n/git1/s3), внешние репо (`gate-web-relay`, `agent-sync`, `banya-bot`, tempelhoff), кто реально ходит по HTTP.
+- Снять **снапшот graph.db.zst** после первичного обогащения для инкрементального дифа.