From b37b4cc1a3a68655be17674de4c92143ce827ce6 Mon Sep 17 00:00:00 2001 From: phobos Date: Sat, 30 May 2026 14:33:22 +0300 Subject: [PATCH] =?UTF-8?q?README:=20public=20docs=20=E2=80=94=20human=20d?= =?UTF-8?q?escription,=20features,=20screenshots=20section,=20update/rollb?= =?UTF-8?q?ack,=20troubleshooting=20table?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 244 ++++++++++++++++++++++++--------------------- docs/img/README.md | 9 ++ 2 files changed, 137 insertions(+), 116 deletions(-) create mode 100644 docs/img/README.md diff --git a/README.md b/README.md index c1a9fc3..27a9bcc 100644 --- a/README.md +++ b/README.md @@ -1,133 +1,154 @@ -# PCA Phobos — Web Panel +# PCA Phobos — VPN, который не отключается -Веб-панель управления для [Phobos](https://git.zerrolabs.org/Ground-Zerro/Phobos) (обфусцированный WireGuard VPN). +**Веб-панель и turnkey-установщик для [Phobos](https://github.com/Ground-Zerro/Phobos)** — обфусцированного WireGuard VPN. Ставится на чистый VPS одной командой, управляет десятками роутеров и устройств с одной страницы, сам переключается между серверами при сбоях и восстанавливается после перезагрузок. -## Быстрый старт (turnkey — с чистого VPS, одной командой) +

+ Панель — активные сессии +

