СТАНКИН Анти-Спам

О проекте

Система модерации Telegram-групп, которая автоматически обнаруживает и блокирует спам-сообщения. Проект разработан для университетских чатов, но применим в любых Telegram-сообществах.

Система анализирует каждое сообщение через BERT-классификатор, проверяет отправителя по внешним базам данных спамеров (CAS, LOLS) и при необходимости дополняет анализ через ChatGPT. Результаты модерации доступны через веб-панель с управлением настройками, просмотром журнала спама и списка ограниченных пользователей.

Возможности

• ML-детекция спама — BERT-классификатор (ruBERT-tiny2) с настраиваемыми порогами уверенности.
• Внешние проверки — интеграция с CAS (Combot Anti-Spam) и LOLS (List of Lame Spammers).
• ChatGPT-анализ — опциональная дополнительная проверка через OpenAI API для серой зоны.
• Веб-панель управления — FastAPI-приложение с авторизацией, управлением настройками и журналами.
• Per-chat настройки — индивидуальные пороги и проверки для каждого чата.
• Автообнаружение чатов — автоматический поиск групп, где бот является администратором.
• Уведомления — отправка алертов о спаме в чат управления с inline-кнопками.
• Резервное копирование — автоматические бэкапы БД через pg_dump с отправкой в Telegram.
• Мониторинг ошибок — интеграция с Sentry для трекинга исключений и логирования.
• Контейнеризация — Docker-образ с многостадийной сборкой, готовый к deploy через docker-compose.

Технологии

• Backend — Python 3.14+, aiogram 3.x, FastAPI, uvicorn.
• База данных — PostgreSQL, asyncpg.
• ML — transformers, ONNX Runtime, tokenizers.
• Фронтенд — TypeScript, SCSS, Tailwind CSS.
• Инфраструктура — Docker, Sentry.
• Внешние API — Telegram Bot API, CAS, LOLS, OpenAI.

Архитектура

graph TB
    subgraph Telegram
        TG[Telegram Bot API]
        CHATS[Группы]
    end

    subgraph Application
        BOT[Бот<br/>aiogram]
        PANEL[Веб-панель<br/>FastAPI]
        RUN[run.py<br/>единый запуск]
    end

    subgraph Services
        MOD[ModerationService]
        SPAM[SpamDetection<br/>BERT + ONNX]
        EXT[External APIs<br/>CAS, LOLS]
        BACKUP[BackupService]
    end

    subgraph Storage
        DB[(PostgreSQL)]
        MODELS[ML-модели<br/>models/]
    end

    subgraph Browser
        UI[Веб-панель<br/>TS + SCSS + Tailwind]
    end

    TG --> BOT
    CHATS --> BOT
    BOT --> MOD
    MOD --> SPAM
    MOD --> EXT
    MOD --> DB
    SPAM --> MODELS
    BOT --> BACKUP
    BACKUP --> DB
    RUN --> BOT
    RUN --> PANEL
    PANEL --> DB
    UI --> PANEL

Система запускается через единый entry point (run.py), который поднимает бота и веб-панель в одном event loop. Бот и панель разделяют общий пул соединений PostgreSQL. Подробное описание архитектуры — в .docs/architecture.md.

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

Требования

• Docker и Docker Compose
• Telegram-бот (токен от @BotFather)
• PostgreSQL 14+

Установка

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

git clone https://scm.overklassniy.space/nyashki/STANKIN_AntiSpam.git
cd STANKIN_AntiSpam

2. Создайте файл .env на основе .env.example и заполните обязательные переменные:

cp .env.example .env
# Отредактируйте .env: BOT_TOKEN, DATABASE_URL, SECRET_KEY, NOTIFICATION_CHAT_ID

3. Запустите через Docker Compose:

docker compose up -d

Веб-панель будет доступна по адресу http://localhost:12523.

Для получения пароля доступа к панели отправьте команду /get_password боту в личные сообщения.

Подробные инструкции по установке — в .docs/installation.md.

Структура проекта

STANKIN_AntiSpam/
  bot/                 Telegram-бот: обработчики, сервисы модерации
  core/                Ядро: конфигурация, БД, репозитории, логирование
  panel/               Веб-панель: FastAPI, REST API, фронтенд
  migrations/          Миграции схемы базы данных
  tests/               Автоматические тесты
  assets/              Медиа-ассеты для документации
  .docs/               Детальная документация
  Dockerfile           Многостадийная сборка Docker-образа
  docker-compose.yml   Конфигурация для deploy
  run.py               Единый entry point
  requirements.txt     Python-зависимости
  package.json         Node.js зависимости для сборки фронтенда

Описание каждого модуля — в README соответствующей директории:

• bot/README.md — модуль Telegram-бота
• core/README.md — ядро и инфраструктура
• panel/README.md — веб-панель управления
• migrations/README.md — миграции схемы базы данных
• tests/README.md — автоматические тесты
• .docs/README.md — детальная документация

Документация

• .docs/installation.md — требования, локальная установка, Docker.
• .docs/configuration.md — переменные окружения, настройки в БД, пороги BERT.
• .docs/architecture.md — архитектура системы, поток данных, компоненты.
• .docs/api.md — REST API эндпоинты, аутентификация, Scalar.
• .docs/deployment.md — Docker deploy, CI/CD, мониторинг, бэкапы.
• .docs/development.md — настройка окружения разработки, сборка фронтенда.
• Дизайн-система — макеты и UI-компоненты веб-панели.

Ветка research

Ветка research содержит исследовательскую часть проекта:

• разведывательный анализ данных (EDA) собранного датасета сообщений;
• эксперименты с моделями классификации (BERT, sklearn-пайплайны, ансамбли);
• подбор гиперпараметров через Optuna с кросс-валидацией;
• сравнение метрик (F1, precision, recall) и выбор лучшей модели;
• Jupyter-ноутбуки с воспроизводимыми экспериментами;
• скрипты обучения и сохранения моделей в директорию models/.

Результаты исследований переносятся в основную ветку master в виде обученных моделей и настроек порогов классификации.