Changelog

[2.6.0] - 2025-11-07

🎯 Основные изменения

🔗 Единый веб-сервер для webhook-режима

🌐 Унифицированный FastAPI-сервер объединяет Telegram webhook, платёжные колбэки, административное API и статические файлы мини-приложения на одном порту 8080
🎚 Гибкие режимы работы:
- webhook — чистая работа через вебхуки (рекомендуется для продакшн)
- polling — классический long polling для локальной разработки
- both — гибридный режим для миграции или повышенной отказоустойчивости
🚀 Полностью готовая инфраструктура для работы через HTTPS webhook — теперь не требуется настройка отдельных контейнеров или портов

⚡️ Производительность webhook

Асинхронная обработка Telegram-апдейтов

📦 Очередь с настраиваемым размером (WEBHOOK_MAX_QUEUE_SIZE)
👷 Пул воркеров для параллельной обработки (WEBHOOK_WORKERS)
⏱️ Контролируемые таймауты постановки в очередь и завершения воркеров
🎯 Валидация входящих данных и защита от переполнения очереди
📊 Детальная телеметрия производительности через /health/telegram-webhook

Оптимизированная обработка перегрузок

🛡 Graceful degradation при высокой нагрузке
🔄 Автоматическое управление backpressure
📈 Мониторинг размера очереди в реальном времени

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

Защита Telegram webhook

🔐 Обязательная проверка X-Telegram-Bot-Api-Secret-Token
🎲 Генерация секретного токена: openssl rand -hex 32
✅ Автоматическая регистрация webhook с защитным токеном при старте
🚫 Отклонение запросов без валидного токена

Защита платёжных колбэков

✅ Автоматическое отклонение недоверенных платёжных уведомлений
🔒 Изоляция обработки каждого платёжного провайдера

🏥 Мониторинг и диагностика

Комплексные health-эндпоинты

/health/unified — агрегированный статус всей системы (режим работы, очереди, интеграции)
/health/telegram-webhook — детальная информация об очереди Telegram (размер, воркеры, производительность)
/health/payment-webhooks — статус активных платёжных интеграций
/health — упрощённый эндпоинт при отключенном административном API

Расширенная телеметрия

📊 Размер очереди webhook в реальном времени
👷 Количество активных воркеров
⚙️ Статус каждого компонента системы
🔗 Информация о подключенных платёжных провайдерах

🔧 Конфигурация webhook

Новые переменные окружения

# Режим работы
BOT_RUN_MODE=webhook  # webhook | polling | both

# Настройки Telegram webhook
WEBHOOK_URL=https://bot.example.com
WEBHOOK_PATH=/telegram/webhook
WEBHOOK_SECRET_TOKEN=your-secret-token  # openssl rand -hex 32
WEBHOOK_DROP_PENDING_UPDATES=true

# Производительность очереди
WEBHOOK_MAX_QUEUE_SIZE=1024
WEBHOOK_WORKERS=4
WEBHOOK_ENQUEUE_TIMEOUT=0.1
WEBHOOK_WORKER_SHUTDOWN_TIMEOUT=30.0

# Единый веб-сервер
WEB_API_ENABLED=true
WEB_API_HOST=0.0.0.0
WEB_API_PORT=8080
WEB_API_ALLOWED_ORIGINS=https://bot.example.com

Документация API (опционально)

📖 WEB_API_DOCS_ENABLED=true для включения Swagger UI
🔗 Доступна по адресам /docs, /redoc и /doc
🔐 Рекомендуется отключать в продакшене

🌐 Интеграция с reverse proxy

Упрощённая архитектура

🎯 Все HTTP-эндпоинты на одном порту (8080)
🔗 Единая точка входа для всех webhook-путей:
- /telegram/webhook — Telegram апдейты
- /yookassa-webhook — платежи YooKassa
- /cryptobot-webhook — платежи CryptoBot
- /miniapp/static — статические файлы мини-приложения
- /app-config.json — конфигурация приложения

Готовые конфигурации прокси

📝 Полные примеры для Caddy и Nginx в документации
🔒 Настройка TLS-терминации
🌍 CORS для мини-приложения
📊 Проксирование health-эндпоинтов для мониторинга

⚠️ Критические изменения (Breaking Changes)

🔴 Архитектура webhook изменена

Все компоненты используют один порт 8080 вместо нескольких
Reverse proxy должен маршрутизировать весь трафик через единую точку входа
Старые отдельные контейнеры для webhook больше не нужны

🔴 Обязательные изменения конфигурации

Необходимо установить BOT_RUN_MODE=webhook для работы через вебхуки
Обязательно задать WEBHOOK_SECRET_TOKEN (команда: openssl rand -hex 32)
Настроить WEBHOOK_URL с публичным HTTPS-доменом
Добавить новые переменные для настройки очереди webhook

🔴 Платёжные провайдеры

Обязательные подписи для колбэков при настроенных секретах
Устаревшие интеграции должны передавать соответствующие заголовки

🔴 Docker Compose

Необходимо удалить публикацию дополнительных портов
Оставить только 8080:8080 для сервиса remnawave_bot
Прокси должен быть в той же Docker-сети (bot_network)

📋 Миграция на webhook-режим

Шаг 1: Обновление .env

# Установите режим webhook
BOT_RUN_MODE=webhook

# Настройте webhook
WEBHOOK_URL=https://bot.example.com
WEBHOOK_PATH=/telegram/webhook
WEBHOOK_SECRET_TOKEN=$(openssl rand -hex 32)
WEBHOOK_DROP_PENDING_UPDATES=true

# Настройте производительность
WEBHOOK_MAX_QUEUE_SIZE=1024
WEBHOOK_WORKERS=4
WEBHOOK_ENQUEUE_TIMEOUT=0.1
WEBHOOK_WORKER_SHUTDOWN_TIMEOUT=30.0

Шаг 2: Обновление docker-compose.yml

services:
  remnawave_bot:
    ports:
      - "8080:8080"  # Только один порт!
    networks:
      - bot_network

Шаг 3: Настройка reverse proxy

# Создайте или подключитесь к сети
docker network create bot_network
docker network connect bot_network <proxy_container_name>

Используйте готовые конфигурации Caddy или Nginx из документации:

Проксирование всех путей на remnawave_bot:8080
Настройка TLS с Let's Encrypt
CORS для /app-config.json

Шаг 4: Развёртывание

cd /path/to/remnawave-bedolaga-telegram-bot
git pull origin main

# Перезапустите контейнеры
make reload

# Или с логами для отслеживания процесса
make reload-follow

Шаг 5: Проверка webhook

# Проверьте общий статус
curl -s https://bot.example.com/health/unified | jq

# Проверьте очередь Telegram
curl -s https://bot.example.com/health/telegram-webhook | jq

# Проверьте платёжные интеграции
curl -s https://bot.example.com/health/payment-webhooks | jq

Шаг 6: Очистка

# Удалите старые контейнеры для отдельных webhook (если были)
docker compose down payments-webhook

🐛 Исправления

Стабильность webhook

✅ Нормализация путей webhook для устранения несоответствий URL из-за пробелов или отсутствующих слэшей
✅ Быстрый отказ при ошибках запуска uvicorn вместо молчаливых зависаний
✅ Корректная обработка переполнения очереди webhook
✅ Улучшенное логирование ошибок регистрации webhook

🧪 Тестирование

Комплексное покрытие webhook

✅ Новый тестовый набор tests/webserver:
- Роутинг Telegram webhook и валидация секретного токена
- Сценарии перегрузки очереди
- Валидация платёжных webhook с проверкой подписей
- Унифицированная отчётность о здоровье системы
- Маршруты административной документации
🗑 Удалены устаревшие внешние тесты webhook
✅ Все тесты проходят успешно

Запуск тестов:

make test

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

Новая документация по webhook

📖 Полное руководство по настройке webhook-режима
🔧 Детальные инструкции по миграции с polling на webhook
🌐 Готовые конфигурации для Caddy и Nginx
💡 Примеры настройки TLS и CORS
🐛 Раздел troubleshooting для диагностики проблем webhook
📊 Гайды по мониторингу и использованию health-эндпоинтов

💪 Производительность

Оптимизация webhook

⚡️ Асинхронная обработка апдейтов без блокировок
🎯 Настраиваемый пул воркеров для параллелизма
📦 Эффективное управление очередью запросов
🔄 Graceful shutdown с корректной обработкой оставшихся задач

🔄 Обновление

⚠️ Перед обновлением:

Создайте резервную копию БД (обязательно!)
Подготовьте конфигурацию reverse proxy (Caddy/Nginx)
Сгенерируйте WEBHOOK_SECRET_TOKEN: openssl rand -hex 32

Через Git:

cd /path/to/remnawave-bedolaga-telegram-bot
git pull origin main
make reload

С логами для мониторинга:

make reload-follow

📇 Доступные команды

make help           # Показать все команды
make up             # Поднять контейнеры (detached)
make up-follow      # Поднять контейнеры с логами
make down           # Остановить и удалить контейнеры
make reload         # Перезапустить контейнеры (detached)
make reload-follow  # Перезапустить контейнеры с логами
make test           # Запустить тесты

🔗 Ссылки

[Release](https://github.com/Fr1ngg/remnawave-bedolaga-telegram-bot/releases/tag/v2.6.0) | [Full Changelog](v2.5.8...v2.6.0)

⚠️ Важно: Это обновление полностью меняет архитектуру работы через webhook. Для продакшн-серверов обязательно:

🔒 Настройте HTTPS reverse proxy (Caddy/Nginx)
🎲 Сгенерируйте WEBHOOK_SECRET_TOKEN
🎚 Установите BOT_RUN_MODE=webhook
📖 Изучите раздел миграции перед обновлением

🚀 Рекомендуется для продакшн: Webhook-режим обеспечивает мгновенную доставку сообщений, меньшую нагрузку на Telegram API и лучшую масштабируемость по сравнению с polling.

Проверка актива — ставьте реакцию 🚀

BEDOLAGA-DEV/remnawave-bedolaga-telegram-bot v2.6.0 on GitHub