Централизованный контроль устройств для Remnawave

Мониторит одновременные подключения пользователей через API панели: собирает IP со всех нод, сравнивает с лимитом устройств каждого пользователя (hwidDeviceLimit) и реагирует на превышения — через Telegram-бота или автоматической блокировкой подписки.

English version · 简体中文

• Агрегация IP со всех нод — полная картина подключений, сравнение с индивидуальным лимитом + погрешность (tolerance)
• Два режима: manual — алерт с inline-кнопками (сброс, бан, whitelist); auto — автоблокировка с автовосстановлением по таймеру
• Порог нарушений — действие только после N превышений за окно (защита от ложных срабатываний)
• Группировка IP по подсетям (/24) или по ASN-провайдерам — против CGNAT и шаринга
• Webhook (JSON POST) о нарушениях с HMAC-подписью
• Статистика и отчёты — команда /stats (за 24ч/неделю + топ-5 нарушителей) и ежедневный отчёт в чат
• Рантайм-настройки через /settings — изменение параметров на лету без перезапуска (хранятся в Redis)
• Whitelist пользователей и IP/CIDR, кулдаун, кэш, выбор часового пояса, ru/en
• Liveness /healthz (опционально, по HEALTH_ADDR) для healthcheck в Docker/оркестраторе
• Логи под docker compose logs -f — сводка по каждому циклу проверки, уровень меняется на лету, LOG_FORMAT=json для Loki/ELK

┌─────────────┐     ┌──────────────────┐     ┌───────────────┐
│  Remnawave  │◄────│  remnawave-      │────►│   Telegram    │
│  Panel API  │     │  limiter         │     │   Bot API     │
└─────────────┘     │  (Go binary)     │     └───────────────┘
                    │  ┌────────────┐  │
                    │  │   Redis    │  │
                    │  └────────────┘  │
                    └──────────────────┘

Один инстанс рядом с панелью или на любом сервере. Установка на ноды не нужна — всё через API. Docker Compose поднимает сервис + Redis.

Цикл проверки: список нод (GET /api/nodes) → параллельный сбор IP по нодам → агрегация по пользователю → фильтр по lastSeen → сравнение с лимит + погрешность → инкремент порогового счётчика → при достижении порога реакция (алерт или автоблокировка).

Сбойная нода не роняет цикл: проверка выполняется по остальным, а в лог идёт предупреждение о неполных данных. Если не ответила ни одна нода, цикл пропускается целиком — иначе отсутствие подключений было бы прочитано как «все в пределах лимита».

• Docker и Docker Compose
• Remnawave 3.0.0+ с API-токеном (scope connections:*, users:* и nodes:read)
• Telegram-бот (@BotFather)

Версии совместимы только в одну сторону: в Remnawave 3.0.0 модуль ip-control переименован в connections, а пользователи идентифицируются числовым id вместо uuid — старые эндпоинты удалены. Поэтому limiter 4.0.0+ не работает с панелью 2.x, а limiter 3.0.0 — с панелью 3.x.

Если панель ещё не обновлена, зафиксируйте образ на релизе 3.0.0 в docker-compose.yml:

image: ghcr.io/syvlech/remnawave-limiter:b422f43

b422f43 — коммит релиза 3.0.0. Отдельного тега образа 3.0.0 в ghcr нет: CI собирает semver-теги только для рефов вида v*, а релиз помечен как 3.0.0 без префикса.

mkdir -p /opt/remnawave-limiter && cd /opt/remnawave-limiter

curl -O https://raw.githubusercontent.com/syvlech/remnawave-limiter/master/docker-compose.yml
curl -O https://raw.githubusercontent.com/syvlech/remnawave-limiter/master/.env.example

cp .env.example .env && nano .env

Обязательные параметры в .env:

REMNAWAVE_API_URL=https://panel.example.com
REMNAWAVE_API_TOKEN=your-api-token-here
TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11X
TELEGRAM_CHAT_ID=-1001234567890
TELEGRAM_ADMIN_IDS=123456789

Запуск, логи и обновление:

docker compose pull && docker compose up -d   # запуск / обновление
docker compose logs -f limiter                # проверка

Все настройки — через .env или переменные окружения.

