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).

Архитектура

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)

Ключевые цепочки вызовов

Выдача клиенту VPN: TG /key (bot/bot.py) → генерит UUID/конфиг → отдаёт subscription-ссылку sub.servaki.online/sub/{token} (sub.py) → клиент подтягивает конфиг.
Добавление WG-peer: MGMT-бот /wg_add (code/bot.py) → HTTP mTLS через Caddy → POST /wg/add_peer (agent.py) → new_wg_client.sh генерит ключи → возврат conf+QR.
Проверка каскада: MGMT-бот /test → GET /cascade/test (agent.py) → outbound-тест RU→FI→exit → отчёт в Telegram.
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 шлёт алерты.
Удалённая перезагрузка ноды: оператор → 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 после первичного обогащения для инкрементального дифа.

7.4 KiB Raw Blame History