RPCM-Project/PrimoGuardBot
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
72 Commits 1 Branch 0 Tags
8170d7a58856da09341dc9f0bb8297d959ff755b
Go to file
Clone
Open with VS Code Open with VSCodium Open with Intellij IDEA
Download ZIP Download TAR.GZ Download BUNDLE

README.md

# 🛡️ PrimoGuard Bot

Умный бот-модератор для Telegram с системой фильтрации спама, банвордов и защитой от флуда.

[ [ [

📑 Содержание

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

Основные функции

✅ Многоуровневая система фильтрации:

  • 🔤 Substring — фильтрация по подстрокам (например: хуй)
  • 📖 Lemma — фильтрация по лемматизации (например: пидорас → пидор, пидорасом, пидораса)
  • 🧩 Part — фильтрация по частям слов без спецсимволов (например: @Astrixkeepbot → заблокирует astrix и bot)

✅ Временные правила:

  • ⏰ Банворды с истечением срока действия
  • 🔄 Автоматическая очистка истёкших правил

✅ Режимы модерации:

  • 🔇 Silence Mode — удаление всех сообщений (режим тишины)
  • ⚔️ Conflict Mode — блокировка конфликтных слов (для предотвращения споров)
  • ✅ Whitelist — исключения для разрешённых слов

✅ Умный антиспам:

  • 🤖 Адаптивные лимиты (текст, пересылки, медиа, callback)
  • 🧠 Детекция спам-паттернов (идентичные сообщения, спам кнопок)
  • ⭐ Система репутации пользователей (0.5x - 2.0x к лимитам)
  • 🚫 Прогрессивные блокировки (1 мин → 2 мин → 5 мин → 15 мин → 1 час)

✅ Статистика и аналитика:

  • 📊 Топ-10 самых частых срабатываний
  • 👥 Статистика по пользователям
  • 📈 Общее количество удалённых сообщений

✅ Администрирование:

  • 👨‍💼 Многоуровневая система администраторов
  • 🔔 Уведомления админов о спаме
  • 🎛️ Удобное управление через команды и callback-кнопки

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

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

git clone https://github.com/yourusername/primo_guard_bot.git
cd primo_guard_bot

2. Создайте файл .env

cp .env.example .env
nano .env

Минимальная конфигурация:

# === BOT SETTINGS ===
BOT_TOKEN=YOUR_BOT_TOKEN_FROM_BOTFATHER

# === ADMIN IDS ===
OWNER_ID=[123456789,987654321]
ADMIN_CHAT_ID=-1001234567890

# === WEBHOOK (если используете) ===
WEBHOOK=true
WEBHOOK_URL=https://yourdomain.com/webhook
SECRET_TOKEN=your_random_secret_32_chars_here

# === SERVER ===
WEBAPP_HOST=0.0.0.0
WEBAPP_PORT=3131

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

docker compose up -d

4. Проверьте логи

docker compose logs -f

5. Добавьте бота в группу

  1. Добавьте бота в вашу группу
  2. Выдайте права администратора (удаление сообщений)
  3. Отправьте /start в группе

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

Полный .env файл

# ═══════════════════════════════════════════════════════════════════════════
#                         🤖 BOT TOKEN
# ═══════════════════════════════════════════════════════════════════════════

# [ОБЯЗАТЕЛЬНО] Токен бота от @BotFather
BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz

# ═══════════════════════════════════════════════════════════════════════════
#                         👤 АДМИНИСТРАТОРЫ И ID
# ═══════════════════════════════════════════════════════════════════════════

# [ОБЯЗАТЕЛЬНО] ID владельцев бота (список через запятую)
OWNER_ID=[123456789,987654321]

# [ОБЯЗАТЕЛЬНО] ID чата для уведомлений админов
ADMIN_CHAT_ID=-1001234567890

# Дополнительные админы (необязательно)
ADMIN_ID=[111111111,222222222]

# ═══════════════════════════════════════════════════════════════════════════
#                         ⚙️ ОСНОВНЫЕ НАСТРОЙКИ БОТА
# ═══════════════════════════════════════════════════════════════════════════

# Имя бота
BOT_NAME=PrimoGuard Bot

# Описание бота (до 512 символов)
BOT_DESCRIPTION=Бот-модератор для защиты чата от спама и нецензурных слов

# Короткое описание (до 120 символов)
BOT_SHORT_DESCRIPTION=Тех.поддержка: @yourusername

# Автоматически обновлять настройки бота при запуске
BOT_EDIT=false

# ═══════════════════════════════════════════════════════════════════════════
#                         🌐 WEBHOOK SETTINGS
# ═══════════════════════════════════════════════════════════════════════════

# Использовать webhook вместо long polling
# false = long polling (для локальной разработки)
# true = webhook (для продакшена, требует HTTPS)
WEBHOOK=true

# URL вебхука (обязателен если WEBHOOK=true)
WEBHOOK_URL=https://yourdomain.com/webhook

# Секретный токен для вебхука (генерируется автоматически если не указан)
SECRET_TOKEN=vK8mP2nQ7xR4wJ9sL6fY3tB5hN0cV1zA

# Хост для сервера (обычно 0.0.0.0)
WEBAPP_HOST=0.0.0.0

# Порт для сервера
WEBAPP_PORT=3131

# Уровень логов (debug, info, warning, error, critical)
LOG_LEVEL=info

# Включить access log
ACCES_LOG=false

# ═══════════════════════════════════════════════════════════════════════════
#                         📊 DATABASE
# ═══════════════════════════════════════════════════════════════════════════

# Путь к базе данных SQLite
DATABASE_PATH=banwords.db

# ═══════════════════════════════════════════════════════════════════════════
#                         🔧 ДОПОЛНИТЕЛЬНЫЕ НАСТРОЙКИ
# ═══════════════════════════════════════════════════════════════════════════

# Префикс команд
PREFIX=/

# Таймаут между сообщениями (антиспам, секунды)
TIMEOUT=3

Docker Compose

Ваш docker-compose.yml уже настроен оптимально:

services:
  primoguard:
    image: whyverum/primo_guard_bot:latest
    container_name: primoguard-bot
    restart: unless-stopped
    
    env_file:
      - .env
    
    volumes:
      - ./banwords.db:/app/banwords.db
      - ./Logs:/app/Logs
    
    deploy:
      resources:
        limits:
          cpus: '1.0'
          memory: 512M
        reservations:
          cpus: '0.25'
          memory: 128M
    
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"
    
    stop_grace_period: 30s
    
    networks:
      - proxy

networks:
  proxy:
    external: true

📝 Команды

Основные команды

Команда Описание Доступ
/start Запуск бота и главное меню Все
/help Помощь по командам Все
/stats Статистика модерации Админы
/id Информация о вашем аккаунте Все
/chatid ID текущего чата Все

Управление банвордами (постоянные)

Команда Пример Описание
/addword /addword хуй Добавить подстроку
/addlemma /addlemma пидорас Добавить лемму
/addpart /addpart astrix Добавить часть слова
/remword /remword хуй Удалить подстроку
/remlemma /remlemma пидорас Удалить лемму
/rempart /rempart astrix Удалить часть

Временные банворды

Команда Пример Описание
/addtempword /addtempword спам 24h Добавить временную подстроку (24 часа)
/addtemplemma /addtemplemma флудить 12h Добавить временную лемму (12 часов)
/remtempword /remtempword спам Удалить временную подстроку

Форматы времени: 1h, 24h, 7d, 30d

Исключения (whitelist)

Команда Пример Описание
/addexcept /addexcept психология Добавить в whitelist
/remexcept /remexcept психология Удалить из whitelist

Конфликтные слова

Команда Пример Описание
/addconflictword /addconflictword политика Добавить конфликтное слово
/stopconflict /stopconflict Включить режим антиконфликта
/unstopconflict /unstopconflict Выключить режим
/conflictstatus /conflictstatus Проверить статус режима

Режим тишины

Команда Описание
/silence 30m Включить тишину на 30 минут
/unsilence Выключить режим тишины
/silencestatus Проверить статус
/extend_silence 1h Продлить тишину на 1 час

Администрирование

Команда Пример Описание
/addadmin /addadmin @username Добавить администратора
/remadmin /remadmin @username Удалить администратора
/listadmins /listadmins Список администраторов
/checkadmin /checkadmin @username Проверить статус

Статистика

Команда Описание
/userstats Статистика по пользователю
/resetstats confirm Сбросить всю статистику

Просмотр правил

Команда Описание
/listwords Список всех подстрок
/listlemmas Список всех лемм
/listparts Список всех частей
/listexcept Список исключений
/listconflict Список конфликтных слов

Утилиты

Команда Описание
/emoji текст Извлечь все эмодзи из текста
/ping Проверить отклик бота
/checkwebhook Проверить статус webhook (админы)

🔍 Система фильтрации

1. Substring (Подстроки)

Как работает: Простой поиск подстроки в тексте.

Правило: "хуй"
✅ Заблокирует: "хуй", "хуйня", "похуй", "нахуй"
❌ Не заблокирует: "психология" (хотя содержит "хуй", но это безобидное слово)

Когда использовать: Для коротких и однозначных матов.

2. Lemma (Лемматизация)

Как работает: Приводит слова к нормальной форме и сравнивает.

Правило: "пидорас" (лемма: "пидор")
✅ Заблокирует: "пидорас", "пидораса", "пидорасом", "пидорасы"
❌ Не заблокирует: "пидор123" (не является словом)

Когда использовать: Для блокировки всех форм слова.

3. Part (Части слов)

Как работает: Удаляет ВСЕ спецсимволы и ищет часть.

Правило: "astrix"
✅ Заблокирует: "@Astrixkeepbot", "astrix.bot", "a-s-t-r-i-x"
❌ Не заблокирует: "astronomy" (не содержит точную последовательность)

Когда использовать: Для блокировки упоминаний ботов/каналов со спецсимволами.

4. Whitelist (Исключения)

Как работает: Проверяется ПЕРВЫМ, до всех фильтров.

Whitelist: "психология"
✅ Пропустит: "я изучаю психологию"
✅ Пропустит: "психолог"

Когда использовать: Для безобидных слов, содержащих мат.

5. Временные правила

Как работает: Автоматически удаляются после истечения срока.

Команда: /addtempword флуд 24h
Результат: Слово "флуд" будет блокироваться 24 часа

Когда использовать: Для временных мер (события, рейды).

🛡️ Middleware

1. BanWordsMiddleware (Основная защита)

Приоритет: Высокий
Применяется к: Все текстовые сообщения

Функции:

  • Проверка на substring, lemma, part
  • Проверка временных банвордов
  • Проверка whitelist
  • Режим тишины
  • Режим антиконфликта

Pipeline проверки:

1. Пропуск админов
2. Проверка whitelist → ПРОПУСТИТЬ
3. Silence Mode → УДАЛИТЬ
4. Conflict Mode + конфликтные слова → УДАЛИТЬ
5. Substring → УДАЛИТЬ
6. Part → УДАЛИТЬ
7. Lemma → УДАЛИТЬ
8. Временные банворды → УДАЛИТЬ
9. ✅ Пропустить сообщение

2. AntiSpamMiddleware (Умный антиспам)

Приоритет: Средний
Применяется к: Все сообщения и callback

Функции:

  • ⚡ Адаптивные лимиты по типам сообщений
  • 🧠 Детекция спам-паттернов
  • ⭐ Система репутации (0.5x - 2.0x)
  • 🚫 Прогрессивные блокировки

Лимиты по умолчанию:

Тип Лимит Окно Описание
📝 Текст 8 сообщений 10 сек Обычные текстовые сообщения
↗️ Пересылки 20 сообщений 10 сек Можно массово пересылать!
🔘 Callback 10 нажатий 10 сек Нажатия на кнопки
📷 Медиа 10 файлов 10 сек Фото, видео, документы
⚡ Команды ∞ - Не ограничены

Умная детекция:

  • ❌ 5 одинаковых текстов подряд → немедленная блокировка
  • ❌ 8 нажатий одной кнопки → блокировка
  • ❌ 7+ медиа подряд → предупреждение

Система репутации:

Новый пользователь: 1.0x (стандартные лимиты)
Хорошее поведение: до 2.0x (лимиты удваиваются!)
Плохое поведение: до 0.5x (лимиты снижаются вдвое)

Прогрессивные блокировки:

1 предупреждение → 2 мин блокировка
2 предупреждения → 4 мин
3 предупреждения → 8 мин
4 предупреждения → 16 мин
5+ предупреждений → 1 час (максимум)

3. LoggingMiddleware (Логирование)

Приоритет: Низкий
Применяется к: Все события

Функции:

  • 📝 Логирование всех команд
  • 📊 Логирование всех событий
  • 🔍 Детальная информация для отладки

4. ErrorHandlingMiddleware (Обработка ошибок)

Приоритет: Последний
Применяется к: Все события

Функции:

  • ❌ Перехват всех исключений
  • 📧 Уведомления админов об ошибках
  • 🔄 Graceful recovery

5. TimingMiddleware (Замер времени)

Приоритет: Первый
Применяется к: Все события

Функции:

  • ⏱️ Замер времени выполнения
  • 📊 Профилирование производительности

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

Сценарий 1: Настройка для чата с матами

# 1. Добавляем основные маты
/addword хуй
/addword блять
/addlemma пидорас
/addlemma ебать

# 2. Добавляем исключения
/addexcept психология
/addexcept архитектура

# 3. Проверяем правила
/listwords

Сценарий 2: Блокировка упоминаний ботов

# 1. Добавляем части названий ботов
/addpart astrix
/addpart keepbot
/addpart spambot

# 2. Проверяем
# ✅ Заблокируется: "@Astrixkeepbot", "astrix_bot"

Сценарий 3: Временная блокировка темы

# Событие: выборы, запрещаем политику на 3 дня
/addtempword политика 3d
/addtempword выборы 3d
/addtemplemma голосовать 3d

# Через 3 дня слова автоматически разблокируются

Сценарий 4: Режим тишины во время рейда

# 1. Включаем тишину на 1 час
/silence 1h

# Все сообщения от не-админов удаляются

# 2. Если рейд продолжается, продлеваем
/extend_silence 30m

# 3. Отключаем вручную
/unsilence

Сценарий 5: Антиконфликтный режим

# 1. Добавляем конфликтные темы
/addconflictword политика
/addconflictword религия
/addconflictlemma спорить

# 2. Включаем режим
/stopconflict

# Теперь сообщения с этими словами удаляются

# 3. Выключаем после события
/unstopconflict

🔧 Troubleshooting

Бот не отвечает в группе

Решение:

# 1. Проверьте права администратора
# Бот ДОЛЖЕН иметь право "Удаление сообщений"

# 2. Проверьте webhook
docker exec primoguard-bot python -c "
from configs import settings
import requests
url = f'https://api.telegram.org/bot{settings.BOT_TOKEN}/getWebhookInfo'
print(requests.get(url).json())
"

# 3. Проверьте логи
docker compose logs -f

# 4. Перезапустите
docker compose restart

Ошибка 401 Unauthorized (Webhook)

Причина: Несовпадение SECRET_TOKEN

Решение:

# 1. Удалите webhook
curl "https://api.telegram.org/botYOUR_TOKEN/deleteWebhook?drop_pending_updates=true"

# 2. Проверьте .env файл
cat .env | grep SECRET_TOKEN

# 3. Перезапустите
docker compose down
docker compose up -d

База данных заблокирована (database is locked)

Решение:

# 1. Остановите все контейнеры
docker compose down

# 2. Проверьте права
sudo chown -R $USER:$USER banwords.db

# 3. Запустите
docker compose up -d

Бот не удаляет сообщения

Проверьте:

  1. ✅ Бот — администратор группы
  2. ✅ Есть право "Удаление сообщений"
  3. ✅ Правила банвордов добавлены (/listwords)
  4. ✅ Пользователь не в списке админов (/listadmins)

❓ FAQ

Как узнать свой ID?

Отправьте /id боту или используйте @userinfobot

Как узнать ID группы?

  1. Добавьте бота в группу
  2. Отправьте /chatid в группе

Можно ли использовать без webhook?

Да! Установите в .env:

WEBHOOK=false

Как добавить несколько админов?

OWNER_ID=[123456789,987654321,555666777]
ADMIN_ID=[111222333,444555666]

Сколько правил можно добавить?

Ограничений нет, но рекомендуется до 1000 слов для оптимальной производительности.

Работает ли на русском и английском?

Да! Поддерживаются все языки с Unicode.

Как сделать backup базы данных?

# Создайте backup
cp banwords.db banwords_backup_$(date +%Y%m%d).db

# Или через Docker
docker cp primoguard-bot:/app/banwords.db ./backup/

Как обновить бота?

# 1. Остановите
docker compose down

# 2. Обновите образ
docker pull whyverum/primo_guard_bot:latest

# 3. Запустите
docker compose up -d

Влияет ли на производительность группы?

Нет! Бот обрабатывает сообщения за ~10-50мс. Для пользователей задержка незаметна.

📊 Мониторинг

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

# Все логи
docker compose logs -f

# Только ошибки
docker compose logs -f | grep ERROR

# Последние 100 строк
docker compose logs --tail=100

# Логи за сегодня
docker compose logs --since $(date +%Y-%m-%d)

Статистика Docker

# Использование ресурсов
docker stats primoguard-bot

# Информация о контейнере
docker inspect primoguard-bot

# Размер логов
docker logs primoguard-bot 2>&1 | wc -l

📄 Лицензия

MIT License - см. LICENSE

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

  • aiogram - асинхронный фреймворк для Telegram Bot API
  • pymorphy2 - морфологический анализатор для русского языка
  • SQLAlchemy - ORM для работы с базой данных

⭐ Если бот помог вам, поставьте звезду на GitHub!

Reference in New Issue View Git Blame Copy Permalink
Description
Бот-модератор для каналов и чатов с комментариями
https://t.me/PrimoWorldInfo
Readme MIT 938 KiB
Languages
Python 95.9%
Markdown 4%