3252a8
6bb2709244
Stamp official Docker builds with a low-cardinality provenance marker and report build_provenance/image_modified in anonymous telemetry. Local and fork builds default to custom, while official GitHub/GitLab release paths mark images as official.
49 lines
5.0 KiB
Markdown
49 lines
5.0 KiB
Markdown
# Анонимная телеметрия установок
|
|
|
|
Чтобы понимать, сколько инсталляций активно и какие версии используются, бот может раз в сутки отправлять один **полностью обезличенный** «heartbeat». Телеметрия задумана как self-hosted friendly: её легко выключить, она не содержит персональных данных и не мешает работе бота.
|
|
|
|
## Что отправляется
|
|
|
|
Каждый сигнал — это случайный непривязанный идентификатор установки плюс грубые факты об окружении:
|
|
|
|
| Поле | Пример | Назначение |
|
|
| --- | --- | --- |
|
|
| `installation_id` | `f47ac10b-...` (UUIDv4) | Случайный идентификатор установки. Генерируется один раз, хранится в БД. Не выводится из токена, домена или ID администраторов. |
|
|
| `app_version` | `v3.4.6+gabc1234` | Полная версия сборки. |
|
|
| `app_version_tag` | `v3.4.6` | Релизный тег для разбивки по версиям. |
|
|
| `build_provenance` | `official` / `custom` | Маркер происхождения образа. `official` ставится только официальной сборкой проекта; локальные сборки и форки считаются `custom`. |
|
|
| `image_modified` | `false` / `true` | Удобный булевый флаг для разбивки: `false` только у официальных образов, `true` у локальных/форк-сборок. |
|
|
| `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 или данные пользователей, точное число пользователей, какой-либо контент, registry образа или URL форка.
|
|
|
|
## Как выключить
|
|
|
|
Достаточно любого из способов:
|
|
|
|
- **`.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` | Интервал между сигналами. |
|