> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bedolagam.ru/llms.txt
> Use this file to discover all available pages before exploring further.

# Мониторинг трафика

> Выявление злоупотреблений и аномального потребления трафика

## Обзор

Система мониторинга трафика v2 выявляет пользователей с аномально высоким потреблением и уведомляет администраторов. Работает в режиме **только уведомлений** — автоматической блокировки нет.

Два типа проверок:

* **Быстрая проверка** — дельта трафика между интервалами
* **Ежедневная проверка** — абсолютный объём за 24 часа

## Включение мониторинга

```env theme={null}
# Глобальный переключатель
TRAFFIC_MONITORING_ENABLED=true

# Быстрая проверка (дельта)
TRAFFIC_FAST_CHECK_ENABLED=true
TRAFFIC_FAST_CHECK_INTERVAL_MINUTES=10
TRAFFIC_FAST_CHECK_THRESHOLD_GB=5.0

# Ежедневная проверка (абсолютный объём за 24ч)
TRAFFIC_DAILY_CHECK_ENABLED=true
TRAFFIC_DAILY_CHECK_TIME=00:00
TRAFFIC_DAILY_THRESHOLD_GB=50.0
```

> [!NOTE]
>
> Все настройки можно менять **без перезапуска** через админ-панель (Мониторинг → Настройки трафика).

## Быстрая проверка (Fast Check)

Проверяет **дельту** — сколько трафика потрачено между двумя снимками.

### Как работает

1. При старте бота создаётся начальный снимок (snapshot) трафика всех пользователей
2. Каждые N минут загружаются текущие данные из Remnawave API
3. Для каждого пользователя вычисляется дельта: `текущий_трафик - предыдущий_трафик`
4. Если дельта превышает порог — отправляется уведомление администратору

> [!NOTE]
>
> При первом запуске проверка не выполняется — бот только сохраняет базовый снимок для последующего сравнения.

### Параметры

| Переменная | Тип | По умолчанию | Описание |
| - | - | - | - |
| `TRAFFIC_FAST_CHECK_ENABLED` | `bool` | `false` | Включить быструю проверку |
| `TRAFFIC_FAST_CHECK_INTERVAL_MINUTES` | `int` | `10` | Интервал между проверками (мин) |
| `TRAFFIC_FAST_CHECK_THRESHOLD_GB` | `float` | `5.0` | Порог дельты трафика (ГБ) |

## Ежедневная проверка (Daily Check)

Проверяет **абсолютный** объём трафика за последние 24 часа через Remnawave Bandwidth Stats API.

### Как работает

1. В указанное время запрашивает статистику трафика каждого пользователя за последние 24 часа
2. Если суммарный трафик превышает порог — отправляется уведомление
3. Запросы выполняются параллельно с ограничением конкурентности

### Параметры

| Переменная | Тип | По умолчанию | Описание |
| - | - | - | - |
| `TRAFFIC_DAILY_CHECK_ENABLED` | `bool` | `false` | Включить ежедневную проверку |
| `TRAFFIC_DAILY_CHECK_TIME` | `str` | `00:00` | Время проверки в формате `HH:MM` (UTC) |
| `TRAFFIC_DAILY_THRESHOLD_GB` | `float` | `50.0` | Порог трафика за 24 часа (ГБ) |

## Фильтрация

### По нодам

Можно указать **белый список** (мониторить только эти ноды) или **чёрный список** (мониторить все, кроме этих).

```env theme={null}
# Белый список — мониторить ТОЛЬКО эти ноды (приоритетнее чёрного)
TRAFFIC_MONITORED_NODES=uuid-node-1,uuid-node-2

# Чёрный список — мониторить все, КРОМЕ этих
TRAFFIC_IGNORED_NODES=uuid-test-node
```

> [!WARNING]
>
> Если указан `TRAFFIC_MONITORED_NODES`, то `TRAFFIC_IGNORED_NODES` игнорируется. Можно добавлять комментарии после `#`.

### По пользователям

Исключение сервисных/туннельных аккаунтов с высоким трафиком:

```env theme={null}
# UUID пользователей для исключения из проверок
TRAFFIC_EXCLUDED_USER_UUIDS=uuid-tunnel-account,uuid-service-account
```

Сравнение UUID регистронезависимое.

## Уведомления

### Куда отправляются

Уведомления отправляются в топик `SUSPICIOUS_NOTIFICATIONS_TOPIC_ID` (с фоллбэком на `ADMIN_NOTIFICATIONS_TOPIC_ID`).

```env theme={null}
SUSPICIOUS_NOTIFICATIONS_TOPIC_ID=123
```

### Защита от спама

