Skip to content
k0te1chPublic

About

Telegram bot that automates podcast episode publishing: mp3 tagging, FTP, WordPress with Podlove, paid platforms. Kafka microservices, Prometheus + Loki + Grafana.

Topics

Resources

Stars

0 stars

Watchers

1 watching

Forks

Latest commit

 

History

240 Commits

Folders and files

Repository files navigation

PodBoxBot

Telegram-бот для подкаст-команды «Разговорный жанр» — автоматизирует рутину публикации эпизода: тегирование mp3, заливка на FTP хостинга, создание поста-черновика в WordPress с Podlove-метаданными и chapters, пересылка анонса в чат.

Стек микросервисный: бот собирает запрос → шлёт в Kafka → отдельные publisher-сервисы (FTP, WordPress, Boosty) забирают и выполняют → возвращают результат через Kafka → бот апдейтит сообщение в Telegram. Полное наблюдение через Prometheus + Loki + Grafana.

Boosty — платная площадка: туда уходит только aftershow (послешоу), пост публикуется на платном уровне подписки (см. BasePublisher.is_paywalled). Кнопка появляется в боте при BOOSTY_ENABLED=true; как получить токены и прогнать живой смоук — app/publishers/Boosty/SMOKE.md. FTP и WordPress — для основного эпизода.

Послешоу под замком публикуется ещё на трёх площадках, у каждой свой сервис (профиль compose paywalled) и флаг <ПЛОЩАДКА>_ENABLED в боте:

Площадка Как работает Состояние
VK Donut эпизод в разделе подкастов с доступом «Только донам» по сессии vk.ru; запасной путь через официальный API (видео или документ) запросы сверены с записью, ждёт сессию
Patreon API v2 постов не создаёт, запросы веб-редактора по куке session_id запросы сверены с записью, ждёт сессию
Sponsr API нет, веб-редактор по куке SESS запросы сверены с записью, ждёт сессию

Что нужно для каждой — в app/publishers/<Площадка>/SMOKE.md.

Что внутри

app/
├── bot/                  # aiogram 3 бот: хендлеры, FSM, клавиатуры, i18n (FTL)
├── publishers/          # каждый: консьюмер publisher.<name>.upload → publish → publisher.<name>.result
│   ├── FTP/              # ftp upload эпизода на хостинг
│   ├── WordPress/        # WP post-new form + Podlove REST API (Application Password)
│   │                     #   для метаданных и chapters
│   ├── Boosty/           # пост на платном уровне (mp3 + обложка-тизер), internal API — aftershow
│   ├── VK/               # эпизод подкаста VK для донов — aftershow
│   ├── Patreon/          # пост для патронов, запросы веб-редактора — aftershow
│   └── Sponsr/           # пост для подписчиков, запросы веб-редактора — aftershow
├── kafka/                # kafka-init: создаёт топики из topics.yaml при старте кластера
├── schema-watcher/       # регистрирует Avro-схемы в Schema Registry
└── shared/
    ├── config/           # pydantic-settings, один источник правды для микросервисов
    └── kafka/            # общий KafkaProducer/Consumer + Avro-схемы
configs/                  # prometheus.yml, loki, grafana datasources, alloy
docker-compose.yml          # стек БЕЗ tun2socks (дефолт, прямой коннект)
docker-compose.tun2socks.yml # стек С tun2socks (для хостов за блокировкой)
utils/bootstrap.sh        # первичный деплой на чистый prod
.env.example              # шаблон переменных окружения

Поток данных

Telegram user
    │
    ▼
podboxbot_bot ──► Kafka topic publisher.{ftp,wordpress,boosty}.upload
                                                     │
                                                     ▼
                                 podboxbot_publisher_{ftp,wordpress,boosty}
                                                     │
                                                     ▼
                            Kafka topic publisher.{ftp,wordpress,boosty}.result
                                                     │
                                                     ▼
                                       podboxbot_bot (Telegram edit_message)

