mirror of
https://github.com/anten-ka/kaskad-pro.git
synced 2026-05-19 11:26:02 +00:00
Kaskad PRO v2.3: progress bar on startup, full uninstall with double confirmation, docs and user guide
Made-with: Cursor
This commit is contained in:
anten-ka
310
DOCS.md
Normal file
310
DOCS.md
Normal file
@@ -0,0 +1,310 @@
|
||||
# Kaskad PRO — документация (v2.2)
|
||||
|
||||
## Что такое Kaskad PRO
|
||||
|
||||
Kaskad PRO — bash-скрипт для Linux, который создаёт **каскадный “мост”** (DNAT + MASQUERADE) между клиентом и вашим зарубежным VPN/Proxy сервером.
|
||||
|
||||
Схема:
|
||||
|
||||
- **Клиент** → **RU VPS (Kaskad PRO)** → **Foreign VPN/Proxy** → Интернет
|
||||
|
||||
Скрипт:
|
||||
|
||||
- Добавляет правила `iptables` (NAT + FORWARD)
|
||||
- Включает `net.ipv4.ip_forward=1`
|
||||
- Включает BBR (fq + bbr)
|
||||
- Сохраняет правила (netfilter-persistent/iptables-persistent где доступно)
|
||||
|
||||
---
|
||||
|
||||
## Требования
|
||||
|
||||
- **VPS с Linux** (Ubuntu/Debian/CentOS/Fedora)
|
||||
- Доступ **root**
|
||||
- Исходящий доступ в интернет (для установки пакетов и GeoIP)
|
||||
- Пакеты (скрипт установит автоматически): `iptables`, `curl`, `jq`, `qrencode` (+ persistent для Debian/Ubuntu)
|
||||
|
||||
---
|
||||
|
||||
## Установка
|
||||
|
||||
### Вариант A: репозиторий публичный
|
||||
|
||||
```bash
|
||||
curl -sL https://raw.githubusercontent.com/anten-ka/kaskad-pro/main/install.sh -o install.sh && chmod +x install.sh && ./install.sh
|
||||
```
|
||||
|
||||
### Вариант B: репозиторий приватный (GitHub PAT)
|
||||
|
||||
```bash
|
||||
curl -sL -H "Authorization: token YOUR_GITHUB_PAT" https://raw.githubusercontent.com/anten-ka/kaskad-pro/main/install.sh -o install.sh && chmod +x install.sh && ./install.sh
|
||||
```
|
||||
|
||||
### Повторный запуск меню
|
||||
|
||||
```bash
|
||||
gokaskad
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Где взять ключи/токены
|
||||
|
||||
### 1) Telegram Bot Token (где взять токен бота)
|
||||
|
||||
Нужен для запуска Telegram-бота.
|
||||
|
||||
1. В Telegram откройте **`@BotFather`**
|
||||
2. Отправьте команду: `/newbot`
|
||||
3. Введите имя бота (любое)
|
||||
4. Введите username бота (должен оканчиваться на `bot`)
|
||||
5. Скопируйте **token**, который выдаст BotFather (формат `123456789:AA...`)
|
||||
|
||||
### 2) Telegram Chat ID (как привязать доступ)
|
||||
|
||||
В Kaskad PRO управление ограничено **по Chat ID**.
|
||||
|
||||
Вариант авто:
|
||||
|
||||
- В меню: `8) Telegram Bot → 2) Chat ID (авто)`
|
||||
- Перед этим отправьте своему боту любое сообщение (например `/start`)
|
||||
|
||||
Вариант вручную:
|
||||
|
||||
- В меню: `8) Telegram Bot → 3) Chat ID (вручную)`
|
||||
- Вставьте chat id (число)
|
||||
|
||||
### 3) GitHub PAT (для приватного репозитория)
|
||||
|
||||
Нужен только если репозиторий **private**, чтобы скачивать `install.sh` по `raw.githubusercontent.com`.
|
||||
|
||||
Рекомендуемый вариант: **fine-grained PAT** с доступом только к репозиторию.
|
||||
|
||||
1. GitHub → Settings → Developer settings → **Personal access tokens** → **Fine-grained tokens**
|
||||
2. Create token
|
||||
3. Repository access: **Only select repositories** → выберите `kaskad-pro`
|
||||
4. Permissions: **Contents = Read-only**
|
||||
5. Сгенерируйте и сохраните токен
|
||||
|
||||
Использование: в команде установки или обновления через `curl -H "Authorization: token ..."`
|
||||
|
||||
---
|
||||
|
||||
## Основные функции (терминальное меню)
|
||||
|
||||
Ниже — что делает каждый пункт меню и когда использовать.
|
||||
|
||||
### 1) AmneziaWG / WireGuard (UDP)
|
||||
|
||||
Создаёт каскад для UDP-сервисов (AWG/WireGuard/OpenVPN-UDP).
|
||||
|
||||
- Вы вводите `IP` и `порт`
|
||||
- Создаётся правило: `udp :порт (RU VPS) → IP:порт (Foreign)`
|
||||
|
||||
На клиенте (AWG/WireGuard) меняете endpoint на IP вашего RU VPS.
|
||||
|
||||
### 2) VLESS / XRay (TCP)
|
||||
|
||||
Каскад для TCP-прокси (VLESS/VMess/Trojan/Reality и т.д.).
|
||||
|
||||
Логика та же:
|
||||
|
||||
- `tcp :порт (RU VPS) → IP:порт (Foreign)`
|
||||
|
||||
### 3) TProxy / MTProto (TCP)
|
||||
|
||||
Каскад для MTProto/TProxy (обычно для Telegram).
|
||||
|
||||
### 4) Custom Rule (TCP/UDP, разные порты)
|
||||
|
||||
Позволяет пробрасывать:
|
||||
|
||||
- разные вход/выход порты
|
||||
- любой TCP/UDP сервис
|
||||
|
||||
Пример: клиент подключается к `RU_VPS:2222`, а трафик уходит на `FOREIGN:22` (SSH).
|
||||
|
||||
### 5) Правила
|
||||
|
||||
Показывает активные DNAT правила (включая IP каскада) и информацию о целевом сервере:
|
||||
|
||||
- имя
|
||||
- примечание
|
||||
- GeoIP (страна/ISP), если определено
|
||||
|
||||
### 6) Ping (live)
|
||||
|
||||
Live ping выбранного целевого IP:
|
||||
|
||||
- обновление каждые 1 сек
|
||||
- ASCII-бар + цветовая шкала
|
||||
- статистика min/max/avg и потери
|
||||
|
||||
### 7) Мониторинг (авто)
|
||||
|
||||
Мониторинг целевых серверов:
|
||||
|
||||
- Интервал проверок: **10 сек / 1 мин / 5 мин**
|
||||
- Порог задержки: в ms
|
||||
- Частота уведомлений (не чаще): **10 сек / 60 сек / 5 мин / 15 мин**
|
||||
- Если задержка выше порога или timeout — отправляет alert в Telegram
|
||||
|
||||
Служба `kaskad-monitor`:
|
||||
|
||||
- запускается автоматически, если есть хотя бы один монитор
|
||||
- останавливается автоматически, если мониторов нет
|
||||
|
||||
### 8) Telegram Bot
|
||||
|
||||
Настройка токена/Chat ID и управление службой `kaskad-bot`.
|
||||
|
||||
### 9) Удалить правило
|
||||
|
||||
Удаляет 1 DNAT правило и связанные INPUT/FORWARD правила.
|
||||
|
||||
### 10) Сбросить всё
|
||||
|
||||
Удаляет **только** правила, созданные Kaskad (по маркеру `kaskad`).
|
||||
|
||||
### 11) Обновить скрипт
|
||||
|
||||
Скачивает свежий `install.sh` из репозитория и заменяет `/usr/local/bin/gokaskad`.
|
||||
|
||||
Если репозиторий приватный — обновление нужно выполнять с PAT (или настроить отдельный update-token внутри скрипта/бота).
|
||||
|
||||
### 12) PROMO
|
||||
|
||||
Партнёрские хостинги и промокоды (плюс QR).
|
||||
|
||||
### 13) Инструкция
|
||||
|
||||
Встроенная краткая инструкция (страницы).
|
||||
|
||||
### 14) Имена серверов
|
||||
|
||||
Редактор имён и примечаний для целевых IP.
|
||||
|
||||
Данные хранятся в `/etc/kaskad/aliases`.
|
||||
|
||||
---
|
||||
|
||||
## Telegram Bot (как пользоваться)
|
||||
|
||||
### Запуск
|
||||
|
||||
1. Создайте токен через `@BotFather`
|
||||
2. На сервере:
|
||||
|
||||
```bash
|
||||
gokaskad
|
||||
```
|
||||
|
||||
Меню:
|
||||
|
||||
- `8) Telegram Bot → 1) Токен бота` — вставьте token
|
||||
- `8) Telegram Bot → 2) Chat ID (авто)` — отправьте боту `/start`, затем Enter в терминале
|
||||
- `8) Telegram Bot → 4) Запустить`
|
||||
|
||||
В Telegram:
|
||||
|
||||
- Отправьте боту `/start`
|
||||
|
||||
### Режимы меню
|
||||
|
||||
- **Inline** — кнопки под сообщением (по умолчанию)
|
||||
- **Reply keyboard** — большие кнопки внизу экрана
|
||||
|
||||
Переключение:
|
||||
|
||||
- В inline: кнопка `⌨️ Reply-клавиатура`
|
||||
- В reply: команда `/inline`
|
||||
|
||||
### Добавление сервера через бота
|
||||
|
||||
Поток:
|
||||
|
||||
1. Нажимаете протокол (AWG/VLESS/MTProto/Custom)
|
||||
2. Вводите IP
|
||||
3. Бот делает:
|
||||
- GeoIP (страна/ISP)
|
||||
- ping 3 раза (1 сек)
|
||||
4. Просит имя
|
||||
5. Просит примечание
|
||||
6. Просит порт(ы)
|
||||
7. Создаёт правило
|
||||
|
||||
### Ping в боте
|
||||
|
||||
- 1 раз — мгновенно
|
||||
- 10 раз — показывает список и среднее
|
||||
- 60 сек — обновляет прогресс каждые 10 секунд, затем итог
|
||||
|
||||
### Мониторинг в боте
|
||||
|
||||
1. `📊 Монитор` → `➕ Добавить` → выбрать сервер
|
||||
2. Выбрать интервал (10с/1мин/5мин)
|
||||
3. Ввести порог (мс)
|
||||
4. Выбрать частоту уведомлений (10с/60с/5мин/15мин)
|
||||
|
||||
---
|
||||
|
||||
## Где хранятся данные
|
||||
|
||||
| Путь | Назначение |
|
||||
|---|---|
|
||||
| `/usr/local/bin/gokaskad` | основной скрипт/команда |
|
||||
| `/etc/kaskad/config` | BOT_TOKEN, BOT_CHAT_ID, MENU_STYLE |
|
||||
| `/etc/kaskad/aliases` | IP → имя/примечание/GeoIP |
|
||||
| `/etc/kaskad/monitors/*.conf` | мониторы IP |
|
||||
| `/var/log/kaskad.log` | лог действий |
|
||||
|
||||
---
|
||||
|
||||
## Службы systemd
|
||||
|
||||
```bash
|
||||
systemctl status kaskad-bot
|
||||
journalctl -u kaskad-bot -f
|
||||
|
||||
systemctl status kaskad-monitor
|
||||
journalctl -u kaskad-monitor -f
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Бот не отвечает
|
||||
|
||||
- Проверьте, что задан `BOT_TOKEN` и `BOT_CHAT_ID`
|
||||
- Проверьте службу:
|
||||
|
||||
```bash
|
||||
systemctl status kaskad-bot
|
||||
journalctl -u kaskad-bot -f
|
||||
```
|
||||
|
||||
### Raw GitHub не скачивается
|
||||
|
||||
Если репозиторий приватный — нужен PAT:
|
||||
|
||||
```bash
|
||||
curl -sL -H "Authorization: token YOUR_GITHUB_PAT" https://raw.githubusercontent.com/anten-ka/kaskad-pro/main/install.sh
|
||||
```
|
||||
|
||||
### Мониторинг не запускается
|
||||
|
||||
Мониторинг запускается автоматически, если есть конфиги в `/etc/kaskad/monitors/`.
|
||||
Проверьте:
|
||||
|
||||
```bash
|
||||
ls -la /etc/kaskad/monitors/
|
||||
systemctl status kaskad-monitor
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Лицензия
|
||||
|
||||
Для частного использования. Распространение запрещено.
|
||||
|
||||
Reference in New Issue
Block a user