English Version | Русская Версия

v1.22.5 — профессиональная экосистема для мониторинга и управления серверной инфраструктурой
(Systemd / Docker / API / WebUI / PWA / Multi-Node / Remote SSH / Backup Manager)

1. О проекте
2. Ключевые возможности
3. Архитектура
4. Быстрый старт
5. Веб-интерфейс
6. Безопасность
7. Структура проекта
8. Документация
9. Лицензия

VPS Manager Telegram Bot — это комплексное решение enterprise-класса для управления серверной инфраструктурой через Telegram и веб-интерфейс.

• Системные администраторы — автоматизация рутинных задач
• DevOps инженеры — мониторинг множества серверов из одной точки
• VPN провайдеры — управление X-ray/VLESS панелями
• Хостинг-провайдеры — клиентский мониторинг

✅ Централизованное управление — один интерфейс для всех серверов
✅ Real-time мониторинг — мгновенные обновления без перезагрузки
✅ Безопасность — enterprise-класса защита с WAF и аудитом
✅ Масштабируемость — от 1 до 1000+ серверов
✅ Мобильность — управление с телефона через Telegram

• ✅ Полная асинхронность — AsyncIO, aiohttp, aiosqlite
• ✅ Низкое потребление — ~100MB RAM на агенте
• ✅ Кольцевые буферы — оптимизация памяти через deque
• ✅ Garbage Collection — автоматическая очистка

• ✅ Неограниченное количество нод — масштабируемая архитектура
• ✅ Real-time метрики — CPU, RAM, Disk, Network
• ✅ Удаленное выполнение — команды на любом сервере
• ✅ Централизованный dashboard — единая панель управления

• ✅ WAF — защита от SQL Injection, XSS, Path Traversal
• ✅ Rate Limiting — защита от DDoS (100 req/min)
• ✅ Brute-force Protection — автоблокировка после 5 попыток
• ✅ Audit Logging — детальные логи всех событий
• ✅ E2E Encryption — Fernet + XOR шифрование
• ✅ RBAC — роли Root/Admin/User

• ✅ PWA — работает как нативное приложение
• ✅ SSE (Server-Sent Events) — обновления без перезагрузки
• ✅ Темная тема — автоматическое переключение
• ✅ Адаптивный дизайн — Mobile-first подход
• ✅ Графики в реальном времени — Chart.js визуализация

• ✅ Real-time статус — все systemd сервисы
• ✅ SSE стриминг — обновления каждые 5 секунд
• ✅ Start/Stop/Restart — управление одной кнопкой
• ✅ Зашифрованное хранилище — персистентная конфигурация
• ✅ Детальная информация — логи, uptime, PID

• ✅ Настраиваемые пороги — CPU/RAM/Disk по выбору
• ✅ Глобальные и индивидуальные — для агента и каждой ноды
• ✅ Даунтайм алерты — нода недоступна > 60 сек
• ✅ SSH мониторинг — уведомления о входах
• ✅ Fail2Ban интеграция — блокировка IP

• ✅ Русский язык — полная локализация
• ✅ English — complete translation
• ✅ Переключение на лету — без перезапуска

• ✅ Docker Compose — простой деплой
• ✅ Два режима — Root (полный доступ) / Secure (изоляция)
• ✅ Автообновление — git pull + restart
• ✅ Watchdog — автоперезапуск при сбое
• ✅ Health checks — мониторинг состояния

Паттерн Agent-Client с централизованным управлением:

┌─────────────────────────────────────────────────┐
│  🤖 Telegram Bot (Main Agent)                   │
│  ├── 📊 SQLite DB (nodes, users, metrics)       │
│  ├── 🌐 Web Dashboard (Aiohttp + SSE)            │
│  ├── 🔌 API на базе aiohttp (HTTP + Real-time)  │
│  └── ⏰ Background Tasks (monitoring, alerts)    │
└─────────────────────────────────────────────────┘
              ↓         ↓         ↓
    ┌─────────┴─────────┴─────────┴───────┐
    │                                     │
┌───▼────┐  ┌────────┐  ┌────────┐  ┌─────▼───┐
│ Node 1 │  │ Node 2 │  │ Node 3 │  │ Node N  │
│ (VPS)  │  │ (VPS)  │  │ (VPS)  │  │ (VPS)   │
└────────┘  └────────┘  └────────┘  └─────────┘

Технологический стек:

