Add aggregate configuration support and update documentation

- Introduced AggregateConfig to manage aggregation settings in the gateway configuration. - Added validation for reserved alias 'agg' and included tests for aggregate alias handling. - Updated config.example.yaml to demonstrate aggregate configuration options. - Enhanced README.md to include information about the new aggregation endpoint and its usage. - Modified gateway.go to integrate the new aggregate handler for processing aggregation requests.
2026-03-30 00:51:19 +07:00
parent 89638d29bb
commit 54306ec6c4
12 changed files with 1031 additions and 6 deletions
@@ -0,0 +1,52 @@
+# Агрегирующие эндпоинты шлюза (`/api/agg/`)
+
+Шлюз **telemt-api** опрашивает несколько upstream [Telemt Control API](API.md) (`GET /v1/stats/users` на каждом сервере из конфигурации) и отдаёт сводные JSON-ответы в формате `{"ok": true, "data": ...}`.
+
+Доступ к **одному** инстансу по-прежнему через прокси: `GET /api/{alias}/…` (например `/api/gt1/v1/stats/users`).
+
+## Маршруты
+
+| Метод | Путь | Описание |
+| --- | --- | --- |
+| GET | `/api/agg/summary` | Сводка по флоту, список опросов upstream, топ пользователей по суммарному `total_octets`. |
+| GET | `/api/agg/traffic` | Трафик по каждому пользователю в разрезе серверов (алиасов). |
+| GET | `/api/agg/unique-ips` | Уникальные IP по пользователю: на каких серверах IP есть в active/recent списках снимка. |
+| GET | `/api/agg/users` | Объединённый список пользователей с `by_server` и суммарным `total_octets`. |
+
+Все методы — **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_octets` | `users` | Отфильтровать пользователей с суммарным трафиком ниже порога. |
+
+## Конфигурация (опционально)
+
+```yaml
+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` отсутствует или несколько серверов в списках — это снимок, не история.
+
+## Примеры
+
+```bash
+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_octets=1000000"
+```