Skip to content

dostapn/3x-ui-vpn-bot

BranchesTags

Repository files navigation

🤖 VPN Telegram Bot для 3x-ui

Telegram-бот для управления VPN-ключами через 3x-ui панель с функциями self-service для клиентов и административной панелью.

Python 3.10+ aiogram 3.13 License: MIT

📋 Содержание

🎯 Возможности

Для клиентов

  • 🔑 Просмотр ключей - VLESS конфиги с Reality параметрами
  • ➕ Запрос нового ключа - отправка запроса администратору
  • 📊 Статистика - просмотр использованного трафика
  • 🔄 Автоуведомления - получение ключей сразу после одобрения
  • 💬 Двусторонняя связь - отправка сообщений админу с поддержкой reply и цитат

Для администратора

  • ✅ Выдача новых ключей - создание клиента в выбранном inbound
  • 🔄 Присвоение существующих - привязка готового ключа к пользователю
  • 🔑 Управление ключами - просмотр всех ключей и привязанных пользователей
  • 👥 Управление пользователями - отвязка ключей, блокировка пользователей
  • 📋 Выбор inbound - создание в конкретном inbound или клонирование
  • 💬 Двусторонняя связь - ответы через Reply с автоматическим определением получателя
  • 🚫 Блокировка - автоматическая блокировка на 24 часа
  • 📊 Списки - незавершённые запросы, все ключи, заблокированные
  • 📈 Отчётность - ежедневные, недельные и месячные отчёты по трафику

📋 Требования

  • Python 3.10+
  • 3x-ui v2.8.8+ (с Xray v26.1.18+)
  • OS Ubuntu 20.04+ или другой Linux
  • Telegram Bot Token - создайте у @BotFather

🚀 Установка

Локальная разработка (Docker)

Рекомендуется для разработки и тестирования.

# 1. Клонируйте репозиторий
git clone <your-repo>
cd 3x-ui-vpn-bot

# 2. Настройте .env
cp .env.example .env
nano .env  # Укажите BOT_TOKEN, ADMIN_ID, XUI_PASSWORD

# 3. Запустите
docker-compose up -d

# 4. Проверьте логи
docker-compose logs -f bot

3x-ui панель: http://localhost:2053

Продакшн деплой (Standalone)

Рекомендуемый способ для работы на VDS рядом с 3x-ui.

# 1. Подключитесь к серверу
ssh root@your-server

# 2. Установите зависимости
sudo apt update && sudo apt install -y python3 python3-pip python3-venv git

# 3. Создайте директорию
sudo mkdir -p /opt/vpn-bot && cd /opt/vpn-bot

# 4. Скопируйте файлы (с вашей машины)
scp -r bot/ requirements.txt vpn-bot.service .env.example root@your-server:/opt/vpn-bot/

# 5. Создайте виртуальное окружение и установите зависимости
sudo python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
deactivate

# 6. Настройте .env
sudo cp .env.example .env
sudo nano .env  # Укажите все параметры
sudo chmod 600 .env

# 7. Установите systemd сервис
sudo cp vpn-bot.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable vpn-bot
sudo systemctl start vpn-bot

# 8. Проверьте статус
sudo systemctl status vpn-bot
sudo journalctl -u vpn-bot -f

⚙️ Конфигурация

Переменные окружения (.env)

# Telegram
BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
ADMIN_ID=123456789

# 3x-ui API (внутренний адрес для бота)
# ВАЖНО: Должен включать протокол http:// или https://
XUI_HOST=http://127.0.0.1:2053
XUI_USERNAME=admin
XUI_PASSWORD=your_password
XUI_USE_SSL_CERT=false  # false для самоподписанных сертификатов

# Server (публичный адрес для клиентов)
DOMAIN=your.domain.com
SUBSCRIPTION_PORT=2096

# Database
DB_PATH=/etc/x-ui/x-ui.db

# Logging
LOG_LEVEL=INFO

Важные параметры:

Параметр Описание Пример
XUI_HOST Внутренний адрес 3x-ui API (обязательно с протоколом) http://127.0.0.1:2053 или https://localhost:8443/dostapn-3x-ui/
XUI_USE_SSL_CERT Проверка SSL сертификата false для самоподписанных, true для валидных
DOMAIN Публичный домен/IP для клиентских подключений example.com или IP адрес
DB_PATH Путь к БД 3x-ui /etc/x-ui/x-ui.db (обычно)

📱 Использование

Команды для клиентов

  • /start - Главное меню
  • /help - Справка
  • /status - Статус бота
  • /id - Ваш Telegram ID
  • 🔑 Мои ключи - Просмотр всех ключей
  • ➕ Запросить новый ключ - Отправить запрос

Команды для администратора

  • /requests - Список незавершённых запросов
  • /keys - Список всех ключей с пользователями
  • /bans - Список заблокированных
  • /unban_ID - Разблокировать пользователя

Работа с запросами (админ)

