Denozordec
d7a63f0da3
- Introduced GeoIP configuration options in config.example.yaml to enable geolocation lookups for the /api/agg/unique-ips endpoint. - Updated the aggregate handler to include optional GeoIP data in responses, enriching unique IP information with country and city details, as well as ASN data if available. - Enhanced documentation in AGGREGATE.md and README.md to reflect the new GeoIP functionality and its usage. - Added a dependency on the geoip2-golang library in go.mod for GeoIP lookups. - Modified tests to accommodate the new GeoIP integration in the aggregate handler.
56 lines
4.8 KiB
Markdown
56 lines
4.8 KiB
Markdown
# Агрегирующие эндпоинты шлюза (`/api/agg/`)
|
||
|
||
Шлюз **telemt-api** опрашивает несколько upstream [Telemt Control API](API.md) (`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](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 списках снимка. При **`geoip.enabled`** в конфиге — из City: `country_code`, `country_name`, `city_name`; при наличии ASN-БД — `asn`, `as_organization` (см. [GEOIP.md](GEOIP.md)); отключить гео для запроса: `?geo=false`. |
|
||
| 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`, он приоритетнее). |
|
||
|
||
## Конфигурация (опционально)
|
||
|
||
```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_megabytes=1"
|
||
```
|