Skip to content

README.md

Latest commit

 

History

History
83 lines (58 loc) · 6.29 KB

README.md

File metadata and controls

83 lines (58 loc) · 6.29 KB

Buzz Buster

Бот для Telegram, предназначенный для ловли определенного типа спама в группах. Принцип действия: первое сообщение от пользователя после присоединения его к группе отправляется на проверку в GPT, если бездушная машина определяет наличие спама - пользователь блокируется во всех группах, где включен бот.

Возможности

  • Автоматическое обнаружение и удаление спама по астраиваемым критериям
  • Легкость установки и использования
  • Автоматическая обработка миграции групп в супергруппы (смена chat_id). При миграции бот автоматически обновляет идентификатор и продолжает работу без потери данных.

Установка

  1. Клонируйте репозиторий:

    git clone https://github.com/insoln/buzz_buster
cd buzz_buster

  2. Настройте переменные окружения. Создайте файл .env и пропишите там необходимые переменные:

    cp .env.example .env
    # Telegram Bot
TELEGRAM_API_KEY=your_telegram_api_key      # Токен бота (из @BotFather)

# OpenAI
OPENAI_API_KEY=your_openai_api_key          # OpenAI API-ключ

# Telegram Admin
ADMIN_TELEGRAM_ID=your_admin_telegram_id    # Telegram ID администратора бота

# Status Logging
STATUSCHAT_TELEGRAM_ID=your_logs_chat_id    # Telegram ID чата для логов

# Критерии спама
INSTRUCTIONS_DEFAULT_TEXT=Любые спам-признаки.

    Данные бота хранятся в базе MySQL, которая поднимается в параллельном контейнере. При желании можно использовать внешний сервер MySQL, тогда в .env нужно раскомментировать соответствующие строки, а в docker-compose.yml, наоборот, закомментировать

  3. Запустите docker:

    docker compose up --build -d

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

  1. Добавьте бота в вашу группу Telegram

  2. Предоставьте ему права администратор (как минимум права на удаление сообщений и бан пользователей)

  3. Выполните команду /start, чтобы бот начал защищать группу от спама

  4. Если стандартные критерии проверки на спам не подходят для конкретной группы (например, в группе активно обсуждается быстрый заработок, и сообщение с подобным контекстом не должно восприниматься как спам), можно задать кастомные критерии командой /set instructions <новые критерии>

    /set instructions Текст содержит гомоглифические подстановки или больше 5 следующих подряд эмодзи.

Как развернуть бота для разработки?

Бот разработан в среде VS Code. Папка .devcontainer позволяет использовать расширение, которое развернет для разработки отдельный контейнер и откроет окно, в котором можно дебажить код.

Шаги для развертывания:

  1. Установите Visual Studio Code.
  2. Установите Remote - Containers расширение для VS Code.
  3. Откройте проект в VS Code.
  4. Нажмите F1, введите Dev Containers: Open Folder in Container... и выберите текущую папку проекта.
  5. Дождитесь, пока контейнер будет развернут и запущен. Может понадобиться несколько секунд на то, чтобы все расширения корректно установились в контейнер.

Как получить поддержку?

Если у вас возникли проблемы или вопросы, откройте issue на GitHub. Пуллреквесты приветствуются.

Примечание о миграции групп в супергруппы

Telegram при апгрейде обычной группы в супергруппу меняет её идентификатор (обычно появляется префикс -100). Если во время отправки сообщения возникает исключение ChatMigrated, бот фиксирует новое значение chat_id во всех связанных таблицах (groups, group_settings, user_entries) и повторяет отправку. Вам не нужно предпринимать дополнительных действий; журнал содержит запись вида:

ChatMigrated detected for chat_id=OLD_ID -> new_id=NEW_ID. Updating persistence and retrying send.
Persisted migration old_group_id=OLD_ID -> new_group_id=NEW_ID in database.

Если миграция произошла до старта контейнера и вы видите ошибки отправки стартового уведомления, просто выполните любое действие (сообщение или команду) в новой супергруппе — бот обновит идентификатор при первой попытке отправить сообщение.