VPNBotX

VPNBotX - open-source проект для продажи VPN-доступа через Telegram-бота и web-админку. Первый провайдер VPN-панели - 3X-UI. Архитектура оставляет место для Marzban, Hiddify и других панелей без переноса бизнес-логики в интеграционный слой.

Состояние разработки

Проект разрабатывается по этапам. На текущем этапе в репозитории есть:

• FastAPI API с healthcheck и JWT-авторизацией web-админки;
• aiogram entrypoint Telegram-бота с командой /start;
• SQLAlchemy 2 модели и первая Alembic-миграция для пользователей, админов, серверов, тарифов и подписок;
• Celery worker и scheduler на Redis;
• React, TypeScript, Vite и Ant Design каркас админ-панели;
• Docker Compose для локального и production-shaped запуска;
• скрипты автоматической установки, обновления, backup и restore PostgreSQL;
• CLI-диагностика vpnbotx doctor, vpnbotx check-db, vpnbotx check-redis;
• базовый REST API для управления 3X-UI серверами и проверки inbound;
• HTTP-provider XuiProvider для 3X-UI с поддержкой cookie-login, CSRF-login и Bearer API token в 3X-UI 3.1.0+;
• раздел Оплата в web-админке с настройками ручной оплаты, Telegram Stars, Cardlink и ЮKassa;
• базовые provider-интерфейсы для создания invoice в Cardlink, ЮKassa и Telegram Stars;
• запуск обновления из админ-панели для owner-роли при явном включении deployment-настроек.

Выдача ключей, полноценный order/payment flow, баланс, subscription endpoint, промо и рефералы добавляются на следующих этапах.

Быстрый локальный запуск

1. Создайте файл окружения:

   cp .env.example .env

2. Задайте в .env значения:

   • POSTGRES_PASSWORD;
   • DATABASE_URL;
   • SYNC_DATABASE_URL;
   • JWT_SECRET_KEY;
   • CREDENTIALS_ENCRYPTION_KEY.

3. Запустите стек:

   docker compose up --build

4. Создайте первого владельца:

   docker compose exec backend_api vpnbotx create-admin --role owner

5. Откройте:

   • web-интерфейс через Nginx: http://localhost;
   • healthcheck API: http://localhost/health;
   • OpenAPI: http://localhost/docs.

Если TELEGRAM_BOT_TOKEN пустой, контейнер бота стартует без polling.

Автоматическая установка на Ubuntu 24.04

Для Ubuntu Server 24.04 предусмотрен интерактивный установщик:

curl -fsSL https://raw.githubusercontent.com/zirocool93/3panel/main/scripts/install.sh -o install.sh
bash install.sh

Он проверяет наличие git, curl, python3, Docker Engine и Docker Compose plugin, при необходимости устанавливает недостающие компоненты, затем запрашивает:

• TELEGRAM_BOT_TOKEN;
• email и пароль первого администратора;
• режим доступа к web-панели: домен/reverse proxy или локальная сеть;
• URL админки и subscription endpoint;
• включать ли обновление из админ-панели.

После этого скрипт создаёт .env, генерирует секреты, запускает production Compose и создаёт owner-админа.

Proxmox LXC поддерживается, но контейнер должен соответствовать минимальным требованиям: 2 vCPU, минимум 2 GB RAM, лучше 3-4 GB RAM, 12 GB диска, включённые nesting и keyctl. Swap в LXC обычно нужно добавлять на Proxmox host, а не изнутри контейнера.

Подробности - в INSTALL.md.

Обновление

Обновление с сервера:

cd /opt/vpnbotx
bash ./scripts/update.sh main

Перед обновлением выполняется backup PostgreSQL, затем подтягивается Git ref, собираются контейнеры, применяются Alembic-миграции и перезапускается Compose.

Обновление из админ-панели

Экран Обновление доступен в каркасе админки. Запуск обновления разрешён только owner-роли и только когда в .env включено:

ADMIN_UPDATES_ENABLED=true
ADMIN_UPDATE_REF=main

Production Compose монтирует checkout проекта и Docker socket в backend_api, чтобы update API мог запустить контролируемый скрипт scripts/admin_update.sh. Это повышенные права на хосте. Не включайте self-update, если deployment должен быть изолирован от Docker daemon.

Подробности - в UPGRADE.md.

Сервисы

Сервис	Назначение
backend_api	FastAPI, OpenAPI, auth, будущие admin/public endpoints
telegram_bot	aiogram runtime
worker	Celery задачи
scheduler	Celery Beat
postgres	основная БД
redis	очередь, брокер и кэш
frontend	web-админка
nginx	reverse proxy

Локальные проверки

pip install ".[dev]"
ruff check app tests
mypy app
pytest
cd frontend && npm install && npm run build

Stage 2: commerce backend flow

Stage 2 adds the backend foundation for selling VPN from Telegram without putting business logic into bot handlers:

• Telegram users are created/updated on /start, including ref_, promo_, plan_ and source_ payload storage.
• Visible tariffs are exposed through TariffCatalogService and GET /api/catalog/tariffs.
• Orders snapshot tariff price, currency, duration and limits at creation time.
• Payments are idempotent by idempotency_key and by non-empty provider + external_payment_id.
• Telegram Stars payloads use order:{order_id}:payment:{payment_id}:user:{user_id}.
• Manual payments can be confirmed or rejected from admin API.
• Successful payment marks the order paid and queues Celery provisioning.
• Provisioning creates or extends VpnSubscription, creates VpnSubscriptionNode rows and calls XuiProvider.
• Public GET /sub/{token} returns active subscription links as text/plain.
• Trial activation is limited to one successful trial per user.

Local flow check:

1. Run alembic upgrade head or start the backend container, which runs migrations.
2. Create a user, tariff and enabled 3X-UI server/inbound in the admin API.
3. Create POST /api/orders, then POST /api/payments.
4. Confirm manual payment with POST /api/payments/{payment_id}/manual-confirm.
5. Ensure the worker is running; provisioning will fill vpn_subscriptions and /sub/{token}.

Frontend pages for orders/payments/subscriptions are intentionally minimal/TODO in this stage; the backend API is the stable contract for the next bot UI pass.

Telegram Bot MVP

The aiogram 3 bot now uses modular routers and handlers over the backend services/facades. Handlers are intentionally thin: they receive Telegram events, call services, render messages and report errors.

Commands:

• /start - create/update Telegram user, process deep links and open the main menu.
• /menu - open the main menu.
• /buy - show visible tariffs and payment actions.
• /vpn - show active VPN subscriptions and subscription links.
• /trial - activate one-time trial access.
• /support - create a Telegram support request.
• /paysupport - start a payment support request.
• /terms - show usage terms placeholder.
• /privacy - show privacy policy placeholder.
• /ref - show referral link.
• /promo - promo-code placeholder.

The current production payment flow is implemented for Telegram Stars: the bot creates an order/payment, sends a Stars invoice, handles pre_checkout_query and delegates successful_payment to TelegramStarsService/PaymentService. Provisioning still runs through Celery and the common SubscriptionProvisioningService. Cardlink and YooKassa settings remain available in the backend/admin panel, but their bot checkout/webhook flows are planned for later stages.

Диагностика развёрнутого backend-контейнера:

docker compose -f docker-compose.prod.yml exec backend_api vpnbotx doctor
docker compose -f docker-compose.prod.yml exec backend_api vpnbotx check-db
docker compose -f docker-compose.prod.yml exec backend_api vpnbotx check-redis

Документация

• INSTALL.md - установка на сервер;
• UPGRADE.md - обновления и self-update;
• ARCHITECTURE.md - модули, БД и жизненные циклы;
• API.md - текущие и планируемые API endpoints.