TG-Invite-Machine

Асинхронная система распределенного сбора аудитории и инвайтинга в Telegram на базе Telethon и Aiogram 3 с изолированным пулом рабочих сессий.

Статус: версия v0.2.0-stable. Кодовая база покрыта набором из 90 автоматизированных тестов. Вопросы по развертыванию или предложения можно отправлять в личные сообщения или открывать в issues.

Important

ДИСКЛЕЙМЕР / DISCLAIMER: Данный программный комплекс разработан исключительно в образовательных целях, для исследования протокола MTProto и тестирования асинхронной архитектуры. Автор и разработчики не несут ответственности за любые последствия использования данного ПО, включая блокировки аккаунтов Telegram, ограничения каналов или нарушение правил платформы (Telegram Terms of Service). Все действия осуществляются конечным пользователем исключительно на свой страх и риск.

---

Контакты

• Личные сообщения в Telegram: https://t.me/ivanchikbyte
• Канал проекта: https://t.me/ivanchik_byte

---

Содержание

1. Возможности
2. Технологический стек
3. Архитектура и схема работы
4. Требования к окружению
5. Установка и запуск
6. Инструкция по работе с ботом
7. Переменные окружения (.env)
8. Тестирование
9. Надежность базы данных
10. Дополнительная документация
11. Отказ от ответственности (Disclaimer)
12. Лицензия

---

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

Управление пулом сессий | Выбор лимитов и задержек | Сбор и дедупликация аудитории | Результат инвайтинга

---

Возможности

• Управление прокси и сетевая изоляция:

  • Поддержка форматов ip:port:user:pass, socks5://user:pass@ip:port, а также IPv6 адресов вида [host]:port.
  • Дедупликация прокси по составному ключу endpoint (host, port, protocol, username) с дешифрованием паролей для исключения повторных вставок и фильтрацией повторов внутри пакета.
  • Автоматическая реактивация отключенных прокси при повторной загрузке или обновлении пароля.
  • Параллельная валидация пула прокси по TCP через asyncio.Semaphore(10) и asyncio.as_completed с прямым зондированием точки Telegram DC2 (149.154.175.54:443).
  • Автоматическое распределение свободных прокси по активным сессиям (кнопка в интерфейсе и автоназначение при старте инвайтинга).
  • Строгая изоляция трафика Zero-Leak (REQUIRE_STRICT_PROXIES): операция прерывается с ошибкой при недоступности прокси, предотвращая выход с прямого IP сервера.
  • Шифрование учетных данных в базе: сессионные токены и пароли защищены симметричным алгоритмом Fernet (AES-128-CBC + HMAC-SHA256).

