> ## 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
```

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

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

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

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

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

<Note>
  При первом запуске проверка не выполняется — бот только сохраняет базовый снимок для последующего сравнения.
</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` игнорируется. Можно добавлять комментарии после `#`.
</Warning>

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

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

```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 переиспользуется — не нужно ждать повторного накопления данных.
</Note>

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

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

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

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

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

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

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

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

```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
```