From ec900379f98f4d9192096d6b0ebb631bd6a39fb7 Mon Sep 17 00:00:00 2001 From: andrey271192 Date: Sat, 2 May 2026 09:14:26 +0300 Subject: [PATCH] docs: full README --- README.md | 86 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 85 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index ff76a03..d349441 100644 --- a/README.md +++ b/README.md @@ -1 +1,85 @@ -# kaskad \ No newline at end of file +# 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 `, `/primary`, `/backup` | +| RU-серверы | `/server-list`, `/server-add`, `/server-remove`, `/bot-key` | +| Ам. серверы | `/ams-list`, `/ams-add`, `/ams-remove` | +| Маршруты | `/ips`, `/list`, `/add `, `/remove `, `/clear` | +| Домены | `/list-domains`, `/add-domain `, `/remove-domain `, `/show-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