Remnawave - Bedolaga Docs

Обзор

Бот управляет VPN подписками через API панели Remnawave. Все операции с пользователями, серверами и трафиком проходят через единый API клиент.

Совместимость с Remnawave 2.7.0

Начиная с версии 2.7.0 панели поддерживаются:

MONTH_ROLLING — стратегия сброса трафика с помесячным скользящим окном
Per-inbound метрики — разбивка трафика по отдельным inbound в реальном времени
Обновлённая модель данных нод — вложенные объекты versions / system вместо плоских полей
Webhook torrent_blocker.report — событие при обнаружении торрент-трафика
Webhook subpage_config_changed — автоматическая инвалидация кэша конфигурации приложения при изменении подстраницы

Настройка подключения

REMNAWAVE_API_URL=https://panel.example.com
REMNAWAVE_API_KEY=your_panel_api_key

Если бот и панель на одном сервере в Docker, используйте внутренний адрес: REMNAWAVE_API_URL=http://remnawave:3000

Защита панели

Для панелей, защищённых через remnawave-reverse-proxy:

# Для панелей установленных скриптом eGames
REMNAWAVE_SECRET_KEY=XXXXXXX:DDDDDDDD

# Или если ключ и значение одинаковые
REMNAWAVE_SECRET_KEY=secret_key_name

Методы авторизации

Конфигурация	Authorization	X-Api-Key
Только API Key	`Bearer <api_key>`	`<api_key>`
Basic Auth	`Bearer <api_key>`	`Basic <user:pass>`
Caddy + API Key	`Basic <caddy_token>`	`<api_key>`
Cookies (eGames)	`Bearer <api_key>`	`<api_key>` + cookies

Автосинхронизация

REMNAWAVE_AUTO_SYNC_ENABLED=true
REMNAWAVE_AUTO_SYNC_TIMES=03:00,15:00

Бот синхронизирует данные с панелью:

При старте бота — полная синхронизация
По расписанию — в указанное время
По команде — через админ-панель

Синхронизируются:

Серверы (сквады) и их статус
Пользователи — сопоставление Telegram ID с аккаунтами панели
Подписки — актуальные даты и параметры

Двунаправленная синхронизация `end_date`

Панель является авторитетным источником для end_date на активных подписках. Как webhook-событие user.modified, так и пакетная синхронизация обновляют end_date в обоих направлениях — вперёд и назад. Ранее принимались только обновления «вперёд» (дата в панели > локальная дата). Теперь изменения, сделанные администратором в панели (например, сокращение подписки), корректно передаются в бота.

60-секундная защита между webhook-событием и пакетной синхронизацией по-прежнему предотвращает конфликты.

Синхронизация в мультитарифном режиме

При MULTI_TARIFF_ENABLED=true каждая подписка получает собственного пользователя в панели (user_{telegram_id}_{short_id}). Синхронизация работает по remnawave_uuid на уровне подписки, а не пользователя.

Panel → Bot: создание подписок для новых пользователей панели
Bot → Panel: matching по суффиксу _short_id в username
Email/OAuth: синхронизация всех пользователей панели для email
Автопривязка: legacy user-level UUID автоматически привязывается к подписке при миграции

Webhooks от панели (real-time события)

Для мгновенной реакции на события подписок вместо периодической синхронизации.

Настройка

1. Переменные окружения:

REMNAWAVE_WEBHOOK_ENABLED=true
REMNAWAVE_WEBHOOK_PATH=/remnawave-webhook
REMNAWAVE_WEBHOOK_SECRET=your_secret_min_32_chars_here

Сгенерируйте секрет: openssl rand -hex 32

Усиление безопасности webhook-верификации. Все платёжные провайдеры переведены на fail-closed модель: CryptoBot, Heleket и Tribute отклоняют запросы при отсутствии API-ключа. Для сравнения подписей используется hmac.compare_digest (timing-safe). CloudPayments отклоняет запросы при отсутствии заголовка подписи.

2. В панели Remnawave:

URL: https://hooks.domain.com/remnawave-webhook
Secret: тот же, что в REMNAWAVE_WEBHOOK_SECRET

3. Проверка:

curl -s https://hooks.domain.com/remnawave-webhook | jq
# {"status": "ok", "service": "remnawave_webhook", "enabled": true}

Поддерживаемые события

Событие	Описание
`user.expired`	Подписка истекла
`user.disabled`	Подписка деактивирована
`user.enabled`	Подписка активирована
`user.limited`	Превышен лимит трафика
`user.traffic_reset`	Трафик сброшен
`user.modified`	Данные подписки изменены
`user.deleted`	Пользователь удалён
`user.revoked`	Ключи подписки отозваны
`user.created`	Пользователь создан
`user.expires_in_*`	Предупреждения об истечении (72/48/24ч)
`user.first_connected`	Первое подключение
`user.bandwidth_usage_threshold_reached`	Порог трафика достигнут
`user_hwid_devices.*`	Устройство добавлено/удалено
`torrent_blocker.report`	Торрент-блокировщик: обнаружено использование торрентов
`subpage_config_changed`	Конфигурация подстраницы изменена (автосброс кэша)
`node.`, `service.`	Административные события