При получении запроса доступны действия:

  • ✅ Выдать новый ключ - Создать клиента в inbound
  • 🔄 Присвоить существующий - Привязать готовый ключ
  • ❌ Отклонить (блок 24ч) - Заблокировать пользователя
  • ❌ Отклонить - Просто отклонить без блокировки
  • 💬 Написать сообщение - Связаться с пользователем

Управление ключами (админ)

Команда /keys показывает все ключи с привязанными пользователями. Для каждого ключа доступно:

  • 👥 Управление пользователями
    • 🗑 Отвязать - удалить привязку ключа от пользователя
    • 🚫 Забанить - заблокировать пользователя на 24ч

🔧 Управление

Управление через systemd

# Запуск/остановка/перезапуск
sudo systemctl start vpn-bot
sudo systemctl stop vpn-bot
sudo systemctl restart vpn-bot

# Статус
sudo systemctl status vpn-bot

# Автозапуск
sudo systemctl enable vpn-bot
sudo systemctl disable vpn-bot

Просмотр логов

# В реальном времени
sudo journalctl -u vpn-bot -f

# Последние N строк
sudo journalctl -u vpn-bot -n 100

# За сегодня
sudo journalctl -u vpn-bot --since today

# С момента последней ошибки
sudo journalctl -u vpn-bot -p err

Мониторинг ресурсов

# Потребление памяти и CPU
ps aux | grep "python.*bot.main"

# Типичные значения: ~80-100 MB RAM, <1% CPU в idle

Запуск тестов (Docker)

# Спек потока отчётов по трафику (all_time, delta, активность)
# Без xui (если своя 3x-ui): --no-deps
docker compose run --rm --no-deps bot python tests/verify_traffic_flow.py

# Или если контейнер уже запущен:
docker exec vpn-bot python tests/verify_traffic_flow.py

🏗 Архитектура

Структура проекта

3x-ui-vpn-bot/
├── bot/
│   ├── __init__.py
│   ├── main.py                    # Точка входа, инициализация бота
│   ├── config.py                  # Конфигурация из .env
│   ├── database.py                # Работа с БД 3x-ui
│   ├── handlers/
│   │   ├── client.py              # Обработчики команд клиентов
│   │   └── admin.py               # Обработчики команд администратора
│   └── utils/
│       ├── xui_api.py             # Обёртка для 3x-ui REST API
│       ├── keyboards.py           # Инлайн и Reply клавиатуры
│       ├── messages.py            # Шаблоны и форматирование сообщений
│       └── scheduler.py           # AsyncIO планировщик для отчётов
├── tests/
│   └── verify_traffic_flow.py     # Спек: проверка потока отчётов по трафику
├── .env.example                   # Пример конфигурации
├── .flake8                        # Конфиг flake8
├── BOT_SCENARIOS.md               # Детальные сценарии взаимодействия
├── CHANGELOG.md                   # История изменений
├── docker-compose.yml             # Docker Compose для разработки
├── Dockerfile                     # Docker образ
├── pyproject.toml                 # Конфиг для linting/formatting
├── requirements.txt               # Python зависимости
├── docker/                        # Docker dev окружение
├── vpn-bot.service                # systemd сервис

База данных

Бот создаёт свои таблицы в БД 3x-ui. Существующие данные не изменяются.

telegram_users - пользователи Telegram

  • tg_id (PRIMARY KEY) - Telegram ID
  • username - Telegram username
  • first_name, last_name - Имя пользователя
  • blocked_until - Timestamp блокировки (NULL если не заблокирован)
  • created_at - Дата регистрации

user_keys - связь пользователи ↔ ключи (один ключ → много пользователей)

  • id - Автоинкремент
  • tg_id - Telegram ID пользователя
  • client_email - Email клиента в 3x-ui
  • inbound_id - ID inbound'а
  • comment - Комментарий
  • created_at - Дата создания
  • UNIQUE(tg_id, client_email) - один пользователь не может иметь ключ дважды

pending_requests - очередь запросов на новые ключи

  • request_id (PRIMARY KEY) - UUID запроса
  • tg_id - Telegram ID
  • username, first_name, last_name - Данные пользователя
  • created_at - Дата запроса

traffic_history - дневные снимки трафика для недельных/месячных отчётов

  • email - Email клиента
  • up, down - Трафик за день (bytes)
  • date - Дата снимка (YYYY-MM-DD)

all_time_snapshots - снимки all_time для расчёта delta и активности

  • email - Email клиента
  • all_time - Накопленный трафик (bytes)
  • date - Дата снимка (YYYY-MM-DD)

Схема взаимодействия

┌─────────────┐
│  Telegram   │
│   Clients   │
└──────┬──────┘
       │
       ▼
┌─────────────┐      ┌──────────────┐
│  VPN Bot    │◄────►│  3x-ui API   │
│  (Python)   │      │  (REST)      │
└──────┬──────┘      └──────┬───────┘
       │                    │
       ▼                    ▼
┌─────────────────────────────────────┐
│        x-ui.db (SQLite)             │
│  ┌────────────────────────────────┐ │
│  │  3x-ui tables                  │ │
│  │  (inbounds, clients, etc.)     │ │
│  └────────────────────────────────┘ │
│  ┌────────────────────────────────┐ │
│  │  Bot tables                    │ │
│  │  (users, keys, requests, etc.) │ │
│  └────────────────────────────────┘ │
└─────────────────────────────────────┘

