remnawave-api: Python SDK для работы с Remnawave

remnawave-api полезен, когда операции Remnawave нужно выполнять повторяемо, а не вручную через dashboard. Главная польза - безопаснее provision users, ротировать данные, проверять лимиты и фиксировать изменения, если credentials и логи обрабатываются аккуратно при росте числа пользователей и подписок сервиса регулярно.

Что такое remnawave-api#

remnawave-api — это Python SDK для работы с панелью Remnawave через REST API. Если говорить простыми словами, он помогает обращаться к панели не вручную через HTTP-запросы, а через готовые Python-методы и модели данных. Это удобно, когда нужно автоматизировать рутину: получать список пользователей, читать конфигурации, интегрировать панель с ботом, биллингом или внутренними скриптами.

Важно знать один нюанс: исходный репозиторий sm1ky/remnawave-api уже переехал в новый проект remnawave/python-sdk. Для новых установок рекомендуется использовать пакет remnawave, а старый remnawave_api считается устаревшим. То есть название в старом репозитории еще встречается, но актуальная ветка разработки живет под новым именем.

Такой SDK обычно используют:

• администраторы VPN-панелей, которым нужна автоматизация;
• разработчики, пишущие внутренние панели, ботов и сервисы;
• технические пользователи, которым важно снизить ручные действия и держать OPSEC-процессы под контролем.

Главная идея инструмента — не просто “сходить в API”, а сделать это типобезопасно и предсказуемо: с контроллерами, Pydantic-моделями и удобной сериализацией.

Установка#

Для работы нужен современный Python 3 и доступ к панели Remnawave, где у вас есть API token. Самый простой путь — установить новый пакет remnawave.

Linux / macOS#

Создайте виртуальное окружение и установите пакет:

python3 -m venv .venv
source .venv/bin/activate
pip install remnawave

Если вы по какой-то причине работаете со старой версией интеграции, можно поставить устаревший пакет:

pip install remnawave_api

Но для новых проектов лучше сразу использовать remnawave.

Windows PowerShell#

python -m venv .venv
.venv\Scripts\Activate.ps1
pip install remnawave

Установка из GitHub-версии#

Если нужен свежий код из ветки разработки:

pip install git+https://github.com/remnawave/python-sdk.git@development

Что подготовить заранее#

Перед запуском вам понадобятся:

• URL вашей панели, например https://vpn.example.com;
• API token из раздела API Tokens;
• рабочий виртуальный env, чтобы не смешивать зависимости с системным Python.

Базовая настройка#

Ниже минимальная рабочая схема: храним параметры в переменных окружения, создаем SDK и делаем первый запрос.

Пример переменных окружения#

export REMNAWAVE_BASE_URL="https://vpn.example.com"
export REMNAWAVE_TOKEN="your_api_token_here"

На Windows PowerShell:

$env:REMNAWAVE_BASE_URL="https://vpn.example.com"
$env:REMNAWAVE_TOKEN="your_api_token_here"

Минимальный Python-скрипт#

import os
import asyncio

from remnawave import RemnawaveSDK

async def main():
    base_url = os.getenv("REMNAWAVE_BASE_URL")
    token = os.getenv("REMNAWAVE_TOKEN")

    if not base_url or not token:
        raise RuntimeError("Не заданы REMNAWAVE_BASE_URL или REMNAWAVE_TOKEN")

    sdk = RemnawaveSDK(base_url=base_url, token=token)

    # Пример: получить список пользователей
    response = await sdk.users.get_all_users_v2()

    print("Всего пользователей:", response.total)
    for user in response.users[:5]:
        print(user)

if __name__ == "__main__":
    asyncio.run(main())

Что здесь происходит#

• RemnawaveSDK(...) создает клиент для панели.
• base_url — адрес вашей панели.
• token — bearer-token, который дает доступ к API.
• asyncio.run(...) нужен, потому что SDK работает асинхронно.
• Ответ приходит не “сырой строкой JSON”, а как объект с полями, которые удобно читать из Python.

Если вы только начинаете, лучше сначала проверить один простой запрос, а уже потом строить автоматизацию вокруг него.

Основные сценарии использования#

1. Быстро получить список пользователей#

Это самый понятный сценарий: нужно посмотреть, кто зарегистрирован в панели, сколько всего активных пользователей и какие данные возвращает API.

import os
import asyncio

from remnawave import RemnawaveSDK

async def main():
    sdk = RemnawaveSDK(
        base_url=os.environ["REMNAWAVE_BASE_URL"],
        token=os.environ["REMNAWAVE_TOKEN"],
    )

    response = await sdk.users.get_all_users_v2()

    print(f"Пользователей всего: {response.total}")
    for user in response.users:
        print(user)

if __name__ == "__main__":
    asyncio.run(main())

Практическая польза:

• быстро проверять состояние базы пользователей;
• строить внутренние отчеты;
• использовать это в админ-боте или дашборде.

2. Работать с профилями конфигурации#

В новых версиях SDK появились отдельные контроллеры для конфиг-профилей. Это полезно, если вам нужно автоматизировать выдачу настроек разным группам пользователей или проверять, какие шаблоны доступны в панели.

Пример общего шаблона:

import os
import asyncio

from remnawave import RemnawaveSDK

async def main():
    sdk = RemnawaveSDK(
        base_url=os.environ["REMNAWAVE_BASE_URL"],
        token=os.environ["REMNAWAVE_TOKEN"],
    )

    profiles = await sdk.config_profiles.get_all_config_profiles()

    for profile in profiles:
        print(profile)

if __name__ == "__main__":
    asyncio.run(main())

Даже если вы пока не планируете сложную автоматизацию, такой доступ полезен для аудита: можно быстро понять, какие профили реально доступны и как они устроены.

3. Интеграция в внутренний ops-скрипт или бота#

SDK удобен, когда нужно встроить Remnawave в цепочку автоматизации: уведомления, тикеты, отчетность, проверку статусов.

Например, вы можете сделать скрипт, который:

• раз в день опрашивает панель;
• сохраняет сводку в лог;
• отправляет сообщение в Telegram или Slack;
• использует данные для биллинга или поддержки.

Скелет такого сценария:

import os
import asyncio
from datetime import datetime

from remnawave import RemnawaveSDK

async def main():
    sdk = RemnawaveSDK(
        base_url=os.environ["REMNAWAVE_BASE_URL"],
        token=os.environ["REMNAWAVE_TOKEN"],
    )

    users = await sdk.users.get_all_users_v2()

    report = {
        "timestamp": datetime.utcnow().isoformat(),
        "total_users": users.total,
    }

    print(report)

if __name__ == "__main__":
    asyncio.run(main())

Это уже хорошая точка входа для дальнейшей автоматизации: вы добавляете хранение в файл, БД или отправку в мониторинг.

Советы и нюансы#

• Используйте новый пакет remnawave, а не старый remnawave_api, если начинаете с нуля. Старое название сохранено только для совместимости.
• Храните токен вне кода. Лучше переменные окружения или .env, чем захардкоженная строка в скрипте.
• Не смешивайте системный Python и проектные зависимости. Виртуальное окружение сильно упрощает жизнь при обновлениях.
• SDK асинхронный, поэтому не забывайте про asyncio.run(...) или другой async-контур.
• Если у вас уже есть старые скрипты под legacy-пакет, проверьте импорты и название пакета при миграции.
• Для продакшена полезно добавить обработку ошибок: недоступность панели, неверный токен, пустой ответ, сетевые таймауты.
• Если вы обновляете интеграцию, сверяйте версию панели Remnawave с версией контракта API. Это особенно важно, если у вас есть старый код под 1.x.

Пример практической проверки перед запуском:

python -c "import os; print(os.getenv('REMNAWAVE_BASE_URL')); print('TOKEN_OK' if os.getenv('REMNAWAVE_TOKEN') else 'TOKEN_MISSING')"

Если переменные на месте, а доступ к панели есть, первый запрос обычно заводится без лишней возни.

Вывод#

remnawave-api — это удобный вход в автоматизацию Remnawave на Python: он упрощает работу с API, уменьшает количество ручных запросов и хорошо подходит для скриптов, ботов и внутренних инструментов. Если вы только начинаете, берите новый пакет remnawave, а старый remnawave_api рассматривайте как легаси-вариант для совместимости.

Что читать дальше?#

• Откройте VPN-гайды GigaTap, чтобы пройти маршрут от настройки до диагностики.
• Используйте помощник VPN start, если нужно выбрать между настройкой, клиентом, docs или профилем.
• Для device-specific импорта откройте VPN client setup hub.
• Сверьте продуктовые шаги в официальных docs GigaTap перед изменением клиентского профиля.
• Для соседнего сценария посмотрите гайд по Xray-core.

Если проблема похожа на mismatch между оплатой, entitlement и реальным provider state, сначала фиксируйте симптомы клиента и только потом меняйте протокол или профиль.

Определение#

• remnawave-api - Python SDK для автоматизации Remnawave API: provisioning пользователей, управление подписками, проверки и операционные отчеты.

Comparison#

Workflow	Когда использовать	На что смотреть
Скрипт remnawave-api	Повторяемая API-работа требует auditability и меньше ручных кликов.	Храните tokens безопасно и не пишите raw responses в логи.
Dashboard changes	Разовое admin-действие быстрее сделать руками.	Ручные изменения сложнее воспроизвести и проверить.
Custom HTTP client	SDK не покрывает нужный endpoint.	Retry, validation, pagination и errors остаются на вас.

FAQ#

Когда автоматизировать задачи Remnawave?#

Автоматизируйте задачи, которые повторяются, влияют на многих пользователей или требуют стабильной истории изменений. Разовое расследование может быть ручным, но provisioning, rotation и checks лучше оформлять скриптами.

Какой главный операционный риск?#

Главный риск не в SDK, а в небезопасной работе с credentials и шумных логах. Tokens, raw user data и полные API responses нужно редактировать до хранения или передачи.