ASN в уведомлениях. Если база MaxMind доступна, рядом с каждым IP в алерте и webhook показывается провайдер (• 91.107.96.11 - Hetzner Online GmbH (Chicago-1)), а в заголовке — счётчик уникальных ASN (Обнаружено: 4 IP (3 ASN)). На логику ограничения не влияет — решения только по количеству IP/подсетей/ASN.

При VIOLATION_THRESHOLD=1 (по умолчанию) реакция на каждое превышение. При большем значении действие выполняется только после накопления N нарушений в окне VIOLATION_THRESHOLD_WINDOW: превышение → проверка cooldown → инкремент счётчика (TTL = окно) → при достижении порога действие и сброс счётчика. Если между нарушениями проходит больше окна — счётчик обнуляется.

Cooldown ставится до инкремента, поэтому счётчик растёт не чаще раза за COOLDOWN, а следующее нарушение замечается на ближайшей проверке. Окно должно вмещать N − 1 таких шагов: VIOLATION_THRESHOLD_WINDOW > (VIOLATION_THRESHOLD − 1) × (COOLDOWN + CHECK_INTERVAL). Конфиг, где это не выполняется, отклоняется при старте и в /settings — иначе порог никогда не был бы достигнут и лимитер молча перестал бы действовать.

Пример при VIOLATION_THRESHOLD=3, VIOLATION_THRESHOLD_WINDOW=3600:

Все сообщения бота — rich-сообщения Telegram (Bot API 10.3, sendRichMessage): заголовки, таблицы, сворачиваемые блоки, время в часовом поясе читателя (tg-time) и цветные кнопки прямо внутри сообщения. Если Telegram отклонит rich-разметку, сообщение всё равно уйдёт — обычным текстом с inline-кнопками. Для отображения нужен клиент Telegram с поддержкой rich-сообщений.

Доступны только администраторам из TELEGRAM_ADMIN_IDS. Регистрируются в меню бота автоматически при старте.

Приоритет источников: Redis-override > .env / переменные окружения > значения по умолчанию. Изменения применяются на лету (например, CHECK_INTERVAL пересоздаёт тикер). Структурные и секретные ключи (API URL/токен, все TELEGRAM_*, REDIS_URL, TIMEZONE, LANGUAGE, WEBHOOK_*, IP_WHITELIST, IGNORED_NODE_UUIDS, MAXMIND_*, DAILY_REPORT_TIME, HEALTH_ADDR, LOG_FORMAT) меняются только через .env + перезапуск. Кнопка «Сбросить к .env» (для ключа или для всех, с подтверждением) убирает override.

Меню работает в одном сообщении, которое перерисовывается на месте:

• Главный экран — таблица всех параметров по разделам (🎯 Обнаружение, 🛡 Действия, ⏳ Пороги и кулдауны, 🌐 Группировка, 🧰 Сервис); ♻️ отмечает значения, изменённые в боте.
• Раздел — значения, подсказки к каждому параметру и кнопки: флаги переключаются одним нажатием (включённые — зелёные), остальные открывают экран редактирования.
• Редактирование — текущее значение, источник (.env или бот), имя переменной, быстрые пресеты (для минут — в человекочитаемом виде, 0 = «навсегда») и ввод своего значения сообщением. Ошибка валидации показывается на том же экране, ввод можно сразу повторить.

Раз в сутки в DAILY_REPORT_TIME (локальное время в TIMEZONE) бот присылает в чат тот же отчёт, что и /stats (нарушений за 24ч/неделю + топ-5). Учитываются только реальные срабатывания после порога VIOLATION_THRESHOLD; «мягкие» предупреждения в статистику не попадают. DAILY_REPORT переключается на лету через /settings, время DAILY_REPORT_TIME — только перезапуском.

При превышении бот отправляет алерт с кнопками:

⚠️ Превышение лимита устройств
┌──────────────────────┬──────────────────────┐
│ 👤 Пользователь      │ username123          │
│ 🔗 Подписка          │ открыть              │
│ 📊 Лимит             │ 3                    │
│ 📡 Обнаружено        │ 5 IP · 2 ASN         │
│ 🚦 Превышение        │ +2                   │
│ 📈 Нарушений за 24ч  │ 3                    │
│ 🕐 Время             │ сб, 29.11 04:15      │  ← в часовом поясе читателя
└──────────────────────┴──────────────────────┘
▾ 📍 IP-адреса (5)
  IP          Провайдер      Нода
  10.0.1.10   Hetzner        node-1
  10.0.3.30   Cloudflare     node-2

