202 lines
5.3 KiB
Markdown
202 lines
5.3 KiB
Markdown
# OpenVPN Monitor API v2 Documentation
|
||
|
||
Этот API предоставляет доступ к данным мониторинга OpenVPN, включая статус клиентов в реальном времени и исторические данные, хранящиеся в Time Series Database (TSDB).
|
||
|
||
**Base URL:** `http://<your-server-ip>:5001/api/v1`
|
||
|
||
---
|
||
|
||
## 1. Статистика по клиенту (Детальная + История)
|
||
|
||
Основной эндпоинт для построения графиков и отчетов. Поддерживает динамическую агрегацию данных (умный выбор детализации).
|
||
|
||
### `GET /stats/<common_name>`
|
||
|
||
#### Параметры запроса (Query Parameters)
|
||
|
||
| Параметр | Тип | По умолчанию | Описание |
|
||
| :--- | :--- | :--- | :--- |
|
||
| `range` | string | `24h` | Период выборки. Поддерживаются форматы: `24h` (часы), `7d` (дни), `30d`, `1y` (годы). |
|
||
| `resolution` | string | `auto` | Принудительная детализация данных. <br>**Значения:**<br>`auto` — автоматический выбор (см. логику ниже)<br>`raw` — сырые данные (каждые 10-30 сек)<br>`5min` — 5 минут<br>`hourly` — 1 час<br>`6h` — 6 часов<br>`daily` — 1 день |
|
||
|
||
#### Логика `resolution=auto`
|
||
API автоматически выбирает таблицу источника данных в зависимости от длительности диапазона:
|
||
* **≤ 24 часов:** `usage_history` (Сырые данные)
|
||
* **≤ 7 дней:** `stats_hourly` (Агрегация по часам)
|
||
* **≤ 3 месяцев:** `stats_6h` (Агрегация по 6 часов)
|
||
* **> 3 месяцев:** `stats_daily` (Агрегация по дням)
|
||
|
||
#### Пример запроса
|
||
|
||
```http
|
||
GET /api/v1/stats/user-alice?range=7d
|
||
|
||
```
|
||
|
||
#### Пример ответа
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"timestamp": "2026-01-08 14:30:00",
|
||
"data": {
|
||
"common_name": "user-alice",
|
||
"status": "Active",
|
||
"real_address": "192.168.1.50:54321",
|
||
"last_activity": "N/A",
|
||
"current_rates": {
|
||
"recv_mbps": 1.5,
|
||
"sent_mbps": 0.2
|
||
},
|
||
"totals": {
|
||
"received_mb": 500.25,
|
||
"sent_mb": 120.10
|
||
},
|
||
"meta": {
|
||
"resolution_used": "stats_hourly",
|
||
"start": "2026-01-01 14:30:00",
|
||
"end": "2026-01-08 14:30:00",
|
||
"record_count": 168
|
||
},
|
||
"history": [
|
||
{
|
||
"timestamp": "2026-01-01 15:00:00",
|
||
"bytes_received": 1048576,
|
||
"bytes_sent": 524288,
|
||
"bytes_received_rate_mbps": 0,
|
||
"bytes_sent_rate_mbps": 0
|
||
},
|
||
...
|
||
]
|
||
}
|
||
}
|
||
|
||
```
|
||
|
||
> **Примечание:** Поля `*_rate_mbps` в массиве `history` возвращают `0` для агрегированных данных (hourly, daily), так как агрегация хранит только суммарный объем трафика.
|
||
|
||
---
|
||
|
||
## 2. Текущая статистика (Все клиенты)
|
||
|
||
Возвращает мгновенный снимок состояния всех известных клиентов.
|
||
|
||
### `GET /stats`
|
||
|
||
#### Пример ответа
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"count": 2,
|
||
"data": [
|
||
{
|
||
"common_name": "user-alice",
|
||
"status": "Active",
|
||
"real_address": "192.168.1.50:54321",
|
||
"current_recv_rate_mbps": 1.5,
|
||
"current_sent_rate_mbps": 0.2,
|
||
"total_received_mb": 500.25,
|
||
"total_sent_mb": 120.10,
|
||
"last_activity": "N/A"
|
||
},
|
||
{
|
||
"common_name": "user-bob",
|
||
"status": "Disconnected",
|
||
"real_address": null,
|
||
"current_recv_rate_mbps": 0,
|
||
"current_sent_rate_mbps": 0,
|
||
"total_received_mb": 1500.00,
|
||
"total_sent_mb": 300.00,
|
||
"last_activity": "2026-01-08 10:00:00"
|
||
}
|
||
]
|
||
}
|
||
|
||
```
|
||
|
||
---
|
||
|
||
## 3. Системная статистика
|
||
|
||
Сводная информация по всему серверу OpenVPN.
|
||
|
||
### `GET /stats/system`
|
||
|
||
#### Пример ответа
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"total_clients": 15,
|
||
"active_clients": 3,
|
||
"total_bytes_received": 10737418240,
|
||
"total_bytes_sent": 5368709120,
|
||
"total_received_gb": 10.0,
|
||
"total_sent_gb": 5.0
|
||
}
|
||
}
|
||
|
||
```
|
||
|
||
---
|
||
|
||
## 4. Сертификаты
|
||
|
||
Информация о сроках действия SSL сертификатов пользователей.
|
||
|
||
### `GET /certificates`
|
||
|
||
#### Пример ответа
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": [
|
||
{
|
||
"file": "user-alice.crt",
|
||
"common_name": "user-alice",
|
||
"days_remaining": "360 days",
|
||
"is_expired": false,
|
||
"not_after": "Jan 8 12:00:00 2027 GMT"
|
||
}
|
||
]
|
||
}
|
||
|
||
```
|
||
|
||
---
|
||
|
||
## 5. Вспомогательные методы
|
||
|
||
### Список клиентов (Упрощенный)
|
||
|
||
Используется для заполнения выпадающих списков в интерфейсе.
|
||
|
||
### `GET /clients`
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": [
|
||
{"common_name": "user-alice", "status": "Active"},
|
||
{"common_name": "user-bob", "status": "Disconnected"}
|
||
]
|
||
}
|
||
|
||
```
|
||
|
||
### Проверка здоровья (Health Check)
|
||
|
||
Проверяет доступность базы данных.
|
||
|
||
### `GET /health`
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"status": "healthy"
|
||
}
|
||
|
||
``` |