Initial release of Kaskad

Каскадная маршрутизация русских сайтов через свой набор RU-серверов
с failover, Telegram-ботом и веб-интерфейсом.

- bin/        — failover-script, route/domain helpers, ams/ru bootstrap
- bot/        — Telegram-бот (Python, long-poll)
- webui/      — Flask single-page dashboard
- docs/       — установка, архитектура, API бота и WebUI
- examples/   — шаблоны конфигов

docs/bot.md

@@ -0,0 +1,88 @@
+# Telegram-бот
+
+Бот живёт на одном из ам. серверов (там, где есть доступ к api.telegram.org). Управляет всеми остальными по SSH через свой ed25519 ключ.
+
+## Доступ
+
+Бот реагирует ТОЛЬКО на сообщения из чата с `chat_id == TG_CHAT_ID` (см. `/etc/wireguard/notify.env`). Остальные сообщения игнорирует.
+
+## Команды
+
+### Туннели
+
+| Команда | Описание |
+|---|---|
+| `/status` | Endpoint и handshake age для каждого ам. сервера |
+| `/use <id>` | Принудительно переключить все ам. на RU-сервер с этим id |
+| `/primary` | Алиас `/use primary` |
+| `/backup` | Алиас `/use backup` |
+| `/failover` | Алиас `/use backup` |
+| `/failback` | Алиас `/use primary` |
+
+### RU-серверы
+
+| Команда | Описание |
+|---|---|
+| `/server-list` | Список RU-серверов с приоритетами |
+| `/server-add <host> <user> <ssh_port> <id> [prio] [password=PW] [label=...] [listen_port=1939] [probe_port=ssh_port]` | Бот SSHит на новый RU, ставит wireguard, генерит ключ, добавляет 4 ам. как peer'ы, открывает 1939/UDP, кладёт свой ключ для будущего управления |
+| `/server-remove <id\|host>` | Удалить RU из ротации (сам сервер не выключается, просто перестаёт использоваться) |
+| `/bot-key` | Показать публичный SSH-ключ бота — для добавления в `authorized_keys` на новом сервере (если не хочется передавать пароль через TG) |
+
+**Безопасность**: при `password=PW` бот после обработки автоматически удаляет своё сообщение через TG API. Но в моменте оно всё равно попадает в логи TG, поэтому надёжнее — использовать ключевую авторизацию (см. `/bot-key`).
+
+### Ам. серверы
+
+| Команда | Описание |
+|---|---|
+| `/ams-list` | Список ам. серверов |
+| `/ams-add <host> <user> <ssh_port> <id> [tunnel_ip=auto] [xray_iface=amn0] [password=PW]` | Бот: ставит wireguard, кладёт свой ключ, генерит WG-ключ ам., выдаёт следующий свободный 10.0.0.X, копирует все скрипты и шаблон ru.conf со sga1, поднимает туннель на текущий primary, ставит cron, и добавляет [Peer] на ВСЕХ RU-серверах |
+| `/ams-remove <id\|host>` | Снять [Peer] со всех RU; обновить JSON. Сам сервер остаётся работать (X-ray, OS), просто перестаёт быть в туннеле |
+
+X-ray на новый ам. сервер бот НЕ ставит — это вне его компетенции.
+
+### Маршруты (IP/CIDR)
+
+| Команда | Описание |
+|---|---|
+| `/ips` | Все маршруты сразу (база + доп.) |
+| `/list` | Только дополнительные (добавленные через бот) |
+| `/add <IP/CIDR ...>` | Добавить (через пробел или с новой строки; `/32` дописывается сам) |
+| `/remove <IP/CIDR ...>` | Удалить |
+| `/clear` | Удалить ВСЕ доп. маршруты |
+
+Базовые подсети (10 крупных сервисов: Яндекс, ВК, Mail.ru, Госуслуги, Ozon) трогать через бот нельзя — они в `/etc/wireguard/ru-base.aips`. Если нужно изменить — править вручную и `/usr/local/bin/ru-routes.sh apply`.
+
+### Домены
+
+| Команда | Описание |
+|---|---|
+| `/list-domains` | Список доменов с количеством IP |
+| `/add-domain <domain ...>` | Резолвит каждый домен через `dig +short A`, добавляет полученные IP как /32 в маршруты на всех ам. серверах. Формат: пробел или с новой строки. |
+| `/remove-domain <domain ...>` | Убирает домен и его IP (если их не использует другой домен). |
+| `/show-domain <domain>` | Текущие IP конкретного домена |
+| `/refresh-domains` | Принудительно перерезолвить все домены |
+
+Cron `17 */6 * * * /usr/local/bin/ru-domains.py refresh` — автоматический refresh каждые 6 часов. Лог: `/var/log/ru-domains.log`.
+
+### Прочее
+
+| Команда | Описание |
+|---|---|
+| `/bot-key` | Публичный SSH-ключ бота |
+| `/help` | Полная справка |
+
+## Уведомления
+
+При каждом автоматическом переключении (failover/failback успех/failback провал) бот шлёт сообщение в `TG_CHAT_ID` с тэгом `[ru-failover @ <hostname>]`. См. `journalctl -t ru-failover` для истории.
+
+## Логи
+
+```bash
+# логи бота
+journalctl -u ru-tg-bot.service -f
+
+# логи failover
+journalctl -t ru-failover -f
+# или
+grep ru-failover /var/log/syslog | tail
+```