Язык / Language: Русский | English
Описание проекта
Этот проект представляет собой Telegram бота для продажи и управления VPN подписками через панель управления 3X-UI. Бот позволяет пользователям приобретать подписки на VPN, создавать и управлять своими профилями, а администраторам — управлять пользователями и отслеживать статистику.
Основные возможности:
- Регистрация пользователей и предоставление пробного периода
- Продление подписки через платежную систему Telegram
- Создание и удаление VPN профилей (VLESS) в панели 3X-UI
- Временные профили на 30 минут для тестирования
- Уведомления об истечении подписки
- Генерация QR-кодов для быстрого подключения
- Новые команды быстрого доступа: /renew, /connect, /stats, /help
- Административное меню для управления пользователями и рассылки сообщений
- Статистика использования трафика
- Автоматическое исправление дат подписок и профилей
- Проверка и синхронизация подписок между 3x-ui и базой данных
Установка и настройка
Предварительные требования
- Python 3.10+
- Панель управления 3X-UI
- Создан inbound с параметром “Безопасность
Reality”
- Опционально: отдельный inbound для временных профилей
- Telegram бот (созданный через
@BotFather)
- SSL сертификаты для HTTPS (для временных профилей)
Шаги установки
- Клонируйте репозиторий:
git clone https://github.com/QueenDekim/XRay-bot
cd XRay-bot
- Установите зависимости:
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
- Настройте переменные окружения:
cp src/.env.example src/.env # Отредактируйте .env файл со своими значениями
- Запустите бота:
python src/app.py
Для запуска веб-сервера временных профилей (опционально):
python src/temp_profile_server.py
Настройка переменных окружения
Обязательные параметры в .env:
BOT_TOKEN - токен вашего Telegram бота от @BotFatherPAYMENT_TOKEN - платежный токен от @BotFatherADMINS - ID администраторов через запятуюXUI_API_URL - URL панели 3X-UI (например: http://ip:54321)XUI_USERNAME и XUI_PASSWORD - учетные данные панелиINBOUND_ID - ID инбаунда в панели 3X-UI- Параметры Reality (публичный ключ, fingerprint, SNI и т.д.)
Опциональные параметры для временных профилей:
TEMP_INBOUND_ID - ID инбаунда для временных профилей (по умолчанию: 2)TEMP_REALITY_PUBLIC_KEY - публичный ключ для временных профилейTEMP_REALITY_FINGERPRINT - fingerprint для временных профилейTEMP_REALITY_SNI - SNI для временных профилейTEMP_REALITY_SHORT_ID - short ID для временных профилейTEMP_REALITY_SPIDER_X - spider X для временных профилейTEMP_WEB_SERVER_PORT - порт веб-сервера временных профилей (по умолчанию: 8080)TEMP_SSL_CERT_PATH - путь к SSL сертификату (fullchain.pem)TEMP_SSL_KEY_PATH - путь к приватному ключу SSL (privkey.pem)
Команды бота
Пользовательские команды
/start - Запуск бота и регистрация/menu - Главное меню/renew - Продление подписки/connect - Подключение к VPN с QR-кодом/stats - Просмотр статистики использования/help - Справка
Административные функции
Администраторы имеют доступ к специальному меню с функциями:
- Добавление/удаление времени подписки
- Удаление пользователя с очисткой профиля в 3x-ui
- Просмотр списка пользователей
- Проверка и исправление расхождений подписок
- Исправление всех профилей с неправильными датами
- Статистика использования сети
- Рассылка сообщений пользователям
- Управление статическими профилями
Техническая архитектура
Файловая структура
./
├── src
│ ├── .env.example # Пример файла конфигурации
│ ├── app.py # Основной файл приложения
│ ├── config.py # Конфигурация приложения
│ ├── database.py # Модели и функции базы данных
│ ├── functions.py # Функции для работы с 3X-UI API
│ ├── handlers.py # Обработчики команд и callback'ов
│ └── temp_profile_server.py # Веб-сервер временных профилей
├── templates # Шаблоны для временных профилей
│ ├── temp_profile.html # Страница временного профиля
│ └── error.html # Страница ошибок
├── docs # Документация на других языках
│ └── README.en_US # Документация на английском языке
├── users.db # Файл базы данных SQLite
├── README.md # Документация на русском языке
└── requirements.txt # Зависимости проекта
База данных
Проект использует SQLite с SQLAlchemy ORM. Основные таблицы:
users - информация о пользователях:
telegram_id - ID пользователя в Telegramsubscription_end - дата окончания подпискиvless_profile_data - данные VPN профиля в JSONis_admin - флаг администратора
static_profiles - статические VPN профили:
name - имя профиляvless_url - VLESS ссылка
Основные компоненты
1. app.py
Главный файл приложения, который:
- Инициализирует базу данных
- Запускает фоновую задачу проверки подписок
- Обрабатывает платежные запросы
- Регистрирует команды бота в меню Telegram
- Запускает polling бота
2. config.py
Загрузка и валидация конфигурации через Pydantic. Содержит:
- Настройки подключения к 3X-UI панели
- Параметры Reality протокола
- Параметры для временных профилей
- Цены и скидки на подписки
- Функции для расчета стоимости
3. database.py
Модели и функции для работы с базой данных:
- Модель
User для хранения пользователей
- Модель
StaticProfile для статических профилей
- Функции управления подписками и профилями
- Функция validate_and_fix_subscription_date для исправления дат
- Функция delete_user для удаления пользователей
- Функции get_users_with_profiles и fix_all_subscription_dates
4. functions.py
Класс XUIAPI для взаимодействия с панелью 3X-UI:
- Аутентификация в панели
- Создание и удаление клиентов
- Обновление времени истечения профилей
- Получение статистики использования
- Генерация VLESS URL
- Функция get_safe_expiry_timestamp для безопасного получения timestamp
- Функция check_and_fix_subscriptions для проверки подписок
- Функция force_update_profile_expiry для принудительного обновления
5. handlers.py
Обработчики команд и callback’ов:
- Команды
/start, /menu, /renew, /connect, /stats, /help
- Обработка платежей
- Административные функции
- Управление профилями
- Обработчики для новых админ-функций
6. temp_profile_server.py
Веб-сервер для временных профилей:
- FastAPI приложение
- Создание временных профилей на 30 минут
- Автоматическое удаление по истечении времени
- HTTPS поддержка с SSL сертификатами
Работа с платежами
Бот использует встроенную платежную систему Telegram. При выборе подписки:
- Пользователь выбирает период подписки
- Бот создает инвойс через
bot.send_invoice()
- После успешной оплаты обрабатывается через
process_successful_payment()
- Подписка пользователя продлевается
- Автоматически обновляется expiry_time в 3x-ui
Административные функции
Администраторы имеют доступ к специальному меню с функциями:
- Добавление/удаление времени подписки
- Удаление пользователя с полным очищением профиля в 3x-ui
- Просмотр списка пользователей
- Проверка подписок - выявление расхождений между 3x-ui и БД
- Исправление профилей - автоматическое исправление всех дат
- Статистика использования сети
- Рассылка сообщений пользователям
- Управление статическими профилями
Интеграция с 3X-UI
Бот взаимодействует с панелью 3X-UI через ее API:
- Аутентификация по логину/паролю
- Получение данных инбаунда
- Добавление клиентов в настройки инбаунда
- Обновление конфигурации инбаунда
- Обновление expiry_time для существующих клиентов
Генерация VLESS URL
Формат VLESS URL для Reality:
vless://{client_id}@{host}:{port}?type=tcp&security=reality&pbk={public_key}&fp={fingerprint}&sni={sni}&sid={short_id}&spx={spider_x}#{remark}
Мониторинг и уведомления
Бот автоматически проверяет подписки каждый час и:
- Уведомляет пользователей за 24 часа до окончания
- Удаляет профили с истекшей подпиской
- Отправляет уведомления администраторам о платежах
- Исправляет некорректные даты подписок
Генерация QR-кодов
Бот автоматически генерирует QR-коды для профилей:
- Использует библиотеку
qrcode
- Создает QR-код с подпиской на профиль
- Отправляет изображение пользователю
Временные профили
Функционал временных профилей позволяет:
- Создавать профили на 30 минут для тестирования
- Использовать отдельный inbound для временных профилей
- Автоматически удалять профили по истечении времени
- Предоставлять доступ через веб-интерфейс
Безопасность
- Все чувствительные данные хранятся в переменных окружения
- Используется валидация конфигурации через Pydantic
- Ограниченный доступ к административным функциям
- Безопасное хранение платежной информации через Telegram
- Валидация и исправление дат подписок
- Проверка расхождений между 3x-ui и базой данных
Возможные проблемы и решения
- Ошибки подключения к 3X-UI - проверьте URL и учетные данные
- Проблемы с платежами - убедитесь в корректности платежного токена
- Ошибки базы данных - проверьте права на запись в директорию
- Не работают уведомления - проверьте настройки времени и часового пояса
- Некорректные даты подписок - используйте функцию “Исправить профили” в админ-меню
- Расхождения в датах - используйте функцию “Проверить подписки” в админ-меню
Для дополнительной информации обращайтесь к документации aiogram и 3X-UI.
Donation USDT (TON Network):
| QR Code |
Address |
 |
UQA9SigQDdUlZhFj3C5L71gFwjs2kSZu1b9g7Huu1PQujrVS |
| Demo - Полностью функциональный бот |
Связь с разработчиком |
| Telegram: @Dekim_vpn_bot |
Telegram: @QueenDek1m |
|
Discord: from_russia_with_love |
评论