8000 GitHub - momai/ClubDoorman: Telegram anti-spam bot · GitHub
[go: up one dir, main page]

Skip to content

About

Telegram anti-spam bot

Resources

Stars

8 stars

Watchers

0 watching

Forks

 
 

Latest commit

 

History

941 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
8000
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Антиспам-бот для Telegram групп с многоуровневой системой защиты. Форк ClubDoorman, адаптированный для открытых общественных чатов.

🚀 Готовое решение

Для русскоязычных чатов

Воспользуйтесь готовым решением — форк ClubDoorman, всегда актуальный и поддерживаемый:

👉 @gate_troitsk_bot — просто добавьте в свой чат, всё работает из коробки.

  • Всегда актуальная версия, поддержка.
  • Бот не требует настроек и команд — всё работает автоматически.
  • Просто добавьте бота — остальное он сделает сам.
  • Простая и необязательная инструкция
  • Связь: @momai

Что нового

  • Надёжное хранение доверенных пользователей в JSON
  • Бан по длине имени (>40 символов временный, >75 постоянный)
  • Авто-удаление сервисных сообщений о банах
  • Оптимизированная обработка новых участников, автоматическая блокировка по спам-листу https://lols.bot/, без показа капчи.

Функции

  • Капча с эмодзи при входе
  • Проверка по базе спамеров
  • ML-фильтрация подозрительных сообщений
  • Система доверия (после 3 обычных сообщений)

Установка

  • DOORMAN_BOT_API: Токен бота (обязательно)
  • DOORMAN_ADMIN_CHAT: ID админ-чата (обязательно)
  • Остальные настройки опциональны

Антиспам для телеграма

Изначально разрабатывался чтобы решить проблему со спамерами в чатах Вастрик.Клуба, но может использоваться и в чатах других форков, да и просто в любых больших чатах.

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

  • Пользователи Клуба с привязанным ботом автоматически добавляются в доверенные
  • При эвенте "пользователь вошёл в чат" выдаётся простенькая капча
  • Если пользователь уже в доверенных, то все проверки пропускаются
  • Если пользователь в известных списках спамеров - нафиг
  • Если в сообщении многовато эмодзи - нафиг
  • Если в сообщении есть слова, которые маскируются под русские но имеют английские буквы внутри - нафиг. Именно этот аспект сейчас затюнен в основном на русскоязычные чаты и может сработать на нормальные слова из языков которые пишутся кириллицей, но пока что все известные кейсы добавлены в тесты.
  • Если в сообщении есть стоп-слова типа "заработок в сети" - нафиг
  • Дальше сообщение очищается от эмодзи, пунктуации, диакритиков и скармливается ML. Если ML считает что спам - нафиг.
  • Если пользователь написал несколько нормальных сообщений, он добавляется в доверенные - спамеры крайне редко "втираются в доверие" и обычно выдают всё первым-вторым сообщением
  • Автоматически бот только удаляет сообщения, банятся пользователи только вручную из админки чтобы снизить урон ложнопозитивных срабатываний
    • Кроме блеклиста. Такие банятся сразу, но это можно выключить
  • Если кого-то в чате забанил не бот, в админку приходит уведомление, возможно бот пропустил спам и его стоит добавить в датасет

Команды админки

Все команды вызываются реплаем на другое сообщение

  • /spam - добавляет сообщение в датасет спама
  • /ham - добавляет сообщение в датасет не-спама
  • /check - прогоняет сообщение через все проверки

Конфиг

Создаём чат-админку, запоминаем ID. Переменные среды:

  • DOORMAN_BOT_API: Токен телеграм бота. Обязательно
  • DOORMAN_ADMIN_CHAT: ID чата админки. Обязательно
  • DOORMAN_CLUB_SERVICE_TOKEN: Сервис токен для Клуба, создаётся тут: https://vas3k.club/apps/. Если переменная не задана, автоматический аппрув людей из Клуба пропускается.
  • DOORMAN_CLUB_URL: Базовый URL для форков Клуба, например https://rationalanswer.club/
  • DOORMAN_BLACKLIST_AUTOBAN_DISABLE: Установить в true или 1 чтобы бот не банил людей (не из Клуба, не approved, из блеклиста) при заходе сразу
  • DOORMAN_LOW_CONFIDENCE_HAM_ENABLE: Установить в true или 1 чтобы отсылать в админку не-спам который имеет низкий конфиденс скор, полезно для чатов где спамеры постоянно проверяют качество ML на прочность
  • DOORMAN_CHANNELS_AUTOBAN_DISABLE: Установить в true или 1 чтобы бот не банил сообщения от имени каналов (кроме тех, которые привязаны к текущей группе)
  • DOORMAN_APPROVE_BUTTON: Установить в true или 1 чтобы к каждому удалённому сообщению добавлялась опция "это свой, знакомый, завсегдатай"
  • DOORMAN_LOOKALIKE_AUTOBAN_DISABLE: Установить в true или 1 чтобы бот не банил сообщения где есть слова, маскируюиеся под русские

