Night Fun Drug Bot TG

Telegram-бот для поиска, просмотра и организации медиа из Rule34 по тегам. Внутри — одиночная выдача и подборки, личная библиотека, коллекции, чёрный список, рекомендации и автоматические подписки. Интерфейс адаптируется под пользователя: простой режим оставляет только основные действия, а расширенный открывает быстрый доступ ко всем инструментам.

Warning

Проект предназначен только для совершеннолетних пользователей (18+). Контент поступает из стороннего сервиса и не хранится в репозитории. Владелец запущенного экземпляра самостоятельно отвечает за ограничение доступа и соблюдение применимых правил.

Содержание

• Возможности
• Интерфейс и навигация
• Быстрый запуск
• Конфигурация
• Запуск в Docker
• Команды бота
• Структура проекта
• Данные, логи и резервное копирование
• Разработка и проверка
• Ограничения
• Участие в разработке
• Лицензия

Возможности

Поиск и подборки

• поиск по тегам, ID поста и случайная выдача;
• подборки до 10 элементов с переходом между страницами;
• сортировка по новизне, популярности или случайным образом;
• фильтры по рейтингу, типу медиа, ориентации и минимальному разрешению;
• выбор качества: auto, preview, sample или original;
• исключение уже просмотренных постов из повторной выдачи;
• автодополнение тегов;
• конструктор запросов с обязательными и исключаемыми тегами;
• сохранённые запросы с собственными фильтрами;
• кнопка похожей подборки и постраничные быстрые действия со всеми тегами поста;
• устойчивая сборка Telegram-альбома: для GIF используется статичное preview, а недоступный оригинал заменяется на sample без разбиения подборки на отдельные сообщения.

Персонализация

• постоянная компактная клавиатура с основными действиями;
• простой и расширенный режимы интерфейса;
• стартовый экран с быстрыми сценариями для нового пользователя;
• хлебные крошки, контекстная помощь и единообразные кнопки возврата;
• отмена любого пошагового ввода кнопкой или командой /cancel;
• настройка состава подписей к изображениям;
• управление максимальным размером загружаемого файла;
• спойлеры для всех медиа или только постов с rating explicit;
• история запросов и личная статистика;
• отображение тегов поста и blacklist одновременно на английском и русском;
• объяснение, какой blacklist-тег заблокировал пост.

Избранное и коллекции

• добавление постов в избранное;
• просмотр избранного списком или новыми Telegram-альбомами по 10 постов на страницу;
• пользовательские коллекции;
• заметки к сохранённым постам;
• отдельная очередь «Посмотреть позже» с автоматическим сроком хранения;
• поиск по тегам и тексту заметок;
• экспорт избранного или отдельной коллекции в ZIP.

Чёрный список

• постоянные и временные исключения;
• добавление и удаление нескольких тегов одной командой;
• готовые наборы;
• импорт и экспорт списка;
• поиск похожих тегов через автодополнение.

Подписки и надёжность

• периодическая доставка новых постов по сохранённым запросам;
• предпросмотр запроса и интервала перед созданием подписки;
• отдельные фильтры rating, типа, ориентации, разрешения, качества и blacklist для каждой подписки;
• накопительный дайджест: от пяти постов либо не реже одного раза в шесть часов;
• настраиваемый интервал и временная пауза подписок;
• кэширование результатов и защита от повторной отправки;
• backoff при отсутствии новых постов;
• очередь неудачных доставок и ручной повтор администратором;
• обработка Telegram rate limits и резервные media URL;
• локальное скачивание и загрузка файла, если Telegram не может получить его по URL;
• проверка MIME, сигнатуры и размера изображения, защита от опасных адресов и перенаправлений.

Рекомендации и массовые действия

• рекомендации на основе частых тегов в избранном без передачи профиля внешнему AI;
• исключение нежелательных тегов из будущих рекомендаций;
• сохранение всей поисковой подборки в избранное или новую коллекцию;
• создание сохранённого запроса или подписки прямо из результатов подборки;
• просмотр занимаемых пользовательских записей и очистка старой истории.

Безопасные пользовательские сценарии

• подтверждение перед удалением подписки, коллекции, избранного или пользовательских данных;
• информативные пустые экраны с кнопкой следующего действия;
• компактные уведомления для быстрых операций без лишних сообщений в чате;
• автоматический сброс незавершённого ввода при переходе в другой основной раздел;
• отдельный раздел «Мои данные» для статистики, хранилища и экспорта.

Интерфейс и навигация

После /start бот показывает короткий онбординг и устанавливает постоянную клавиатуру. Новый пользователь получает простой режим с четырьмя основными кнопками; режим можно переключить в Настройки → Интерфейс.

