This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

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

Развёртывание, CI/CD, мониторинг и резервное копирование СТАНКИН Анти-Спам.

Docker

Docker-образ

Образ собирается локально из Dockerfile:

stankin-antispam:latest

Dockerfile использует многостадийную сборку:

1. frontend-builder — сборка фронтенда (Node.js 22, TypeScript, SCSS, Tailwind)
2. deps-builder — установка Python-зависимостей через uv (Python 3.14)
3. schema-builder — временный Postgres, применение миграций и pg_dump --schema-only в schema.sql
4. erd-builder — сборка статического ERD-вьювера Liam (@liam-hq/cli) из schema.sql в erd_dist
5. pkg-builder — системные пакеты из Chainguard dev-образа (для ONNX Runtime и pg_dump)
6. runtime — минимальный образ на базе Chainguard Python

Runtime-образ не содержит shell, что уменьшает поверхность атаки.

Диаграмма БД (ERD)

Панель раздаёт интерактивную диаграмму схемы базы данных по адресу /erd (вьювер Liam ERD, собирается на стадии erd-builder). Страница доступна только авторизованным пользователям панели, как и /docs. Без Docker-сборки каталог panel/erd_dist отсутствует и /erd отдаёт 404.

Docker Compose

Конфигурация docker-compose.yml:

services:
  app:
    build: .
    image: stankin-antispam:latest
    container_name: stankin-antispam
    user: root
    env_file: .env
    environment:
      ORT_DISABLE_TELEMETRY: "1"
      TZ: "Europe/Moscow"
    network_mode: host
    volumes:
      - ./models:/app/models
      - ./logs:/app/logs
      - ./data:/app/data
    restart: unless-stopped

Используется network_mode: host: контейнер работает в сети хоста, поэтому публикация портов не требуется — веб-панель доступна на порту PANEL_PORT (по умолчанию 12523) напрямую. Переменная ORT_DISABLE_TELEMETRY отключает телеметрию onnxruntime, которая вызывает падение по SIGSEGV на Python 3.14.

Монтируемые директории:

• models/ — ML-модели (BERT, ONNX)
• logs/ — файлы логов
• data/ — данные приложения

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

1. Установите Docker и Docker Compose на сервер
2. Склонируйте репозиторий или создайте директорию с docker-compose.yml и .env
3. Заполните .env (минимум: BOT_TOKEN, DATABASE_URL, SECRET_KEY, NOTIFICATION_CHAT_ID)
4. Убедитесь, что PostgreSQL доступен с сервера
5. Запустите:

docker compose up -d

6. Проверьте логи:

docker compose logs -f

Обновление

docker compose build
docker compose up -d

Образ пересобирается локально из Dockerfile.

Сборка образа

Docker-образ собирается вручную на сервере из Dockerfile при обновлении:

docker compose build
docker compose up -d

Многостадийная сборка кеширует слои фронтенда и Python-зависимостей, поэтому повторная сборка занимает заметно меньше времени, чем первая.

CI

CI настроен через Forgejo Actions в .forgejo/workflows/ci.yml. Workflow запускается при пуше в master и вручную (workflow_dispatch).

Джобы:

• test — установка Python 3.14 через uv, прогон unit- и интеграционных тестов pytest с отчётом покрытия. Реальная БД и сеть не требуются: тесты используют фейковый пул соединений.
• build-and-push — сборка Docker-образа и публикация в реестр scm.overklassniy.space/nyashki/stankin-antispam:latest. Запускается после успешных тестов.
• repo-stats — генерация отчёта о статистике кода через scc, результат загружается как артефакт прогона.
• wiki — синхронизация каталога .docs в вики-репозиторий STANKIN_AntiSpam.wiki.git. Выполняется только если в пуше изменились файлы .docs (или при ручном запуске). Файлы раскладываются по страницам с числовым префиксом, README.md становится главной страницей Home.md; синхронизация полностью пересоздаёт вики.

Для работы джоб использует секрет FGJ_TOKEN (права на реестр контейнеров и запись в вики).

Мониторинг

Sentry

Интеграция с Sentry настраивается через переменные окружения:

• SENTRY_DSN — обязательный для включения мониторинга
• SENTRY_TRACES_SAMPLE_RATE — процент трейс-сессий
• SENTRY_ENABLE_LOGS — отправка логов как structured logs
• SENTRY_LOGS_LEVEL — уровень логов для structured logs
• SENTRY_BREADCRUMBS_LEVEL — уровень breadcrumbs
• SENTRY_EVENT_LEVEL — уровень events

Sentry перехватывает:

• Неперехваченные исключения в обработчиках бота
• Ошибки в FastAPI-приложении
• Контекстные breadcrumbs для диагностики

Версия приложения (APP_VERSION) передаётся в Sentry как release.

Логирование

Логи записываются в файлы в директории logs/ и выводятся в stdout. Уровень логирования зависит от режима:

• Обычный режим — INFO
• Тестовый режим (TESTING=true) — DEBUG

Резервное копирование

Автоматические бэкапы

Настраиваются через веб-панель или API:

• BACKUP_ENABLED — включение автоматических бэкапов
• BACKUP_START_TIME — время начала (формат HH:MM)
• BACKUP_INTERVAL_HOURS — интервал в часах

Процесс:

1. Создание дампа БД через pg_dump
2. Вычисление SHA-256 хеша файла
3. Отправка файла в Telegram-чат управления в тред NOTIFICATION_CHAT_BACKUP_THREAD

Ручной бэкап

Через API:

curl -X POST http://localhost:12523/api/v1/backup \
  -H "Cookie: session=..."

Через веб-панель — кнопка создания резервной копии в разделе настроек.

Требуется наличие pg_dump в окружении. В Docker-образе postgresql-client предустановлен.