Схемы сообщений (app/shared/kafka/schemas/*.avsc) регистрируются schema-watcher'ом автоматически при старте.

Развёртывание на чистом prod-сервере

Минимальные требования

  • Linux (Debian/Ubuntu проверены).
  • docker ≥ 23, docker compose v2, curl, jq, bash ≥ 4.
  • ~4 ГБ RAM свободно для всего стека (Kafka, Grafana, Loki — основные едоки).

Если у тебя только docker-compose v1 — поставь плагин v2:

sudo apt-get update && sudo apt-get install -y docker-compose-plugin
docker compose version   # должно показать v2.x

Шаги

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

    git clone https://github.com/k0te1ch/PodBoxBot.git
    cd PodBoxBot

    main всегда releasable; для воспроизводимого деплоя можно выехать на тег последнего релиза (git checkout v0.3.1).

  2. Подготовить .env:

    cp .env.example .env
    nano .env

    Минимум, что надо заполнить (остальное — опционально или со значениями по умолчанию):

    Переменная Что это
    TELEGRAM_API_TOKEN токен бота от @BotFather
    TELEGRAM_SERVER_API_ID / _HASH для self-hosted telegram-bot-api (my.telegram.org)
    FORWARD_CHAT_USERNAME username публичной группы/канала (формат @group) или числовой id чата, в котором бот состоит: туда бот будет форвардить анонсы
    ADMINS_ID список ID Telegram-юзеров, которым разрешено пользоваться
    FTP_SERVER / FTP_LOGIN / FTP_PASSWORD креды FTP-хостинга
    WP_URL / WP_LOGIN / WP_PASSWORD креды WordPress-юзера для form-логина
    WP_APP_PASSWORD Application Password для REST API (WP Admin → Users → Profile → Application Passwords)
    REDIS_PASSWORD произвольный, для встроенного redis
    LOCAL True если телеграм-API локальный
  3. Выбрать compose-файл:

    • Хост за рубежом / есть прямой доступ к Telegram DC → используй дефолтный docker-compose.yml (без прокси-слоя).
    • Хост в РФ / за блокировкой и есть SOCKS-прокси (например xray на localhost:10808) → docker-compose.tun2socks.yml (заворачивает трафик telegram-bot-api через tun2socks).
  4. Запустить bootstrap:

    chmod +x utils/bootstrap.sh
    
    # Прямой коннект (дефолт)
    ./utils/bootstrap.sh
    
    # С tun2socks (за блокировкой)
    ./utils/bootstrap.sh -f docker-compose.tun2socks.yml

    Скрипт проходит 7 фаз:

    1. Preflight: проверка docker/compose/curl/jq, .env, ключей по .env.example.
    2. Backup существующих volumes в ./backups/<utc-ts>/ (на первом запуске пропускается).
    3. docker compose pull + build.
    4. Поэтапный up: kafka → wait healthy → schema-registry → wait healthy → kafka-init → wait exit 0 → schema-watcher → sleep 60s → остальное.
    5. Verify topics: сверка с app/kafka/topics.yaml.
    6. Verify schemas: сверка с app/shared/kafka/schemas/*.avsc.
    7. Smoke pub/sub через временный топик bootstrap.smoke.<ts>.

    Скрипт идемпотентен — повторный запуск ничего не ломает.

Что доступно после успешного запуска

Сервис URL Зачем
Grafana http://<host>:3000 (admin/admin) Дашборды по бот/publisher метрикам, логи из Loki
Kafdrop http://<host>:9000 UI для Kafka — посмотреть топики, оффсеты, сообщения
Telegram бот в Telegram пишешь боту, проверяешь сценарии

Вторая Prometheus для метрик

Бот отдаёт метрики на bot:8080/metrics, публишеры пушат свои в Pushgateway; оттуда их скрейпит Prometheus этого стека. Сервис metrics-forwarder (Alloy, configs/metrics/personal-forwarder.alloy) шлёт копию метрик бота и публишеров ещё в одну Prometheus. Метрики хоста, Redis и Kafka туда не уходят.

Переменная .env По умолчанию Что делает
PERSONAL_METRICS_REMOTE_WRITE_URL пусто адрес .../api/v1/write приёмника (Prometheus с --web.enable-remote-write-receiver). Пусто: пересыльщик пишет одну строку в лог и ждёт
PERSONAL_METRICS_SOURCE podboxbot метка source у всех пересланных рядов

Сервис стартует вместе со стеком. После изменения адреса: docker compose up -d metrics-forwarder.

Какие метрики есть

Бот (bot:8080/metrics), кроме апдейтов и ошибок из SDK:

  • sagenza_event_upload_step_total{step, outcome}: шаги диалога загрузки (done, invalid, cancelled, expired, download_failed, number_failed);
  • sagenza_event_episode_prepared_total{type_episode, source}: готовые mp3 из диалога и из RSS;
  • sagenza_event_publish_requested_total{platform, type_episode, attempt}: нажатия кнопок публикации, attempt="repeat" у повторных;
  • sagenza_event_episode_published_total{platform, type_episode, action}, sagenza_event_publish_failed_total{platform, type_episode, stage}, sagenza_event_publish_retry_total{platform, stage};
  • podboxbot_time_to_publish_seconds{platform, type_episode} и podboxbot_time_to_publish_all_seconds{type_episode}: от получения mp3 до первой публикации на площадке и на всех площадках эпизода (нужен Redis);
  • podboxbot_episode_audio_size_bytes, podboxbot_episode_audio_duration_seconds, podboxbot_mp3_download_seconds;
  • sagenza_event_rss_poll_total{result}, sagenza_event_rss_episode_total{type_episode, via}, podboxbot_rss_last_success_timestamp_seconds, podboxbot_rss_consecutive_failures;
  • sagenza_event_admin_action_total{action}, podboxbot_active_admins{window}, podboxbot_admin_last_action_timestamp_seconds, podboxbot_admins_configured;
  • podboxbot_last_publish_timestamp_seconds{platform}, podboxbot_build_info{version}, sagenza_event_kafka_consumer_restart_total{topic};
  • process_*, python_*: память, CPU и GC процесса бота.

Публишеры (Pushgateway, <имя> это ftp, wp, boosty, vk, patreon, sponsr): <имя>_upload_{success,failure}_total{target}, <имя>_upload_retry_total{target, stage}, <имя>_upload_duration_seconds{target}, <имя>_upload_error_total{stage, error}, <имя>_last_success_timestamp_seconds, у Boosty ещё boosty_session_ok, boosty_session_expires_at_timestamp_seconds, boosty_session_refresh_total{result}.

В метках нет id пользователей, логинов и текстов: только площадка, тип эпизода, шаг, действие и класс ошибки; target это имя файла или номер эпизода.

Апгрейд

bootstrap.sh рассчитан на первый деплой. На горячий апгрейд:

git pull
docker compose build --no-cache bot publisher_ftp publisher_wordpress publisher_boosty
docker compose up -d

Устойчивость к ребуту хоста

После перезагрузки хоста Docker поднимает контейнеры по restart: always без соблюдения depends_on (это правило уровня docker compose up, а не рантайма демона). Поэтому бот/publisher'ы могут стартовать раньше Kafka и Schema Registry. Защита выстроена в три слоя:

  1. In-process readiness-гейты (app/shared/kafka/wait_for_kafka.py): каждый consumer ждёт Kafka + Schema Registry перед подпиской, каждый producer — перед первой публикацией. Порядок старта перестаёт иметь значение; события не теряются в окне прогрева.
  2. Супервайзер result-consumer'ов в боте: если consumer-loop падает или readiness истекает по таймауту — он перезапускается. Бот не остаётся «полуживым» (Telegram отвечает, а приём result-событий мёртв).
  3. systemd-юнит (deploy/podboxbot.service): на загрузке поднимает стек оркестрованно (docker compose up -d, depends_on соблюдается), на ребуте/останове — graceful docker compose stop (Kafka успевает дописать KRaft-логи → нет коррупции kafka_data). Установка — см. комментарий в самом файле юнита. После systemctl enable --now любой reboot (в т.ч. по cron) проходит безопасно.

Слои 1–2 работают сами по себе; слой 3 рекомендуется на проде, который регулярно перезагружается.

Разработка

  • Локальные venv'ы по сервисам:
    • cd app/bot && poetry install --with testing,dev
    • cd app/publishers/FTP && poetry install
    • cd app/publishers/WordPress && poetry install
    • cd app/publishers/Boosty && poetry install
  • Lint: poetry -C app/bot run ruff check app
  • Unit-тесты бота: make test, или из корня репозитория в окружении бота pytest --ignore=tests/e2e --ignore=tests/unit/publishers -q. Настройки pytest лежат в корневом pytest.ini, запускать нужно из корня и без -c: иначе фикстуры из conftest.py разных каталогов смешиваются. Тесты publisher-сервисов зависят от их собственных пакетов (asyncssh, aioprometheus и т.д.), которых нет в venv бота — запускай их из venv соответствующего сервиса, например: make test-publishers, или из корня в окружении сервиса pytest -o addopts="" tests/unit/publishers/ftp -q
  • CI (GitHub Actions, .github/workflows/ci.yml): ruff lint + format, тесты бота и отдельная джоба на каждый publisher-сервис (test-publisher-ftp / test-publisher-wordpress / test-publisher-boosty). main всегда зелёный.
  • Ветки: GitHub flow — ветка на задачу (feat/..., fix/..., chore/...) → PR в main → squash-merge. Напрямую в main не пушим; main всегда releasable.
  • Коммиты: Conventional Commits (feat(...), fix(...), refactor(...), chore(...)) — они же управляют версией релиза (см. ниже).

Релизы

Релизы автоматизированы через release-please (workflow .github/workflows/release-please.yml). Тегами, версией (version.txt) и CHANGELOG.md управляет CI — вручную их трогать не нужно.

На каждый push в main release-please пересчитывает следующую версию по типам коммитов и держит открытым release-PR с обновлённым changelog:

  • fix: → patch (0.3.0 → 0.3.1)
  • feat: → minor (0.3.0 → 0.4.0)
  • ! / BREAKING CHANGE: → major (пока версия 0.x и включён bump-minor-pre-major, ломающее идёт в minor)

Ветку release-PR release-please пересобирает поверх свежего main после каждого push (always-update в release-please-config.json), так что она не отстаёт от main даже после коммитов, которые не попадают в changelog. Проверки на release-PR запускает сам workflow release-please через workflow_dispatch: PR открыт от GITHUB_TOKEN, и обычный запуск по pull_request GitHub оставляет ждать ручного одобрения («action_required»). Одобрять его не нужно: запуск по dispatch копирует результаты обязательных джоб в статусы коммита с теми же именами (джоба report-required-checks), и правило main принимает их. Сами check runs запуска по workflow_dispatch GitHub в обязательные проверки PR не засчитывает. Если меняется список обязательных проверок в правиле, его же надо поправить в needs этой джобы.

Накопились изменения — смержи release-PR: release-please создаст тег vX.Y.Z, GitHub Release и обновит CHANGELOG.md. Единственный рычаг версии — типы Conventional Commits, попадающих в main.

Заметки к релизу для админов

После выкладки новой версии бот рассылает админам, что изменилось. Текст берётся не из CHANGELOG.md (там английские заголовки коммитов), а из release-notes/ru/<версия>.md: простой список пунктов на русском.

- Если сервер с эпизодами недоступен, бот сообщает об ошибке, а не зависает.
- Кнопка «Сайт» работает и для выпусков без таймкодов.

Строки с - или * становятся пунктами, строки с # пропускаются, остальное уходит как обычный текст. Пишем для людей, которые пользуются ботом: что изменилось для них, без названий модулей, номеров PR и хешей. Если файла для версии нет, админы получат только «Бот обновлён до версии X.»

Порядок такой:

  1. Пока открыт release-PR, смотрим в нём номер версии (.release-please-manifest.json).
  2. Обычным PR в main добавляем release-notes/ru/<версия>.md (коммит docs(release-notes): add notes for X.Y.Z).
  3. После мержа release-please пересоберёт свою ветку, и файл окажется в release-PR.

Джоба release-notes в CI падает на release-PR, если файла для его версии нет или он пустой. Если к релизу добавились новые изменения и версия выросла (например, 0.8.1 → 0.9.0), файл нужен под новый номер.

Лицензия

См. LICENSE.

About

Telegram bot that automates podcast episode publishing: mp3 tagging, FTP, WordPress with Podlove, paid platforms. Kafka microservices, Prometheus + Loki + Grafana.

Topics

Resources

Stars

0 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages