3252a8
a0ea2261f4
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
47 lines
4.4 KiB
Markdown
47 lines
4.4 KiB
Markdown
# Анонимная телеметрия установок
|
|
|
|
Чтобы понимать, сколько инсталляций активно и какие версии используются, бот может раз в сутки отправлять один **полностью обезличенный** «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` | Интервал между сигналами. |
|