317 lines
17 KiB
Markdown
317 lines
17 KiB
Markdown
# 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), что обеспечивает безопасность управления вашими торрентами.
|
||
|
||
## Архитектура проекта
|
||
|
||
Проект использует модульную архитектуру для улучшения поддерживаемости, тестируемости и расширяемости кода.
|
||
|
||
### Структура проекта
|
||
|
||
```
|
||
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
|
||
├── main.go # Старый файл (legacy, для обратной совместимости)
|
||
├── 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`:**
|
||
```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 секунд, поэтому может быть небольшая задержка
|
||
- Это нормальное поведение и не требует настройки
|