denozord/telemt-api

Fork 0

Files

T

Denozordec 4a4f15bd0b

Publish telemt-api gateway Docker image / test (push) Successful in 27s

Details

Publish telemt-api gateway Docker image / build-and-push (push) Successful in 1m26s

Details

Update aggregate API to use binary megabytes and enhance documentation

- Changed API responses and internal calculations to use binary megabytes (MiB) instead of octets for traffic metrics.
- Updated relevant endpoints in AGGREGATE.md to reflect the new metric units.
- Modified handler and merge logic to accommodate the new data structure and ensure accurate traffic reporting.
- Enhanced tests to validate the changes in traffic calculations and summary data.
- Deprecated the use of total_octets in favor of total_megabytes for consistency across the API.

2026-03-30 01:04:00 +07:00

4.5 KiB

Raw Blame History

Агрегирующие эндпоинты шлюза (`/api/agg/`)

Шлюз telemt-api опрашивает несколько upstream Telemt Control API (GET /v1/stats/users на каждом сервере из конфигурации) и отдаёт сводные JSON-ответы в формате {"ok": true, "data": ...}.

Единицы трафика в агрегатах: поля *_megabytes — это двоичные мегабайты (MiB), 1 MiB = 1024² октетов (как у Telemt в ответе считаются октеты, шлюз делит на MiB для удобства).

Доступ к одному инстансу по-прежнему через прокси: GET /api/{alias}/… (например /api/gt1/v1/stats/users) — там по-прежнему total_octets как в API.md.

Маршруты

Метод	Путь	Описание
GET	`/api/agg/summary`	Сводка по флоту, список опросов upstream, `fleet_total_megabytes` / `fleet_total_connections`. Два топа (размер задаётся `top_n`): `top_users` — самые «прожорливые» по суммарному трафику (MiB) по всем серверам; `top_users_by_unique_ips` — по максимальному `active_unique_ips` среди серверов для пользователя (как в Telemt, снимок).
GET	`/api/agg/traffic`	Трафик по каждому пользователю в разрезе серверов: `servers.<alias>.total_megabytes`.
GET	`/api/agg/unique-ips`	Уникальные IP по пользователю: на каких серверах IP есть в active/recent списках снимка.
GET	`/api/agg/users`	Объединённый список пользователей с `by_server` и суммарным `total_megabytes`.

Все методы — GET; действует тот же whitelist, что и для остального API шлюза.

Query-параметры

Параметр	Где	Значение
`aliases`	все	Список алиасов через запятую (например `gt1,gt2`). Если не задан — см. `aggregate.include_aliases` в YAML или все серверы из `servers`.
`top_n`	`summary`	Размер топа пользователей (по умолчанию `10`, максимум `1000`).
`include_links`	`users`	`true` — добавить сгенерированные `tg://proxy` ссылки (берётся первая успешная запись по пользователю).
`min_total_megabytes`	`users`	Порог суммарного трафика пользователя в MiB (строго больше 0).
`min_total_octets`	`users`	Устаревший вариант порога в октетах (если задан `min_total_megabytes`, он приоритетнее).

Конфигурация (опционально)

aggregate:
  include_aliases:
    - gt1
    - gt2

Если блок отсутствует или include_aliases пуст, по умолчанию участвуют все записи servers.

Имя алиаса agg в servers запрещено (зарезервировано под префикс /api/agg/).

Ограничения

Один и тот же username на разных серверах может соответствовать разным учётным записям; агрегатор сопоставляет строки по имени — учитывайте при интерпретации сумм.
У Telemt в UserInfo нет поля «IP последний раз подключался к серверу X». В unique-ips поле primary_server заполняется только если ровно один сервер видит IP в active_unique_ips_list на момент запроса; иначе primary_server отсутствует или несколько серверов в списках — это снимок, не история.

Примеры

curl -sS "http://127.0.0.1:8080/api/agg/summary"
curl -sS "http://127.0.0.1:8080/api/agg/traffic?aliases=gt1,gt2"
curl -sS "http://127.0.0.1:8080/api/agg/unique-ips"
curl -sS "http://127.0.0.1:8080/api/agg/users?include_links=false&min_total_megabytes=1"

4.5 KiB Raw Blame History Unescape Escape

Агрегирующие эндпоинты шлюза (/api/agg/)