transmission-telegram

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

CLI

Установка

Просто скачайте подходящий бинарный файл для вашей ОС, поместите transmission-telegram в ваш $PATH и готово.

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

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

Wiki

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

Standalone

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

Пример docker-compose

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), что обеспечивает безопасность управления вашими торрентами.

Архитектура проекта

Проект использует модульную архитектуру для улучшения поддерживаемости, тестируемости и расширяемости кода.

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

transmission-telegram/
├── cmd/
│   └── bot/
│       └── main.go              # Точка входа приложения
├── internal/
│   ├── config/                  # Конфигурация приложения
│   │   ├── config.go           # Загрузка и валидация конфигурации
│   │   └── constants.go         # Константы приложения
│   ├── bot/                     # Telegram бот
│   │   ├── bot.go              # Основная структура бота
│   │   ├── handlers.go          # Обработчики команд
│   │   ├── helpers.go           # Вспомогательные функции
│   │   └── constants.go         # Константы бота (HELP текст)
│   ├── transmission/            # Transmission клиент
│   │   ├── client.go           # Кэшированный клиент с TTL
│   │   └── interfaces.go       # Интерфейсы для тестируемости
│   ├── monitor/                 # Мониторинг завершения торрентов
│   │   └── monitor.go          # RPC polling мониторинг
│   ├── formatter/               # Форматирование сообщений
│   │   └── formatter.go        # Форматирование торрентов для Telegram
│   └── logger/                  # Логирование
│       └── logger.go            # Логгер с маскированием секретов
├── pkg/
│   └── utils/                   # Утилиты
│       └── markdown.go          # Экранирование Markdown
├── Dockerfile                   # Docker образ
└── go.mod                       # Зависимости Go

Основные компоненты

internal/config

• Загрузка конфигурации из флагов и переменных окружения
• Валидация параметров при старте
• Безопасное хранение конфигурации

internal/bot

• Обработка Telegram обновлений
• Маршрутизация команд к соответствующим обработчикам
• Управление live-обновлениями сообщений
• Отправка сообщений с автоматическим разбиением на части

internal/transmission

• Обертка над Transmission RPC API
• Кэширование результатов запросов (TTL: 2 секунды)
• Автоматическая инвалидация кэша при изменениях
• Интерфейсы для упрощения тестирования

internal/monitor

• Мониторинг завершения торрентов через RPC polling
• Отслеживание изменения статусов торрентов
• Callback-уведомления о завершении загрузок

internal/formatter

• Единообразное форматирование информации о торрентах
• Поддержка различных форматов (краткий, детальный, для паузы и т.д.)
• Экранирование Markdown символов

internal/logger

• Централизованное логирование
• Автоматическое маскирование секретных данных (токены, пароли)
• Поддержка записи в файл или stdout

Преимущества новой архитектуры

• Модульность: Каждый компонент имеет четкую ответственность
• Тестируемость: Интерфейсы позволяют легко создавать mock-объекты
• Безопасность: Маскирование секретов в логах, валидация конфигурации
• Производительность: Кэширование API запросов, оптимизация live-обновлений
• Поддерживаемость: Устранено дублирование кода, улучшена читаемость
• Расширяемость: Легко добавлять новые команды и функции

Dependency Injection

Проект использует dependency injection вместо глобальных переменных:

• Все зависимости передаются через конструкторы
• Упрощает тестирование и изоляцию компонентов
• Позволяет легко заменять реализации (например, для тестов)

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

Бот автоматически отправляет уведомления в 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:

{
  "logging-enabled": true,
  "message-level": 2
}

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

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

Для CLI:

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

Для Docker Standalone:

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:

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 секунд, поэтому может быть небольшая задержка
  • Это нормальное поведение и не требует настройки