📚 Обновлена документация проекта

- Добавлено подробное описание бизнес-логики и технической составляющей
- Обновлен алгоритм работы с реальной реализацией
- Добавлен статус проекта (полностью функционален)
- Указана папка загрузок /home/qbittorrent/Downloads
- Расширены возможности системы
- Добавлена информация о мониторинге загрузки
This commit is contained in:
vrubelroman 2025-10-06 01:36:20 +03:00
parent e38be704ff
commit badfb124db

430
README.md
View file

@ -1,115 +1,329 @@
# Movie Search API # 📚 searchTorrentDownl - Полная документация
Проект для поиска фильмов с использованием The Movie Database (TMDB) API. ## 🎯 Описание проекта
## Возможности **searchTorrentDownl** - это полнофункциональная система для поиска и загрузки фильмов через торренты. Приложение интегрирует поиск фильмов через TMDB API с поиском торрентов на популярных трекерах и автоматическим добавлением в qBittorrent клиент.
- 🔍 Поиск фильмов по названию через TMDB API ### 🎬 Бизнес-логика:
- 🎬 Отображение информации о фильмах (постер, описание, рейтинг) 1. **Поиск фильмов** - пользователь вводит название фильма
- 🔗 Поиск торрентов для выбранного фильма 2. **Выбор фильма** - из результатов поиска выбирается нужный фильм
- 📊 Отображение детальной информации о торрентах (размер, разрешение, качество) 3. **Поиск торрентов** - система ищет доступные торренты на всех подключенных трекерах
- 🚀 Интеграция с torAPI для добавления торрентов в клиент 4. **Фильтрация и ранжирование** - торренты сортируются по качеству, размеру и количеству сидов
- 🌐 Веб-интерфейс для удобного поиска 5. **Автоматическое добавление** - выбранный торрент автоматически добавляется в qBittorrent
- 📱 Адаптивный дизайн 6. **Загрузка** - файлы загружаются в настроенную папку
- 🐳 Запуск в Docker контейнере
- 🔌 REST API для интеграции
## Запуск ### 🔧 Техническая составляющая:
- **Frontend**: HTML/CSS/JavaScript с адаптивным дизайном
- **Backend**: FastAPI с асинхронной обработкой запросов
- **Поиск фильмов**: TMDB API для получения метаданных
- **Поиск торрентов**: TorAPI для работы с трекерами (RuTracker, Kinozal, RuTor, NoNameClub)
- **Клиент**: qBittorrent-nox на хосте для загрузки
- **Контейнеризация**: Docker для изоляции сервисов
- **Сеть**: Docker networks для связи между компонентами
### С помощью Docker Compose ## 🏗️ Архитектура системы
### Компоненты системы:
1. **FastAPI приложение** (Docker контейнер) - основной веб-сервис
2. **TorAPI-Search** (Docker контейнер) - поиск торрентов по названию
3. **TorAPI-qBittorrent** (Docker контейнер) - получение magnet ссылок по ID
4. **qBittorrent-nox** (хостовая система) - клиент для загрузки торрентов
## 📋 Технические требования
### Системные требования:
- **ОС**: Linux (Ubuntu/Debian)
- **Docker**: 20.10+
- **Docker Compose**: 2.0+
- **Python**: 3.12+
- **RAM**: минимум 2GB
- **Диск**: минимум 10GB свободного места
### Зависимости:
- FastAPI 0.115.0
- Uvicorn 0.30.6
- httpx 0.27.2
- BeautifulSoup4 4.12.3
- qBittorrent-nox 4.6.7+
## 🚀 Установка и настройка
### 1. Установка qBittorrent на хост
```bash ```bash
docker compose up --build -d # Установка qBittorrent-nox
sudo apt update
sudo apt install qbittorrent-nox
# Создание пользователя для qBittorrent
sudo useradd -r -s /bin/false qbittorrent
sudo mkdir -p /home/qbittorrent/Downloads
sudo chown -R qbittorrent:qbittorrent /home/qbittorrent
# Создание systemd сервиса
sudo tee /etc/systemd/system/qbittorrent.service > /dev/null <<EOF
[Unit]
Description=qBittorrent Command Line Client
After=network.target
[Service]
Type=forking
User=qbittorrent
Group=qbittorrent
UMask=007
ExecStart=/usr/bin/qbittorrent-nox -d --webui-port=8080
Restart=on-failure
RestartSec=5
TimeoutStopSec=300
[Install]
WantedBy=multi-user.target
EOF
# Включение и запуск сервиса
sudo systemctl enable qbittorrent
sudo systemctl start qbittorrent
``` ```
### Доступ к приложению ### 2. Настройка qBittorrent
- **Веб-интерфейс**: http://localhost:8089 1. Откройте браузер: http://localhost:8080
- **API**: http://localhost:8089/api/search/{название_фильма} 2. Войдите с логином `admin` и паролем `vrubel07`
3. Настройте параметры:
- **Connection**: порт 6881, включить UPnP/NAT-PMP
- **BitTorrent**: включить DHT, PeX, Local Peer Discovery
- **Downloads**: папка `/home/qbittorrent/Downloads` (настроена автоматически)
## API Endpoints **Важно**: Все загруженные файлы сохраняются в `/home/qbittorrent/Downloads/`
### GET / ### 3. Запуск Docker контейнеров
Главная страница с формой поиска
### POST /search ```bash
Поиск фильмов через веб-форму # Клонирование репозитория
git clone <repository-url>
cd searchTorrentDownl
**Параметры:** # Создание сети для TorAPI
- `movie_title` (form) - название фильма для поиска docker network create torrentvideo_default
### GET /api/search/{movie_title} # Запуск всех сервисов
API endpoint для поиска фильмов docker compose up -d --build
**Параметры:**
- `movie_title` (path) - название фильма для поиска
### GET /api/torrents/{movie_title}
API endpoint для поиска торрентов фильма
**Параметры:**
- `movie_title` (path) - название фильма для поиска
- `year` (query, optional) - год выпуска фильма
### GET /torrents/{movie_title}
Страница с результатами поиска торрентов
**Параметры:**
- `movie_title` (path) - название фильма для поиска
- `year` (query, optional) - год выпуска фильма
**Пример ответа API торрентов:**
```json
{
"torrents": [
{
"title": "Inception (2010) - 1080p - BluRay",
"size_bytes": 2684354560,
"size_readable": "2.5 GB",
"resolution": "1080p",
"quality": "BluRay",
"seeds": 150,
"peers": 25,
"magnet": "magnet:?xt=urn:btih:example0",
"download_url": "http://example.com/torrent0.torrent"
}
],
"movie_title": "Inception",
"year": "2010"
}
``` ```
## Конфигурация ## ⚙️ Конфигурация
Приложение использует следующие переменные окружения: ### Переменные окружения
- `TMDB_API_KEY` - API ключ для TMDB (по умолчанию: 6d58225585fb77af5945a964de41849f) #### Основное приложение (movie-search):
- `HOST` - хост для запуска (по умолчанию: 0.0.0.0) ```bash
- `PORT` - порт для запуска (по умолчанию: 8000) TMDB_API_KEY=6d58225585fb77af5945a964de41849f
TORAPI_URL=http://localhost:8088
TORRENT_SEARCH_URL=http://localhost:8443
TORRENT_ADD_URL=http://localhost:8444
QBITTORRENT_HOST=localhost
QBITTORRENT_PORT=8080
QBITTORRENT_USERNAME=admin
QBITTORRENT_PASSWORD=vrubel07
```
## Технологии #### TorAPI-qBittorrent:
```bash
PROXY_ADDRESS=172.17.0.1
PROXY_PORT=8080
USERNAME=admin
PASSWORD=vrubel07
```
- **FastAPI** - веб-фреймворк ### Docker Compose конфигурация
- **Jinja2** - шаблонизатор
- **httpx** - HTTP клиент
- **Docker** - контейнеризация
- **TMDB API** - источник данных о фильмах
## Использование ```yaml
version: '3.8'
services:
movie-search:
build: .
ports:
- "8089:8000"
environment:
- TMDB_API_KEY=6d58225585fb77af5945a964de41849f
- TORAPI_URL=http://localhost:8088
- TORRENT_SEARCH_URL=http://localhost:8443
- TORRENT_ADD_URL=http://localhost:8444
- QBITTORRENT_HOST=localhost
- QBITTORRENT_PORT=8080
- QBITTORRENT_USERNAME=admin
- QBITTORRENT_PASSWORD=vrubel07
networks:
- torrentvideo_default
### Поиск фильмов и торрентов TorAPI-Search:
image: lifailon/torapi:latest
ports:
- "8443:8443"
networks:
- torrentvideo_default
1. **Поиск фильма**: Введите название фильма на главной странице TorAPI-qBittorrent:
2. **Выбор фильма**: Нажмите кнопку "🔍 Найти торренты" на понравившемся фильме image: lifailon/torapi:latest
3. **Просмотр торрентов**: Изучите доступные торренты с информацией о размере, разрешении и качестве ports:
4. **Скачивание**: Используйте кнопки для скачивания .torrent файла или magnet-ссылки - "8444:8443"
5. **Добавление в клиент**: Нажмите "Добавить в клиент" для автоматического добавления в qBittorrent environment:
- PROXY_ADDRESS=172.17.0.1
- PROXY_PORT=8080
- USERNAME=admin
- PASSWORD=vrubel07
networks:
- torrentvideo_default
### Интеграция с torAPI networks:
torrentvideo_default:
external: true
```
Приложение интегрировано с вашим torAPI сервисом (порт 8088) для автоматического добавления торрентов в qBittorrent клиент. ## 🔧 API Endpoints
## Структура проекта ### Основное приложение (порт 8089)
#### Веб-интерфейс:
- `GET /` - главная страница поиска
- `POST /search` - поиск фильмов
- `GET /torrents/{movie_title}` - страница с торрентами
#### API:
- `GET /api/search/{movie_title}` - поиск фильмов через TMDB
- `GET /api/torrents/{movie_title}` - поиск торрентов
- `GET /api/torrent/id/{torrent_id}` - получение информации о торренте по ID
- `POST /api/add-torrent` - добавление торрента в qBittorrent
### TorAPI-Search (порт 8443)
- `GET /api/search/title/{provider}?q={query}` - поиск торрентов по названию
- `GET /api/provider/list` - список доступных провайдеров
### TorAPI-qBittorrent (порт 8444)
- `GET /api/search/id/{provider}?id={torrent_id}` - получение magnet ссылки по ID
## 🎬 Поддерживаемые трекеры
- **RuTracker** - rutracker.org, rutracker.net, rutracker.nl
- **Kinozal** - kinozal.tv, kinozal.me, kinozal.guru
- **RuTor** - rutor.info, rutor.is
- **NoNameClub** - nnmclub.to
## 🔄 Алгоритм работы
### 1. Поиск фильма:
1. Пользователь вводит название фильма в веб-форму
2. FastAPI приложение обращается к TMDB API с запросом
3. Получает список фильмов с метаданными (постер, описание, рейтинг, год)
4. Отображает результаты в удобном интерфейсе
### 2. Поиск торрентов:
1. Пользователь выбирает фильм и нажимает "Найти торренты"
2. Приложение обращается к TorAPI-Search (порт 8443)
3. TorAPI ищет торренты на всех подключенных трекерах:
- RuTracker (rutracker.org, rutracker.net, rutracker.nl)
- Kinozal (kinozal.tv, kinozal.me, kinozal.guru)
- RuTor (rutor.info, rutor.is)
- NoNameClub (nnmclub.to)
4. Результаты фильтруются и ранжируются по релевантности, качеству и количеству сидов
### 3. Добавление торрента:
1. Пользователь нажимает "Добавить в клиент" на выбранном торренте
2. Приложение получает ID торрента и обращается к TorAPI-qBittorrent (порт 8444)
3. TorAPI-qBittorrent получает magnet ссылку по ID торрента
4. Приложение генерирует "чистую" magnet ссылку с публичными трекерами
5. Через qBittorrent Web API торрент добавляется в клиент
6. qBittorrent начинает загрузку в папку `/home/qbittorrent/Downloads`
### 4. Мониторинг загрузки:
1. Пользователь может отслеживать прогресс через qBittorrent веб-интерфейс
2. Файлы автоматически сохраняются в настроенную папку
3. После завершения загрузки файлы готовы к просмотру
## 🛠️ Устранение неполадок
### Проблема: qBittorrent не может добавить торренты
**Решение:**
1. Проверьте настройки qBittorrent (DHT, PeX, LPD включены)
2. Убедитесь, что порт 6881 открыт
3. Проверьте подключение к интернету
### Проблема: TorAPI не может подключиться к трекерам
**Решение:**
1. Проверьте, что трекеры доступны
2. Убедитесь, что нет блокировки на уровне роутера/провайдера
3. Проверьте логи контейнеров: `docker logs TorAPI-Search`
### Проблема: Приложение не может подключиться к qBittorrent
**Решение:**
1. Проверьте, что qBittorrent запущен: `sudo systemctl status qbittorrent`
2. Проверьте доступность: `curl http://localhost:8080/api/v2/app/version`
3. Проверьте учетные данные в переменных окружения
## 📊 Мониторинг
### Проверка статуса сервисов:
```bash
# qBittorrent
sudo systemctl status qbittorrent
# Docker контейнеры
docker ps
# Логи приложения
docker logs movie-search --tail 50
# Логи TorAPI
docker logs TorAPI-Search --tail 50
docker logs TorAPI-qBittorrent --tail 50
```
### Проверка торрентов в qBittorrent:
```bash
curl -s -X POST "http://localhost:8080/api/v2/auth/login" -d "username=admin&password=vrubel07" -c cookies.txt
curl -s -b cookies.txt "http://localhost:8080/api/v2/torrents/info" | jq '.[] | {name: .name, state: .state, progress: .progress}'
```
## 🔒 Безопасность
### Рекомендации:
1. Измените пароли по умолчанию
2. Настройте файрвол для ограничения доступа
3. Используйте HTTPS в продакшене
4. Регулярно обновляйте зависимости
### Настройка файрвола:
```bash
# Разрешить доступ к веб-интерфейсам
sudo ufw allow 8080/tcp # qBittorrent
sudo ufw allow 8089/tcp # Приложение
sudo ufw allow 6881/tcp # BitTorrent
sudo ufw allow 6881/udp # BitTorrent
```
## 📈 Производительность
### Оптимизация:
1. Настройте лимиты загрузки в qBittorrent
2. Используйте SSD для папки загрузок
3. Настройте кэширование в браузере
4. Мониторьте использование ресурсов
### Рекомендуемые настройки qBittorrent:
- Максимальная скорость загрузки: 80% от пропускной способности
- Максимальная скорость отдачи: 20% от пропускной способности
- Максимальное количество активных торрентов: 10-20
- Максимальное количество подключений: 200-500
## 🆘 Поддержка
При возникновении проблем:
1. Проверьте логи всех сервисов
2. Убедитесь, что все порты доступны
3. Проверьте настройки сети и файрвола
4. Создайте issue в репозитории проекта
## 📁 Структура проекта
``` ```
searchTorrentDownl/ searchTorrentDownl/
@ -124,3 +338,49 @@ searchTorrentDownl/
│ └── error.html # Страница ошибок │ └── error.html # Страница ошибок
└── README.md # Документация └── README.md # Документация
``` ```
## 🎯 Возможности
- 🔍 **Поиск фильмов** по названию через TMDB API с полными метаданными
- 🎬 **Информация о фильмах** - постер, описание, рейтинг, год выпуска, актеры
- 🔗 **Поиск торрентов** на 4 популярных трекерах одновременно
- 📊 **Детальная информация** о торрентах - размер, разрешение, качество, количество сидов
- 🚀 **Автоматическое добавление** торрентов в qBittorrent одним кликом
- 🌐 **Веб-интерфейс** с удобным поиском и навигацией
- 📱 **Адаптивный дизайн** для работы на любых устройствах
- 🐳 **Контейнеризация** для простого развертывания
- 🔌 **REST API** для интеграции с другими системами
- ⚡ **Асинхронная обработка** для высокой производительности
- 🛡️ **Безопасность** - генерация чистых magnet ссылок с публичными трекерами
## ✅ Статус проекта
**🟢 ПРОЕКТ ПОЛНОСТЬЮ ФУНКЦИОНАЛЕН**
- ✅ Поиск фильмов работает
- ✅ Поиск торрентов работает
- ✅ Добавление торрентов в qBittorrent работает
- ✅ Загрузка файлов работает
- ✅ Веб-интерфейс работает
- ✅ API работает
- ✅ Все сервисы интегрированы
## 🚀 Быстрый старт
### Запуск с помощью Docker Compose
```bash
docker compose up --build -d
```
### Доступ к приложению
- **Веб-интерфейс**: http://localhost:8089
- **qBittorrent**: http://localhost:8080 (admin/vrubel07)
- **API**: http://localhost:8089/api/search/{название_фильма}
---
**Версия документации**: 1.0
**Дата обновления**: $(date)
**Автор**: AI Assistant