From dde311aab101685880c5c5ddc07761525e66399f Mon Sep 17 00:00:00 2001 From: savsis Date: Thu, 10 Sep 2026 22:30:18 +0500 Subject: [PATCH] docs: mermaid architecture/payment/node-add diagrams, stability notes, troubleshooting Co-Authored-By: Claude Sonnet 5 --- README.md | 79 ++++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 64 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index b055b00..9e46de6 100644 --- a/README.md +++ b/README.md @@ -17,22 +17,43 @@ ## Архитектура +```mermaid +flowchart LR + tg["Telegram юзер"] -->|кнопки| bot["bot.py (aiogram)"] + browser["Браузер / Happ-клиент"] -->|"/sub/{token}"| api["api.py (FastAPI)"] + admin["Админ в браузере"] -->|"/admin/api/*"| api + + bot --> db[("SQLite (db.py)")] + api --> db + + api -->|локально| xray["Xray на этой же ноде"] + api -->|SSH, paramiko| remote["Управляемые ноды"] + + subgraph node1 [Управляемая нода] + remote --> xray2["Xray"] + end ``` -┌─────────────┐ ┌──────────────────────────────┐ -│ Telegram │──────▶│ bot.py (aiogram) │ -│ юзер │ │ выдаёт токен подписки │ -└─────────────┘ └──────────────┬────────────────┘ - │ SQLite (db.py) -┌─────────────┐ ┌──────────────▼────────────────┐ -│ браузер / │──────▶│ api.py (FastAPI) │ -│ Happ клиент │ │ /sub/{token}, /admin/api/* │ -└─────────────┘ │ админка на / (admin.html) │ - └──────────────┬────────────────┘ - │ SSH (paramiko) - ┌──────────────▼────────────────┐ - │ Xray на этой же ноде │ - │ + управляемые ноды по SSH │ - └─────────────────────────────────┘ + +Панель и первая VPN-нода живут на одном сервере. Дополнительные ноды подключаются по SSH (management-ключ, генерится сам при первом добавлении ноды) — панель не устанавливает на себя ничего от ноды, только управляет клиентами через SSH-команды и Xray Stats API. + +### Поток оплаты (когда `PAYMENTS_ENABLED=true`) + +```mermaid +sequenceDiagram + participant U as Юзер (бот) + participant B as bot.py + participant P as ЮKassa/Platega + participant A as api.py + participant X as Xray + + U->>B: выбрал тариф + B->>P: создать платёж + P-->>B: ссылка на оплату + B-->>U: кнопка "Оплатить" + U->>P: оплатил + P->>A: webhook (подпись проверяется) + A->>X: добавить клиента + A->>U: уведомление в Telegram ``` Панель и первая VPN-нода живут на одном сервере. На 443 порту нельзя одновременно держать и настоящий HTTPS (для сайта/подписки), и замаскированный под HTTPS VLESS+Reality трафик — поэтому перед Xray стоит `nginx stream` модуль с `ssl_preread`, который смотрит SNI входящего TLS-соединения и роутит: домены панели/подписки идут на nginx-бэкенд, всё остальное (в том числе Reality-трафик с левым SNI) — на Xray. @@ -91,6 +112,21 @@ bash <(curl -Ls https://panel.example.com/install/ТОКЕН.sh) Вставляешь на чистый сервер (тот же Ubuntu 22/24 или Debian 11/12) — нода сама всё ставит и регистрируется. Если включал WS+TLS — скрипт выпустит для неё отдельный Let's Encrypt сертификат (нужна ещё одна A-запись, см. таблицу выше). Если включал Hysteria2 — поднимет отдельный процесс на UDP. +```mermaid +sequenceDiagram + participant Admin as Админ + participant Panel as Панель + participant Node as Новая нода + + Admin->>Panel: Ноды → Добавить ноду + Panel->>Panel: генерит Reality-ключи, токен + Panel-->>Admin: команда bash <(curl ...ТОКЕН.sh) + Admin->>Node: вставляет команду по SSH + Node->>Node: ставит Xray, настраивает transports + Node->>Panel: POST /nodes/register/ТОКЕН + Panel->>Panel: нода активна, доступна в боте +``` + ## Приём оплаты По умолчанию бот выдаёт подписки бесплатно по кнопке — платежи выключены (`PAYMENTS_ENABLED=false`). Чтобы продавать доступ: @@ -108,6 +144,19 @@ bash <(curl -Ls https://panel.example.com/install/ТОКЕН.sh) Выключено по умолчанию (`HWID_LIMIT_ENABLED=false`) — клиенты, которые не шлют `x-hwid`, при включённом лимите вообще не получат подписку, так что включай только если знаешь, что твои пользователи сидят на приложениях с поддержкой этого заголовка. `HWID_FALLBACK_LIMIT` — лимит по умолчанию для всех, в админке (Подписки → кнопка «Устройства» у юзера) можно посмотреть/удалить привязанные устройства и задать индивидуальный лимит. +## Стабильность и производительность + +- `install.sh` ретраит все сетевые шаги (apt, git, pip, certbot, установка Xray) — 3 попытки с паузой, типичная причина падения свежих VPS-установок это не баги, а моргнувшая сеть/зеркало пакетов. +- SQLite в WAL-режиме + `synchronous=NORMAL` (стандартная безопасная связка для этого режима) — меньше блокировок между ботом и апи, которые пишут в одну базу параллельно. +- Индексы на всех горячих путях (`subscriptions(active, expires_at)` — дергается ботом каждые 90 секунд на проверку истечения; `subscriptions(tg_id)`, `devices(tg_id)`, `payments(status)`) — на паре сотен юзеров разницы не увидишь, но на тысячах — увидишь. +- CI гоняет не только синтаксис, а реальный импорт `api.py`/`bot.py` целиком плюс smoke-тесты платёжной и HWID-логики на живом Ubuntu — ловит баги при импорте/вайринге модулей до того, как они попадут на прод. + +## Частые проблемы при установке + +- **Certbot не может выпустить сертификат** — почти всегда значит DNS A-записи ещё не проехали (обнови и подожди 5-10 минут) или порт 80 занят чем-то ещё (`ss -ltnp | grep :80`). +- **Xray не стартует после установки** — `mbs logs xray`, почти всегда конфликт порта 443 с чем-то другим, что уже там висит (другая панель, старый nginx на 443 напрямую). +- **Панель недоступна, но сервисы `active`** — проверь `nginx -t` и `systemctl status nginx`, скорее всего SNI-роутер (`/etc/nginx/stream.d/mbs.conf`) не подхватился — `nginx -s reload` после любых правок туда вручную. + ## Разработка / вклад Код простой — без сборки фронта, без ORM, без лишних абстракций. `admin.html` — один файл, vanilla JS. Питон-часть — обычные функции, SQLite напрямую.