Спасибо

Translation

If you're willing to do the heavy lifting of translating all the text of this bot to other languages, please let me know first before running headfirst and creating a PR.

Воспользуйтесь готовым ботом — просто добавьте в свой чат:

👉 @gate_troitsk_bot

Особенности:

  • ✅ Работает из коробки без настроек
  • ✅ Всегда актуальная версия
  • ✅ Поддержка и обновления
  • ✅ Подробная инструкция
  • 📞 Связь: @momai

🛡️ Как работает защита

Бот использует пошаговый алгоритм проверки новых участников:

1. Тихий бан по блэклисту

  • Проверка новых участников через архив спамеров lols.bot
  • Автоматическая блокировка на 4 часа при обнаружении в списке
  • Блокировка пользователей с именами длиннее 75 символов
  • Всё происходит в тихом режиме без уведомлений

2. Капча при входе

  • Простая капча с эмодзи для новых участников
  • 60 секунд на решение
  • Временный бан на 20 минут при неудаче
  • Приветственное сообщение после успешного прохождения

3. Умный антиспам

  • Анализ первых сообщений пользователя
  • Поиск спам-паттернов и маскировки через похожие символы
  • Детект рекламы и подозрительных ссылок
  • Удаление сообщений с перебором эмодзи
  • Три сценария: пропуск, спорное сообщение, удаление

4. LLM анализ

  • Анализ профиля и фото с помощью Gemini 2.5 Flash
  • Автоматическое определение подозрительных аккаунтов
  • Read-only режим на 10 минут для спорных случаев

5. Система доверия

  • Пользователь попадает в доверенные после трёх обычных сообщений
  • Доверенные пользователи не проходят анализ сообщений

6. Каскадный режим

  • при проходе сообщений через фильтры, бот может запросить финальное решение о автоматическом действии у AI, что позволяет сократить ручные действия в админке бота.

⚙️ Установка и настройка

Переменные окружения

Обязательные:

  • DOORMAN_BOT_API - токен Telegram бота
  • DOORMAN_ADMIN_CHAT - ID админ-чата

Опциональные:

  • DOORMAN_CLUB_SERVICE_TOKEN - сервис токен для Клуба
  • DOORMAN_CLUB_URL - базовый URL для форков Клуба
  • DOORMAN_BLACKLIST_AUTOBAN_DISABLE - отключить авто-бан по блэклисту
  • DOORMAN_LOW_CONFIDENCE_HAM_ENABLE - отправлять в админку не-спам с низким конфиденсом
  • DOORMAN_CHANNELS_AUTOBAN_DISABLE - отключить бан сообщений от каналов
  • DOORMAN_APPROVE_BUTTON - добавить кнопку "это свой" к удалённым сообщениям
  • DOORMAN_LOOKALIKE_AUTOBAN_DISABLE - отключить бан маскирующихся слов

Docker Compose

version: '3'
services:
  doorman:
    image: ghcr.io/momai/clubdoorman:latest
    restart: always
    volumes:
      - ./data:/app/data
    environment:
      - DOORMAN_BOT_API=1234567890:AAAA-YOUR-TOKEN-HERE
      - DOORMAN_ADMIN_CHAT=-1001234567890

🎯 Команды админки

Все команды вызываются ответом на сообщение:

  • /spam - добавить сообщение в датасет спама
  • /ham - добавить сообщение в датасет не-спама
  • /check - проверить сообщение через все фильтры

🧪 Опыт использования

В первый день бот может показаться строгим к новичкам, но это временно. После написания 3 обычных сообщений пользователи попадают в доверенные, и фильтрация прекращается.

Важно понимать:

  • Бот не банит пользователей за сообщения, только удаляет подозрительные
  • Ложные срабатывания отслеживаются и исправляются
  • Алгоритмы регулярно обновляются
  • Автоматически банятся только пользователи из блэклистов

🔗 Ссылки

🙏 Благодарности

  • lols.bot - за борьбу со спамерами и API для бан-листов
  • github.com/umputun/tg-spam - за идеи и датасет
  • @kpblcaoo - за покрытие кода тестами и огромную помощь в рефакторинге

Создано для местных сообществ, но теперь используется в различных типах групп.

Golden Master / Early-path semantics (hardening 2025 Q3)

Часть инфраструктуры качества — Golden Master baseline — получила расширение: добавлены явные RuleCode для ранних веток (до основного анализа): Phase1 PrivateSkip, NewMembers, LeftMemberCleanup, ChannelMessage; Phase2 системные / fast-path / AI ветки: SystemNoUser, BotMessage, CaptchaPending, AlreadyApproved, ClubMemberSkip, AiProfileRestricted, ModeratedGeneric + уточнены semantics для /command и banlist. Это убрало временные overrides и делает регрессии более заметными. Полная документация: ClubDoorman.Baseline/usage.md (секция Semantics).

About

Telegram anti-spam bot

Resources

Stars

8 stars

Watchers

0 watching

Forks

Releases

Used by

Contributors

Languages

0