TG_autoposter/docs/USERBOT_QUICKSTART.md

Telethon UserBot Microservice - Краткая инструкция

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

1. Подготовка конфигурации

Добавьте в .env:

# 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. Первый запуск (Авторизация)

# Запустить интерактивно для авторизации
python userbot_service.py

# Следовать инструкциям - введите SMS код когда придет
# Сессия сохранится в sessions/userbot_session.session

3. Запуск в Docker

# Пересобрать все контейнеры
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 задачи

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)

# Методы:
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)

# Задачи:
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 не авторизован"

# Удалить старую сессию
rm sessions/userbot_session.session

# Авторизироваться заново
python userbot_service.py

"FloodWait 3600"

Это нормально - Telegram ограничивает быстрые запросы. Парсер автоматически ждет и продолжает.

"Нет доступа к группе"

1. Убедитесь что UserBot добавлен в группу
2. Дайте администраторские права если нужно

📝 Примеры

Пример 1: Синхронизировать все группы по расписанию

# В 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: Получить количество ботов в группе

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: Найти членов по имени

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
• Исходный код: 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)