From 5647d339b14efa5ff0cff2f9180cf33565481f70 Mon Sep 17 00:00:00 2001 From: embeddevio Date: Wed, 21 Oct 2026 23:28:59 +0300 Subject: [PATCH] =?UTF-8?q?chore(#16):=20=D0=BA=D0=B0=D1=80=D0=BA=D0=B0?= =?UTF-8?q?=D1=81=20=D0=BF=D0=B0=D0=BA=D0=B5=D1=82=D0=BE=D0=B2=20backend,?= =?UTF-8?q?=20=D1=82=D0=B5=D1=81=D1=82=D0=BE=D0=B2=20=D0=B8=20=D0=B7=D0=B0?= =?UTF-8?q?=D0=B3=D0=BB=D1=83=D1=88=D0=BA=D0=B8=20ui/deploy/tests?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- backend/awg_agent/README.md | 16 ++++++++++++++++ backend/awg_agent/__init__.py | 5 +++++ backend/awg_api/README.md | 13 +++++++++++++ backend/awg_api/__init__.py | 5 +++++ backend/tests/test_skeleton.py | 13 +++++++++++++ deploy/README.md | 12 ++++++++++++ tests/netns/README.md | 13 +++++++++++++ ui/README.md | 14 ++++++++++++++ 8 files changed, 91 insertions(+) create mode 100644 backend/awg_agent/README.md create mode 100644 backend/awg_agent/__init__.py create mode 100644 backend/awg_api/README.md create mode 100644 backend/awg_api/__init__.py create mode 100644 backend/tests/test_skeleton.py create mode 100644 deploy/README.md create mode 100644 tests/netns/README.md create mode 100644 ui/README.md diff --git a/backend/awg_agent/README.md b/backend/awg_agent/README.md new file mode 100644 index 0000000..6c9b353 --- /dev/null +++ b/backend/awg_agent/README.md @@ -0,0 +1,16 @@ +# awg_agent — привилегированный агент + +Запускается как root в контейнере: всё, что требует NET_ADMIN и доступа к ядру. + +| Модуль | Ответственность | Задача | +|---|---|---| +| `vpn/` | парсинг/валидация `.conf`, up/down/restart туннеля, `awg show` → статус | #22 | +| `watchdog/` | контроль handshake, авто-восстановление, fail-closed | #23 | +| `netfilter/` | iptables/ipset, policy routing, atomic swap, MSS clamping, IPv6 | #24 | +| `geoip/` | RIPE Stat, кэш-снапшот, расписание, fallback | #25 | +| `dns/` | dnsmasq, домены → ipset, защита от DNS-утечки | #26 | +| `routing/` | режимы (GeoIP / DNS / All-VPN / Direct-only), reconcile, исключения | #27 | +| `metrics/` | RX/TX, direct vs VPN, история, агрегаты | #28 | +| `devices/` | активные устройства LAN и их политики | #29 | + +Интерфейс для `awg_api` — unix-socket `/run/awg/agent.sock` (см. ADR-002). diff --git a/backend/awg_agent/__init__.py b/backend/awg_agent/__init__.py new file mode 100644 index 0000000..ec9c356 --- /dev/null +++ b/backend/awg_agent/__init__.py @@ -0,0 +1,5 @@ +"""Привилегированный агент awg-dash: туннель, маршрутизация, GeoIP, DNS, метрики.""" + +__version__ = "0.0.1" + +__all__ = ["__version__"] diff --git a/backend/awg_api/README.md b/backend/awg_api/README.md new file mode 100644 index 0000000..288c805 --- /dev/null +++ b/backend/awg_api/README.md @@ -0,0 +1,13 @@ +# awg_api — control plane + +Непривилегированный процесс: FastAPI + REST API v1 + WebSocket + отдача статики UI. + +| Модуль | Ответственность | Задача | +|---|---|---| +| `app.py` | lifespan, конфиг, логирование, error model, статика | #31 | +| `routers/` | эндпоинты по OpenAPI (status, config, routing, devices, logs, auth) | #32 | +| `ws/` | `/api/v1/metrics/stream` | #33 | +| `security/` | токен, CSRF, rate limit, маскировка секретов | #34 | +| `store/` | SQLite (WAL), миграции, audit log, apply/rollback | #20 | + +Контракт — `docs/openapi.yaml` (задача #19), TS-клиент генерируется в `ui/src/api/generated/`. diff --git a/backend/awg_api/__init__.py b/backend/awg_api/__init__.py new file mode 100644 index 0000000..e02b912 --- /dev/null +++ b/backend/awg_api/__init__.py @@ -0,0 +1,5 @@ +"""FastAPI-приложение awg-dash: REST API v1, WebSocket, статика UI.""" + +__version__ = "0.0.1" + +__all__ = ["__version__"] diff --git a/backend/tests/test_skeleton.py b/backend/tests/test_skeleton.py new file mode 100644 index 0000000..3e572ae --- /dev/null +++ b/backend/tests/test_skeleton.py @@ -0,0 +1,13 @@ +"""Скелетные тесты: пакеты импортируются, версия объявлена.""" + +import awg_agent +import awg_api + + +def test_versions_match() -> None: + assert awg_agent.__version__ == awg_api.__version__ + + +def test_public_api_declared() -> None: + assert "__version__" in awg_agent.__all__ + assert "__version__" in awg_api.__all__ diff --git a/deploy/README.md b/deploy/README.md new file mode 100644 index 0000000..77c784a --- /dev/null +++ b/deploy/README.md @@ -0,0 +1,12 @@ +# deploy — сборка и развёртывание + +| Артефакт | Назначение | Задача | +|---|---|---| +| `Dockerfile` | multi-stage: amneziawg-go + awg-tools → runtime alpine | #18 | +| `entrypoint.sh` | супервизор: `awg-agent` (root) + `awg-api` | #18 | +| `docker-compose.dev.yml` | dev-стенд: порт 8080, тома `/config` `/data`, healthcheck | #21 | +| `docker-compose.test.yml` | стенд для тестов | #21 | +| `grafana/` | дашборд JSON (опциональный профиль monitoring) | #46 | +| `awg0.conf.example` | пример клиентского конфига | #22 | + +Запуск по ТЗ (после релиза): `--network=host`, `--device=/dev/net/tun`, `--cap-add=NET_ADMIN --cap-add=SYS_MODULE`, `--restart always`. diff --git a/tests/netns/README.md b/tests/netns/README.md new file mode 100644 index 0000000..e6139e1 --- /dev/null +++ b/tests/netns/README.md @@ -0,0 +1,13 @@ +# tests/netns — сетевой тестовый стенд + +Задача **#21**, используется тестами #41 и #43. + +Цель: проверять split-tunnel без реального VPN-провайдера и без доступа к продакшн-сети. + +План харнесса: +1. Создать netns: `client`, `gw` (шлюз с awg-интерфейсом), `uplink` (имитация ISP). +2. Поднять мок WireGuard-endpoint (userspace) вместо реального сервера. +3. Запустить шлюз в netns с теми же правилами, что в контейнере. +4. Проверить, куда ушёл пакет: интерфейс/метка/счётчики ipset и iptables. + +Точки входа: `tests/netns/run.sh` (вызывается через `make test-netns`). diff --git a/ui/README.md b/ui/README.md new file mode 100644 index 0000000..5a4d4bd --- /dev/null +++ b/ui/README.md @@ -0,0 +1,14 @@ +# ui — Web UI (React + TypeScript + Tailwind + shadcn-ui) + +Тёмная тема, 6 страниц из ТЗ. Каркас — задача **#35**, страницы — #36–#39, E2E — #42. + +| Маршрут | Страница | Задача | +|---|---|---| +| `/` | Dashboard: статус, трафик, handshake, аптайм | #36 | +| `/routing` | редактор правил, ipset, домены, режимы, DnD+diff | #37 | +| `/config` | загрузка `.conf`, валидация, маскировка ключей | #38 | +| `/devices` | устройства и политики | #39 | +| `/logs` | журнал, счётчики RETURN vs MARK | #39 | +| `/settings` | GeoIP-расписание, обновления, интеграции | #39 | + +API-клиент генерируется из OpenAPI (#19) в `src/api/generated/`. Взаимодействие: REST + WebSocket.