# 📚 searchTorrentDownl - Полная документация

## 🎯 Описание проекта

**searchTorrentDownl** - это полнофункциональная система для поиска и загрузки фильмов через торренты. Приложение интегрирует поиск фильмов через TMDB API с поиском торрентов на популярных трекерах и автоматическим добавлением в qBittorrent клиент.

### 🎬 Бизнес-логика:
1. **Поиск фильмов** - пользователь вводит название фильма
2. **Выбор фильма** - из результатов поиска выбирается нужный фильм
3. **Поиск торрентов** - система ищет доступные торренты на всех подключенных трекерах
4. **Фильтрация и ранжирование** - торренты сортируются по качеству, размеру и количеству сидов
5. **Автоматическое добавление** - выбранный торрент автоматически добавляется в qBittorrent
6. **Загрузка** - файлы загружаются в настроенную папку

### 🔧 Техническая составляющая:
- **Frontend**: HTML/CSS/JavaScript с адаптивным дизайном
- **Backend**: FastAPI с асинхронной обработкой запросов
- **Поиск фильмов**: TMDB API для получения метаданных
- **Поиск торрентов**: TorAPI для работы с трекерами (RuTracker, Kinozal, RuTor, NoNameClub)
- **Клиент**: qBittorrent-nox на хосте для загрузки
- **Контейнеризация**: Docker для изоляции сервисов
- **Сеть**: Docker networks для связи между компонентами

## 🏗️ Архитектура системы

### Компоненты системы:

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
# Установка 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

1. Откройте браузер: http://localhost:8080
2. Войдите с логином `admin` и паролем `vrubel07`
3. Настройте параметры:
   - **Connection**: порт 6881, включить UPnP/NAT-PMP
   - **BitTorrent**: включить DHT, PeX, Local Peer Discovery
   - **Downloads**: папка `/home/qbittorrent/Downloads` (настроена автоматически)

**Важно**: Все загруженные файлы сохраняются в `/home/qbittorrent/Downloads/`

### 3. Запуск Docker контейнеров

```bash
# Клонирование репозитория
git clone <repository-url>
cd searchTorrentDownl

# Создание сети для TorAPI
docker network create torrentvideo_default

# Запуск всех сервисов
docker compose up -d --build
```

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

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

#### Основное приложение (movie-search):
```bash
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
```

### Docker Compose конфигурация

```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

  TorAPI-qBittorrent:
    image: lifailon/torapi:latest
    ports:
      - "8444:8443"
    environment:
      - PROXY_ADDRESS=172.17.0.1
      - PROXY_PORT=8080
      - USERNAME=admin
      - PASSWORD=vrubel07
    networks:
      - torrentvideo_default

networks:
  torrentvideo_default:
    external: true
```

## 🔧 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/
├── app.py                 # Основное приложение
├── requirements.txt       # Python зависимости
├── Dockerfile            # Docker образ
├── docker-compose.yml    # Docker Compose конфигурация
├── templates/            # HTML шаблоны
│   ├── index.html       # Главная страница
│   ├── results.html     # Страница результатов поиска фильмов
│   ├── torrents.html    # Страница результатов поиска торрентов
│   └── error.html       # Страница ошибок
└── 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