Skip to content

README.ru.md

Latest commit

 

History

History
434 lines (332 loc) · 16.6 KB

README.ru.md

File metadata and controls

434 lines (332 loc) · 16.6 KB

Парсер групп Telegram

Языки: English | Русский

Инструмент для поиска и фильтрации групп/каналов Telegram по ключевым словам и количеству участников.

Содержание

Русский

Возможности

  • Поиск групп/каналов Telegram по ключевым словам
  • Генерация комбинаций город+слово для комплексного регионального поиска
  • Автоматическое удаление дублирующихся поисковых запросов
  • Фильтрация результатов по минимальному количеству участников
  • Возобновление прерванных операций (отслеживание прогресса)
  • Ограничение скорости и защита от флуда
  • Раздельные процессы поиска и фильтрации для лучшей производительности

Настройка

  1. Установите зависимости:

    npm install telegram

  2. Создайте учетные данные Telegram API:

    • Перейдите на https://my.telegram.org/apps
    • Создайте новое приложение
    • Получите ваши API_ID и API_HASH

  3. Настройте окружение: Создайте файл .env:

    API_ID=ваш_api_id
API_HASH=ваш_api_hash
PHONE_NUMBER=+79001234567
TG_2FA=ваш_пароль_2fa  # Опционально, только если включена 2FA

  4. Подготовьте поисковые запросы: Создайте файл queries.txt с одним поисковым термином на строку:

    криптовалюта трейдинг
биткоин
эфириум
программирование
работа москва
фриланс

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

Командная строка

Шаг 1: Поиск групп

Вариант A: Обычный поиск

node parse.js

Вариант B: Поиск по комбинациям городов

node parse.js --cities

Другие опции:

node parse.js --reset-progress    # Сбросить прогресс поиска
node parse.js --help             # Показать справку

Это будет:

  • Автоматически удалять дубли из queries.txt, cities.txt и words.txt
  • Искать группы/каналы по ключевым словам из queries.txt (обычный режим) или по сгенерированным комбинациям (режим городов)
  • Сохранять результаты с количеством участников в groups.json
  • Отслеживать прогресс в processed_queries.json
  • Продолжать с места остановки при прерывании

Режим городов (--cities):

  • Генерирует все комбинации из cities.txt и words.txt
  • Создает файл queries_cities.txt с комбинациями типа "Москва работа", "Москва фриланс" и т.д.
  • Использует эти комбинации для поиска вместо queries.txt

Шаг 2: Извлечение ID групп (опционально)

node extract_ids.js                    # Извлечь ID с фильтрацией по участникам
node extract_ids.js --with-usernames   # Извлечь ID с username
node extract_ids.js --no-filter        # Извлечь все ID без фильтрации
node extract_ids.js --help             # Показать справку

Это будет:

  • Читать группы из groups.json
  • Фильтровать по минимальному количеству участников (из конфига)
  • Извлекать только ID групп (по одному на строку)
  • Сохранять в group_ids.txt

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

Отредактируйте config.json для настройки параметров:

{
  "search": {
    "queriesFile": "queries.txt",
    "limitPerQuery": 20,
    "saveFile": "groups.json",
    "processedQueriesFile": "processed_queries.json",
    "twoLevelParsing": {
      "enabled": true,
      "firstLevel": {
        "limitPerQuery": 100,
        "maxWords": 30
      },
      "secondLevel": {
        "limitPerQuery": 20,
        "useAllWords": true
      }
    }
  },
  "extract": {
    "inputFile": "groups.json",
    "outputFile": "group_ids.txt",
    "includeUsernames": false,
    "minParticipants": 1000,
    "filterByParticipants": true
  },
  "throttle": {
    "betweenQueriesMs": 3000,
    "betweenRequestsMs": 1200,
    "maxRetries": 3,
    "retryBackoffMultiplier": 2,
    "floodWaitCapSec": 900
  }
}

Описание параметров:

Поиск (search):

  • queriesFile - файл с ключевыми словами для поиска
  • limitPerQuery - максимальное количество результатов на запрос
  • saveFile - файл для сохранения всех найденных групп
  • processedQueriesFile - файл для отслеживания обработанных запросов
  • twoLevelParsing - настройки двухуровневого парсинга:
    • enabled - включить двухуровневый парсинг
    • firstLevel.limitPerQuery - лимит результатов для первого уровня (высокий)
    • firstLevel.maxWords - количество первых слов для первого уровня
    • secondLevel.limitPerQuery - лимит результатов для второго уровня (обычный)
    • secondLevel.useAllWords - использовать все слова для второго уровня

Извлечение ID (extract):

  • inputFile - входной файл с группами (по умолчанию groups.json)
  • outputFile - выходной файл с ID (по умолчанию group_ids.txt)
  • includeUsernames - добавлять ли @username после ID
  • minParticipants - минимальное количество участников для фильтрации
  • filterByParticipants - включить ли фильтрацию по участникам

Ограничения (throttle):

  • betweenQueriesMs - задержка между поисковыми запросами (мс)
  • betweenRequestsMs - задержка между API запросами (мс)
  • maxRetries - максимальное количество повторов при ошибке
  • retryBackoffMultiplier - множитель увеличения задержки при повторах
  • floodWaitCapSec - максимальное время ожидания при FLOOD_WAIT (сек)

🔄 Двухуровневый парсинг

Новая функция для более эффективного сбора данных в режиме городов:

Принцип работы:

  1. Первый уровень: Использует высокий лимит (100) для первых N слов (30)
  2. Второй уровень: Использует обычный лимит (20) для всех слов

Преимущества:

  • Больше результатов для популярных запросов
  • Экономия времени на менее популярных запросах
  • Гибкая настройка через конфигурацию