📈 Отчётность

Начиная с версии 1.5.0 бот автоматически отправляет отчёты по трафику. С v1.5.2 используется колонка all_time из client_traffics (работает без Xray API).

Как работает

  1. Ежедневный отчёт — каждый день в 00:01

    • Все клиенты: Профиль | Всего (all_time) | Δ вчера | Активность
    • Формат delta: X.XX GB (было: Y.YY GB) или 0.00 GB (вчера: −) для новых
    • Активность: X из Y, 0 из Y: неактивен N дн. подряд, показаний нет

  2. Недельный отчёт — по понедельникам в 00:01

    • Все клиенты: Профиль | Всего | За период | X из 7 дн.

  3. Месячный отчёт — 1-го числа в 00:01

    • Все клиенты: Профиль | Всего | За период | X из N дн.

Планировщик (Scheduler)

  • Использует APScheduler для асинхронного выполнения задач
  • Работает параллельно с основным polling'ом бота
  • Логирует все действия в журнал systemd

Требования для отчётности

  • Синхронизация времени на сервере
  • Доступ к таблицам client_traffics, traffic_history, all_time_snapshots в БД

🐛 Troubleshooting

Бот не запускается

# Проверьте конфигурацию
cd /opt/vpn-bot
source venv/bin/activate
python -c "from bot.config import config; print('Config OK')"

# Проверьте подключение к 3x-ui
curl -k http://127.0.0.1:2053/login

# Проверьте права на БД
ls -la /etc/x-ui/x-ui.db
sudo chmod 644 /etc/x-ui/x-ui.db

База данных заблокирована

# Проверьте процессы
sudo lsof /etc/x-ui/x-ui.db

# Перезапустите сервисы
sudo systemctl restart x-ui
sudo systemctl restart vpn-bot

Ошибки API 3x-ui

# Проверьте доступность
curl -k -X POST http://127.0.0.1:2053/login \
  -d "username=admin&password=yourpassword"

# Проверьте логи
sudo journalctl -u vpn-bot -n 100 -p err

Бот не отвечает

# Проверьте статус
sudo systemctl status vpn-bot

# Проверьте логи в реальном времени
sudo journalctl -u vpn-bot -f

# Перезапустите
sudo systemctl restart vpn-bot

Найти путь к БД 3x-ui

# Поиск БД
sudo find /etc -name "x-ui.db" 2>/dev/null
sudo find /var -name "x-ui.db" 2>/dev/null

# Проверка доступа
sudo sqlite3 /etc/x-ui/x-ui.db "SELECT COUNT(*) FROM inbounds;"

Отчёты не отправляются

С v1.5.2 отчёты формируются из колонки all_time в client_traffics. Первый запуск сохраняет снимки; отчёт придёт на следующий день.

# Проверьте логи scheduler'а
sudo journalctl -u vpn-bot | grep -E "scheduler|daily traffic|all_time"

# Проверьте клиентов и all_time
sudo sqlite3 /etc/x-ui/x-ui.db "SELECT email, all_time FROM client_traffics LIMIT 5;"

# Убедитесь, что админ ID верный в .env
grep ADMIN_ID /opt/vpn-bot/.env

🔒 Безопасность

  • ✅ Проверка прав администратора на всех admin-хендлерах
  • ✅ Автоматическая блокировка при отклонении запроса
  • ✅ Валидация данных перед отправкой в API
  • ✅ Логирование всех действий с timestamp'ами
  • ✅ Использование существующей БД 3x-ui (нет дублирования)
  • ✅ Защита .env файла (chmod 600)
  • ✅ Отсутствие хранения паролей в памяти
  • ✅ HTTPS поддержка для 3x-ui API

📚 Дополнительно

Сценарии взаимодействия

Подробные сценарии работы с ботом для клиентов и администраторов:

📄 BOT_SCENARIOS.md - Полное описание всех сценариев

  • 14 детальных сценариев (7 клиентских + 7 административных)
  • Примеры реальных диалогов с ботом
  • Пошаговые инструкции для каждого действия

История изменений

Все изменения проекта документируются в CHANGELOG.md

Текущая версия: 1.5.2 (отчёты по all_time)

Правила для разработчиков

🤖 AGENTS.md - Правила для AI-агентов при разработке

  • Стандарты качества кода (PEP 8, Type Hints)
  • Требования к комментариям и документации
  • Процесс тестирования и deployment

🔗 Ссылки

📝 Лицензия

MIT License

🤝 Поддержка

Если возникли вопросы:

  1. Проверьте секцию Troubleshooting
  2. Изучите логи: sudo journalctl -u vpn-bot -f
  3. Откройте Issue с описанием проблемы и релевантными логами

About

🤖 Telegram-бот для управления VPN-ключами 3x-ui панели. Self-service для клиентов + админка для управления пользователями и ключами. Python + aiogram + SQLite.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages