SaveVideoBot 🤖

Полнофункциональный Telegram-бот для скачивания видео и аудио с популярных платформ.

Разработано DenisNekrasov.dev

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

• 📺 Поддержка множества платформ: YouTube, TikTok, Instagram, Twitter, Facebook, Reddit, Vimeo, Dailymotion, Twitch, Bilibili, VKontakte
• 🎵 Форматы: Видео (MP4, WebM) и аудио (MP3, M4A)
• ⚡ Асинхронная обработка: Фоновые загрузки через Celery
• 🛡️ Защита от спама: Rate limiting с Redis
• 📊 Мониторинг: Prometheus метрики и админ-панель
• 🔧 Масштабируемость: Kubernetes-ready с HPA
• 🐳 Контейнеризация: Docker и docker-compose
• 🔄 CI/CD: GitHub Actions с автоматическим деплоем

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

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Telegram Bot  │    │   FastAPI App   │    │  Celery Worker  │
│   (aiogram)     │◄──►│   (Webhook)     │◄──►│   (yt-dlp)      │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│      Redis      │    │   PostgreSQL    │    │   File Storage  │
│   (Rate Limit)  │    │   (Metadata)    │    │   (Temp Files)  │
└─────────────────┘    └─────────────────┘    └─────────────────┘

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

• Backend: Python 3.11+, FastAPI, aiogram 3.x
• База данных: PostgreSQL, SQLAlchemy, Alembic
• Кэш: Redis
• Фоновые задачи: Celery
• Загрузка видео: yt-dlp
• Мониторинг: Prometheus, Flower
• Контейнеризация: Docker, Kubernetes
• CI/CD: GitHub Actions

📋 Требования

• Python 3.11+
• PostgreSQL 15+
• Redis 7+
• Docker & Docker Compose
• Kubernetes (для продакшена)

🚀 Быстрый старт

1. Клонирование репозитория

git clone https://github.com/RoXyGeNOFF/SaveVideoBot.git
cd SaveVideoBot

2. Установка CLI (рекомендуется)

# Установить зависимости CLI
make cli-install

# Или вручную
pip install -r requirements-cli.txt
chmod +x savevideobot.py svb

3. Настройка переменных окружения

# Инициализация конфигурации
./svb config-init

# Или вручную
cp env.example .env

Отредактируйте .env файл:

# Telegram Bot Configuration
BOT_TOKEN=your_telegram_bot_token_here
ADMIN_ID=123456789,987654321

# Database Configuration
POSTGRES_URL=postgresql://user:password@localhost:5432/botdb

# Redis Configuration
REDIS_URL=redis://localhost:6379/0

# Bot Mode (webhook or polling)
BOT_MODE=polling

4. Запуск

# Разработка (с CLI)
./svb dev

# Продакшен (с CLI)
./svb prod

# Или традиционно
docker-compose -f docker-compose.dev.yml up --build
docker-compose up --build

4. Локальная разработка

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

# Запуск PostgreSQL и Redis
docker-compose -f docker-compose.dev.yml up db redis -d

# Применение миграций
alembic upgrade head

# Запуск бота
python -m app.bot

# Запуск Celery worker
celery -A app.celery_app worker --loglevel=info

# Запуск FastAPI
python -m app.main

🐳 Docker

Сборка образа

# Продакшен
docker build -t savevideobot .

# Разработка
docker build -f Dockerfile.dev -t savevideobot:dev .

Docker Compose сервисы

• app: Основное приложение (FastAPI + Bot)
• celery_worker: Celery worker для фоновых задач
• celery_beat: Celery beat для периодических задач
• flower: Мониторинг Celery
• db: PostgreSQL база данных
• redis: Redis кэш
• nginx: Reverse proxy (опционально)

☸️ Kubernetes

Развертывание в Kubernetes

# Создание namespace
kubectl apply -f k8s/namespace.yaml

# Настройка секретов
kubectl create secret generic savevideobot-secrets \
  --from-literal=BOT_TOKEN=your_bot_token \
  --from-literal=ADMIN_ID=123456789 \
  --from-literal=POSTGRES_PASSWORD=your_password \
  --from-literal=WEBHOOK_SECRET=your_webhook_secret \
  --namespace=savevideobot

# Применение манифестов
kubectl apply -f k8s/configmap.yaml
kubectl apply -f k8s/redis-postgres.yaml
kubectl apply -f k8s/deployment.yaml
kubectl apply -f k8s/service.yaml
kubectl apply -f k8s/ingress.yaml
kubectl apply -f k8s/hpa.yaml
kubectl apply -f k8s/monitoring.yaml

Helm Chart

# Установка Helm chart
helm install savevideobot ./helm/savevideobot

# Обновление
helm upgrade savevideobot ./helm/savevideobot

# Удаление
helm uninstall savevideobot

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

Переменные окружения

Переменная	Описание	По умолчанию
BOT_TOKEN	Токен Telegram бота	-
ADMIN_ID	ID администратора	-
POSTGRES_URL	URL PostgreSQL	-
REDIS_URL	URL Redis	-
BOT_MODE	Режим бота (webhook/polling)	webhook
WEBHOOK_URL	URL для webhook	-
RATE_LIMIT_REQUESTS	Лимит запросов в минуту	10
MAX_FILE_SIZE	Максимальный размер файла (байты)	500MB
DOWNLOAD_TIMEOUT	Таймаут загрузки (секунды)	300

Поддерживаемые платформы

• YouTube (youtube.com, youtu.be)
• TikTok (tiktok.com)
• Instagram (instagram.com)
• Twitter/X (twitter.com, x.com)
• Facebook (facebook.com, fb.watch)
• Reddit (reddit.com)
• Vimeo (vimeo.com)
• Dailymotion (dailymotion.com)
• Twitch (twitch.tv)
• Bilibili (bilibili.com)
• VKontakte (vk.com)

📊 Мониторинг

Prometheus метрики

• savevideobot_download_requests_total - Общее количество запросов
• savevideobot_download_duration_seconds - Время загрузки
• savevideobot_file_size_bytes - Размер файлов
• savevideobot_active_downloads - Активные загрузки
• savevideobot_rate_limit_hits_total - Срабатывания rate limit

🚀 CLI Launcher

SaveVideoBot включает мощный CLI для управления всеми аспектами системы:

# Основные команды
./svb dev              # Запуск разработки
./svb prod             # Запуск продакшена
./svb status           # Статус системы
./svb logs             # Просмотр логов

# Сервисы
./svb bot              # Запуск бота
./svb api              # Запуск API
./svb worker           # Запуск Celery worker

# База данных
./svb migrate          # Миграции БД
./svb db-reset         # Сброс БД

# Kubernetes
./svb k8s-deploy       # Деплой в K8s
./svb k8s-status       # Статус K8s

# Полная справка
./svb help

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

Endpoints

• /health - Проверка здоровья
• /metrics - Prometheus метрики
• /api/stats - Статистика бота
• /api/requests - Список запросов
• /flower - Мониторинг Celery

Админ-панель

Используйте команду /admin в Telegram для доступа к админ-панели:

• 📢 Рассылка сообщений - Отправка сообщений всем пользователям
• 📊 Статистика системы
• 👥 Топ пользователи
• 📺 Топ платформы
• 📋 Последние запросы
• 🔧 Системная информация
• 👥 Управление пользователями

Административные команды:

• /admin - Открыть админ-панель
• /broadcast - Рассылка сообщений
• /block_user <user_id> - Заблокировать пользователя
• /unblock_user <user_id> - Разблокировать пользователя
• /user_info <user_id> - Информация о пользователе
• /reset_user <user_id> - Сбросить лимиты пользователя

🔄 CI/CD

GitHub Actions

Проект включает полный CI/CD pipeline:

1. Тестирование: pytest, flake8, black, isort
2. Сборка: Docker образ
3. Безопасность: Trivy сканирование
4. Деплой: Автоматический деплой в staging/production
5. Уведомления: Slack уведомления

Workflow файлы

• .github/workflows/ci.yml - Основной CI/CD pipeline
• .github/workflows/cd.yml - Continuous Deployment

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

# Запуск всех тестов
pytest

# С покрытием кода
pytest --cov=app --cov-report=html

# Конкретный тест
pytest tests/test_video_downloader.py::TestVideoDownloader::test_detect_platform_youtube

# Линтинг
flake8 app/
black --check app/
isort --check-only app/

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

Webhook endpoint

POST /webhook
Content-Type: application/json

{
  "update_id": 123456789,
  "message": {
    "message_id": 1,
    "from": {
      "id": 123456789,
      "username": "user"
    },
    "text": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  }
}

REST API

# Статистика
GET /api/stats

# Запросы пользователя
GET /api/users/{user_id}/requests

# Сброс лимитов
POST /api/users/{user_id}/reset-limits

# Поддерживаемые платформы
GET /api/platforms

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

• Rate limiting для защиты от спама
• Валидация URL
• Ограничение размера файлов
• Автоматическая очистка временных файлов
• HTTPS для webhook
• Secrets management в Kubernetes
• Административные права с проверкой ID

📢 Рассылка сообщений

Функции рассылки:

• Текстовая рассылка - Отправка текстовых сообщений всем пользователям
• Фото с подписью - Отправка изображений с текстовой подписью
• Прогресс в реальном времени - Отображение статистики отправки
• Анти-флуд защита - Задержка между отправками
• Обработка ошибок - Пропуск заблокированных пользователей

Как использовать:

1. Откройте админ-панель (/admin или кнопка "🛠 Административные инструменты")
2. Выберите "📢 Отправить сообщение всем пользователям"
3. Введите текст или отправьте фото с подписью
4. Дождитесь завершения рассылки

Управление пользователями:

• Блокировка - /block_user <user_id>
• Разблокировка - /unblock_user <user_id>
• Информация - /user_info <user_id>
• Статистика - Просмотр количества активных/заблокированных пользователей

📈 Масштабирование

Горизонтальное масштабирование

# Увеличение количества реплик
kubectl scale deployment savevideobot-app --replicas=5

# Автоматическое масштабирование (HPA)
kubectl apply -f k8s/hpa.yaml

Мониторинг производительности

# Проверка подов
kubectl get pods -n savevideobot

# Логи приложения
kubectl logs -f deployment/savevideobot-app -n savevideobot

# Метрики
curl http://localhost:9090/metrics

🛠️ Разработка

Добавление новой платформы

1. Обновите SUPPORTED_PLATFORMS в app/config.py:

SUPPORTED_PLATFORMS = {
    "newplatform.com": "NewPlatform",
    # ... остальные платформы
}

2. Протестируйте с yt-dlp:

yt-dlp --list-formats "https://newplatform.com/video"

3. Добавьте тесты в tests/test_video_downloader.py

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

savevideobot/
├── app/                    # Основное приложение
│   ├── handlers/          # Обработчики команд
│   ├── services/          # Бизнес-логика
│   ├── utils/             # Утилиты
│   ├── bot.py             # Telegram бот
│   ├── main.py            # FastAPI приложение
│   └── celery_app.py      # Celery конфигурация
├── k8s/                   # Kubernetes манифесты
├── tests/                 # Тесты
├── alembic/               # Миграции БД
├── docker-compose.yml     # Docker Compose
├── Dockerfile             # Docker образ
└── README.md              # Документация

🐛 Отладка

Логи

# Логи приложения
docker-compose logs app

# Логи Celery worker
docker-compose logs celery_worker

# Логи базы данных
docker-compose logs db

Частые проблемы

1. Бот не отвечает: Проверьте BOT_TOKEN и режим работы
2. Ошибки загрузки: Проверьте доступность yt-dlp и интернет
3. Проблемы с БД: Проверьте подключение к PostgreSQL
4. Rate limiting: Увеличьте лимиты или сбросьте кэш Redis

📄 Лицензия

MIT License - см. файл LICENSE

🤝 Вклад в проект

1. Fork репозитория
2. Создайте feature branch (git checkout -b feature/amazing-feature)
3. Commit изменения (git commit -m 'Add amazing feature')
4. Push в branch (git push origin feature/amazing-feature)
5. Откройте Pull Request

📞 Поддержка

• 📧 Email: [email protected]
• 💬 Telegram: @RoXyGeNOFF
• 🐛 Issues: GitHub Issues

🙏 Благодарности

• yt-dlp - За загрузку видео
• aiogram - За Telegram Bot API
• FastAPI - За веб-фреймворк
• Celery - За фоновые задачи

---

⭐ Если проект вам понравился, поставьте звезду!