docs: full README

README.md

@@ -1 +1,85 @@
-# kaskad
+# Kaskad
+
+Каскадная маршрутизация русских сайтов через свой набор RU-серверов (WireGuard) с автоматическим failover, Telegram-ботом и веб-интерфейсом.
+
+## Что это
+
+Несколько зарубежных серверов с X-ray («ам.») держат WireGuard-туннели к одному из RU-серверов. Российские IP/домены идут через RU, всё остальное — через зарубежный. Если RU упал — за минуту переключение на следующий по приоритету. Когда восстановился — пробный failback с автоматическим откатом если WG не отвечает.
+
+```
+телефон/клиент ──> ам. сервер (X-ray) ──┬──> RU primary  ──> RU-сайты
+                                        ├──> RU backup   (failover)
+                                        └──> RU N        (по приоритету)
+                  └──> остальное идёт напрямую через ам.
+```
+
+## Возможности
+
+- **N RU-серверов** в конфиге, упорядочены по приоритету
+- **Авто-failover** по handshake age + TCP-проба; cooldown между переключениями; автоматический failback с проверкой
+- **Telegram-бот** для всех операций: смотреть статус, переключать вручную, добавлять/удалять серверы, домены, IP
+- **Веб-интерфейс** с тем же функционалом
+- **Маршруты по доменам**: бот резолвит `vk.com → IP`, добавляет в маршруты на всех ам. серверах. Cron каждые 6ч переподнимает резолв
+- **Доп. подсети/IP** добавляются на лету через бот или WebUI; переживают рестарт туннеля и сервера
+- **Уведомления в TG** при каждом failover/failback
+
+## Структура репозитория
+
+```
+kaskad/
+├── bin/                     # скрипты для ам. серверов (failover, switch, routes, domains)
+├── bot/                     # Telegram-бот + systemd unit
+├── webui/                   # Flask-приложение
+├── examples/                # шаблоны конфигов
+├── docs/                    # подробная документация
+└── README.md
+```
+
+## Быстрый старт
+
+См. [docs/install.md](docs/install.md) для полной установки.
+
+Краткая последовательность:
+
+1. **Настроить первый RU-сервер** вручную (см. `docs/install.md` § «RU-сервер»)
+2. **Настроить первый ам. сервер** (см. § «Ам. сервер»)
+3. **Создать `/etc/wireguard/ru-servers.json`** по шаблону `examples/ru-servers.example.json`
+4. **Запустить TG-бот** на одном из ам. серверов (`bot/ru-tg-bot.service`)
+5. **(опц.) Запустить WebUI** на том же ам. сервере (`webui/ru-webui.service`)
+6. Дальше — добавлять RU/ам./домены/IP через бот или WebUI
+
+## Команды бота
+
+| Категория | Команды |
+|---|---|
+| Туннели | `/status`, `/use <id>`, `/primary`, `/backup` |
+| RU-серверы | `/server-list`, `/server-add`, `/server-remove`, `/bot-key` |
+| Ам. серверы | `/ams-list`, `/ams-add`, `/ams-remove` |
+| Маршруты | `/ips`, `/list`, `/add <IP/CIDR>`, `/remove <IP/CIDR>`, `/clear` |
+| Домены | `/list-domains`, `/add-domain <domain>`, `/remove-domain <domain>`, `/show-domain <domain>`, `/refresh-domains` |
+| Прочее | `/help` |
+
+Полный синтаксис: [docs/bot.md](docs/bot.md).
+
+## Веб-интерфейс
+
+Запускается на любом ам. сервере (там же где бот), HTTP basic auth.
+
+После запуска: `http://<ам-сервер>:8088`
+
+Подробнее: [docs/webui.md](docs/webui.md).
+
+## Архитектура
+
+См. [docs/architecture.md](docs/architecture.md) — как устроены failover, маршрутизация, синхронизация конфига между серверами.
+
+## Безопасность
+
+- Конфиги (`ru-servers.json`, `notify.env`, `webui.env`) с правами `600`, **не коммитятся** в репо
+- SSH между серверами — по ключам; пароли используются только при первичной онбординге нового сервера через `password=` в боте/WebUI и **сразу затираются** после установки ключа
+- Веб-интерфейс через basic auth, рекомендуется ставить за HTTPS reverse-proxy (nginx/caddy)
+- Telegram-бот принимает команды только от заранее заданного `TG_CHAT_ID`
+
+## Лицензия
+
+MIT