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'ом автоматически при старте.
- Linux (Debian/Ubuntu проверены).
docker≥ 23,docker composev2,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-
Клонировать репо:
git clone https://github.com/k0te1ch/PodBoxBot.git cd PodBoxBotmainвсегда releasable; для воспроизводимого деплоя можно выехать на тег последнего релиза (git checkout v0.3.1). -
Подготовить
.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_USERNAMEusername публичной группы/канала (формат @group) или числовой id чата, в котором бот состоит: туда бот будет форвардить анонсыADMINS_IDсписок ID Telegram-юзеров, которым разрешено пользоваться FTP_SERVER/FTP_LOGIN/FTP_PASSWORDкреды FTP-хостинга WP_URL/WP_LOGIN/WP_PASSWORDкреды WordPress-юзера для form-логина WP_APP_PASSWORDApplication Password для REST API (WP Admin → Users → Profile → Application Passwords) REDIS_PASSWORDпроизвольный, для встроенного redis LOCALTrueесли телеграм-API локальный -
Выбрать compose-файл:
- Хост за рубежом / есть прямой доступ к Telegram DC → используй
дефолтный
docker-compose.yml(без прокси-слоя). - Хост в РФ / за блокировкой и есть SOCKS-прокси (например xray на
localhost:10808) →docker-compose.tun2socks.yml(заворачивает трафик telegram-bot-api черезtun2socks).
- Хост за рубежом / есть прямой доступ к Telegram DC → используй
дефолтный
-
Запустить bootstrap:
chmod +x utils/bootstrap.sh # Прямой коннект (дефолт) ./utils/bootstrap.sh # С tun2socks (за блокировкой) ./utils/bootstrap.sh -f docker-compose.tun2socks.yml
Скрипт проходит 7 фаз:
- Preflight: проверка docker/compose/curl/jq,
.env, ключей по.env.example. - Backup существующих volumes в
./backups/<utc-ts>/(на первом запуске пропускается). docker compose pull + build.- Поэтапный
up: kafka → wait healthy → schema-registry → wait healthy → kafka-init → wait exit 0 → schema-watcher → sleep 60s → остальное. - Verify topics: сверка с
app/kafka/topics.yaml. - Verify schemas: сверка с
app/shared/kafka/schemas/*.avsc. - Smoke pub/sub через временный топик
bootstrap.smoke.<ts>.
Скрипт идемпотентен — повторный запуск ничего не ломает.
- Preflight: проверка docker/compose/curl/jq,
| Сервис | URL | Зачем |
|---|---|---|
| Grafana | http://<host>:3000 (admin/admin) |
Дашборды по бот/publisher метрикам, логи из Loki |
| Kafdrop | http://<host>:9000 |
UI для Kafka — посмотреть топики, оффсеты, сообщения |
| Telegram бот | в Telegram | пишешь боту, проверяешь сценарии |
Бот отдаёт метрики на 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. Защита выстроена в три слоя:
- In-process readiness-гейты (
app/shared/kafka/wait_for_kafka.py): каждый consumer ждёт Kafka + Schema Registry перед подпиской, каждый producer — перед первой публикацией. Порядок старта перестаёт иметь значение; события не теряются в окне прогрева. - Супервайзер result-consumer'ов в боте: если consumer-loop падает или readiness истекает по таймауту — он перезапускается. Бот не остаётся «полуживым» (Telegram отвечает, а приём result-событий мёртв).
- systemd-юнит (
deploy/podboxbot.service): на загрузке поднимает стек оркестрованно (docker compose up -d, depends_on соблюдается), на ребуте/останове — gracefuldocker compose stop(Kafka успевает дописать KRaft-логи → нет коррупцииkafka_data). Установка — см. комментарий в самом файле юнита. Послеsystemctl enable --nowлюбойreboot(в т.ч. по cron) проходит безопасно.
Слои 1–2 работают сами по себе; слой 3 рекомендуется на проде, который регулярно перезагружается.
- Локальные venv'ы по сервисам:
cd app/bot && poetry install --with testing,devcd app/publishers/FTP && poetry installcd app/publishers/WordPress && poetry installcd 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.»
Порядок такой:
- Пока открыт release-PR, смотрим в нём номер версии (
.release-please-manifest.json). - Обычным PR в
mainдобавляемrelease-notes/ru/<версия>.md(коммитdocs(release-notes): add notes for X.Y.Z). - После мержа release-please пересоберёт свою ветку, и файл окажется в release-PR.
Джоба release-notes в CI падает на release-PR, если файла для его версии
нет или он пустой. Если к релизу добавились новые изменения и версия
выросла (например, 0.8.1 → 0.9.0), файл нужен под новый номер.
См. LICENSE.