mirror of
https://github.com/andrey271192/kaskad.git
synced 2026-09-20 13:49:56 +00:00
86 lines
5.2 KiB
Markdown
86 lines
5.2 KiB
Markdown
# 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
|