Перейти к содержимому
Документация
Дополнительно
Локальный HTTP API конфигураций

Локальный HTTP API конфигураций

Доверенные локальные инструменты могут использовать разбор, компиляцию, установленные GeoData и проверку libXray самого приложения. Отдельный CLI не нужен. API не импортирует и не сохраняет данные, не меняет настройки, не загружает зависимости и не управляет запуском VPN.

Включение и авторизация

Откройте Дополнительно → Xray → Локальный API, включите его и сохраните. По умолчанию API отключён и доступен только на компьютере. Приложение должно работать и завершить подготовку служб. Скрытое окно не мешает; выход из приложения останавливает API, даже если VPN продолжает работать.

Адрес по умолчанию — http://127.0.0.1:18587, диапазон портов — 1024–65535. Прослушивается только IPv4 loopback, не локальная сеть. Автоматические порты Xray SOCKS/metrics исключают сохранённый порт API даже при отключённом API. Порты inbounds, заданные пользователем, не переписываются.

Скопируйте Token из приложения в защищённое хранилище доверенного локального инструмента. Каждый запрос требует Authorization: Bearer <token>. Token сохраняется при перезапуске; сброс немедленно отзывает прежнее значение. Отключение API сохраняет Token, очистка данных удаляет его; резервная копия подключений его не содержит.

Не помещайте Token в запрос к ИИ, URL, аргументы командной строки, репозиторий или журнал. Настраивайте авторизацию отдельно от генерируемого текста. Подключайтесь напрямую к указанному loopback-адресу, обходите прокси окружения и отключайте перенаправления. Запросы с браузерным Origin и межсайтовый доступ не поддерживаются. Token не защищает от вредоносного ПО, уже получившего доступ к вашей учётной записи.

API версии 1

Метод и путь Результат
GET /api/v1/info Версии API, приложения и Core; платформа и поддерживаемые типы конфигураций
POST /api/v1/config/validate Разбор и проекция проверки приложения, затем проверка конфигурации libXray
POST /api/v1/config/compile Предварительная рабочая конфигурация без проверки ядром и запуска

POST использует Content-Type: application/json, размер тела ограничен 16 МиБ. Передавайте исходную конфигурацию как текстовую строку, не как повторно закодированный объект, чтобы позиции ошибок относились к оригиналу.

{
  "kind": "raw",
  "text": "{\n  \"name\": \"Direct example\",\n  \"outbounds\": [{\"protocol\": \"freedom\", \"tag\": \"direct\"}]\n}"
}

Пример не содержит данных прокси и использует прямой доступ; это не предоставляемый VPN-сервер.

kind Содержимое text
outbound Один объект outbound, как в редакторе узла, не документ с обёрткой outbounds
routing Обычная собственная маршрутизация с пустыми входными слотами
advanced-routing Расширенный собственный JSON в пределах разрешённых полей шаблона
raw Полная конфигурация Raw JSON

Необязательное name следует правилам выбранного типа; имя конфигурации не равно тегу outbound. validate не принимает options и дополнительные outbounds. Проверка маршрутов использует заглушки, а не фактически выбранные узлы.

Предварительная компиляция

Для compile кроме kind и text передайте явный объект options:

{
  "platform": "macos",
  "sessionDirectory": "/explicit/preview-directory",
  "metricsPort": 19001,
  "socksPort": 19002,
  "ipv6": true
}
  • platform: ios, macos, android, windows или linux. Это цель генерации, а не удалённого запуска.
  • Для Windows нужен windowsMode: "exe" или "msix"; для Windows/Linux обязателен interfaceName.
  • Для routing и advanced-routing также нужен корневой массив outbounds с реальными узлами по числу пустых слотов. outbound и raw используют собственные узлы и не принимают дополнительный массив.
  • Необязательные tunDnsIpv4Address, tunDnsIpv6Address, logEnabled, logFilesSupported, logLevel, dnsLog, maskAddress при пропуске используют значения компилятора по умолчанию, а не текущие настройки пользователя.
  • Пути GeoData указывают на каталог установленного приложения. Генерация для другой платформы не создаёт там эти пути. Компиляция не проверяет доступность портов и интерфейсов, не создаёт каталог сеанса и не записывает активную конфигурацию.

Интерпретация результата

Проверяйте status (passed, failed, notRun) и stage (input, compile, kernel). HTTP 200 не означает успешную проверку; passed на этапе compile означает только создание предварительной конфигурации.

Диагностика содержит код и причину; path, offset, line, column добавляются лишь при надёжном определении. Смещение начинается с 0, строки и столбцы — с 1. Смещения и столбцы считаются в кодовых единицах UTF-16. Путь — массив, например ["routing", "rules", 0, "domain"]. Не угадывайте позицию исходника по тексту ошибки Core или сгенерированному JSON.

validationConfig и compiledConfig — JSON-текст, который может содержать секреты. Защищайте сохранённые результаты и читайте limitations. Занятость возвращает 409, слишком большой запрос — 413, недоступность службы — 503; это не успешная проверка.

Проверка создаёт и закрывает экземпляр Core без запуска VPN, но может иметь побочные эффекты в процессе. Это не песочница для недоверенных конфигураций. Она не загружает недостающие GeoData, не проверяет ограничения имён и количества в базе, не доказывает правильность реального сочетания узлов и не гарантирует запуск или связь. Тайм-аут клиента не отменяет начавшуюся нативную проверку; не повторяйте её автоматически.

Создание конфигураций с ИИ · Границы конфигураций

Последнее обновление
Проверка задержкиЖурналы и конфигурация