# 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