JSON для HAPP VPN: настройка, импорт конфигураций и управление через API

Что такое JSON и зачем он нужен в VPN

JSON (JavaScript Object Notation) — это лёгкий текстовый формат обмена данными, основанный на парах «ключ-значение». Он широко применяется в веб-разработке, API и конфигурационных файлах благодаря простоте чтения и обработки. В контексте VPN JSON используется для хранения настроек подключения: адреса серверов, протоколы, параметры шифрования, маршрутизации и другие опции.

В экосистеме HAPP JSON играет две ключевые роли. Во-первых, это формат импорта конфигураций серверов: пользователь может добавить сервер, вставив JSON-объект, который затем передаётся ядру XRAY. Во-вторых, JSON используется в API Happ-Proxy для управления подписками, устройствами и отправки push-уведомлений. Понимание структуры JSON помогает точнее настраивать соединение и автоматизировать администрирование.

Важно отметить, что JSON сам по себе не обеспечивает шифрование — он лишь структурирует данные. Безопасность соединения зависит от протокола (VLESS, VMess, Shadowsocks и т.д.) и настроек шифрования, которые передаются внутри JSON.

Форматы добавления конфигураций в HAPP

Приложение HAPP поддерживает несколько способов добавления VPN-конфигураций:

• Ручной ввод — через кнопку «+» на главном экране, где можно детально заполнить параметры протокола.
• Импорт по ссылке или QR-коду — автоматическое распознавание схем vless://, vmess://, ss://, trojan://, hysteria2:// и других.
• Подписки — стандартные текстовые списки серверов или расширенные JSON-массивы.

JSON-подписки представляют собой массивы объектов, каждый из которых описывает отдельный сервер. Такой формат удобен для провайдеров, которые хотят передать не только адрес и протокол, но и дополнительные параметры: метаданные, маршруты, настройки TLS и т.д.

При импорте JSON-конфигурации HAPP обрабатывает её особым образом, что подробно описано в следующем разделе.

Прямая передача JSON в ядро XRAY: принцип 1:1

Когда пользователь импортирует конфигурацию в формате JSON, HAPP передаёт её ядру XRAY практически в неизменном виде. Это означает, что стандартные правила маршрутизации, фильтры и настройки интерфейса приложения не накладываются на JSON-файл. Конфигурация работает ровно так, как она прописана в исходном коде.

Этот принцип «прямой передачи» даёт продвинутым пользователям полный контроль над поведением ядра, но требует аккуратности: любая ошибка в JSON (например, неправильный синтаксис или неверное имя поля) может привести к сбою подключения. Поэтому перед использованием рекомендуется проверять JSON на валидность с помощью онлайн-инструментов или локальных утилит.

Несмотря на прямую передачу, HAPP сохраняет контроль над системным окружением ядра через профили маршрутизации. Это включает управление GEO-файлами (базами геоданных), возможность их оптимизации (урезанные версии) и настройку DNS-туннелирования. Параметры удалённого DNS берутся из активного профиля маршрутизации и могут быть изменены пользователем.

Косвенное управление через HAPP: GEO-файлы и DNS

Хотя JSON-конфигурация передаётся в XRAY напрямую, HAPP позволяет влиять на некоторые аспекты работы ядра через профили маршрутизации. Это важно для адаптации конфигурации под конкретные задачи.

Управление GEO-файлами. Пользователь может выбрать, какие базы геоданных (например, geoip.dat, geosite.dat) будут переданы ядру. Это влияет на правила маршрутизации, которые используют геолокацию IP-адресов и доменов.

Оптимизация GEO-файлов. При активации функции «Урезанные GEO-файлы» ядро получит только необходимые фрагменты баз, соответствующие выбранным тегам. Это экономит оперативную память и ускоряет запуск, особенно на слабых устройствах.

DNS-туннелирование. Параметры удалённого DNS (Remote DNS) берутся из активного профиля маршрутизации приложения. Пользователь может изменить их, чтобы направить DNS-запросы через VPN или использовать специфические резолверы.

Таким образом, даже при использовании «сырого» JSON-конфига можно гибко настраивать окружение ядра, не редактируя сам файл.

Расширенные параметры URI-схем: фрагментация и шумы

Для борьбы с DPI (deep packet inspection) HAPP поддерживает расширенные параметры в URI-ссылках, которые также могут быть включены в JSON-конфигурации. Эти инструменты помогают маскировать трафик и избегать блокировок.

Фрагментация — разбиение пакетов на части, чтобы DPI не мог распознать сигнатуру протокола. Параметр задаётся как fragment=length,interval,packets[,maxSplit], где length — длина фрагмента, interval — интервал между ними, packets — количество пакетов, maxSplit — максимальное число разбиений.

Шумы — добавление случайных данных в трафик для имитации обычного интернет-трафика. Работают только совместно с фрагментацией. Параметр: noises=type,packet,delay[,applyTo], например noises=rand,50-150,10-50,ip. Здесь type — тип шума, packet — диапазон размеров, delay — задержка, applyTo — к чему применять (например, ip).

Важно: настройки внутри сервера имеют приоритет только если выключены глобальные настройки приложения. Если глобальные параметры включены, они переопределяют серверные.

Метаданные и визуализация серверов в JSON

