API

Блок api открывает управляющий gRPC-интерфейс, через который внешние инструменты (xray api ..., панели наблюдаемости, клиенты динамических правил) взаимодействуют с работающим экземпляром Xray. Блок настраивает внутренний входящий, трафик которого движок маршрутизации затем должен куда-то направить — обычно правилом по inboundTag.

Параметры

Поле	Тип	По умолчанию	Допустимые значения	Описание
tag	string	(required)	<inbound tag>	Тег, под которым входящий API виден движку маршрутизации. Значение обязано быть непустым; пустой тег отклоняется на этапе разбора.
listen	string	127.0.0.1:0	<host:port>	Адрес, на котором слушает gRPC API. Если не задан, вместо TCP-слушателя регистрируется внутренний внутрипроцессный входящий.
services	[]string	[]	HandlerService | LoggerService | StatsService | ObservatoryService | RoutingService | ReflectionService	Список открываемых API-сервисов. Сопоставляются без учёта регистра; неизвестные имена молча игнорируются.

Исходный код: infra/conf/api.go:16-20 · зафиксировано на v26.7.28 (5ca6f4b)

Допустимые сервисы

Имена в массиве services отображаются на регистрации gRPC-сервисов в APIConfig.Build (infra/conf/api.go:28-43). Сопоставление не зависит от регистра — "HandlerService", "handlerservice" и "HANDLERSERVICE" принимаются одинаково.

Сервис	Назначение
HandlerService	Добавление и удаление входящих и исходящих во время работы.
LoggerService	Переоткрытие файлов журналов (полезно с logrotate).
StatsService	Чтение счётчиков, публикуемых при включённом stats.
ObservatoryService	Запрос последних результатов наблюдателя за задержками.
RoutingService	Проверка решений маршрутизации и перезагрузка правил.
ReflectionService	Стандартная gRPC-рефлексия, позволяющая универсальным клиентам исследовать API.

Примеры

Минимальная управляющая конечная точка с доступными счётчиками статистики:

{
  "stats": {},
  "api": {
    "tag": "api",
    "listen": "127.0.0.1:10085",
    "services": ["HandlerService", "StatsService"]
  },
  "routing": {
    "rules": [
      { "type": "field", "inboundTag": ["api"], "outboundTag": "api" }
    ]
  }
}

Примечания

• tag не может быть пустым — Build возвращает "API tag can't be empty." (infra/conf/api.go:23-25).
• Сочетайте api.services с правилом маршрутизации, которое перехватывает inboundTag: ["api"] и направляет его в одноимённый внутрипроцессный исходящий. Без этого API доступен на прослушиваемом порту, но у движка маршрутизации нет правила для этого трафика.
• Для сбора метрик в стиле Prometheus предпочтителен блок metrics — он открывает обычную HTTP-точку без gRPC-механики.

Исходный код: infra/conf/api.go:16-20 · v26.7.28 (5ca6f4b)