Пример:

  • 28 городов × 30 первых слов = 840 запросов с лимитом 100
  • 28 городов × 129 всех слов = 3612 запросов с лимитом 20
  • Итого: 4452 запроса вместо 3612 в обычном режиме

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

node test_two_level.js  # Проверить настройки двухуровневого парсинга

🌐 Веб-интерфейс

Современный веб-интерфейс для удобного управления:

Установка:

npm install                 # Установить зависимости
npm run server             # Запустить API сервер (порт 3001)
npm run dev                # Запустить React приложение (порт 3000)

Доступ: Откройте http://localhost:3000 в браузере

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

  • 🔍 Управление парсингом - Запуск/остановка с логами в реальном времени
  • 📋 Извлечение ID - Извлечение ID групп с настройками фильтрации
  • 📁 Управление файлами - Редактирование queries, cities, words файлов
  • ⚙️ Конфигурация - Управление всеми настройками включая двухуровневый парсинг
  • 📊 Статистика - Статистика в реальном времени с отслеживанием прогресса

Продакшен:

npm run build              # Сборка для продакшена
npm run preview            # Предпросмотр сборки

API Endpoints:

  • POST /api/parse - Запуск обычного парсинга
  • POST /api/parse-cities - Запуск парсинга городов
  • POST /api/extract - Извлечение ID с опциями
  • GET /api/files/:filename - Получить содержимое файла
  • PUT /api/files/:filename - Сохранить содержимое файла
  • GET /api/config - Получить конфигурацию
  • PUT /api/config - Сохранить конфигурацию
  • GET /api/stats - Получить статистику
  • ws://localhost:3001/ws - Логи в реальном времени через WebSocket

Сброс прогресса

node parse.js --reset-progress        # Сбросить прогресс поиска

Формат вывода

Группы сохраняются в формате JSON:

[
  {
    "id": "123456789",
    "title": "Название группы",
    "username": "username_группы",
    "type": "supergroup",
    "access_hash": "значение_хеша",
    "participants_count": 1500
  }
]

Типы групп:

  • group - обычная группа
  • supergroup - супергруппа
  • channel - канал

Файлы

Основные скрипты:

  • parse.js - Основной скрипт поиска
  • extract_ids.js - Скрипт извлечения ID с фильтрацией
  • test_two_level.js - Утилита тестирования двухуровневого парсинга

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

  • config.json - Основная конфигурация
  • .env - Переменные окружения (API ключи)

Файлы данных:

  • queries.txt - Ключевые слова для поиска (обычный режим)
  • cities.txt - Список городов (для режима --cities)
  • words.txt - Список слов (для режима --cities)
  • queries_cities.txt - Сгенерированные комбинации город+слово

Выходные файлы:

  • groups.json - Все найденные группы с количеством участников
  • group_ids.txt - Извлеченные ID групп (только ID)
  • processed_queries.json - Прогресс поиска
  • session.json - Сессия Telegram

Веб-интерфейс:

  • server.js - Express API сервер
  • src/ - Исходный код React приложения
  • index.html - HTML шаблон
  • vite.config.js - Конфигурация Vite
  • package.json - Зависимости и скрипты

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

Частые проблемы

  1. Ошибка "Password is empty"

    • Добавьте пароль 2FA в файл .env: TG_2FA=ваш_пароль
    • Или введите его при запросе скрипта

  2. Ошибки FLOOD_WAIT

    • Скрипт автоматически обрабатывает их и ждет нужное время
    • При необходимости увеличьте задержки в config.json

  3. Сессия истекла

    • Удалите файл session.json и запустите скрипт заново
    • Пройдите авторизацию повторно

  4. Группы не найдены

    • Проверьте поисковые термины в queries.txt
    • Попробуйте более общие или популярные ключевые слова
    • Убедитесь, что термины написаны правильно

  5. Ошибка "Account has 2FA enabled"

    • У вас включена двухфакторная аутентификация
    • Добавьте пароль 2FA в .env или введите при запросе

  6. Медленная работа

    • Это нормально из-за ограничений Telegram API
    • Не уменьшайте задержки слишком сильно, чтобы избежать блокировки
    • Используйте прогресс-файлы для возобновления работы

Рекомендации

  1. Для лучших результатов поиска:

    • Используйте разнообразные ключевые слова
    • Включайте синонимы и вариации написания
    • Добавляйте как русские, так и английские термины
    • Не беспокойтесь о дублях в queries.txt - они автоматически удаляются

  2. Для стабильной работы:

    • Не запускайте несколько экземпляров одновременно
    • Регулярно проверяйте логи на наличие ошибок
    • Делайте резервные копии результатов

  3. Для оптимизации:

    • Сначала запустите поиск с небольшим количеством запросов
    • Настройте параметры фильтрации под ваши нужды
    • Используйте разные минимальные значения участников для разных целей

Примеры использования

Поиск криптовалютных групп

# queries.txt
криптовалюта
биткоин
ethereum
трейдинг
блокчейн
DeFi
NFT

# config.json - увеличиваем минимум участников
"minParticipants": 5000

Поиск рабочих чатов

Обычный режим:

# queries.txt
работа москва
вакансии
фриланс
удаленная работа
программист
дизайнер

# config.json - уменьшаем минимум участников
"minParticipants": 500

Режим городов (рекомендуется):

# cities.txt
Москва
Санкт-Петербург
Казань
Новосибирск

# words.txt
работа
вакансии
фриланс
программист
дизайнер

# Запуск
node parse.js --cities

Поиск образовательных каналов

# queries.txt
программирование
python
javascript
курсы
обучение
IT

# config.json
"minParticipants": 1000