Для удобства организации списка серверов HAPP поддерживает метаданные, которые можно добавлять в JSON-конфигурацию. Это позволяет заменить техническое название (например, «VMess») на понятное описание.

В URI-ссылках метаданные добавляются после символа #, например vless://...@server:port#Мой сервер. В JSON-конфигурации для этого используется поле "meta": {"serverDescription": "Ваш текст"}.

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

API Happ-Proxy: управление подписками и устройствами

Happ-Proxy предоставляет REST API для автоматизации управления VPN-подписками. Базовый URL API — https://happ-proxy.com. Все запросы требуют параметры provider_code (8 символов) и auth_key (32 символа). Ответы приходят в формате JSON с полями rc (код результата) и msg (сообщение).

Основные методы:

• GET /api/add-install — создание новой ссылки провайдера (install). Параметры: install_code (12 символов, опционально), note (до 255 символов).
• GET /api/update-install — изменение параметров ссылки: install_limit (от 1 до 100), note, status (5 — Disabled, 10 — Active).
• GET /api/list-install — получение списка ссылок. Если не указан id, возвращаются последние 5000 записей.
• GET /api/list-hwid — список HWID (устройств) по конкретной ссылке. Требуется install_code или install_id.
• GET /api/delete-hwid — удаление устройства по HWID.
• GET /api/add-domain — привязка домена подписки. Требуется domain_hash (SHA-256 от домена в нижнем регистре).
• GET /api/delete-domain — удаление домена.
• GET /api/list-domain — список доменов.

Пример создания ссылки:

GET /api/add-install?provider_code=Ab12Cd34&auth_key=AbcdEfgh...&install_limit=10

Ответ: {"rc":1,"msg":"Ok","install_code":"ABCDEF123456","id":33}.

Удалённое управление: push-уведомления и команды

API Happ-Proxy позволяет отправлять push-уведомления и команды удалённого управления на устройства пользователей. Это полезно для информирования об обновлениях или принудительного изменения настроек.

Push-уведомления — метод POST /remote/notification. Требуется активная подписка и тариф Enterprise. Тело запроса — JSON с полем PushNotificationForm, содержащим body, type_push (optional или force), expire_days, а также опционально title, link_for_open, background_image, locales (для локализации). Можно указать os (массив операционных систем) или hwid (до 5 устройств через запятую).

Ограничения:

• Общая рассылка (без HWID) — не чаще 1 раза в 5 минут.
• Размер сообщения после base64-кодирования — не более 4096 байт.
• Если указан hwid, параметр os игнорируется.

Команды удалённого управления — метод POST /remote/command. Доступен на тарифах Pro и Enterprise. Позволяет менять настройки приложения на устройствах. Обязательные параметры: specific_device_toggle (true/false), settings (JSON с настройками). Если specific_device_toggle=true, требуется hwid; если false — os.

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

{
  "PushNotificationForm": {
    "body": "Please update your app",
    "type_push": "optional",
    "expire_days": 7
  },
  "os": ["android"]
}

Практические примеры JSON-конфигураций и ссылок

Рассмотрим несколько примеров, которые помогут понять, как выглядят JSON-конфигурации и URI-ссылки в HAPP.

Пример простого JSON-объекта для настройки VPN (гипотетический):

{
  "server": "192.168.1.1",
  "protocol": "VLESS",
  "security": {
    "auth": "password",
    "cipher": "AES-256-GCM"
  }
}

Обратите внимание: реальные конфигурации XRAY имеют более сложную структуру, включая поля outbounds, inbounds, routing и т.д.

Пример URI-ссылки Hysteria2:

hy2://user:pass@host:port/?insecure=1#Мой сервер

Пример ссылки с фрагментацией и шумами:

vless://uuid@host:port?fragment=length,interval,packets&noises=rand,50-150,10-50,ip#Сервер с защитой

Пример JSON-подписки (фрагмент):

[
  {
    "outbounds": [
      {
        "protocol": "vless",
        "settings": {
          "vnext": [
            {
              "address": "example.com",
              "port": 443,
              "users": [
                {"id": "uuid", "encryption": "none"}
              ]
            }
          ]
        }
      }
    ],
    "meta": {
      "serverDescription": "Основной сервер"
    }
  }
]

Эти примеры демонстрируют гибкость формата и возможности настройки.

Ограничения, безопасность и лучшие практики

При работе с JSON-конфигурациями и API важно учитывать ограничения и соблюдать меры безопасности.

Ограничения API:

• install_limit не может быть меньше текущего количества HWID.
• Нельзя отменить push-уведомление менее чем за 10 минут до запланированного времени.
• Для массовых рассылок действует антиспам-ограничение: 1 раз в 5 минут.
• Максимальный размер сообщения — 4096 байт после base64.

Безопасность:

• Никогда не передавайте auth_key третьим лицам. Храните его в защищённом месте.
• Используйте HTTPS при обращении к API.
• Проверяйте JSON на валидность перед импортом, чтобы избежать ошибок.
• Регулярно обновляйте приложение HAPP для получения новых функций и исправлений.

Лучшие практики:

• Для массового управления используйте API, а не ручное редактирование.
• Применяйте метаданные для удобной организации серверов.
• Используйте фрагментацию и шумы только при необходимости, так как они могут увеличивать нагрузку на устройство.
• Следите за лимитами HWID и своевременно удаляйте неиспользуемые устройства через API.

Вопросы и ответы