• Backend: Python 3.10+, Aiogram 3.x, Aiohttp, Tortoise ORM
• Database: SQLite (aiosqlite)
• Frontend: Tailwind CSS, Vanilla JavaScript, Chart.js
• Real-time: Server-Sent Events (SSE)
• Security: Argon2, Fernet, XOR encryption
• Infrastructure: Docker, Docker Compose, Systemd

📖 Подробнее: ARCHITECTURE.md

Минимальные:

• Ubuntu 20.04+ / Debian 11+
• Python 3.10+
• 1 GB RAM
• 10 GB Disk

Рекомендуемые:

• 2 GB RAM
• 20 GB SSD
• 2 CPU cores

1. Получите токен бота в @BotFather
2. Узнайте свой Telegram ID через @userinfobot
3. Убедитесь, что установлены curl и git:

   sudo apt update && sudo apt install -y curl git

bash <(wget -qO- https://raw.githubusercontent.com/jatixs/tgbotvpscp/main/deploy.sh)

Выберите режим установки:

• 1) Docker - Secure Mode — Рекомендуется (изоляция, безопасность)
• 3) Docker - Root Mode — Полный доступ (для перезагрузки сервера)

Введите данные:

• Bot Token (от BotFather)
• Admin User ID (ваш Telegram ID)

🎉 Бот запущен! API доступен на http://YOUR_IP:8080

1. Откройте Telegram → 🖥 Ноды
2. Нажмите ➕ Добавить ноду
3. Введите имя → Скопируйте токен

bash <(wget -qO- https://raw.githubusercontent.com/jatixs/tgbotvpscp/main/deploy.sh)

Выберите 8) Установить НОДУ (Клиент)

Введите:

• URL агента: http://MAIN_SERVER_IP:8080
• Токен: полученный от бота

✅ Нода появится в списке через несколько секунд!

http://YOUR_SERVER_IP:8080

Первый вход:

• Username: admin
• Password: admin (измените после входа!)

• Real-time графики CPU/RAM/Disk
• Список всех нод с статусами
• Сетевой трафик (текущий и исторический)
• Быстрые действия (перезагрузка, обновление)

• Alerts Config — пороги уведомлений (CPU 80%, RAM 90%, Disk 85%)
• Keyboard Config — видимость кнопок в Telegram
• User Management — добавление/удаление пользователей
• Language — смена языка интерфейса

• Статус всех systemd сервисов
• Управление (Start/Stop/Restart)
• Добавление в мониторинг
• Детальная информация (PID, uptime, logs)

• Bot logs (real-time)
• Watchdog logs
• Node logs (для каждой ноды отдельно)
• Audit logs (события безопасности)

Важно:

• GET /api и GET /api/ возвращают JSON-индекс с описанием групп маршрутов и не отдают метрики.
• GET /api/events, GET /api/events/logs, GET /api/events/node, GET /api/events/services являются внутренними SSE-потоками и не предназначены для прямого открытия в браузере.
• Для SSE требуется клиент с заголовком Accept: text/event-stream (EventSource в WebUI).
• GET /api/terminal/ws является внутренним WebSocket endpoint и для обычного HTTP-запроса возвращает 426 Upgrade Required.

Auth API:

• POST /api/login/request — запрос magic link через Telegram
• POST /api/login/password — вход по логину и паролю
• GET /api/login/magic — вход по magic link
• POST /api/auth/telegram — вход через Telegram widget
• POST /api/login/reset — запрос сброса пароля
• POST /api/reset/confirm — подтверждение сброса пароля
• GET /api/security/telegram_only_mode — текущее состояние режима Telegram-only
• POST /api/security/telegram_only_mode — переключение режима Telegram-only
• GET /api/sessions/list — список активных веб-сессий
• POST /api/sessions/revoke — отзыв одной сессии
• POST /api/sessions/revoke_all — отзыв всех остальных сессий
• POST /api/settings/password — смена пароля веб-панели

Node API:

• GET /api/heartbeat — health probe для агента/нод
• POST /api/heartbeat — heartbeat от ноды с HMAC-подписью
• GET /api/nodes/list — список нод
• POST /api/nodes/add — добавить ноду
• POST /api/nodes/delete — удалить ноду
• POST /api/nodes/rename — переименовать ноду
• GET /api/nodes/monitor/list — данные страницы мониторинга
• GET /api/nodes/monitor/detail?token=... — детали конкретной ноды
• GET /api/nodes/monitor/services?token=... — сервисы конкретной ноды
• POST /api/nodes/monitor/command — отправить команду на ноду
• POST /api/nodes/monitor/service_action — действие над сервисом ноды

