docs

2026-07-02 23:13:13 +07:00
parent e997a20fe6
commit d4a57c0b6a
34 changed files with 524 additions and 67 deletions
@@ -0,0 +1,38 @@
+# `modules/nodes` — Control Plane VPN-нод
+
+Оркестратор физических VPN-серверов: добавление новой ноды по SSH и раздача списка
+живых нод клиентам/лендингу. Единственный модуль без зависимостей от остальных.
+
+## Роуты
+
+- `public_router` (за `auth_guard`, обычный юзер):
+  - `GET /nodes` — список активных нод (`status = 'online'`), отсортирован по
+    возрастанию `current_load` — то есть новые юзеры естественным образом идут на самые
+    свободные сервера.
+  - `GET /nodes/stats` — агрегаты для лендинга (страна, загрузка, статус). **`uptime` —
+    заглушка**, см. TODO в `controller.rs`.
+  - `GET /nodes/routing` — конфиг для клиентского приложения (Tauri/mobile). **Сейчас
+    неполный** — см. TODO в `controller.rs` и в корневом README.
+- `admin_router` (за `auth_guard` **и** `admin_guard`, в таком порядке — `admin_guard`
+  ожидает, что `auth_guard` уже положил юзера в extensions):
+  - `POST /admin/nodes` — добавить и заprovisioning новую ноду.
+  - `DELETE /admin/nodes/{id}` — удалить ноду из БД (саму VPS-машину это не трогает).
+
+## Провижининг (`service.rs::provision_node_via_ssh`)
+
+Синхронная (в смысле — блокирующий поток через `spawn_blocking`, но HTTP-запрос ждёт её
+целиком, см. TODO) операция по `ssh2`:
+
+1. Подключается к `ip:22` с таймаутом 15с, логинится по паролю root (временный пароль,
+   передаётся один раз при создании ноды).
+2. Гоняет `templates/init_node.sh` (обязателен — если файла нет, провижининг падает с
+   ошибкой, а не деплоит полуживую ноду) с переменными `NODE_IP`/`GH_TOKEN`.
+3. Прописывает публичный ключ control plane (`keys/netrunner_master_ed25519.pub`,
+   создаётся заранее, см. `main.rs::ensure_master_ssh_key`) в `authorized_keys` и **жёстко
+   выключает парольный SSH-вход** (hardening-скрипт внутри метода) — после провижининга
+   зайти на ноду можно только по ключу.
+4. Не более 3 одновременных провижинингов (`Semaphore::new(3)`), чтобы не заDDoSить сам
+   control plane при массовом добавлении нод.
+
+Одновременно с провижинингом только `add_vpn_node` пишет запись в БД — если SSH-шаг
+упал, запись не создаётся вовсе (не остаётся полуживых нод в базе).