Files

T

3252a8 a0ea2261f4 feat: anonymous opt-out install telemetry beacon

Add a once-a-day anonymous heartbeat (PostHog) so maintainers can see
active installs and version/OS breakdowns. Self-hosted friendly: opt out
via TELEMETRY_ENABLED in .env or the Admin -> System toggle (applied
without a restart), or by clearing the endpoint/key.

- Share version resolution in bot/utils/app_version.py so the admin
  sidebar and the beacon report the same build version
- TelemetryWorker sends an opaque install id plus coarse facts only
  (version, OS/arch, python, locale, enabled providers, user-count
  range); never tokens, domains or user data
- Register the worker in main_worker.py behind a Redis single-flight lock
- Expose TELEMETRY_* settings and an Admin -> System manifest toggle
- Document the payload and opt-out in docs/configuration/telemetry.md
- Cover bucketing, payload shape and anonymity with tests

2026-06-01 14:14:02 +03:00

4.4 KiB

Raw Blame History

Анонимная телеметрия установок

Чтобы понимать, сколько инсталляций активно и какие версии используются, бот может раз в сутки отправлять один полностью обезличенный «heartbeat». Телеметрия задумана как self-hosted friendly: её легко выключить, она не содержит персональных данных и не мешает работе бота.

Что отправляется

Каждый сигнал — это случайный непривязанный идентификатор установки плюс грубые факты об окружении:

Поле	Пример	Назначение
`installation_id`	`f47ac10b-...` (UUIDv4)	Случайный идентификатор установки. Генерируется один раз, хранится в БД. Не выводится из токена, домена или ID администраторов.
`app_version`	`v3.4.6+gabc1234`	Полная версия сборки.
`app_version_tag`	`v3.4.6`	Релизный тег для разбивки по версиям.
`os` / `arch`	`linux` / `x86_64`	Платформа.
`python_version`	`3.12.7`	Версия рантайма.
`locale`	`ru`	Язык по умолчанию.
`payment_providers`	`["stars", "yookassa"]`	Идентификаторы включённых платёжных провайдеров (без ключей и секретов).
`users_bucket`	`51-200`	Число пользователей в виде диапазона, не точное значение.
`webapp_enabled` / `panel_configured`	`true`	Флаги конфигурации.

Время приёма (last_seen) проставляет коллектор. «Активные установки» = уникальные installation_id, от которых сигнал приходил за последние ~48 часов; «разбивка по версиям» = последняя версия на каждую установку.

Чего там нет

Никогда не отправляются: токен бота, домены, URL вебхуков, ключи платёжных систем и Remnawave, ID или данные пользователей, точное число пользователей, какой-либо контент.

Как выключить

Достаточно любого из способов:

.env: TELEMETRY_ENABLED=False, затем перезапуск.
Веб-админка: Admin → System → «Анонимная статистика установки». Переключатель применяется без перезапуска (читается из БД на каждом тике).
Сборка/образ: оставить пустыми TELEMETRY_ENDPOINT или TELEMETRY_API_KEY — без точки доставки беакон не запускается.

Доставка

Беакон шлёт POST {TELEMETRY_ENDPOINT}/capture/ в формате PostHog ({api_key, event, distinct_id, properties}). Доставка строго fire-and-forget: таймаут 10 секунд, любые ошибки проглатываются и логируются на уровне debug — телеметрия не может задержать или уронить воркер. При нескольких репликах воркера за интервал отправляет только одна (через Redis-lock).

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

Переменная	По умолчанию	Назначение
`TELEMETRY_ENABLED`	`True`	Главный переключатель (opt-out). Дублируется тогглом в админке.
`TELEMETRY_ENDPOINT`	`https://eu.i.posthog.com`	Хост приёма PostHog. Пусто — телеметрия выключена.
`TELEMETRY_API_KEY`	пусто	Project API key PostHog (`phc_...`). Это write-only ключ ingest, его безопасно зашивать в образ. Пусто — телеметрия выключена.
`TELEMETRY_INTERVAL_HOURS`	`24`	Интервал между сигналами.

4.4 KiB Raw Blame History