ithueti guard bot

Telegram-бот для модерации чата комментариев канала.

Функциональность

• Проверяет новых или неизвестных пользователей в модерируемых чатах: на вступление и первое сообщение.
• На проверку отвечает картинкой из CHALLENGE_IMAGE_PATH.
• Пока challenge активен, бот не засчитывает обычные сообщения пользователя как ответ.
• Если пользователь ответил reply-сообщением на challenge за отведенное время, бот регистрирует его.
• Если пользователь не ответил, бот удаляет исходные сообщения пользователя, свои challenge-сообщения и банит пользователя.
• Администраторы и модераторы регистрируются автоматически. Обычные участники чата и подписчики REQUIRED_CHANNEL всё равно проходят первую проверку.
• Сообщения от имени REQUIRED_CHANNEL не проходят challenge-проверку. Сообщения, отправленные в чат от имени стороннего канала, проходят challenge и могут быть забанены как sender chat.
• Реакция от незарегистрированного пользователя или стороннего канала сразу приводит к бану.
• В личке пользователь может проверить статус командой /status: отдельно статус в чате и ignore-статус в боте.
• Пользователь может написать боту любое сообщение, чтобы бот снял сохраненный бан и зарегистрировал его.
• Прочие личные сообщения и медиа пересылаются админам. Если Telegram запрещает пересылку, бот пробует скопировать сообщение, затем отправляет fallback вида @username: текст или user_id: текст.
• Если админ ставит реакцию на пересланное сообщение в личке бота, бот ставит такую же реакцию на исходное сообщение пользователя и отвечает админу Ответил..
• Админка в личке включается фразой ADMIN_SECRET.
• Админу доступны /help, /status @username, /ban @username, /remove @username, /unban @username, /reg @username, /unreg @username, /mod @username, /demod @username, /modlist, /ignorelist, /banlist, /reglist, /sublist, /ignore @username, /unignore @username.
• Для публичных каналов бот сопоставляет @username с внутренним sender chat id сам.
• /remove @username банит пользователя в модерируемых чатах и в REQUIRED_CHANNEL.
• /unban @username разбанивает пользователя в модерируемых чатах и в REQUIRED_CHANNEL, затем регистрирует его.
• /mod @username выдаёт пользователю права модератора, /demod @username снимает их, /modlist показывает список.
• /modlist, /ignorelist, /banlist, /reglist и /sublist без аргумента показывают последние 10 элементов; с аргументом принимают только целое число элементов.
• Если админ нажал в меню команду, которой нужен username, бот попросит прислать @username следующим сообщением.
• /reg @username и /mod @username можно применять к пользователям, которых бот ещё не видел.
• Модератор не видит админское меню, но может в модерируемом чате использовать ban, remove и unban.
• Админские команды можно писать с username или ответом на сообщение пользователя/канала. Reply-режим работает в чате и в личке бота на пересланных админу сообщениях.
• Пользователей из ignore-списка бот не пересылает админам в личке.

.env

Бот читает настройки из .env:

BOT_TOKEN=123456:telegram-bot-token
ADMIN_SECRET=change-me

REQUIRED_CHANNEL=@ithueti
MODERATED_CHAT_IDS=-1001234567890

DATABASE_PATH=/state/guard_bot.sqlite3
CHALLENGE_TIMEOUT_SECONDS=60
CHALLENGE_IMAGE_PATH=/state/cptch.png
LOG_LEVEL=INFO

Переменные:

• BOT_TOKEN - токен Telegram-бота из BotFather.
• ADMIN_SECRET - фраза, которая включает админку в личке бота.
• REQUIRED_CHANNEL - публичный канал, который бот показывает пользователю в подсказке.
• MODERATED_CHAT_IDS - id модерируемых чатов через запятую.
• DATABASE_PATH - путь к SQLite-базе внутри контейнера.
• CHALLENGE_TIMEOUT_SECONDS - время на ответ challenge-картинке.
• CHALLENGE_IMAGE_PATH - путь к картинке challenge внутри контейнера.
• LOG_LEVEL - уровень логов.

Запуск Через Docker

Создай .env, затем запусти:

docker compose up --build -d

Логи:

docker compose logs -f bot

Остановка:

docker compose down

State

SQLite-база хранится в директории state рядом с проектом:

state/guard_bot.sqlite3

docker-compose.yml монтирует эту директорию в контейнер как /state, поэтому для Docker-запуска DATABASE_PATH должен указывать на файл внутри /state.

Директория state/ добавлена в .gitignore. Если удалить state, бот потеряет зарегистрированных пользователей, сохраненные баны, список админов, список модераторов, ignore-список и активные challenge-проверки.