-Ставит ВСЁ со всеми зависимостями: wg-obfuscator, WireGuard, обфускатор-сервисы, -веб-панель, nginx, скрипты онбординга роутеров и сторож авто-восстановления. -Предустановленный Phobos НЕ требуется. +--- + +## Что это простыми словами + +Обычный VPN падает, когда падает сервер или провайдер банит IP. **PCA Phobos — нет.** + +- 🌐 **Маскированный WireGuard** — трафик не отличить от обычного, проходит мимо DPI и блокировок по сигнатуре. +- 🔁 **Авто-переключение между серверами** — сервер лёг или порт прикрыли → роутер сам прыгает на резервный за ~10–15 секунд, без твоего участия. +- 📡 **Работает за любым NAT** — серый IP, мобильный интернет, домашний роутер за провайдером. Управление едет внутри самого защищённого туннеля, поэтому бан публичного IP ему не страшен. +- 🖥️ **Одна команда — новое устройство** — создал клиента в панели → вставил команду на роутер → готово. +- ♻️ **Само-восстановление** — роутер перезагрузился, провайдер сменил IP, сервис отвалился → система поднимет всё обратно сама. +- 📱 **Телефоны** — Android (PhobosWG, с обфускацией) и iPhone (обычный WireGuard) через QR-код. + +--- + +## Возможности + +- **Активные сессии** — VPN IP, Real IP, метка, handshake, трафик RX/TX, Kick. +- **Клиенты VPN** — добавление/удаление, статус online (по handshake на любом сервере), назначение сервера. +- **Мульти-сервер + failover** — приоритеты, балансировка по нагрузке (CPU/RAM), резервные серверы; роутеры переключаются автоматически. +- **NAT-friendly управление** — роутеры сами тянут конфиг по туннелю (`10.25.0.1`), переживает бан публичного IP. +- **Авто-восстановление роутеров** — серверный сторож (watchdog) поднимает роутер после неудачной перезагрузки через KeenDNS. +- **Конфиги для телефона** — 📱 Android `phobos://` + QR, 🍎 iPhone обычный WireGuard + QR. +- **Метки** — имя объекта по IP (видно в сессиях и Telegram). +- **Срок подписки** — дата окончания, обратный отсчёт, автокик + предупреждения. +- **Telegram-уведомления** — подключение/отключение, сервер вверх/вниз, истечение подписки, авто-восстановление. +- **Двуязычный интерфейс** RU/EN + подсказки `?` у каждого действия. +- **Версии и обновления** — обновление и откат прямо из панели. + +--- + +## Скриншоты + +| Сессии | Клиенты | Серверы | +|--------|---------|---------| +| ![Сессии](docs/img/sessions.png) | ![Клиенты](docs/img/clients.png) | ![Серверы](docs/img/servers.png) | + +> Если картинки не отображаются — положи свои PNG в `docs/img/` (`sessions.png`, `clients.png`, `servers.png`). + +--- + +## Быстрый старт (с чистого VPS, одной командой) + +Ставит **всё** со всеми зависимостями: wg-obfuscator, WireGuard, обфускатор-сервисы, веб-панель, nginx, скрипты онбординга роутеров, сторож авто-восстановления. Предустановленный Phobos **не требуется**. ```bash bash <(curl -fsSL https://raw.githubusercontent.com/andrey271192/PCA_Phobos/main/install.sh) ``` -> Если репозиторий приватный — добавь `GH_TOKEN`: -> ```bash -> GH_TOKEN=ghp_xxx bash <(curl -fsSL -H "Authorization: token ghp_xxx" \ -> https://raw.githubusercontent.com/andrey271192/PCA_Phobos/main/install.sh) -> ``` +### С параметрами -### Вторичный сервер (для failover/балансировки) +```bash +PANEL_PASS=МойПароль TG_TOKEN=123:abc TG_CHAT=123456789 \ +bash <(curl -fsSL https://raw.githubusercontent.com/andrey271192/PCA_Phobos/main/install.sh) +``` + +| Переменная | По умолчанию | Описание | +|-------------------|-----------------|----------| +| `PANEL_PASS` | `OcAdmin2026!` | Пароль панели (логин `admin`) | +| `PANEL_PORT` | случайный | Порт веб-панели | +| `API_KEY` | случайный | Общий ключ (агенты + pull-токен роутеров) | +| `OBF_PORTS` | `2083,5443,993` | Порты обфускатора | +| `TG_TOKEN`/`TG_CHAT` | пусто | Telegram-уведомления | +| `ALLOW_PLAIN_WG` | пусто | `=1` открыть порт 51820 для iOS WireGuard (без обфускации) | + +После установки панель напечатает адрес, логин, пароль и **API key** — сохрани их. + +### Вторичный сервер (для failover / балансировки) ```bash MAIN_SERVER= MAIN_API_KEY= \ bash <(curl -fsSL https://raw.githubusercontent.com/andrey271192/PCA_Phobos/main/server/secondary-setup.sh) ``` -### С кастомными параметрами - -```bash -PANEL_PASS=AdminPass456 \ -TG_TOKEN=1234567890:AABBCCDDaabbccdd \ -TG_CHAT=123456789 \ -bash <(curl -fsSL https://raw.githubusercontent.com/andrey271192/PCA_Phobos/main/install.sh) -``` - -| Переменная | По умолчанию | Описание | -|--------------|----------------|---------------------------------| -| `PANEL_PASS` | `OcAdmin2026!` | Пароль веб-панели (admin) | -| `TG_TOKEN` | пусто | Telegram bot token | -| `TG_CHAT` | пусто | Telegram chat ID для уведомлений| -| `PANEL_PORT` | `8443` | Порт веб-панели | +Затем в панели → **Серверы** → добавь его в список. --- -## Возможности +## Клиенты для телефона -- **Активные сессии** — VPN IP, Real IP, handshake, трафик RX/TX, Kick -- **Клиенты VPN** — добавить/удалить через Phobos, статус online/offline -- **Именование объектов** — привязать имя к Real IP (отображается в сессиях и Telegram) -- **Срок подписки** — дата окончания для каждого клиента: - - Date picker в таблице клиентов - - Обратный отсчёт (18д, 3д⚠️, завтра⚠️, истёк⛔) - - При истечении: автокик + Telegram уведомление - - Предупреждения за 3 дня и 1 день -- **Telegram уведомления** — 🟢 подключение, 🔴 отключение, ⚠️ за 3 дня, ⛔ истёк -- **Настройки** — смена пароля панели, Telegram bot token + chat ID, интервал мониторинга -- **Инфо о сервере** — порты, пути, команда установки на роутер +В таблице **Клиенты** у каждого клиента есть кнопки: + +- 📱 **Android** — `phobos://`-ссылка + QR для приложения **PhobosWG** (с обфускацией). Скан QR → импорт. +- 🍎 **iPhone / iOS** — обычный WireGuard-конфиг + QR для официального WireGuard (**без** обфускации). Требует открытого порта 51820 (`ALLOW_PLAIN_WG=1` при установке). + +> Для каждого устройства создавай **отдельного клиента** (свой ключ и IP). Один конфиг на двух устройствах = конфликт ключей. + +--- + +## Обновление и откат + +Проект версионируется (см. файл `VERSION` и git-теги `vX.Y.Z`). + +**Из панели:** Настройки → «Версия и обновления» → **Обновить** / **Откатить**. + +**Из консоли:** + +```bash +phobos-update # обновить до последней версии +phobos-update v1.1.0 # обновить до конкретной версии (git tag) +phobos-update --rollback # откатить на предыдущую версию +phobos-update --version # показать установленную и доступную версию +phobos-update --list # список бэкапов +``` + +Обновляется только слой панели и скриптов. **Ключи WireGuard, `server.env` и клиенты не трогаются.** Перед каждым обновлением делается бэкап → откат восстанавливает его. + +--- + +## Возможные проблемы и решения + +| Симптом | Причина | Решение | +|---------|---------|---------| +| **Команда установки → 403 / не качается** | репозиторий приватный | Сделай репозиторий публичным, либо ставь с токеном: `GH_TOKEN=ghp_xxx bash <(curl -fsSL -H "Authorization: token ghp_xxx" .../install.sh)` | +| **Панель не открывается** | панель перезапускалась (обновление) / сервер недоступен | Подожди 5 сек, обнови страницу. Проверь: `systemctl status phobos-panel` | +| **Клиент Offline, хотя работает** | роутер на резервном сервере | Норма — статус считается по handshake на **любом** сервере; обнови страницу | +| **«SSH timeout» при тесте роутера** | роутер за NAT, входящий SSH закрыт | Это нормально — управление идёт по pull-каналу через туннель, SSH не нужен | +| **У роутера нет интернета на LAN-устройствах** | WG-интерфейс `private` / нет привязки устройства к политике | На роутере: `security-level public` + `ip hotspot host policy `; health-скрипт чинит это сам в течение ~5 мин | +| **Роутер не поднялся после перезагрузки** | Entware/USB не запустил автозагрузку | Сторож (watchdog) поднимет за ~3 мин (нужны KeenDNS + web-логин роутера в `router_access`), либо перезагрузи роутер ещё раз | +| **iPhone не подключается по `phobos://`** | на iOS нет приложения-обфускатора | Используй 🍎-конфиг (обычный WireGuard) + открой 51820 (`ALLOW_PLAIN_WG=1`) | +| **Смена сервера применяется не сразу** | роутер тянет конфиг по cron | Применяется за ~12–15 сек, не мгновенно | +| **Забыл порт панели** | случайный порт | `cat /opt/phobos-panel/.port` | +| **Забыл API key** | | `grep server_api_key /opt/phobos-panel/settings.json` | + +Логи: `journalctl -u phobos-panel -n 50` · сторож: `/opt/Phobos/server/watchdog.log` · роутер: `/opt/etc/Phobos/health.log`. --- ## Архитектура ``` -Keenetic Router → wg-obfuscator (client) → :51821 → wg-obfuscator (server) → :51820 WireGuard → Internet - │ - 10.25.0.x - │ - Web Panel :8443 - (Flask + Gunicorn) -``` - -- Протокол: WireGuard + wg-obfuscator (обфускация от DPI) -- Аутентификация: ключевые пары (нет паролей — только WireGuard ключи) -- Подсеть VPN: `10.25.0.0/16` -- Мониторинг сессий: каждые 30 сек (настраивается) - ---- - -## Управление - -```bash -# Phobos (VPN) -phobos # Интерактивное меню -systemctl status wg-quick@wg0 # WireGuard -systemctl status wg-obfuscator # Обфускатор -wg show wg0 # Активные peers - -# Веб-панель -systemctl status phobos-panel -systemctl restart phobos-panel -journalctl -u phobos-panel -f -``` - ---- - -## Структура файлов - -``` -/opt/Phobos/ -├── clients/ # Клиенты VPN (ключи, конфиги) -│ └── {name}/ -│ ├── metadata.json -│ ├── {name}.conf -│ └── wg-obfuscator.conf -├── server/ -│ ├── server.env # Конфигурация сервера -│ └── wg-obfuscator.conf -└── repo/server/scripts/ - └── phobos-client.sh # Управление клиентами - -/opt/phobos-panel/ -├── app.py # Flask веб-панель -├── settings.json # Настройки (пароль, Telegram, метки, сроки) -└── .secret_key # Ключ сессии - -/etc/wireguard/ -└── wg0.conf # WireGuard конфигурация -``` - ---- - -## Обновление панели - -```bash -curl -fsSL https://raw.githubusercontent.com/andrey271192/PCA_Phobos/main/app.py \ - > /opt/phobos-panel/app.py -systemctl restart phobos-panel +Телефон/Роутер → wg-obfuscator (клиент) ──обфускация──► сервер :2083/5443/993 + │ де-обфускация + WireGuard :51820 + │ 10.25.0.x + ┌──────────┴──────────┐ + Веб-панель Failover на + (Flask+Gunicorn) резервные серверы ``` +- Протокол: **WireGuard + wg-obfuscator** (обфускация от DPI). +- Управление роутерами — по **туннелю** (`10.25.0.1`), устойчиво к бану публичного IP. +- Состояние: JSON-файлы (без БД). --- @@ -141,19 +162,10 @@ systemctl restart phobos-panel ## На основе и благодарности -PCA Phobos — это веб-панель и turnkey-инсталлятор поверх: +PCA Phobos — это веб-панель и turnkey-инсталлятор поверх отличных открытых проектов: -- [**Phobos**](https://github.com/Ground-Zerro/Phobos) (Ground-Zerro) — обфусцированный WireGuard. Поддержать автора: [Boosty](https://boosty.to/ground_zerro) ❤️ -- [**WireGuard Easy**](https://github.com/wg-easy/wg-easy) (Emile Nijssen, AGPL-3.0) — веб-панель WireGuard, на которой основан Phobos. Поддержать автора: [GitHub Sponsors](https://github.com/sponsors/WeeJeWel) ❤️ -- [**wg-obfuscator**](https://github.com/ClusterM/wg-obfuscator) (ClusterM) — обфускация WireGuard-трафика. Поддержать автора: [Boosty](https://boosty.to/cluster) ❤️ +- [**Phobos**](https://github.com/Ground-Zerro/Phobos) — обфусцированный WireGuard, автор **Ground_Zerro**. Поддержать: [Boosty](https://boosty.to/ground_zerro) ❤️ +- [**WireGuard Easy**](https://github.com/wg-easy/wg-easy) — веб-панель WireGuard (AGPL-3.0), автор **Emile Nijssen**. Поддержать: [GitHub Sponsors](https://github.com/sponsors/WeeJeWel) ❤️ +- [**wg-obfuscator**](https://github.com/ClusterM/wg-obfuscator) — обфускация WireGuard-трафика (GPL-3.0), автор **ClusterM**. Поддержать: [Boosty](https://boosty.to/cluster) ❤️ Спасибо авторам за отличные инструменты. - -## Клиенты для телефона - -В таблице клиентов у каждого клиента есть кнопки: - -- 📱 **Android** — `phobos://`-ссылка + QR для приложения **PhobosWG** (с обфускацией). Скан QR → импорт. -- 🍎 **iPhone / iOS** — обычный WireGuard-конфиг + QR для официального WireGuard (БЕЗ обфускации). Требует открытого порта 51820 на сервере (поставь `ALLOW_PLAIN_WG=1` при установке, либо удали правило `iptables ... 51820 ... DROP`). - -> Для каждого устройства создавай **отдельного клиента** (свой ключ и IP). Один конфиг на двух устройствах = конфликт ключей. diff --git a/docs/img/README.md b/docs/img/README.md new file mode 100644 index 0000000..c16fafd --- /dev/null +++ b/docs/img/README.md @@ -0,0 +1,9 @@ +# Скриншоты + +Положи сюда 3 PNG (панель открыта — сделай скрины своих страниц): + +- `sessions.png` — страница «Сессии» +- `clients.png` — страница «Клиенты» +- `servers.png` — страница «Серверы» + +README в корне на них ссылается. Рекомендуемая ширина ~1000–1400px.