✅ UserBot Integration Complete: Fixed container startup, integrated UserBot menu to main bot
MAJOR FIXES: ✅ Fixed UserBot container startup by making TELEGRAM_BOT_TOKEN optional ✅ Broke circular import chain between app modules ✅ Made Config.validate() conditional for UserBot-only mode ✅ Removed unused celery import from userbot_service.py INTEGRATION: ✅ UserBot menu now accessible from main bot /start command ✅ Added 🤖 UserBot button to main keyboard ✅ Integrated userbot_manager.py handlers: - userbot_menu: Main UserBot interface - userbot_settings: Configuration - userbot_collect_groups: Gather all user groups - userbot_collect_members: Parse group members ✅ UserBot handlers properly registered in ConversationHandler CONTAINERS: ✅ tg_autoposter_bot: Running and handling /start commands ✅ tg_autoposter_userbot: Running as standalone microservice ✅ All dependent services (Redis, PostgreSQL, Celery workers) operational STATUS: Bot is fully operational and ready for testing
This commit is contained in:
274
docs/USERBOT_QUICKSTART.md
Normal file
274
docs/USERBOT_QUICKSTART.md
Normal file
@@ -0,0 +1,274 @@
|
||||
# Telethon UserBot Microservice - Краткая инструкция
|
||||
|
||||
## 🚀 Быстрый старт
|
||||
|
||||
### 1. Подготовка конфигурации
|
||||
|
||||
Добавьте в `.env`:
|
||||
|
||||
```bash
|
||||
# Telethon Client Configuration
|
||||
USE_TELETHON=true
|
||||
TELETHON_API_ID=12345678 # Получить на https://my.telegram.org
|
||||
TELETHON_API_HASH=abcdef1234567890abcde # Получить на https://my.telegram.org
|
||||
TELETHON_PHONE=+1234567890 # Номер телефона UserBot
|
||||
TELETHON_FLOOD_WAIT_MAX=60 # Макс время ожидания при flood
|
||||
```
|
||||
|
||||
### 2. Первый запуск (Авторизация)
|
||||
|
||||
```bash
|
||||
# Запустить интерактивно для авторизации
|
||||
python userbot_service.py
|
||||
|
||||
# Следовать инструкциям - введите SMS код когда придет
|
||||
# Сессия сохранится в sessions/userbot_session.session
|
||||
```
|
||||
|
||||
### 3. Запуск в Docker
|
||||
|
||||
```bash
|
||||
# Пересобрать все контейнеры
|
||||
docker-compose build
|
||||
|
||||
# Запустить все сервисы
|
||||
docker-compose up -d
|
||||
|
||||
# Проверить логи userbot
|
||||
docker-compose logs -f userbot
|
||||
```
|
||||
|
||||
## 📊 Использование
|
||||
|
||||
### Через Telegram бот
|
||||
|
||||
Команда `/sync_groups` автоматически:
|
||||
1. ✅ Инициализирует UserBot если нужно
|
||||
2. 📊 Парсит всех участников групп
|
||||
3. 💾 Сохраняет в PostgreSQL БД
|
||||
4. ✏️ Обновляет информацию о группах
|
||||
|
||||
```
|
||||
/sync_groups
|
||||
⏳ Синхронизирую группы через UserBot парсер...
|
||||
✅ Синхронизация завершена!
|
||||
📊 Результаты:
|
||||
• 🔄 Синхронизировано: 5 групп
|
||||
```
|
||||
|
||||
### Через Celery задачи
|
||||
|
||||
```python
|
||||
from app.userbot.tasks import parse_group_task, sync_all_groups_task
|
||||
|
||||
# Парсить одну группу
|
||||
parse_group_task.delay(chat_id=-1001234567890)
|
||||
|
||||
# Синхронизировать все группы
|
||||
sync_all_groups_task.delay()
|
||||
|
||||
# Парсить участников с лимитом
|
||||
parse_group_members_task.delay(chat_id=-1001234567890, limit=5000)
|
||||
```
|
||||
|
||||
### Мониторинг в Flower
|
||||
|
||||
http://localhost:5555
|
||||
|
||||
## 📁 Структура файлов
|
||||
|
||||
```
|
||||
app/userbot/
|
||||
├── __init__.py # Пакет
|
||||
├── parser.py # Основной парсер Telethon
|
||||
└── tasks.py # Celery задачи
|
||||
|
||||
app/handlers/
|
||||
└── commands.py # Команда /sync_groups (обновлена)
|
||||
|
||||
app/database/
|
||||
├── repository.py # GroupRepository.add_or_update_group()
|
||||
└── member_repository.py # GroupMemberRepository.add_or_update_member()
|
||||
|
||||
docker-compose.yml # Добавлен сервис userbot
|
||||
Dockerfile.userbot # Dockerfile для userbot контейнера
|
||||
userbot_service.py # Точка входа микросервиса
|
||||
|
||||
docs/
|
||||
└── USERBOT_MICROSERVICE.md # Полная документация
|
||||
```
|
||||
|
||||
## 🔄 Архитектура
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ Telegram Python-telegram-bot │
|
||||
│ (Основной бот) │
|
||||
└────────────────┬────────────────────────────────────────┘
|
||||
│
|
||||
/start, /sync_groups, /help
|
||||
│
|
||||
┌────────┴─────────────────────┐
|
||||
│ │
|
||||
▼ ▼
|
||||
Callback Handlers sync_groups_command
|
||||
(Управление UI) │
|
||||
│ │
|
||||
│ ┌────────────┴──────┐
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
Celery Tasks PostgreSQL UserBot Parser
|
||||
│ │ (telethon)
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
Flower Monitor Tables: TelethonClient
|
||||
(http:5555) - groups (telethon_session)
|
||||
- messages │
|
||||
- members │
|
||||
▼
|
||||
Telegram UserBot
|
||||
(@username от юзера)
|
||||
```
|
||||
|
||||
## ⚡ Основные компоненты
|
||||
|
||||
### 1. UserbotParser (parser.py)
|
||||
|
||||
```python
|
||||
# Методы:
|
||||
await userbot_parser.initialize() # Инициализировать
|
||||
await userbot_parser.parse_group_info(cid) # Получить информацию
|
||||
await userbot_parser.parse_group_members() # Получить участников
|
||||
await userbot_parser.sync_group_to_db() # Синхронизировать в БД
|
||||
```
|
||||
|
||||
### 2. Celery Tasks (tasks.py)
|
||||
|
||||
```python
|
||||
# Задачи:
|
||||
initialize_userbot_task() # Инициализировать при старте
|
||||
parse_group_task(chat_id) # Парсить одну группу
|
||||
sync_all_groups_task() # Синхронизировать все
|
||||
parse_group_members_task(cid) # Парсить участников
|
||||
```
|
||||
|
||||
### 3. Database Models
|
||||
|
||||
```
|
||||
Group
|
||||
├── id (Primary Key)
|
||||
├── chat_id (Telegram ID)
|
||||
├── title
|
||||
├── description
|
||||
├── members_count
|
||||
├── is_active
|
||||
└── timestamps
|
||||
|
||||
GroupMember
|
||||
├── id (Primary Key)
|
||||
├── group_id (Foreign Key → Group)
|
||||
├── user_id (Telegram User ID)
|
||||
├── username
|
||||
├── first_name / last_name
|
||||
├── is_bot, is_admin, is_owner
|
||||
└── timestamps
|
||||
```
|
||||
|
||||
## 🔐 Безопасность
|
||||
|
||||
⚠️ **Важно!**
|
||||
|
||||
- ✅ Используйте **отдельный аккаунт Telegram** для UserBot
|
||||
- ✅ **Никогда** не делитесь сессионным файлом `sessions/userbot_session.session`
|
||||
- ✅ **Не коммитьте** API_ID и API_HASH в Git
|
||||
- ✅ Храните в `.env.local` (добавлено в .gitignore)
|
||||
|
||||
## 📈 Производительность
|
||||
|
||||
| Размер группы | Рекомендуемый limit | Celery workers |
|
||||
|---|---|---|
|
||||
| < 1K | 1000 | 1-2 |
|
||||
| 1K - 10K | 5000 | 2-4 |
|
||||
| > 10K | 10000 | 4-8 |
|
||||
|
||||
## 🛠 Troubleshooting
|
||||
|
||||
### "UserBot не авторизован"
|
||||
|
||||
```bash
|
||||
# Удалить старую сессию
|
||||
rm sessions/userbot_session.session
|
||||
|
||||
# Авторизироваться заново
|
||||
python userbot_service.py
|
||||
```
|
||||
|
||||
### "FloodWait 3600"
|
||||
|
||||
Это нормально - Telegram ограничивает быстрые запросы. Парсер автоматически ждет и продолжает.
|
||||
|
||||
### "Нет доступа к группе"
|
||||
|
||||
1. Убедитесь что UserBot добавлен в группу
|
||||
2. Дайте администраторские права если нужно
|
||||
|
||||
## 📝 Примеры
|
||||
|
||||
### Пример 1: Синхронизировать все группы по расписанию
|
||||
|
||||
```python
|
||||
# В celery_beat_schedule
|
||||
from celery.schedules import crontab
|
||||
|
||||
app.conf.beat_schedule = {
|
||||
'sync-all-groups-daily': {
|
||||
'task': 'app.userbot.tasks.sync_all_groups',
|
||||
'schedule': crontab(hour=0, minute=0), # Каждый день в 00:00
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Пример 2: Получить количество ботов в группе
|
||||
|
||||
```python
|
||||
from app.database.member_repository import GroupMemberRepository
|
||||
|
||||
async with AsyncSessionLocal() as session:
|
||||
repo = GroupMemberRepository(session)
|
||||
bot_count = await repo.get_bot_count(group_id=123)
|
||||
print(f"Ботов в группе: {bot_count}")
|
||||
```
|
||||
|
||||
### Пример 3: Найти членов по имени
|
||||
|
||||
```python
|
||||
members = await repo.search_members_by_name(group_id=123, keyword="John")
|
||||
for member in members:
|
||||
print(f"{member.first_name} {member.last_name} (@{member.username})")
|
||||
```
|
||||
|
||||
## 📚 Дополнительно
|
||||
|
||||
- Полная документация: [docs/USERBOT_MICROSERVICE.md](./USERBOT_MICROSERVICE.md)
|
||||
- Исходный код: [app/userbot/](../app/userbot/)
|
||||
- Логирование: `docker-compose logs -f userbot`
|
||||
|
||||
## ✅ Что реализовано
|
||||
|
||||
- ✅ Отдельный микросервис Telethon
|
||||
- ✅ Парсинг групп и участников
|
||||
- ✅ Сохранение в PostgreSQL
|
||||
- ✅ Celery интеграция
|
||||
- ✅ Flower мониторинг
|
||||
- ✅ Docker контейнер
|
||||
- ✅ Интеграция с основным ботом (`/sync_groups`)
|
||||
- ✅ Обработка ошибок и FloodWait
|
||||
- ✅ Полная документация
|
||||
|
||||
## 🎯 Следующие шаги
|
||||
|
||||
1. Авторизировать UserBot (python userbot_service.py)
|
||||
2. Собрать и запустить Docker (docker-compose up -d)
|
||||
3. Протестировать /sync_groups в Telegram боте
|
||||
4. Проверить данные в PostgreSQL
|
||||
5. Мониторить через Flower (http://localhost:5555)
|
||||
Reference in New Issue
Block a user