| Механизм | Описание |
| - | - |
| **Кулдаун на пользователя** | Повторное уведомление по тому же пользователю не чаще `TRAFFIC_NOTIFICATION_COOLDOWN_MINUTES` (по умолчанию 60 мин) |
| **Лимит за проверку** | Максимум 10 уведомлений за одну проверку |
| **Задержка между отправками** | 0.5 сек между уведомлениями для защиты от rate limit Telegram |

```env theme={null}
TRAFFIC_NOTIFICATION_COOLDOWN_MINUTES=60
```

### Формат уведомления

```
⚠️ Превышение трафика

👤 Имя Фамилия
🆔 ID: 123456789
📱 Username: @username

🔑 UUID: user-uuid-here

⚡ Быстрая проверка
📊 За интервал: 7.50 ГБ
📊 Порог: 5.00 ГБ
🚨 Превышение: 2.50 ГБ

🖥 Сервер: DE-Frankfurt-1
   node-uuid-here

🕐 24.02.2026 15:30:00 UTC
```

Для ежедневной проверки заголовок меняется на «Суточная проверка», трафик показывается как «За 24 часа».

## Производительность

| Переменная | Тип | По умолчанию | Описание |
| - | - | - | - |
| `TRAFFIC_CHECK_BATCH_SIZE` | `int` | `1000` | Размер пакета при загрузке пользователей из Remnawave API |
| `TRAFFIC_CHECK_CONCURRENCY` | `int` | `10` | Параллельные запросы при ежедневной проверке |

## Хранение данных

Снимки трафика хранятся в **Redis** с автоматическим фоллбэком на оперативную память.

| Переменная | Тип | По умолчанию | Описание |
| - | - | - | - |
| `TRAFFIC_SNAPSHOT_TTL_HOURS` | `int` | `24` | Время жизни снимка в Redis (часы) |

**Redis-ключи:**

| Ключ | Содержимое |
| - | - |
| `traffic:snapshot` | JSON-словарь `{uuid: bytes}` |
| `traffic:snapshot:time` | Время последнего снимка (ISO) |
| `traffic:notifications:{uuid}` | Время последнего уведомления (TTL 24ч) |

> [!NOTE]
>
> При перезапуске бота снимок из Redis переиспользуется — не нужно ждать повторного накопления данных.

## Админ-панель

В разделе **Мониторинг** доступны:

* **Проверка трафика** — ручной запуск быстрой проверки с отображением результатов (топ-10 нарушителей)
* **Настройки трафика** — изменение всех параметров без перезапуска:
  * Вкл/выкл быстрой и ежедневной проверок
  * Интервал, пороги, время ежедневной проверки
  * Кулдаун уведомлений
  * Информация о фильтрах нод и пользователей (только чтение)

## Устаревшие параметры

Для обратной совместимости с v1 поддерживаются:

| Переменная | Описание |
| - | - |
| `TRAFFIC_THRESHOLD_GB_PER_DAY` | Порог в ГБ/день (используется как порог быстрой проверки если `TRAFFIC_FAST_CHECK_ENABLED=false`) |
| `TRAFFIC_MONITORING_INTERVAL_HOURS` | Интервал в часах (конвертируется в секунды) |

> [!WARNING]
>
> Рекомендуется использовать новые переменные `TRAFFIC_FAST_CHECK_*` и `TRAFFIC_DAILY_*` вместо устаревших.

## Полный пример конфигурации

```env theme={null}
# Глобальный переключатель
TRAFFIC_MONITORING_ENABLED=true

# Быстрая проверка: каждые 5 минут, порог 3 ГБ
TRAFFIC_FAST_CHECK_ENABLED=true
TRAFFIC_FAST_CHECK_INTERVAL_MINUTES=5
TRAFFIC_FAST_CHECK_THRESHOLD_GB=3.0

# Ежедневная проверка: в полночь, порог 30 ГБ
TRAFFIC_DAILY_CHECK_ENABLED=true
TRAFFIC_DAILY_CHECK_TIME=00:00
TRAFFIC_DAILY_THRESHOLD_GB=30.0

# Мониторить только определённые ноды
TRAFFIC_MONITORED_NODES=uuid-prod-node-1,uuid-prod-node-2

# Исключить сервисные аккаунты
TRAFFIC_EXCLUDED_USER_UUIDS=uuid-tunnel-account

# Уведомления: кулдаун 30 минут, в отдельный топик
TRAFFIC_NOTIFICATION_COOLDOWN_MINUTES=30
SUSPICIOUS_NOTIFICATIONS_TOPIC_ID=123

# Производительность
TRAFFIC_CHECK_BATCH_SIZE=500
TRAFFIC_CHECK_CONCURRENCY=5
TRAFFIC_SNAPSHOT_TTL_HOURS=48
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.