transmission-telegram/README.md

# transmission-telegram

#### Управляйте Transmission через Telegram.

<img src="https://raw.github.com/pyed/transmission-telegram/master/demo.gif" width="400" />

## CLI

### Установка

Просто [скачайте](https://github.com/pyed/transmission-telegram/releases) подходящий бинарный файл для вашей ОС, поместите `transmission-telegram` в ваш `$PATH` и готово.

Или, если у вас установлен `Go`: `go get -u github.com/pyed/transmission-telegram`

## Использование

[Wiki](https://github.com/pyed/transmission-telegram/wiki)

## Установка через Docker

### Standalone

```bash
docker run -d --name transmission-telegram \
kevinhalpin/transmission-telegram:latest \
-token=<Ваш Токен Бота> \
-master=<Ваш Username> \
-url=<Transmission RPC> \
-username=<Transmission Если Нужно> \ 
-password=<Transmission Если Нужно>
```

### Пример docker-compose

```yaml
version: '2.4'
services:
  transmission:
    container_name: transmission
    environment:
      - PUID=${PUID_DOCKUSER}
      - PGID=${PGID_APPZ}
    image: linuxserver/transmission
    network_mode: 'host'
    hostname: 'transmission'
    volumes:
      - ${CONFIG}/transmission:/config
      - ${DATA}/transmission/downloads:/downloads

telegram-transmission-bot:
    container_name: telegram-transmission-bot
    restart: on-failure
    depends_on:
      - transmission
      - plex
      - emby
    network_mode: 'host'
    image: kevinhalpin/transmission-telegram:latest
    command: '-token=${TELEGRAM_TRANSMISSION_BOT} -master=${TELEGRAM_USERNAME} -url=${TRANSMISSION_URL} -username=${TRANSMISSION_USERNAME} -password=${PASS}'
```

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

Этот проект представляет собой Telegram-бота для управления клиентом BitTorrent Transmission. Бот позволяет:

- **Просмотр торрентов**: список всех торрентов, фильтрация по статусу (загрузка, раздача, на паузе, проверка), поиск по имени или трекеру
- **Управление торрентами**: добавление (по URL, magnet-ссылке или файлу .torrent), запуск, остановка, удаление, проверка целостности
- **Мониторинг**: просмотр статистики, скорости загрузки/отдачи, информации о конкретных торрентах с live-обновлениями
- **Настройки**: установка лимитов скорости, изменение директории загрузки, сортировка торрентов
- **Уведомления**: автоматические уведомления о завершении загрузок через мониторинг RPC API (работает автоматически, без дополнительной настройки)

Бот работает только с авторизованными пользователями (masters), что обеспечивает безопасность управления вашими торрентами.

## Настройка уведомлений о завершении загрузок

Бот автоматически отправляет уведомления в Telegram, когда торрент завершает загрузку. Для этого используется **мониторинг через RPC API** (рекомендуемый метод), который работает без дополнительной настройки.

### Метод 1: Мониторинг через RPC API (рекомендуется) ⭐

Этот метод работает автоматически и не требует дополнительной настройки. Бот периодически опрашивает Transmission через RPC API и отслеживает изменение статуса торрентов с "Загрузка" на "Раздача".

#### Как это работает

1. **Автоматический запуск**: Мониторинг запускается автоматически при старте бота
2. **Polling**: Бот опрашивает статус торрентов каждые 10 секунд через RPC API
3. **Обнаружение завершения**: При переходе торрента из статуса "Downloading" в "Seeding" (или при достижении 100% загрузки) отправляется уведомление
4. **Активация**: Отправьте боту любое сообщение (например, `/help`), чтобы он запомнил ваш chat ID для отправки уведомлений

#### Преимущества

- ✅ Не требует доступа к файловой системе
- ✅ Не требует настройки логирования в Transmission
- ✅ Работает в любой конфигурации (Docker, standalone, и т.д.)
- ✅ Более надежный и быстрый метод
- ✅ Не зависит от формата логов

#### Пример уведомления

Когда торрент завершит загрузку, вы получите сообщение вида:
```
✅ Completed: My-Torrent-Name
```

### Метод 2: Мониторинг через лог-файл (альтернативный)

Альтернативный метод - мониторинг лог-файла Transmission. Этот метод требует дополнительной настройки, но может быть полезен в некоторых случаях.

#### Шаг 1: Включение логирования в Transmission

1. Откройте настройки Transmission (через веб-интерфейс или конфигурационный файл `settings.json`)
2. Включите логирование, установив параметр `"message-level": 2` (или выше) в `settings.json`
3. Убедитесь, что логирование включено: `"logging-enabled": true`

Для Docker-контейнера Transmission (linuxserver/transmission) логи обычно находятся в:
- `/config/transmission.log` (внутри контейнера)
- `${CONFIG}/transmission/transmission.log` (на хосте, если смонтирован volume)

**Пример настройки в `settings.json`:**
```json
{
  "logging-enabled": true,
  "message-level": 2
}
```

#### Шаг 2: Настройка бота для мониторинга логов

Добавьте параметр `-transmission-logfile` с путем к лог-файлу Transmission при запуске бота.

#### Для CLI:

```bash
transmission-telegram \
  -token=<Ваш Токен Бота> \
  -master=<Ваш Username> \
  -url=<Transmission RPC> \
  -transmission-logfile=/path/to/transmission.log
```

#### Для Docker Standalone:

```bash
docker run -d --name transmission-telegram \
  -v /path/to/transmission.log:/transmission.log:ro \
  kevinhalpin/transmission-telegram:latest \
  -token=<Ваш Токен Бота> \
  -master=<Ваш Username> \
  -url=<Transmission RPC> \
  -transmission-logfile=/transmission.log
```

#### Для docker-compose:

```yaml
version: '2.4'
services:
  transmission:
    container_name: transmission
    environment:
      - PUID=${PUID_DOCKUSER}
      - PGID=${PGID_APPZ}
    image: linuxserver/transmission
    network_mode: 'host'
    hostname: 'transmission'
    volumes:
      - ${CONFIG}/transmission:/config
      - ${DATA}/transmission/downloads:/downloads

  telegram-transmission-bot:
    container_name: telegram-transmission-bot
    restart: on-failure
    depends_on:
      - transmission
    network_mode: 'host'
    image: kevinhalpin/transmission-telegram:latest
    volumes:
      - ${CONFIG}/transmission/transmission.log:/transmission.log:ro
    command: >
      -token=${TELEGRAM_TRANSMISSION_BOT}
      -master=${TELEGRAM_USERNAME}
      -url=${TRANSMISSION_URL}
      -username=${TRANSMISSION_USERNAME}
      -password=${PASS}
      -transmission-logfile=/transmission.log
```

#### Шаг 3: Активация уведомлений

**Важно**: После запуска бота с параметром `-transmission-logfile`, отправьте боту любое сообщение (например, `/help` или `list`). Это необходимо для того, чтобы бот запомнил ваш chat ID и мог отправлять уведомления.

#### Как это работает

Бот мониторит указанный лог-файл в реальном времени и ищет строки с паттерном `"Incomplete" to "Complete"`, которые Transmission записывает при завершении загрузки торрента. При обнаружении такой строки бот автоматически извлекает имя завершенного торрента и отправляет уведомление в Telegram.

**Пример строки в логе Transmission:**
```
[2017-02-22 21:00:00.898] My-Torrent-Name State changed from "Incomplete" to "Complete" (torrent.c:2218)
```

### Устранение проблем

#### Устранение проблем (метод через лог-файл)

- **Уведомления не приходят**: 
  - Убедитесь, что логирование включено в Transmission (`logging-enabled: true`)
  - Проверьте, что путь к лог-файлу указан правильно
  - Убедитесь, что бот имеет доступ на чтение к лог-файлу
  - Отправьте боту сообщение после запуска, чтобы он запомнил ваш chat ID

- **Лог-файл не найден**:
  - Проверьте путь к файлу в настройках Transmission
  - Для Docker: убедитесь, что volume с лог-файлом смонтирован правильно
  - Проверьте права доступа к файлу

- **Бот не видит изменения в логе**:
  - Убедитесь, что Transmission действительно пишет в указанный файл
  - Проверьте уровень логирования (`message-level` должен быть 2 или выше)

#### Устранение проблем (метод через RPC API)

- **Уведомления не приходят**:
  - Убедитесь, что бот имеет доступ к Transmission RPC API
  - Проверьте, что Transmission работает и доступен по указанному URL
  - Отправьте боту сообщение после запуска, чтобы он запомнил ваш chat ID
  - Проверьте логи бота на наличие ошибок подключения к Transmission

- **Задержка уведомлений**:
  - Бот опрашивает статус каждые 10 секунд, поэтому может быть небольшая задержка
  - Это нормальное поведение и не требует настройки