System API:

• GET /api/logs — последние строки bot log
• GET /api/logs/system — системные логи
• POST /api/logs/clear — очистка логов
• POST /api/settings/save — сохранение настроек уведомлений
• POST /api/settings/system — сохранение системных порогов
• POST /api/settings/keyboard — сохранение конфигурации клавиатуры
• POST /api/settings/metadata — сохранение web metadata
• POST /api/settings/language — смена языка WebUI
• POST /api/users/action — управление пользователями
• GET /api/update/check — проверка обновлений
• POST /api/update/run — запуск обновления
• GET /api/notifications/list — список уведомлений
• POST /api/notifications/read — отметить уведомления прочитанными
• POST /api/notifications/clear — очистить уведомления
• POST /api/traffic/reset — сброс статистики трафика
• GET /api/services — список управляемых сервисов
• GET /api/services/available — список доступных сервисов
• GET /api/services/info/{name} — информация о сервисе
• POST /api/services/{action} — действие над сервисом (start|stop|restart)
• POST /api/services/manage — добавить или удалить сервис из мониторинга

Streaming / Internal API:

• GET /api/events — основной SSE поток dashboard
• GET /api/events/logs — SSE поток логов
• GET /api/events/node — SSE поток детальной карточки ноды
• GET /api/events/services — SSE поток менеджера сервисов
• GET /api/agent/ipv4 — список IPv4 адресов агента
• GET /api/terminal/creds — загрузка сохраненных SSH credentials
• POST /api/terminal/creds — сохранение SSH credentials
• GET /api/terminal/stats — статистика сервера для web terminal
• GET /api/terminal/ws — WebSocket endpoint терминала

Установка как приложение:

1. Откройте Dashboard в браузере
2. Нажмите "Установить" (Chrome) или "Добавить на главный экран" (Mobile)
3. Используйте как нативное приложение

Преимущества PWA:

• Работает офлайн (кэширование)
• Иконка на рабочем столе
• Полноэкранный режим
• Push-уведомления (в разработке)

• Whitelist — только авторизованные Telegram ID
• Role-Based Access Control (RBAC)
• Anti-spam middleware (1 запрос/сек на пользователя)

• Argon2 — рекомендованное OWASP хеширование паролей
• Server-side sessions — безопасные куки
• CSRF Protection — токены для всех POST запросов
• Brute-force Protection — блокировка после 5 попыток на 5 минут
• Rate Limiting — 100 API запросов/мин на IP

Автоматическое обнаружение:

