Обзор
Бот управляет VPN подписками через API панели Remnawave. Все операции с пользователями, серверами и трафиком проходят через единый API клиент.
Настройка подключения
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 с аккаунтами панели
- Подписки — актуальные даты и параметры
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
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.* | Устройство добавлено/удалено |
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 | Синхронизация данных подписки (трафик, даты, статус) |
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
- Аномальном трафике
- Восстановлении после падения
