mrleo1nid/PnvPanel

Fork 0

Files

T

Leonid Pershin b2ae358250

CI / Backend (build + test) (push) Successful in 1m22s

Details

CI / Frontend (lint + typecheck + build) (push) Successful in 33s

Details

Implement billing functionality and enhance role management

- Introduced billing capabilities, allowing users to request payments for subscription periods (3/6/12 months) with admin approval via Telegram.
- Updated role management to include a `BillingEnabled` property, preventing billing for admin roles.
- Enhanced the `CreateRoleCommand` and `UpdateRoleCommand` to accept billing parameters, ensuring proper handling during role creation and updates.
- Added new endpoints for billing management and integrated billing checks into VPN config creation to enforce payment requirements.
- Updated related services, models, and tests to support the new billing features, ensuring comprehensive coverage and functionality.
- Enhanced documentation to reflect the new billing processes and role management changes.

2026-07-19 01:38:16 +03:00

12 KiB

Raw Blame History

Product Vision & Scope

Проблема

Раздача VPN-доступов через «голую» панель 3x-ui неудобна: администратор вручную заводит клиентов, копирует ссылки, следит за трафиком и сроками. Конечные пользователи не имеют самообслуживания — за каждым конфигом идут к админу.

Решение

PnvPanel — тонкий, но красивый слой самообслуживания поверх одной или нескольких панелей 3x-ui:

Пользователь регистрируется, сам создаёт себе VPN-конфиги, видит трафик/срок, получает ссылку-подписку и QR-код, отзывает ненужные конфиги.
Администратор подключает VPN-серверы (ноды 3x-ui), выбирает какие inbounds доступны для самообслуживания, задаёт лимиты, управляет пользователями и видит статистику в реальном времени.

PnvPanel не заменяет Xray/3x-ui — он оркестрирует их через API (ThreeXui.Net) и хранит свою проекцию данных (пользователи, привязки конфигов, история трафика) в PostgreSQL.

Роли

Роль	Возможности
Guest	Регистрация, вход, публичный эндпоинт подписки (`/sub/{token}`).
User	После активации — CRUD своих конфигов (в рамках квоты роли и доступных инбаундов), просмотр трафика/срока, ссылка/QR, отзыв.
Admin	Всё выше без лимитов + ноды, публикация inbounds с выбором ролей, роли/квоты, активация пользователей, каталог приложений, стата.
(кастомные)	Админ создаёт роли (напр. `vip`) со своей квотой конфигов и назначает их пользователям.

RBAC — динамические роли с квотой

Роли реализованы через ASP.NET Core Identity, но AppRole расширен полем MaxConfigs (квота на число конфигов). Авторизация — policy-based.
Системные роли сидируются: admin (без лимита) и user (MaxConfigs из env, по умолчанию 3).
Админ может создавать новые роли с другой квотой и назначать их пользователям.
У пользователя ровно одна роль; его квота = MaxConfigs этой роли.

Активация пользователей

После регистрации пользователь не активирован и не может создавать конфиги.
Он отправляет запрос на активацию с комментарием (напр. «я Никита» — чтобы админ понял, кто это).
Админ одобряет/отклоняет запрос на сайте или в Telegram. После одобрения — доступно создание конфигов.

Аутентификация и восстановление доступа

Логин — по username (email в системе не используется; SMTP не нужен).
Восстановление пароля: только через привязанный Telegram (self-service). Если Telegram не привязан — пароль сбрасывает админ.
Пока Telegram не привязан, панель настойчиво напоминает это сделать (баннер/уведомления в UI) — это единственный способ самому восстановить доступ.

Сид администратора

Учётка админа сидируется при первом старте из переменных окружения (username, пароль, Telegram id админов). Пример — .env.example. Telegram id админа задаётся через env и используется для админ-действий и уведомлений в боте.

Каналы доступа

Веб-панель (React SPA) — основной интерфейс для User и Admin.
Telegram-бот — вспомогательный канал для User: ссылка на сайт, просмотр своих конфигов и passwordless-вход на сайт через привязанный Telegram (вместо пароля). Детали — telegram-bot.md.

Ключевые пользовательские сценарии

U0. Регистрация и активация