• Импорт сессий, 2FA и управление пулом:

  • Конвертация TData (.zip) через библиотеку opentele2 с правильной привязкой DC и использованием проектных TELEGRAM_API_ID / TELEGRAM_API_HASH.
  • Защита от атак через архивы: проверка канонических путей, лимит распаковки 150 МБ и до 2000 файлов, отклонение символических ссылок.
  • Загрузка одиночных файлов .session с оперативной проверкой авторизации.
  • Поддержка облачных паролей (2FA): диалоговый запрос пароля, мгновенное удаление сообщения пользователя из чата Telegram и сохранение зашифрованного токена.
  • Пакетный импорт: загрузка ZIP-архива с папками сессий и общим файлом proxies.txt для автоматического связывания.
  • Двухколоночная интерактивная сетка аккаунтов (2-Column Grid UI) с бейджами статусов ([OK P#], [CD], [SKIP], [NO PRX]), постраничной навигацией и возможностью исключения воркеров из кампании в один клик.

• Предстартовая настройка и контроль задач:

  • Два специализированных режима работы (Dual Modes):
    • Безопасная карусель (Safe Carousel): дрип-инвайтинг с увеличенными органическими паузами (1-3 мин) и автоматической фильтрацией только недавно активной аудитории для максимальной долговечности рабочих сессий.
    • Целевой план (Target Plan): жесткая остановка строго по достижению целевого числа успешных инвайтов (successful_invites == max_invites) независимо от промежуточных приватных ограничений.
  • Централизованный менеджер задач InviteTaskManager: единый владелец фонового процесса, корректная отмена задач и сохранение дескриптора до завершения цикла без гонок состояния.
  • Выделенный модуль системной консоли (app/bot/dashboard.py): разделение логики формирования дашборда и обработчиков меню для чистоты архитектуры.
  • Выбор лимита пользователей через чипы: [ 5 ], [ 10 ], [ 20 ], [ 50 ], [ Все ] или ввод произвольного числа.
  • Предустановленные профили задержек:
    • Осторожный: 50-110 секунд, минимальная нагрузка для свежих номеров.
    • Обычный: 35-75 секунд, стандартный баланс скорости и надежности.
    • Быстрый: 17-37 секунд, для прогретых аккаунтов.
    • Кастомный интервал: произвольный диапазон секунд (custom:min:max), включая режим без задержки 0:0.
  • Возобновление остановленных или приостановленных задач по ID из базы данных (invite_resume_paused_{id}).
  • Мгновенный сброс суточных лимитов инвайтов по кнопке на главном экране и в меню параметров.

• Инвайтинг и алгоритмы защиты от блокировок:

  • Честная карусель воркеров (Fair Worker Carousel): выбор сессий упорядочен по Account.last_attempt_at.asc().nullsfirst() с безусловной фиксацией времени попытки, исключая залипание на одном номере при приватных ошибках.
  • Снимок активности аудитории (Activity Snapshot): фиксация времени последней активности last_seen_at в AudienceMember на основе статусов UserStatusOnline и UserStatusRecently при парсинге, что позволяет локально фильтровать свежую аудиторию без дополнительных тяжелых RPC-запросов.
  • Предварительная синхронизация (Pre-Sync): автоматический опрос участников целевого чата перед запуском для исключения лишних попыток добавления уже состоящих пользователей.
  • Настраиваемый блэклист приватности: пропуск пользователей с закрытым инвайтом по глобальной истории AudienceHistory.
  • Сохранение очереди пользователей: при временных флуд-ограничениях (FloodWait, PeerFlood) или бане аккаунта целевой пользователь не удаляется из очереди и остается в статусе pending.
  • Автоматическое ожидание PeerFlood: пауза на 5 минут (PEER_FLOOD_COOLDOWN_MINUTES) с обратным отсчетом в реальном времени и автоматическим возобновлением инвайтинга без вмешательства оператора.
  • Сброс счетчика Circuit Breaker при каждом успешном инвайте для исключения ложных пауз на редких единичных задержках.
  • Тримодальная модель джиттера: 25% быстрых действий, 60% действий в среднем темпе и 15% долгих пауз для эмуляции поведения человека.
  • Предпросмотр чата (Pre-invite): выставление онлайн-статуса, листание 2-4 публикаций и отправка отметки прочтения перед добавлением.
  • Автомиграция чатов: при выборе обычной группы бот предлагает мигрировать ее в супергруппу через MigrateChatRequest.

• Сбор аудитории (Collector):

  • Сбор активных участников: выгрузка авторов сообщений за последние 1-30 дней из открытых чатов или комментариев каналов.
  • Сбор всех участников: алфавитная итерация по списку пользователей для обхода системного лимита Telegram в 10 000 контактов.
  • Сохранение снимка онлайн-активности участников (last_seen_at) для последующей умной фильтрации во время кампании.
  • Потоковая выгрузка базы: порционная запись файла по 1000 записей без избыточного расхода оперативной памяти.
  • Дедупликация: отсев ботов, удаленных аккаунтов и дубликатов на уровне ограничений базы данных.

• Аудит и аналитика:

  • Автоматическая пакетная проверка пула аккаунтов через официального @SpamBot с обработкой FloodWait и детекцией отозванных сессий.
  • Выгрузка отчетов о состоянии базы и сессий в формате Excel (.xlsx) через неблокирующий поток asyncio.to_thread.

---

Технологический стек

• Язык разработки: Python 3.12+
• Бот управления (Control Plane): aiogram 3.x (асинхронный роутинг, FSM, middleware)
• MTProto движок (Data Plane): Telethon 1.45+ (асинхронный клиент, управление сессиями)
• Конвертер TData: opentele2
• База данных: SQLAlchemy 2.0 Async (aiosqlite по умолчанию, полная совместимость с asyncpg / PostgreSQL)
• Криптография: Cryptography (Fernet)
• Экспорт данных: openpyxl
• Контейнеризация: Docker и Docker Compose

---

Архитектура и схема работы

Управление системой изолировано от сетевых вызовов MTProto:

flowchart TD
    subgraph ControlPlane["Control Plane (aiogram 3)"]
        ADMIN["Администратор"]
        BOT["Бот управления"]
        FSM["FSM диалоги (лимиты и паузы)"]
    end

    subgraph DataStorage["Хранилище данных"]
        DB[("SQLite WAL / PostgreSQL")]
        VAULT["Fernet Cryptography"]
    end

    subgraph WorkerPlane["Data Plane (Telethon MTProto)"]
        MANAGER["Task Manager & Orchestrator"]
        W1["Worker 1 (SOCKS5 Прокси A)"]
        W2["Worker 2 (SOCKS5 Прокси B)"]
        WN["Worker N (SOCKS5 Прокси N)"]
    end

    subgraph TelegramCloud["Telegram API"]
        SRC["Группы-доноры (парсинг)"]
        CHECK["@SpamBot (аудит)"]
        DST["Целевой канал / Супергруппа"]
    end

    ADMIN --> BOT
    BOT --> FSM
    FSM --> MANAGER
    MANAGER --> DB
    VAULT <--> DB
    MANAGER --> W1
    MANAGER --> W2
    MANAGER --> WN
    W1 -->|Сбор участников| SRC
    W2 -->|Проверка спам-блока| CHECK
    WN -->|Инвайтинг с предпросмотром| DST

Loading

Подробное техническое описание компонентов и последовательности вызовов приведено в docs/ARCHITECTURE.md.

---

Требования к окружению

• Операционная система: Linux (Ubuntu 22.04+, Debian 12+), macOS или Windows (WSL2).
• Оперативная память: от 512 МБ RAM.
• Установленный Docker и Docker Compose V2, либо Python 3.12+.
• Учетные данные приложения Telegram (api_id и api_hash с my.telegram.org).
• Токен бота от @BotFather.

---

Установка и запуск

1. Клонирование и настройка конфигурации

git clone https://github.com/ivanchik-byte/tg-invite-machine.git
cd tg-invite-machine
cp .env.example .env

# Сгенерируйте секретный ключ Fernet для шифрования данных
python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

Заполните значения в созданном файле .env.

2. Запуск через Docker Compose (Linux / macOS)

docker compose up -d --build

Просмотр логов:

docker compose logs -f

3. Запуск через Docker на Windows (Docker Desktop)

1. Установите Docker Desktop для Windows (убедитесь, что включен бэкенд WSL 2 в настройках Docker Desktop).
2. Запустите Docker Desktop и дождитесь статуса Engine running.
3. Откройте PowerShell или Терминал Windows в папке проекта:

# Клонирование репозитория (если еще не склонирован)
git clone https://github.com/ivanchik-byte/tg-invite-machine.git
cd tg-invite-machine

# Создание файла конфигурации
Copy-Item .env.example .env

# Генерация ключа Fernet через Python (или любой установленный Python)
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

4. Откройте файл .env в блокноте или редакторе кода (notepad .env), укажите ваш BOT_TOKEN, ADMIN_ID, TELEGRAM_API_ID, TELEGRAM_API_HASH и вставьте сгенерированный ключ ENCRYPTION_KEY.
5. Соберите и запустите контейнер:

docker compose up -d --build

6. Для отслеживания логов выполните:

docker compose logs -f

7. Для остановки сервиса:

docker compose down

4. Локальный запуск без Docker

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

Детальное руководство по всем шагам установки находится в файле INSTALL.md.

---

Инструкция по работе с ботом

После запуска отправьте команду /start вашему боту с аккаунта администратора (ADMIN_ID).

1. Добавление прокси:

   • Перейдите в раздел Прокси -> Добавить прокси.
   • Отправьте прокси в формате ip:port:user:pass или socks5://user:pass@ip:port.
   • Система автоматически выполнит проверку TCP-соединения.

2. Загрузка аккаунтов:

   • Перейдите в раздел Аккаунты -> Загрузить TData / Session.
   • Отправьте .zip архив с папкой tdata или файл .session.
   • Если на номере включен облачный пароль (2FA), введите его в ответном сообщении. Бот автоматически сотрет ваше сообщение из чата для безопасности.

3. Сбор аудитории:

   • Перейдите в раздел Сбор аудитории.
   • Укажите ссылку на открытый чат или группу с комментариями канала.
   • Выберите режим: сбор активных пользователей (авторы сообщений за последние N дней) или сбор всех участников.
   • По завершении бот сохранит пользователей в базу и пришлет .txt файл.

4. Запуск инвайтинга:

   • Перейдите в раздел Инвайтер -> Запустить.
   • Отправьте ссылку на целевой канал или супергруппу.
   • В открывшемся меню параметров выберите лимит участников ([ 5 ], [ 10 ], [ 20 ], [ 50 ], [ Все ] или введите свой), а также скоростной режим или интервал в секундах.
   • Нажмите Запустить инвайтинг. Ход выполнения и статистика отображаются в реальном времени.

---

Переменные окружения (.env)

Параметр	Тип	По умолчанию	Описание
BOT_TOKEN	string	-	Токен Telegram-бота управления
ADMIN_ID	int	-	Telegram ID администратора (доступ к боту строго ограничен)
TELEGRAM_API_ID	int	-	API ID приложения с my.telegram.org
TELEGRAM_API_HASH	string	-	API Hash приложения с my.telegram.org
ENCRYPTION_KEY	string	-	32-байтный base64 ключ Fernet
DATABASE_URL	string	sqlite+aiosqlite:///data/inviter.db	Строка подключения к базе данных
DEFAULT_SPEED_PROFILE	string	normal	Профиль скорости: cautious, normal, fast
MIN_DELAY_BETWEEN_INVITES	int	30	Нижняя граница базовой задержки (сек)
MAX_DELAY_BETWEEN_INVITES	int	60	Верхняя граница базовой задержки (сек)
MAX_INVITES_PER_SESSION_DAILY	int	20	Дневной лимит успешных инвайтов на сессию
CIRCUIT_BREAKER_FLOOD_THRESHOLD	int	3	Порог ошибок для защитной паузы
PEER_FLOOD_COOLDOWN_MINUTES	int	5	Длительность паузы при временном PeerFlood (в минутах)
REQUIRE_STRICT_PROXIES	bool	true	Запрет работы без активного прокси (Zero-Leak)

---

Тестирование

Кодовая база покрыта набором из 90 автоматизированных тестов:

• Шифрование и дешифрование сессий и 2FA паролей (Fernet).
• Честная карусель воркеров: ротация пула по last_attempt_at без залипаний.
• Фильтрация свежей аудитории по снимку активности (last_seen_at).
• Режимы инвайтинга: Безопасная карусель и Целевой план с учетом промежуточных отказов.
• Двухколоночная интерактивная сетка аккаунтов и исключение воркеров из кампании.
• Остановка инвайтинга строго по достижении max_invites.
• Расчет тримодальных задержек и кастомных диапазонов custom:min:max.
• Алгоритм Circuit Breaker и эмуляция органического чтения (Pre-invite).
• Парсинг прокси, валидация по Telegram DC2 и защита от утечки IP адреса (Zero-Leak).
• Дедупликация прокси по endpoint-четверкам и внутрипакетная фильтрация повторов.
• Централизованный контроль жизненного цикла задач в InviteTaskManager и корректная отмена.
• Сохранение целевых пользователей в очереди при флуд-ошибках.
• Потоковая выгрузка базы аудитории и защита архивов (лимит файлов и объема).
• FSM диалоги, построение инлайн-клавиатур и реэкспорт функций дашборда.

Запуск тестового набора:

./venv/bin/pytest -W error

Результат:

============================== 90 passed in 7.44s ==============================

---

Надежность базы данных

По умолчанию система использует SQLite через драйвер aiosqlite. Для исключения ошибок блокировки файла при параллельной работе инвайтера, парсера и бота управления настроены следующие параметры:

1. Режим журнала WAL (PRAGMA journal_mode=WAL;). Запись не блокирует одновременное чтение.
2. Синхронизация NORMAL (PRAGMA synchronous=NORMAL;). Снижает нагрузку на диск без риска повреждения базы данных.
3. Таймаут ожидания блокировки 15 секунд (connect_args={"timeout": 15}).
4. Индексы по статусам задач, участникам и датам отлежки.

Для высоконагруженных окружений поддерживается подключение к PostgreSQL через изменение параметра DATABASE_URL.

---

Дополнительная документация

• docs/ARCHITECTURE.md: подробное техническое описание архитектуры, конвейеров данных и моделей БД.
• INSTALL.md: пошаговое руководство по установке и настройке.
• SECURITY.md: политика безопасности, Zero-Leak модель и правила сообщения об уязвимостях.

---

Отказ от ответственности (Disclaimer)

Данное программное обеспечение разработано исключительно в ознакомительных, научно-исследовательских и образовательных целях для демонстрации реализации сетевых протоколов (MTProto) и отказоустойчивой асинхронной архитектуры на Python.

• Использование только для тестов: Проект предназначен для тестирования на собственных тестовых стендах, каналах и контролируемых тестовых аккаунтах.
• Отсутствие гарантий: Программный код предоставляется по принципу "AS IS" ("КАК ЕСТЬ"), без каких-либо явных или подразумеваемых гарантий безошибочности, надежности или пригодности для определенных сценариев.
• Ограничение ответственности: Автор, контрибьюторы и лица, связанные с разработкой, ни при каких обстоятельствах не несут ответственности за любые прямые, косвенные или случайные последствия использования или невозможности использования данного ПО. Это включает, но не ограничивается:
  • Временные или постоянные ограничения и блокировки учетных записей Telegram (PeerFlood, FloodWait, SpamBot restrictions, удаление номеров).
  • Ограничение видимости, принудительное удаление или наложение фильтров на каналы, чаты и группы.
  • Потерю данных, утечку сессий при некорректном хранении или финансовые издержки.
• Соблюдение правил платформы: Пользователь несет единоличную и полную персональную ответственность за соблюдение Пользовательского соглашения Telegram (Telegram Terms of Service), спам-политики сервиса и законов своей страны.
• Использование на свой страх и риск: Любые действия по импорту сессий, отправке запросов через MTProto и управлению контактами выполняются вами исключительно под вашу личную ответственность.

---

Лицензия

MIT License. Исходный код предоставлен в образовательных и исследовательских целях.