• ❌ SQL Injection (UNION SELECT, OR 1=1)
• ❌ XSS (<script>, javascript:)
• ❌ Path Traversal (../, %2e%2e)
• ❌ Command Injection (;, |, `)
• ❌ LDAP Injection

• Fernet — симметричное шифрование конфигов (users.json, services.json)
• XOR + Base64 — легковесное шифрование для веб-клиента (SSE events)

Записываются:

• Login attempts (success/fail)
• Password resets
• User additions/deletions
• Configuration changes
• WAF triggers

Privacy:

• IP маскируются (203.0.113.XXX)
• Токены скрываются (abc123...)
• GDPR compliant

Файл: logs/audit/audit.log

/opt/tg-bot/
├── bot.py                    # Точка входа
├── watchdog.py              # Автоперезапуск
├── migrate.py               # Миграция данных
├── manage.py                # CLI управление
├── .env                     # Конфигурация
├── requirements.txt         # Python зависимости
├── docker-compose.yml       # Docker конфигурация
├── Dockerfile               # Образ контейнера
├── deploy.sh                # Установщик
├── core/                    # Ядро системы
│   ├── config.py            # Загрузка конфигурации
│   ├── auth.py              # Авторизация
│   ├── i18n.py              # Мультиязычность
│   ├── keyboards.py         # UI генератор
│   ├── messaging.py         # Уведомления
│   ├── middlewares.py       # Middleware бота
│   ├── models.py            # ORM модели (Tortoise)
│   ├── nodes_db.py          # База данных нод
│   ├── shared_state.py      # Мост Bot ↔ Web
│   ├── tasks.py             # Фоновые задачи
│   ├── utils.py             # Утилиты
│   ├── web/                 # Web-слой (aiohttp)
│   │   ├── app.py           # Маршруты и инициализация
│   │   ├── auth.py          # Web-авторизация (пароль/magic link/Telegram)
│   │   ├── middlewares.py   # WAF, CSRF, Rate Limiting
│   │   ├── api_nodes.py     # API нод на базе aiohttp
│   │   ├── api_system.py    # Системный API на базе aiohttp
│   │   ├── streaming.py     # SSE потоки
│   │   └── views.py         # Jinja2 HTML страницы
│   ├── static/              # CSS, JS
│   └── templates/           # HTML шаблоны
├── modules/                 # Функциональные модули (18 модулей)
│   ├── selftest.py          # Сводка о сервере
│   ├── traffic.py           # Мониторинг трафика
│   ├── services.py          # Менеджер сервисов
│   ├── nodes.py             # Управление нодами
│   ├── users.py             # Управление пользователями
│   ├── backups.py           # Менеджер бэкапов
│   ├── notifications.py     # Фоновые алерты
│   └── ...                  # +11 модулей
└── node/                    # Клиент для удаленных серверов
    └── node.py              # Агент ноды

📖 Подробная документация: ARCHITECTURE.md

• 📘 ARCHITECTURE.md — Полная архитектура проекта
• 🧩 custom_module.md — Создание модуля для бота
• 🌐 web_module.md — Создание веб-модуля (WebUI + Бот)
• 📝 CHANGELOG.md — История изменений

# Статус
docker compose -f /opt/tg-bot/docker-compose.yml ps

# Перезапуск
docker compose -f /opt/tg-bot/docker-compose.yml restart bot-secure

# Логи (real-time)
docker compose -f /opt/tg-bot/docker-compose.yml logs -f bot-secure

# Остановка
docker compose -f /opt/tg-bot/docker-compose.yml stop

# Запуск
docker compose -f /opt/tg-bot/docker-compose.yml up -d

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

# Перезапуск
sudo systemctl restart tg-bot

# Логи
sudo journalctl -u tg-bot -f

# Остановка
sudo systemctl stop tg-bot

# База данных
cp /opt/tg-bot/config/nodes.db /backup/nodes.db.$(date +%F)

# Конфигурации
tar -czf /backup/tg-bot-config-$(date +%F).tar.gz /opt/tg-bot/config/

# Логи
tar -czf /backup/tg-bot-logs-$(date +%F).tar.gz /opt/tg-bot/logs/

# Автоматическое (через бота)
# Telegram → 🔧 Утилиты → 🔄 Обновить VPS → Обновить бота

# Ручное
cd /opt/tg-bot
git pull
source venv/bin/activate
pip install -r requirements.txt --upgrade
sudo systemctl restart tg-bot

• GET / — Dashboard (требуется авторизация)
• POST /api/login — Вход в систему
• POST /api/logout — Выход

• GET /api/dashboard_data — Данные дашборда
• GET /api/events — SSE stream (уведомления)
• GET /api/events/services — SSE stream (сервисы)

• GET /api/nodes — Список всех нод
• POST /api/nodes/register — Регистрация ноды
• POST /api/nodes/{token}/metrics — Отправка метрик
• POST /api/nodes/{id}/delete — Удаление ноды

• GET /api/health — Health check
• GET /api/logs/{type} — Получение логов
• POST /api/system_config — Сохранение конфигурации
• POST /api/alerts_config — Настройки алертов

📖 Полная документация API: ARCHITECTURE.md#api

Мы приветствуем вклад в проект!

1. 🐛 Сообщить о баге — Issues
2. 💡 Предложить функцию — Discussions
3. 🔧 Отправить Pull Request
4. 📖 Улучшить документацию
5. ⭐ Поставить звезду — это мотивирует!

# Клонирование
git clone https://github.com/jatixs/tgbotvpscp.git
cd tgbotvpscp

# Создание виртуального окружения
python3 -m venv venv
source venv/bin/activate

# Установка зависимостей
pip install -r requirements.txt

# Настройка .env
cp .env.example .env
nano .env

# Запуск
python bot.py

Этот проект распространяется под лицензией GPL-3.0. См. файл LICENSE для деталей.

Jatix

• 📧 Почта: jatix.com@mail.ru
• 💬 Telegram: @jatix
• 🌐 GitHub: @jatixs

Если проект оказался полезным, поддержите его:

• ⭐ Поставь звезду на GitHub
• 🔄 Поделись с друзьями
• 💰 Донат

Версия: 1.22.5 (Build 76)
Лицензия: MIT License
Статус: Релиз

Сделано с ❤️ для сообщества DevOps