Пользователь регистрируется → получает роль user, статус не активирован.
Отправляет запрос на активацию с комментарием («я Никита»).
Админ видит запрос (на сайте и/или в Telegram) → «Активировать» / «Отклонить».
После одобрения пользователь может создавать конфиги (в пределах квоты роли).

U1. Пользователь создаёт конфиг

Входит в панель (активирован) → «Создать конфиг».
Видит только инбаунды, доступные его роли (напр. «Германия (Trojan)»); выбирает нужный.
Проверка квоты: число активных конфигов < MaxConfigs его роли.
Бэкенд создаёт клиента в 3x-ui (AddClient), сохраняет привязку VpnConfig в БД.
Пользователь получает connection string, ссылку-подписку и QR-код.

U2. Пользователь следит за трафиком

Фоновая синхронизация тянет трафик из 3x-ui; изменения приходят в UI через SignalR (без перезагрузки).
Это только отображение: лимиты по трафику не реализованы — единственная квота — число активных конфигов на роль. Конфиг живёт, пока его явно не отзовут — если только его роль не подписана на биллинг (см. domain-model.md), тогда неоплаченный конфиг может быть временно приостановлен.

A1. Админ подключает ноду и публикует инбаунды

Вводит адрес панели 3x-ui, логин/пароль (шифруются при хранении).
PnvPanel проверяет доступность, синхронизирует список inbounds.
Админ публикует нужные inbounds (напр. «Германия (Trojan)») и указывает роли, которым разрешено создавать конфиги в этом инбаунде (напр. user, vip).

A3. Админ управляет ролями и активацией

Создаёт роль (напр. vip) с нужной квотой конфигов, назначает пользователям.
Обрабатывает запросы на активацию (на сайте или в Telegram): видит комментарий заявителя, решает.

A2. Админ управляет пользователями

Список пользователей, их конфигов и потребления; блокировка/разблокировка; принудительный отзыв конфигов.

T1. Пользователь привязывает Telegram и входит без пароля

В веб-панели (войдя по username+паролю) нажимает «Привязать Telegram» → получает deep-link в бота.
Открывает бота → аккаунт привязывается к его Telegram.
В следующий раз на сайте выбирает «Войти через Telegram» → подтверждает вход в боте → входит без пароля.
В боте может смотреть свои конфиги и открывать сайт.

Функциональность

Реализовано:

Регистрация/вход (JWT + Identity); сид админа из env.
Динамические роли с квотой конфигов (сид admin/user); создание ролей и назначение админом.
Активация пользователей по запросу с комментарием (одобрение на сайте и в Telegram).
Управление нодами; публикация inbounds с выбором доступных ролей.
Создание/просмотр/отзыв конфигов пользователем (проверки активации, квоты, доступа роли к инбаунду); ссылка-подписка + QR.
Синхронизация трафика (фоновая) + realtime-обновления по SignalR.
Базовая статистика для админа.
Telegram-бот: ссылка на сайт, просмотр конфигов, привязка/регистрация через Telegram и passwordless-вход.
Светлая/тёмная тема сайта.
Страница инструкций по подключению + каталог приложений по ОС (админ ведёт, юзер видит сгруппировано).
Лента новостей: админ публикует Markdown-посты, все пользователи видят их живой лентой (SignalR).
Единый Docker-образ (фронт+бек) + PostgreSQL в docker-compose.

Не реализовано:

Тарифы/биллинг/платежи.
Многоуровневые квоты, автопродление, промокоды.
Балансировка нагрузки между нодами, автоскейл.
Реферальная программа; расширенные уведомления (через Telegram/веб).
Мультиязычность сверх RU/EN.

Нефункциональные требования

Безопасность: секреты нод шифруются at-rest; JWT с коротким TTL + refresh; rate-limiting на auth/Telegram-эндпоинты и публичную подписку (создание конфигов им пока не покрыто).
Наблюдаемость: структурные логи (Serilog), health-checks нод, метрики.
Отказоустойчивость к нодам: недоступность одной ноды не роняет панель; операции идемпотентны где возможно.
Производительность: списки с пагинацией; синхронизация трафика батчами.

12 KiB Raw Blame History Unescape Escape