[🔄 Сбросить подключения]
[🔒 Отключить навсегда] [🔒 Отключить на 10 мин]  ← вторая — если AUTO_DISABLE_DURATION > 0
[🔇 Игнорировать 15 мин]                           ← если IGNORE_DURATION > 0, иначе "🔇 Игнорировать"

После нажатия кнопки содержимое алерта сохраняется, кнопки исчезают, а внизу появляется итог: что сделано, кем и когда. После отключения подписки остаётся кнопка «🔓 Включить подписку» — действие можно отменить. Если алерт отредактировать нельзя (он удалён, слишком старый или Telegram отверг правку), итог приходит отдельным сообщением ответом на алерт.

Длительность «Отключить на N мин» и «Игнорировать N мин» запоминается в самой кнопке при отправке алерта: смена AUTO_DISABLE_DURATION/IGNORE_DURATION через /settings не меняет смысл уже отправленных кнопок. «Отключить навсегда» и «Включить подписку» снимают запланированное автовосстановление, чтобы старый таймер не включил пользователя снова.

Подписка отключается автоматически, бот шлёт информационный алерт с кнопкой «Включить подписку». При AUTO_DISABLE_DURATION > 0 подписка восстанавливается по таймеру, и в алерте видно, когда это произойдёт.

Уведомления в пределах допуска (AUTO_NOTIFY_SOFT=true). Когда нужно банить только при заметном превышении (TOLERANCE), но знать о тех, кто уже вышел за HWID-лимит:

«Мягкие» предупреждения используют отдельный кулдаун (cooldown:soft:), не увеличивают счётчик нарушений за 24ч, не учитываются в VIOLATION_THRESHOLD и шлют webhook с событием soft_violation_detected.

При нарушении limiter может отправить HTTP POST на WEBHOOK_URL (работает в обоих режимах). К каждому запросу добавляется X-Timestamp (unix-время отправки). Если задан WEBHOOK_SECRET, добавляются заголовки:

Проверка на получателе (псевдокод): hmac_sha256(secret, ts + "." + body) == header["X-Signature-V2"] и now − ts < 300.

Отправка не блокирует цикл мониторинга. При сетевой ошибке, 5xx или 429 доставка повторяется (до 3 попыток); 4xx считается осознанным отказом получателя и не повторяется. Событие переживает остановку сервиса: при SIGTERM limiter дожидается отправки, а не теряет её.

Пример payload:

{
  "event": "violation_detected",
  "action_mode": "auto",
  "user": {
    "user_id": 123,
    "username": "john",
    "email": "[email protected]",
    "telegram_id": 123456789,
    "subscription_url": "https://panel.example.com/sub/abc"
  },
  "violation": {
    "ips": [
      { "ip": "1.2.3.4", "node_name": "DE-1", "node_uuid": "node-uuid-1", "last_seen": "2025-11-29T12:00:00Z", "asn": 24940, "asn_org": "Hetzner Online GmbH" },
      { "ip": "5.6.7.8", "node_name": "US-1", "node_uuid": "node-uuid-2", "last_seen": "2025-11-29T12:01:00Z" }
    ],
    "ip_count": 5,
    "device_limit": 3,
    "tolerance": 1,
    "effective_limit": 4,
    "violation_count_24h": 3,
    "device_group_count": 5,
    "grouping_mode": "ip"
  },
  "action": { "auto_disable_duration_min": 10 },
  "timestamp": "2025-11-29T12:05:00Z"
}

Как узнать Telegram Chat ID? Добавьте @userinfobot и отправьте /start. Для группы/канала — @getidsbot.

Что если API панели недоступен? Сервис логирует ошибку, пропускает цикл и пробует снова через CHECK_INTERVAL. Запросы к API повторяются до 3 раз с exponential backoff и джиттером; при 429 и 408 повтор тоже выполняется, а заголовок Retry-After от панели учитывается. Цикл, в котором не удалось опросить ни одну ноду, не считается успешным — /healthz в этом случае покажет проблему.

Можно ли использовать Redis от Remnawave? Можно, но не рекомендуется — проект поднимает свой Redis. Для существующего укажите REDIS_URL.

Как изменить лимит пользователя? Через поле hwidDeviceLimit в настройках подписки в панели Remnawave.

GitHub Issues · GNU GPL v3.0 — см. LICENSE