8.6 KiB

Raw Blame History

DispelEvilBot

Telegram-бот клана Dispel Evil (aiogram 3 + Postgres). Монорепозиторий: общий пакет common используется сервисом бота bot (и, в будущем, админкой admin).

Структура

common/     # общий пакет: config, logging, db, repositories, models, texts, analytics
bot/        # сервис бота: handlers, services, keyboards, middlewares, notifications
admin/      # сервис админки: FastAPI + Jinja2/HTMX (Блок 4), свой Dockerfile
sql/        # миграции Flyway (V__*.sql, R__*.sql)
clickhouse/ # init-скрипты ClickHouse (схема аналитики)
docs/       # документация (docs/events.md — события аналитики)
scripts/    # эксплуатационные скрипты (проверка контура, бэкап событий)
images/     # статичные картинки (приветствие)
deploy/     # материалы деплоя (Caddyfile, инструкции)
tests/      # тесты
Dockerfile  # образ бота
docker-compose.yml / docker-compose.prod.yml
.gitea/     # CI (Gitea Actions)

Требования

Python 3.12
PostgreSQL 14+
ClickHouse 25.3 (аналитика событий; можно выключить — CLICKHOUSE_ENABLED=false)

Настройка

cp .env.example .env
# заполнить BOT_TOKEN, DB_*, чаты и ADMIN_IDS
pip install -r requirements.txt

Запуск

APP_ENV=dev python -m bot     # dev
APP_ENV=prod python -m bot    # prod

или через ./start.sh (режим берётся из APP_ENV).

Админка (FastAPI) запускается отдельным процессом: python -m admin (зависимости — requirements-admin.txt), по умолчанию слушает 0.0.0.0:8000, проверка живучести — GET /healthz.

База данных

Схема управляется миграциями Flyway в sql/ (V__*.sql — versioned, R__*.sql — repeatable). При Docker-развёртывании накат выполняется автоматически сервисом migrate перед ботом.

Админка (Блок 4)

Отдельный сервис admin/ (FastAPI + Jinja2/HTMX), запуск python -m admin. Раздел «Сообщения» читает и правит шаблоны из bot.message_templates, каждое изменение пишется в bot.message_template_history (аудит и материал для отката). Стартовые тексты — sql/V15__seed_message_templates.sql (генерируются из common/texts, тест сверяет их). Бот читает тексты из БД через TTL-кеш (TEMPLATE_CACHE_TTL, по умолчанию 45 с), поэтому правка применяется без перезапуска; при недоступной БД бот использует тексты из кода. Предпросмотр использует тот же render(), что и бот.

Раздел «Расписания» — CRUD рассылок (bot.schedules + история): время, дни недели, таймзона, шаблон и вкл/выкл. Бот раз в минуту читает активные расписания из БД; если база недоступна — использует расписание из кода (совпадает с сидом V16).

Аналитика (ClickHouse)

Все значимые действия бота пишутся в ClickHouse в единую таблицу analytics.events. Контракт событий — docs/events.md (типы, payload, примеры запросов).

схема — clickhouse/init/001_events.sql (применяется при первой инициализации контейнера);
клиент и батчинг — common/analytics/ (запись неблокирующая, сбой ClickHouse не влияет на бота);
сырые события живут на VPS 7 дней и ежедневно уезжают архивом на домашний сервер, на VPS остаются агрегаты (events_daily, money_daily) — см. DEPLOY.md;
выключается флагом CLICKHOUSE_ENABLED=false.

Уведомления в чат логов

В ALERT_CHAT_ID (если задан) уходят: вход и выход участников, успешные очищения и ежечасный пинг «бот живой». Отправка не критична: ошибки только пишутся в лог.

Docker

Локальный запуск (postgres + migrate + clickhouse + bot + admin):

cp .env.example .env      # заполнить
docker compose up --build

CI собирает два образа: dispelevilbot-bot и dispelevilbot-admin. Админка в compose по умолчанию публикуется только на loopback (127.0.0.1:${ADMIN_HTTP_PORT}, test 8100 / prod 8101); для nginx-proxy-manager задаётся ADMIN_BIND_IP=172.17.0.1, наружу выйдет вместе с доменом и TLS (Блок 4.2).

Прод/test-контуры — один docker-compose.prod.yml, разделяются Compose-проектом и env-файлом:

docker compose -p prod --env-file env/prod.env -f docker-compose.prod.yml up -d
docker compose -p test --env-file env/test.env -f docker-compose.prod.yml up -d

Пошаговое развёртывание контуров test/prod — см. DEPLOY.md.

Разработка

pip install -r requirements-dev.txt
ruff check .
black --check .
pytest

Бэкап событий

Сырые события ClickHouse ежедневно забираются с VPS домашним сервером (pull), на VPS остаются только агрегаты и последние дни сырых данных:

make backup E=test     # на домашнем сервере: ./scripts/clickhouse_backup.sh test

Настройка, cron и SSH-доступ — см. DEPLOY.md.

Версионирование

Единый источник версии — common/version.py (__version__), текущая — 0.4.4.
Схема — SemVer-подобная (MAJOR.MINOR.PATCH); git-тег = v + версия (v0.1).
Docker-образы тегируются версией (Блок 2), события ClickHouse получают bot_version (Блок 3).
Выпуск: изменить common/version.py → коммит → аннотированный тег vX.Y → git push --tags.

Процесс работы с git

Проект ведётся в режиме trunk-based (один разработчик): основная работа — прямо в master.

master — интеграционная ветка, всегда в рабочем состоянии.
Релизы — аннотированные теги vX.Y (см. «Версионирование»).
Для крупных/рискованных изменений — короткая ветка feature/... и merge обратно в master.
Push в master → CI (Gitea Actions) собирает образ; авто-выката в прод нет.
Выкатка: сначала контур test, затем prod по подтверждению (см. Блок 2.5 плана).
Переход на «ветки + PR» и защиту ветки — когда появится второй разработчик.

# обычная работа: сообщение без префиксов, по существу изменения
git add -A
git commit -m "Краткое описание изменения"
git push origin master

# выпуск релиза
# 1) поднять __version__ в common/version.py
git commit -am "Версия X.Y"
git tag -a vX.Y -m "Release vX.Y"
git push origin master --tags

Команды бота

/ник, /список, /кто, /инфо, /помощь, /очищение, /яички, /магазин, /рейтинг, /отписка, /подписка.

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

общие — .env.example (включая CLICKHOUSE_* и параметры батчинга ANALYTICS_*);
контуры — env/prod.env.example, env/test.env.example;
бэкап событий — env/backup.env.example.

8.6 KiB Raw Blame History Unescape Escape