PrimoGuardBot-

🔤 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. Добавьте бота в группу

Добавьте бота в вашу группу
Выдайте права администратора (удаление сообщений)
Отправьте /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

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

Проверьте:

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

❓ FAQ

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

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

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

Добавьте бота в группу
Отправьте /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!

README.md Unescape Escape

📑 Содержание

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

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

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

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

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

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

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

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

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

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

Docker Compose

📝 Команды

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

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

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

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

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

Режим тишины

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

Статистика

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

Утилиты

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

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

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

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

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

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

🛡️ Middleware

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

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

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

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

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

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

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

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

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

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

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

🔧 Troubleshooting

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

Ошибка 401 Unauthorized (Webhook)

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

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

❓ FAQ

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

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

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

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

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

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

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

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

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

📊 Мониторинг

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

Статистика Docker

📄 Лицензия

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

README.md

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

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