При включённых webhooks бот защищает подписки от перезаписи данными из периодической синхронизации в течение 60 секунд после получения события.

Уведомления пользователям

При получении webhook-событий бот может отправлять уведомления пользователям в Telegram (или по email для email-only пользователей).

Главный переключатель

# Включить уведомления пользователям от вебхуков (по умолчанию true)
WEBHOOK_NOTIFY_USER_ENABLED=true

Если false — ни одно пользовательское уведомление не отправляется, даже если отдельные типы включены.

Настройка по типам

Каждый тип уведомления можно включить или выключить отдельно. Все по умолчанию включены.

Переменная	По умолчанию	События	Что получает пользователь
`WEBHOOK_NOTIFY_SUB_STATUS`	`true`	`user.disabled`, `user.enabled`	Подписка отключена / активирована
`WEBHOOK_NOTIFY_SUB_EXPIRED`	`true`	`user.expired`, `user.expired_24_hours_ago`	Подписка истекла / истекла вчера
`WEBHOOK_NOTIFY_SUB_EXPIRING`	`true`	`user.expires_in_72h/48h/24h`	Подписка истекает через 3/2 дня / завтра
`WEBHOOK_NOTIFY_SUB_LIMITED`	`true`	`user.limited`	Лимит трафика исчерпан
`WEBHOOK_NOTIFY_TRAFFIC_RESET`	`true`	`user.traffic_reset`	Трафик сброшен, лимит доступен
`WEBHOOK_NOTIFY_SUB_DELETED`	`true`	`user.deleted`	Подписка удалена из панели
`WEBHOOK_NOTIFY_SUB_REVOKED`	`true`	`user.revoked`	Ключ подписки обновлён
`WEBHOOK_NOTIFY_FIRST_CONNECTED`	`true`	`user.first_connected`	Первое подключение к VPN
`WEBHOOK_NOTIFY_NOT_CONNECTED`	`true`	`user.not_connected`	Подписка активна, но нет подключения
`WEBHOOK_NOTIFY_BANDWIDTH_THRESHOLD`	`true`	`user.bandwidth_usage_threshold_reached`	Использовано N% трафика
`WEBHOOK_NOTIFY_DEVICES`	`true`	`user_hwid_devices.added/deleted`	Новое устройство / устройство удалено

Примеры сообщений

Подписка истекает завтра:

🔴 Подписка истекает завтра!

Осталось менее 24 часов. Продлите подписку прямо сейчас.

[Продлить подписку] [Закрыть]

Лимит трафика исчерпан:

⚠️ Достигнут лимит трафика

Вы исчерпали весь доступный трафик.
Докупите трафик или дождитесь сброса.

[Докупить трафик] [Моя подписка] [Закрыть]

Первое подключение:

🎉 Первое подключение!

Вы впервые подключились к VPN. Добро пожаловать!

[Моя подписка] [Закрыть]

Тихие события

Некоторые webhook-события обрабатываются без уведомления пользователю:

Событие	Что происходит
`user.modified`	Синхронизация данных подписки — панель авторитетна. Обновляет трафик, статус и `end_date` в обоих направлениях (вперёд и назад)
`user.created`	Логирование создания пользователя в панели

Все переменные WEBHOOK_NOTIFY_* можно менять без перезапуска бота через админ-панель (Настройки).

Мониторинг серверов

Переменная	Описание
`SERVER_STATUS_MODE`	`disabled`, `external_link`, `external_link_miniapp`, `xray`
`SERVER_STATUS_EXTERNAL_URL`	Ссылка на внешний мониторинг
`SERVER_STATUS_METRICS_URL`	URL метрик XrayChecker
`MONITORING_INTERVAL`	Интервал проверки (секунды, по умолчанию 60)

Бот отправляет уведомления администраторам при:

Падении сервера (недоступен)
Высокой нагрузке CPU/RAM
Аномальном трафике
Восстановлении после падения

​Обзор

​Совместимость с Remnawave 2.7.0

​Настройка подключения

​Защита панели

​Методы авторизации

​Автосинхронизация

​Двунаправленная синхронизация end_date

​Синхронизация в мультитарифном режиме

​Webhooks от панели (real-time события)

​Настройка

​Поддерживаемые события

​Уведомления пользователям

​Главный переключатель

​Настройка по типам

​Примеры сообщений

​Тихие события

​Мониторинг серверов

Обзор

Совместимость с Remnawave 2.7.0

Настройка подключения

Защита панели

Методы авторизации

Автосинхронизация

Двунаправленная синхронизация `end_date`

Синхронизация в мультитарифном режиме

Webhooks от панели (real-time события)

Настройка

Поддерживаемые события

Уведомления пользователям

Главный переключатель

Настройка по типам

Примеры сообщений

Тихие события

Мониторинг серверов