Главное меню
├── 🔎 Поиск
│   ├── Поиск по тегам
│   ├── Случайный пост и подборки
│   ├── Конструктор запроса
│   └── История и сохранённые запросы
├── ⭐ Библиотека
│   ├── Избранное и коллекции
│   ├── На потом
│   └── Поиск и рекомендации
├── 🔔 Подписки
│   ├── Создание с предпросмотром
│   ├── Индивидуальные фильтры
│   └── Общая пауза и дайджест
├── 🚫 Чёрный список
├── ⚙️ Настройки
└── 👤 Мои данные (расширенный режим)

На экранах пошагового ввода всегда доступна кнопка ❌ Отмена. То же действие выполняет команда /cancel. Контекстные кнопки ℹ️ объясняют только текущий раздел, а общая справка доступна через ❓ Помощь.

Технологии

• Python 3.11+
• python-telegram-bot
• aiohttp
• aiosqlite
• SQLite с WAL
• Docker Compose — опционально

Точные версии Python-зависимостей закреплены в requirements.txt.

Быстрый запуск

1. Получите исходный код

git clone https://github.com/EnoTiK11m/night_fun_drug_bot_tg.git
cd night_fun_drug_bot_tg

2. Создайте виртуальное окружение

Windows PowerShell:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

Linux и macOS:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

3. Настройте окружение

Скопируйте пример конфигурации:

Copy-Item .env.example .env

Для Linux и macOS:

cp .env.example .env

Заполните как минимум три обязательные переменные:

BOT_TOKEN=your_telegram_bot_token
API_USER_ID=your_rule34_api_user_id
API_KEY=your_rule34_api_key

Токен Telegram создаётся через @BotFather. Данные Rule34 API доступны в настройках аккаунта сервиса.

4. Запустите бота

python bot.py

SQLite-база и необходимые таблицы создаются автоматически при первом запуске.

Конфигурация

Все параметры читаются из переменных окружения или файла .env.

Переменная	Обязательная	Значение по умолчанию	Назначение
BOT_TOKEN	да	—	Токен Telegram-бота
API_USER_ID	да	—	ID пользователя Rule34 API
API_KEY	да	—	Ключ Rule34 API
SEARCH_COOLDOWN_SECONDS	нет	3	Пауза между пользовательскими поисками
SUBSCRIPTION_CHECK_INTERVAL_SECONDS	нет	120	Частота проверки подписок; минимум 30 секунд
SUBSCRIPTION_MAX_POSTS_PER_USER_PASS	нет	45	Максимум обрабатываемых подписок пользователя за проход, от 1 до 45
SUBSCRIPTION_MAX_TOTAL	нет	20	Максимум подписок пользователя, включая приостановленные
SUBSCRIPTION_MAX_ACTIVE	нет	10	Максимум одновременно активных подписок пользователя
SUBSCRIPTION_QUERY_MAX_LENGTH	нет	256	Максимальная длина нормализованного запроса подписки
SUBSCRIPTION_QUERY_MAX_TAGS	нет	20	Максимальное число тегов в запросе подписки
SUBSCRIPTION_CREATE_COOLDOWN_SECONDS	нет	30	Пауза между созданием новых подписок; обновление существующей не ограничивается
SUBSCRIPTION_CACHE_MAX_PER_QUERY	нет	250	Максимум строк кэша на пару пользователь/запрос
SUBSCRIPTION_CACHE_MAX_ROWS	нет	100000	Жёсткий глобальный лимит строк кэша подписок
SUBSCRIPTION_CACHE_CLEANUP_BATCH_SIZE	нет	500	Максимум удалений из каждого SQLite-кэша за проход
SUBSCRIPTION_CACHE_CLEANUP_INTERVAL_SECONDS	нет	900	Интервал фоновой очистки SQLite-кэшей
POST_CACHE_TTL_HOURS	нет	168	Срок хранения записей общего кэша постов в часах
POST_CACHE_MAX_ROWS	нет	100000	Жёсткий лимит строк общего кэша постов
USER_STATE_TTL_MINUTES	нет	30	TTL временного process-local состояния пользователя
USER_STATE_CLEANUP_INTERVAL_SECONDS	нет	300	Интервал очистки временного состояния пользователей
TELEGRAM_GLOBAL_REQUESTS_PER_SECOND	нет	20	Общая частота запросов к Telegram Bot API
TELEGRAM_PER_CHAT_REQUESTS_PER_SECOND	нет	0.75	Частота запросов для одного пользователя или чата
TELEGRAM_RATE_LIMIT_BURST	нет	3	Допустимый кратковременный burst запросов
TELEGRAM_RATE_LIMIT_STATE_TTL_SECONDS	нет	900	TTL неактивных per-chat buckets limiter-а
TELEGRAM_MAX_RETRY_AFTER_ATTEMPTS	нет	2	Максимальное число повторов после RetryAfter
GLOBAL_DOWNLOAD_CONCURRENCY	нет	4	Общий лимит одновременных внешних загрузок процесса
ZIP_EXPORT_WORKERS	нет	1	Число обработчиков FIFO-очереди ZIP-экспорта, от 1 до 2
ZIP_EXPORT_QUEUE_SIZE	нет	8	Максимум ожидающих ZIP-заданий
ZIP_EXPORT_TIMEOUT_SECONDS	нет	600	Общий timeout одного ZIP-задания
ZIP_EXPORT_MAX_FILES	нет	120	Максимум файлов в одном экспорте
ZIP_EXPORT_MAX_FILE_BYTES	нет	20971520	Максимальный фактический размер одного скачанного файла
ZIP_EXPORT_MAX_TOTAL_BYTES	нет	209715200	Максимум фактически скачанных байт на экспорт
ZIP_EXPORT_PART_BYTES	нет	47185920	Целевой предел одной ZIP-части
ZIP_EXPORT_MAX_PARTS	нет	5	Максимальное число ZIP-частей
ZIP_EXPORT_MAX_TEMP_BYTES	нет	100663296	Максимум временного дискового пространства задания
ZIP_EXPORT_PROGRESS_INTERVAL_SECONDS	нет	3	Минимальный интервал обновления прогресса в Telegram
DB_PATH	нет	bot_data.db	Путь к SQLite-базе
INSTANCE_LOCK_WAIT_SECONDS	нет	20	Максимальное ожидание освобождения межпроцессного lock, от 0 до 120 секунд
INSTANCE_LOCK_RETRY_INTERVAL_SECONDS	нет	0.25	Интервал проверки межпроцессного lock, от 0.05 до 5 секунд
ADMIN_USER_IDS	нет	пусто	Telegram user ID администраторов через запятую
ALLOWED_USER_IDS	нет	пусто	Разрешённые пользователи личных чатов через запятую
ALLOWED_CHAT_IDS	нет	пусто	Разрешённые Telegram chat ID через запятую
ALLOW_GROUP_CHATS	нет	false	Разрешить работу в группах
TAG_TRANSLATION_ENABLED	нет	true	Фоновый перевод тегов на русский при отображении
GIT_UPDATE_REMOTE	нет	origin	Фиксированный Git remote для админского обновления
GIT_UPDATE_BRANCH	нет	main	Фиксированная ветка для админского обновления
GIT_UPDATE_COMMAND_TIMEOUT_SECONDS	нет	60	Timeout одной Git-команды обновления
GIT_UPDATE_PIP_TIMEOUT_SECONDS	нет	300	Timeout установки изменившихся зависимостей

