chore(#16): skeleton репозитория — README, Makefile, линтеры, зависимости

2026-10-21 23:28:50 +03:00
parent f7936fa882
commit 63c4fa930d
8 changed files with 240 additions and 38 deletions
@@ -1,40 +1,64 @@
 # awg-dash

-# awg-dash 🚀
-
-**awg-dash** — это легковесная и удобная веб-панель (Dashboard) для визуального управления сервером **Amnezia WireGuard (AWG)**. Она позволяет создавать, удалять и просматривать конфигурации пользователей в один клик через современный веб-интерфейс, защищенный от блокировок.
-
-[![License: MIT](https://shields.io)](https://opensource.org)
-[![GitHub Stars](https://shields.io)](https://github.com)
-
---
-
-## ✨ Особенности / Features
-
- 🛠️ **Полная поддержка Amnezia WireGuard:** Тонкая настройка параметров обфускации (`Jc`, `Jmin`, `Jmax`, `S1`, `S2`, `H1`, `H2`, `H3`, `H4`) прямо из панели.
- 👥 **Управление пользователями:** Создание, удаление, временная заморозка и управление лимитами пиров (клиентов).
- 📊 **Мониторинг в реальном времени:** Графики потребления трафика, статус подключения клиентов и общая нагрузка на сервер.
- 📱 **QR-коды и конфиги:** Мгновенная генерация QR-кодов и скачивание `.conf` файлов для импорта в официальное приложение Amnezia.
- 🔒 **Безопасность:** Авторизация по паролю/токену, поддержка сессий и возможность работы за обратным прокси (Nginx, Caddy).
- 🐳 **Docker-first:** Быстрый запуск одной командой через Docker Compose.
-
---
-
-## 🛠️ Технологический стек / Tech Stack
-
- **Backend:** Node.js (Express) / Python (FastAPI) / Go *(выберите нужное)*
- **Frontend:** Vue.js / React / Простой HTML+JS *(выберите нужное)*
- **База данных:** SQLite / JSON-file (минималистично, без тяжелых БД)
- **Ядро:** Amnezia WireGuard (модифицированная утилита `wg`)
-
---
-
-## 🚀 Быстрый старт / Quick Start
-
-### Способ 1: Через Docker Compose (Рекомендуемый)
-
-1. Клонируйте репозиторий:
-   ```bash
-   git clone https://github.com
-   cd awg-dash
-   ```
+VPN-шлюз **AmneziaWG** с интеллектуальной маршрутизацией: один Docker-образ = туннель + policy routing + split-tunnel (GeoIP / DNS) + REST API v1 + Web UI (тёмная тема).
+
+- Эпик и декомпозиция: Gitea issue **#15** (`embeddevio/awg-dash`).
+- Исполнение: Hermes Kanban, борда **`awg-dash`** (`hermes kanban --board awg-dash list`).
+- PoC-референс: `embeddevio/amneziawg-docker-gateway` (bash + iptables, `docs/technical-specification.md`).
+
+## Архитектура
+
+Два процесса в одном образе:
+
+| Процесс | Пользователь | Ответственность |
+|---|---|---|
+| `awg-agent` | root | awg/wg-интерфейс, iptables/ipset, dnsmasq, policy routing, метрики |
+| `awg-api` | непривилегированный | FastAPI: REST API v1, WebSocket, статика UI |
+
+Обмен — unix-socket `/run/awg/agent.sock`; состояние — SQLite в `/data`, конфиги `.conf` в `/config`.
+Принятые решения зафиксированы в `docs/adr/`.
+
+## Быстрый старт (после релиза 1.0)
+
+```bash
+docker run -dit --name=vpn-gateway \
+  --network=host \
+  --device=/dev/net/tun:/dev/net/tun \
+  --cap-add=NET_ADMIN --cap-add=SYS_MODULE \
+  --restart always \
+  -v /srv/awg/config:/config -v /srv/awg/data:/data \
+  registry.example.com/vpn-gateway:latest
+```
+
+Web UI: `http://<host>:8080`. До релиза образ собирается локально: `make build`.
+
+## Разработка
+
+```bash
+make venv    # локальное окружение (.venv)
+make lint    # ruff + mypy
+make test    # pytest + coverage (порог 70%)
+make build   # docker build образа (задача #18)
+make dev-up  # dev-стенд (задача #21)
+```
+
+Сетевые тесты выполняются в netns-стенде (`tests/netns/`), без реального VPN-провайдера.
+
+## Структура репозитория
+
+| Путь | Назначение |
+|---|---|
+| `backend/awg_agent/` | привилегированный агент: туннель, маршрутизация, GeoIP, DNS, метрики |
+| `backend/awg_api/` | FastAPI-приложение (REST + WS + статика UI) |
+| `backend/tests/` | unit/integration-тесты (pytest) |
+| `ui/` | React + TypeScript + Tailwind + shadcn-ui |
+| `deploy/` | Dockerfile, compose-профили, entrypoint, Grafana-дашборд |
+| `docs/adr/` | архитектурные решения |
+| `tests/netns/` | сетевой тестовый стенд |
+
+## Процесс разработки
+
+1 задача = 1 issue = 1 ветка `feat/<issue>-slug` = 1 PR.
+
+Гейты мержа: CI green, coverage нового кода ≥ 70 %, security scan low/none, ревью владельца роли.
+Merge в `main` и деплой в prod — только TechLead после гейтов. Все операции с репозиторием — через Gitea MCP.