batch-bot/README.md

Batch Bot - Telegram Comment Bot

Автоматический бот для генерации и публикации комментариев в Telegram от имени нескольких пользователей.

🏗 Архитектура

┌─────────────────────────────────────────────────────────────┐
│              Telegram Bot (Controller)                      │
│  @BotFather bot для управления и модерации                 │
└─────────────────────────────────────────────────────────────┤
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│              Session Workers                                │
│  Воркеры для каждого пользователя (user sessions)          │
└─────────────────────────────────────────────────────────────┤
                          │
          ┌───────────────┼───────────────┐
          ▼               ▼               ▼
   ┌────────────┐  ┌────────────┐  ┌────────────┐
   │ user_1.session│ │ user_2.session│ │ user_3.session│
   └────────────┘  └────────────┘  └────────────┘

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

• ✅ Мультиаккаунт — работа с несколькими сессиями одновременно
• ✅ AI генерация — комментарии через Ollama (локальная LLM)
• ✅ Модерация — inline-кнопки для одобрения/отклонения
• ✅ Редактирование — возможность изменить текст перед отправкой
• ✅ Статистика — учёт сгенерированных/отправленных комментариев
• ✅ Безопасность — разделение контроллера и воркеров
• ✅ Docker — полная контейнеризация

🚀 Быстрый старт

1. Настройка

# Скопируйте .env.example в .env
cp .env.example .env

# Отредактируйте .env
nano .env

Обязательные параметры:

Параметр	Описание
BOT_TOKEN	Токен бота от @BotFather
TELEGRAM_API_ID	API ID аккаунта
TELEGRAM_API_HASH	API Hash аккаунта
LOG_GROUP_ID	ID чата для модерации (с -100)
ADMIN_IDS	Telegram ID администраторов
OLLAMA_URL	URL внешнего Ollama

2. Создание сессий

# Установка зависимостей
pip install -r requirements.txt

# Запуск авторизации
python auth.py

Введите номер телефона и код из Telegram.

Для нескольких аккаунтов:

• Запустите python auth.py несколько раз
• Или скопируйте .session файлы в sessions/

3. Запуск Docker

# Сборка и запуск
docker-compose build
docker-compose up -d

# Логи
docker-compose logs -f

# Остановка
docker-compose down

Сервисы:

• controller — бот для модерации
• worker — отправка комментариев

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

Команды бота

Команда	Описание
/start	Главное меню
/stats	Статистика
/pending	Ожидающие комментарии
/sessions	Сессии
/groups	Управление группами
/add_group ID	Добавить группу
/help	Справка

Добавление группы

Через команду:

/add_group 1416283017

Через меню:

1. Отправьте /groups
2. Нажмите "➕ Добавить группу"
3. Отправьте ID группы

Управление группами:

• /groups — показать список
• Нажмите на группу для управления (пауза/удаление)

Модерация комментариев

1. Бот получает новый пост из группы
2. Генерирует комментарий через Ollama
3. Отправляет в LOG_GROUP_ID на модерацию
4. Администратор нажимает:
   • ✅ Одобрить — опубликовать комментарий
   • ❌ Отклонить — удалить комментарий
   • 🔄 Регенерировать — новый вариант
   • ✏️ Редактировать — изменить текст

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

Переменные окружения

Параметр	По умолчанию	Описание
BOT_TOKEN	-	Токен Telegram бота
TELEGRAM_API_ID	-	API ID для воркеров
TELEGRAM_API_HASH	-	API Hash для воркеров
LOG_GROUP_ID	-	ID чата для модерации
ADMIN_IDS	-	ID администраторов
OLLAMA_URL	http://host.docker.internal:11434	URL Ollama
OLLAMA_MODEL	qwen3:30b-a3b	Модель для генерации
INITIAL_SCAN_LIMIT	20	Кол-во сообщений для сканирования
COMMENT_DELAY_MIN	1	Мин. задержка перед отправкой (сек)
COMMENT_DELAY_MAX	5	Макс. задержка перед отправкой (сек)

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

batch-bot/
├── .env.example          # Пример конфигурации
├── .gitignore
├── docker-compose.yml    # Docker конфигурация
├── Dockerfile            # Образ для controller/worker
├── requirements.txt      # Python зависимости
├── auth.py              # Скрипт авторизации
├── prompt.txt           # Шаблон для LLM
├── bot/
│   ├── config.py        # Конфигурация
│   ├── controller.py    # Бот для модерации
│   ├── worker.py        # Воркер для отправки
│   ├── db.py            # База данных
│   ├── keyboard.py      # Inline-клавиатуры
│   ├── ollama.py        # Ollama API
│   └── session_manager.py  # Управление сессиями
├── sessions/            # .session файлы (том Docker)
├── logs/                # Логи (том Docker)
└── data/                # БД и данные (том Docker)

🐳 Docker

Запуск

# Сборка
docker-compose build

# Запуск
docker-compose up -d

# Логи
docker-compose logs -f controller
docker-compose logs -f worker

# Остановка
docker-compose down

Тома

Том	Описание
./sessions:/app/sessions	Файлы сессий
./logs:/app/logs	Логи
./data:/app/data	База данных

Сетевые настройки

Linux:

OLLAMA_URL=http://172.17.0.1:11434

macOS/Windows:

OLLAMA_URL=http://host.docker.internal:11434

🔐 Безопасность

• .env и *.session файлы добавлены в .gitignore
• Не коммитьте сессии в репозиторий
• Используйте разные аккаунты для воркеров
• Ограничьте доступ через ADMIN_IDS

📊 База данных

Таблицы:

Таблица	Описание
comments	Комментарии (текст, статус, сессия)
sessions	Информация о сессиях
stats	Статистика по дням
target_groups	Целевые группы для мониторинга

⚠️ Важные замечания

1. Telegram ToS — использование нескольких аккаунтов может нарушать условия Telegram
2. Задержки — настройте COMMENT_DELAY_MIN/MAX для естественности
3. Лимиты — не отправляйте слишком много комментариев с одного аккаунта
4. Ollama — должен быть доступен по сети для воркера

🐛 Решение проблем

Бот не подключается:

• Проверьте BOT_TOKEN в .env
• Убедитесь, что бот добавлен в LOG_GROUP_ID как администратор

Сессия не авторизуется:

• Запустите python auth.py заново
• Проверьте TELEGRAM_API_ID и TELEGRAM_API_HASH

Ollama не отвечает:

• Проверьте URL в .env
• Убедитесь, что модель загружена: ollama list

"Нет групп в БД":

• Добавьте группу через бота: /add_group ID

Комментарии не отправляются:

• Проверьте что аккаунт вступил в группу комментариев
• Worker автоматически вступает при отправке

📝 Лицензия

MIT

📞 Контакты

• Telegram: @your_username
• Email: your@email.com