Если ALLOWED_USER_IDS не задан, бот доступен всем пользователям в личных чатах. Группы запрещены по умолчанию. Пользователи из ADMIN_USER_IDS всегда получают доступ.

Не добавляйте .env, базы, логи и резервные копии в Git. Эти пути уже исключены через .gitignore.

Запуск в Docker

Создайте .env, затем выполните:

docker compose up -d --build
docker compose logs -f bot

Compose хранит данные вне контейнера:

• ./data — SQLite-база;
• ./logs — журналы приложения.

Остановка:

docker compose down

Не запускайте несколько экземпляров приложения с одной SQLite-базой.

Запуск на Windows

Для локальной эксплуатации предусмотрены:

• rule34.bat — запускает бота и перезапускает его после сбоя или команды /restart;
• start_hidden.vbs — запускает тот же сценарий без окна консоли;
• START_HIDDEN_README.txt — краткая инструкция для скрытого запуска.

Команды бота

Пользовательские команды

Команда	Назначение
/start	Обновить постоянную клавиатуру и открыть быстрый старт
/search <tags>	Найти один пост по тегам
/random	Получить случайный пост
/gallery <tags>	Получить подборку до 10 элементов; random — случайная подборка
/id <post_id>	Найти пост по ID
/tags <query>	Найти подходящие названия тегов
/blacklist	Открыть меню чёрного списка
/blacklist add <tags>	Добавить один или несколько тегов
/blacklist remove <tags>	Удалить один или несколько тегов
/whyblocked <post_id или tags>	Показать совпадения с чёрным списком
/favorites	Открыть избранное
/collections	Управлять коллекциями избранного
/presets	Управлять сохранёнными запросами
/recommendations	Получить рекомендации по избранному
/later	Открыть очередь «Посмотреть позже»
/storage	Показать использование пользовательского хранилища
/history	Показать историю поиска
/stats	Показать личную статистику
/subscriptions	Управлять автоматическими подписками
/settings	Настроить подписи, подборки, качество и режим интерфейса
/cancel	Отменить текущий пошаговый ввод

