DispelEvilBot/DEPLOY.md

Развёртывание

Клонируем репозиторий и поднимаем контур Compose-ом. Контуры test и prod разделяются именем проекта (-p) и файлом окружения (--env-file) — у каждого свои БД и volume'ы, на одной машине не пересекаются.

1. Клонировать

git clone ssh://git@<gitea-host>:2222/mpakobecex/DispelEvilBot.git
cd DispelEvilBot

2. Подготовить окружение

cp env/test.env.example env/test.env
# заполнить: BOT_TOKEN, DB_PASSWORD, CHAT_ID (основной чат), ALERT_CHAT_ID (опц.),
# ADMIN_IDS (опц.), CLICKHOUSE_PASSWORD (аналитика событий)

Порт ClickHouse на хосте (CLICKHOUSE_HTTP_PORT) у контуров должен различаться: prod — 8123, test — 8124 (иначе контейнеры конфликтуют на одной VPS).

3. Логин в registry (если пакет приватный)

docker login git.mpakosrv.ru -u mpakobecex -p <ТОКЕН с read:package>

Если пакет сделать публичным — логин не нужен.

4. Запуск

# тестовый контур
docker compose -p test --env-file env/test.env -f docker-compose.prod.yml up -d

# прод (когда понадобится)
cp env/prod.env.example env/prod.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 logs -f

Что происходит при старте

1. postgres поднимается и проходит healthcheck;
2. migrate (Flyway) накатывает миграции из sql/ — для пустой БД с нуля;
3. clickhouse поднимается и применяет clickhouse/init/001_events.sql — только при первой инициализации пустого data-каталога;
4. bot стартует (Запуск DispelEvilBot v<версия> (APP_ENV=...)), аналитика и рассылки — в нём же.

Проверка контура (сервисы, миграции, Postgres, ClickHouse):

make check E=test

ClickHouse (аналитика событий)

События всех действий бота пишутся в analytics.events (контракт — docs/events.md). ClickHouse наружу не публикуется: только loopback хоста (127.0.0.1:${CLICKHOUSE_HTTP_PORT}).

make ch E=test      # clickhouse-client контура
# пример: события за сегодня по типам
docker compose -p test --env-file env/test.env -f docker-compose.prod.yml exec -T clickhouse \
  sh -lc 'clickhouse-client --user "$CLICKHOUSE_USER" --password "$CLICKHOUSE_PASSWORD" \
  --query "SELECT event_type, count() FROM analytics.events WHERE toDate(event_time) = today() GROUP BY event_type"'

Если ClickHouse недоступен, бот продолжает работать: события уходят в stdout (WARNING), полностью выключить можно флагом CLICKHOUSE_ENABLED=false.

Изменения схемы: clickhouse/init/*.sql применяются лишь на пустом data-каталоге, поэтому на существующем контуре DDL нужно применить вручную (make ch E=...).

Бэкап событий (забирает домашний сервер)

Сырые события живут на VPS ограниченное время: раз в сутки домашний сервер сам забирает вчерашнюю партицию (pull), складывает её в Parquet.gz, импортирует в свой ClickHouse и сверяет количество строк — только после сверки на VPS удаляются партиции старше BACKUP_GRACE_DAYS (по умолчанию 7). На VPS остаются агрегаты (events_daily, money_daily).

Входящий SSH на домашний сервер не нужен: он инициирует соединение сам.

Разовая настройка:

# на домашнем сервере
git clone ssh://git@<gitea-host>:2222/mpakobecex/DispelEvilBot.git
cd DispelEvilBot
cp env/backup.env.example env/backup.env   # VPS_SSH, VPS_PORT, VPS_PROJECT_DIR, VPS_SSH_KEY, BACKUP_DIR, CLICKHOUSE_*

Требования: на VPS — пользователь с доступом к docker и каталог с репозиторием (VPS_PROJECT_DIR, там запускается docker compose); на домашнем сервере — clickhouse-client и локальный ClickHouse. Настройка SSH-доступа — deploy/ssh-access.md.

Проверочный прогон (без cron): make backup E=test или ./scripts/clickhouse_backup.sh test.

Cron на домашнем сервере (вчерашний день уже закрыт, время московское):

0 4 * * * cd /srv/DispelEvilBot && ./scripts/clickhouse_backup.sh test >> /var/log/clickhouse-backup-test.log 2>&1

Ошибка на любом шаге оставляет данные на VPS (партиции не удаляются) и пишет понятный лог. Импорт дня идемпотентен: повторный прогон не дублирует строки.

Если контур на VPS не запущен (нет работающего clickhouse или не найден каталог проекта), скрипт пишет об этом в лог и завершается с кодом 0 — для cron это не ошибка.

Обновление и откат

# обновление: поменять IMAGE_TAG в env/<контур>.env, затем
docker compose -p <контур> --env-file env/<контур>.env -f docker-compose.prod.yml pull
docker compose -p <контур> --env-file env/<контур>.env -f docker-compose.prod.yml up -d

Откат — вернуть предыдущий IMAGE_TAG (например, commit-sha) и повторить.

Контуры

Контур	env-файл	БД	APP_ENV	Бот
test	env/test.env	dispel_evil_test	dev	тестовый
prod	env/prod.env	dispel_evil	prod	боевой

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

См. env/prod.env.example / env/test.env.example (контуры) и env/backup.env.example (бэкап событий).

Дашборд (позже)

Superset поднимается на домашнем сервере и читает локальный ClickHouse с полной историей событий (сюда ежедневно приезжают архивы). Отдельный read-only пользователь ClickHouse и сам дашборд — финальный этап, в этот контур не входят.

Перенос данных на прод (позже, короткое окно простоя)

1. Остановить старого бота.
2. pg_dump -Fc -f dump.pgc <старая_бд>.
3. Поднять прод-контур (миграции создадут чистую схему).
4. Загрузить данные: pg_restore --data-only --disable-triggers -d dispel_evil dump.pgc.
5. Сверить: число пользователей, SUM(money.amount), число сообщений.
6. Переключить бота, проверить команды.

Бэкап старой БД обязателен. Дубли в tg_users/de_users/unsubscribe при загрузке нужно устранить до создания PK (миграция V12 делает дедуп, но при загрузке поверх миграций дедуп — вручную).