41fb62f62e
Создана структура документации, описывающая функциональность, установку, использование CLI, архитектуру и интеграции с TorrAPI и OpenRouter. Добавлены примеры конфигурации и метаданных, а также описание структуры выходных данных.
148 lines
5.1 KiB
Markdown
148 lines
5.1 KiB
Markdown
# TorrAPI (Поиск на трекерах)
|
||
|
||
GenAudioBookInfo использует [TorrServer](https://github.com/YouROK/TorrServer) / TorrAPI-совместимый сервер для поиска аудиокниг на торрент-трекерах и получения метаданных раздач.
|
||
|
||
---
|
||
|
||
## Что такое TorrAPI
|
||
|
||
TorrServer — локальный сервис, который предоставляет JSON API для поиска по популярным торрент-трекерам:
|
||
|
||
- **Rutracker** — крупнейший русскоязычный трекер
|
||
- **Rutor** — популярный трекер
|
||
- **Kinozal** — кино и аудиокниги
|
||
- И другие трекеры в зависимости от конфигурации TorrServer
|
||
|
||
---
|
||
|
||
## Установка TorrServer
|
||
|
||
TorrServer распространяется отдельно. Скачать: [github.com/YouROK/TorrServer/releases](https://github.com/YouROK/TorrServer/releases)
|
||
|
||
```bash
|
||
# Linux/macOS
|
||
./TorrServer -port 9200
|
||
|
||
# Windows
|
||
TorrServer.exe -port 9200
|
||
```
|
||
|
||
После запуска TorrServer доступен на `http://localhost:9200`.
|
||
|
||
---
|
||
|
||
## Настройка в `config.yaml`
|
||
|
||
```yaml
|
||
torrapi:
|
||
url: http://localhost:9200 # Адрес TorrAPI сервера
|
||
```
|
||
|
||
Можно переопределить флагом:
|
||
```bash
|
||
./genaudiobookinfo -api http://192.168.1.10:9200 D:\Audiobooks
|
||
```
|
||
|
||
---
|
||
|
||
## Как выполняется поиск
|
||
|
||
### Алгоритм поиска одной книги
|
||
|
||
```
|
||
1. Попытаться найти по title (названию из тегов / имени папки)
|
||
2. Если результатов нет и title ≠ author:
|
||
попытаться найти по author (автору)
|
||
3. Если найдено: взять детали лучшего результата
|
||
4. Если не найдено: следующая попытка (до search_retries раз)
|
||
5. Если все попытки исчерпаны: переместить в ERROR/
|
||
```
|
||
|
||
### Критерий выбора лучшего результата
|
||
|
||
Трекеры ранжируются в порядке приоритета:
|
||
|
||
1. **Rutracker** (наиболее полные метаданные)
|
||
2. **Rutor**
|
||
3. **Kinozal**
|
||
4. Остальные (по количеству сидов)
|
||
|
||
Из результатов одного трекера выбирается раздача с наибольшим числом сидов.
|
||
|
||
---
|
||
|
||
## Ограничение параллелизма
|
||
|
||
Параметр `search_concurrency` (по умолчанию `2`) ограничивает число одновременных HTTP-запросов к TorrAPI через семафор. Это предотвращает перегрузку TorrServer при большом количестве воркеров.
|
||
|
||
```yaml
|
||
processing:
|
||
workers: 6 # воркеров до 6
|
||
search_concurrency: 2 # но к TorrAPI ходят только 2 одновременно
|
||
```
|
||
|
||
---
|
||
|
||
## Ретраи поиска
|
||
|
||
Если поиск вернул пустой результат или произошла ошибка сети:
|
||
|
||
```yaml
|
||
processing:
|
||
search_retries: 3 # попыток
|
||
search_retry_delay: 3s # пауза между попытками
|
||
```
|
||
|
||
Это полезно если TorrServer временно перегружен или трекер недоступен.
|
||
|
||
---
|
||
|
||
## Получаемые данные
|
||
|
||
После успешного поиска `GetDetail()` возвращает:
|
||
|
||
| Поле | Описание |
|
||
|---|---|
|
||
| `Title` | Полное название раздачи (трекерное) |
|
||
| `Comment` | Описание раздачи (аннотация книги) |
|
||
| `Year` | Год издания (если указан на трекере) |
|
||
| `Genre` | Жанр |
|
||
| `Authors` | Авторы в трекерном формате |
|
||
| `CoverURL` | URL обложки для скачивания |
|
||
| `Seeds` | Количество сидов |
|
||
| `Size` | Размер раздачи |
|
||
| `TrackerURL` | Ссылка на страницу раздачи |
|
||
|
||
Эти данные записываются в `metadata.json` в секцию `torrent.*`.
|
||
|
||
---
|
||
|
||
## Диагностика
|
||
|
||
### TorrServer недоступен
|
||
|
||
```
|
||
WARN TorrAPI недоступен: dial tcp 127.0.0.1:9200: connection refused
|
||
```
|
||
|
||
Решение: убедиться, что TorrServer запущен на указанном порту.
|
||
|
||
### Ничего не найдено
|
||
|
||
```
|
||
WARN [Книга] не найдена на трекерах (попытка 1/3)
|
||
...
|
||
ERROR [Книга] перемещена в ERROR/ после 3 попыток
|
||
```
|
||
|
||
Возможные причины:
|
||
- Нестандартное имя папки (числа, латиница вместо кириллицы)
|
||
- Книга действительно отсутствует на трекерах
|
||
- Слишком короткое/общее название
|
||
|
||
### Проверка вручную
|
||
|
||
```bash
|
||
curl "http://localhost:9200/api/v1/search?query=Акунин+Азазель" | jq .
|
||
```
|