В простом режиме постоянная клавиатура содержит четыре действия: поиск, случайный пост, библиотеку и все разделы. Расширенный режим добавляет быстрые кнопки подборок и подписок. Сохранённые запросы, коллекции, рекомендации и «На потом» сгруппированы во вложенных разделах, а редкие действия с постом открываются кнопкой ••• Ещё.

Команды администратора

Команда	Назначение
/health	Проверить Rule34 API, SQLite, фоновые задачи и свободное место
/adminstats	Показать runtime-метрики и статистику базы
/retry_failed	Повторить до 20 неудачных доставок подписок
/restart	Завершить процесс с кодом перезапуска для внешнего launcher
/version	Показать commit, ветку, дату и состояние рабочей копии
/update_check	Проверить наличие новых commit без изменения проекта
/update	Создать backup, установить fast-forward обновление и перезапустить бот

Административные команды доступны только ID из ADMIN_USER_IDS; команды обновления дополнительно ограничены личным чатом. /update не принимает remote, ветку или shell-аргументы от Telegram и выполняет только git pull --ff-only с настроенными значениями. Для автоматического возобновления после /restart или /update необходим rule34.bat, Docker с restart policy или другой process manager.

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

Путь	Ответственность
bot.py	Telegram handlers, пользовательские сценарии и фоновые задачи
api_handler.py	Асинхронный клиент Rule34 API, пагинация и autocomplete
database.py	Схема и миграции SQLite, настройки, кэш, подписки и избранное
bot_media.py	Безопасная доставка медиа, fallback URL и retries
bot_delivery.py	Ограничение скорости отправки и Telegram cooldown
bot_features.py	Фильтры галереи, выбор качества и runtime-метрики
bot_keyboards.py	Постоянная и inline-клавиатуры
bot_formatting.py	Подписи, Markdown и форматирование данных
bot_state.py	Временное состояние диалогов и callback payload
tag_translation.py	Фоновый перевод тегов и работа с кэшем переводов
config.py	Чтение и валидация конфигурации
scripts/backup_sqlite.py	Согласованная резервная копия работающей SQLite-базы
tests/	Модульные и интеграционные тесты
docs/PRODUCTION.md	Краткое руководство по эксплуатации

Данные, логи и резервное копирование

По умолчанию база хранится в bot_data.db. Приложение включает WAL, foreign keys и busy timeout для безопасной конкурентной работы в рамках одного процесса.

Создание согласованной резервной копии локальной базы:

python scripts/backup_sqlite.py --db bot_data.db --output-dir backups

Для Docker:

python scripts/backup_sqlite.py --db data/bot_data.db --output-dir backups

Основные логи находятся в logs/:

• info.log — рабочие события и heartbeat;
• warnings.log — предупреждения;
• errors.log — ошибки и traceback;
• startup_output.log и startup_errors.log — вывод Windows launcher до настройки logging.

Приложение ротирует рабочие журналы. Практические рекомендации по эксплуатации находятся в docs/PRODUCTION.md.

Переводы тегов сохраняются в SQLite и постепенно заполняются фоновой задачей. Для отсутствующих переводов бот отправляет только названия тегов во внешний сервис Google Translate; поисковые запросы, пользовательские ID и медиа не передаются.

Разработка и проверка

Установка зависимостей:

python -m pip install -r requirements.txt
python -m pip check

Проверка синтаксиса и запуск тестов:

python -m compileall -q bot.py api_handler.py database.py config.py bot_delivery.py bot_features.py bot_formatting.py bot_keyboards.py bot_media.py bot_zip_export.py bot_state.py tag_translation.py
python -m unittest discover -s tests -v

Эти проверки также выполняются в GitHub Actions при push и pull request.

Ограничения

• Бот использует long polling и рассчитан на один активный процесс с одной SQLite-базой.
• Доступность поиска и файлов зависит от Rule34 API и его CDN.
• Telegram не поддерживает GIF как animation внутри media group. В обычной галерее бот использует статичное preview; в режиме анимаций GIF отправляются отдельно.
• Дайджест отправляется после накопления пяти постов или через шесть часов; его можно запросить вручную в меню подписок.
• ZIP-экспорт включает только статичные изображения поддерживаемых форматов и ограничен размером Telegram.
• Проект не предоставляет встроенную проверку возраста — доступ должен контролировать оператор экземпляра.

Участие в разработке

1. Создайте отдельную ветку.
2. Внесите изменения и добавьте тесты.
3. Запустите локальные проверки.
4. Откройте pull request с описанием поведения и способа проверки.

Сообщения об ошибках и предложения принимаются через GitHub Issues.

Лицензия

Проект распространяется по лицензии MIT. Полный текст находится в файле LICENSE.

Автор: EnoTiK11m.