`policy`, `stats`, `api`, `metrics`

Цель

Разобрать блоки Xray JSON, которые отвечают за локальные политики, статистику, управляющий API и экспорт метрик, а также показать их связь с 3x-ui, безопасностью и диагностикой.

Теория

Эти блоки относятся не к базовому пути inbound -> routing -> outbound, а к управлению и наблюдаемости:

policy задает поведение пользователей разных уровней и включает счетчики;
stats включает внутренний механизм статистики;
api открывает gRPC-интерфейс для управления и получения данных;
metrics экспортирует статистику и отладочные данные через HTTP endpoint.

В 3x-ui статистика, лимиты, активность клиентов и часть управляющих действий зависят от того, какие возможности Xray включены в конфигурации.

История

По мере роста Xray из простого proxy-core в управляемую платформу появились механизмы runtime-управления, статистики и экспорта состояния. Они нужны панелям управления, автоматизации, мониторингу и диагностике, но одновременно расширяют поверхность атаки.

Архитектура

Связь блоков:

Упрощенная модель:

users / levels
  -> policy.levels
  -> stats enabled by policy
  -> api StatsService / metrics endpoint
  -> 3x-ui, xray api, monitoring

Учебный фрагмент конфигурации:

{
  "policy": {
    "levels": {
      "0": {
        "handshake": 4,
        "connIdle": 300,
        "statsUserUplink": true,
        "statsUserDownlink": true
      }
    },
    "system": {
      "statsInboundUplink": true,
      "statsInboundDownlink": true,
      "statsOutboundUplink": true,
      "statsOutboundDownlink": true
    }
  },
  "stats": {},
  "api": {
    "tag": "api",
    "listen": "127.0.0.1:8080",
    "services": ["StatsService"]
  },
  "metrics": {
    "listen": "127.0.0.1:11111"
  }
}

Это учебный пример. Для production нужно отдельно проверять версию Xray-core, модель доступа, firewall, необходимость API и необходимость metrics.

Настройка

Базовая последовательность:

1. Определить, нужна ли статистика вообще. 2. Включить stats. 3. Включить нужные счетчики в policy.levels и policy.system. 4. Убедиться, что у пользователей есть email, если нужна user statistics. 5. Включить api только для конкретных сервисов, которые действительно нужны. 6. Оставить api.listen и metrics.listen на 127.0.0.1, если нет строгой причины делать иначе. 7. Закрыть API/metrics firewall и не публиковать их напрямую в интернет. 8. Проверить данные через xray api или локальный metrics endpoint.

Если используется старый способ API через отдельный tunnel inbound и routing, нужно отдельно проверить связку:

api inbound tag -> routing rule -> api outbound tag

Разбор параметров

`policy`

Параметр	Назначение	Комментарий
`levels`	политики по user level	ключи уровней записываются строками, например `"0"`
`handshake`	лимит времени handshake	слишком малое значение ломает медленные сети
`connIdle`	idle timeout	влияет на долгие соединения
`uplinkOnly`	время после закрытия downlink	помогает корректно завершать соединения
`downlinkOnly`	время после закрытия uplink	влияет на закрытие сессий
`statsUserUplink`	user uplink stats	требует `stats` и пользовательский `email`
`statsUserDownlink`	user downlink stats	нужно для статистики по пользователю
`statsUserOnline`	online user stats	зависит от активности соединений
`bufferSize`	размер внутреннего буфера	влияет на память, UDP и производительность

`policy.system`

Параметр	Назначение
`statsInboundUplink`	inbound uplink counters
`statsInboundDownlink`	inbound downlink counters
`statsOutboundUplink`	outbound uplink counters
`statsOutboundDownlink`	outbound downlink counters

`stats`

stats включается наличием объекта:

{
  "stats": {}
}

Без соответствующих флагов в policy нужные счетчики не появятся.

`api`

Параметр	Назначение	Риск
`tag`	тег API outbound	нужен для routing при классической схеме
`listen`	адрес и порт API	не должен быть публичным без отдельной защиты
`services`	список сервисов	включать только нужные сервисы

Примеры сервисов: StatsService, HandlerService, LoggerService, RoutingService. HandlerService и RoutingService особенно чувствительны, потому что позволяют менять inbound/outbound или routing.

`metrics`

Параметр	Назначение	Риск
`tag`	outbound tag для metrics	используется в tunnel-схеме
`listen`	прямой HTTP endpoint	при публичной экспозиции раскрывает отладочные данные

Metrics endpoint может предоставлять pprof и expvars, включая stats и observatory. Это удобно для диагностики, но опасно при внешней публикации.

Типовые ошибки

включить stats, но забыть флаги в policy;
ожидать user statistics без email у пользователя;
опубликовать api.listen или metrics.listen на публичном адресе;
включить все API services без необходимости;
не связать API inbound с routing при классической схеме;
считать metrics безопасным публичным endpoint;
уменьшить handshake или connIdle без тестов в реальной сети;
менять bufferSize ради "оптимизации" без понимания влияния на UDP и память.

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

api и metrics относятся к административной и диагностической поверхности. Их нельзя публиковать напрямую в интернет как обычный пользовательский inbound.

Минимальные правила:

слушать 127.0.0.1, если внешний доступ не нужен;
закрыть доступ firewall;
включать только необходимые API services;
не использовать HandlerService без строгого контроля доступа;
не отдавать metrics наружу без reverse proxy, auth и network allowlist;
учитывать, что stats раскрывает пользователей, трафик, inbound/outbound tags

и признаки активности;

проверять связь с 3x-ui: панель может использовать статистику для UI, лимитов

и отображения активности.

Чек-лист

Понятно, зачем включается статистика.
stats присутствует, если нужны счетчики.
Нужные флаги включены в policy.levels и policy.system.
У пользователей есть email, если нужны user stats.
api слушает только доверенный адрес.
В api.services включены только нужные сервисы.
metrics не опубликован напрямую в интернет.
Firewall ограничивает API/metrics.
Проверена совместимость с 3x-ui.
Security review выполнен до production.

Источники для сверки

Project X: Local Policy — https://xtls.github.io/en/config/policy.html
Project X: Statistics — https://xtls.github.io/en/config/stats.html
Project X: API Interface — https://xtls.github.io/en/config/api.html
Project X: Metrics — https://xtls.github.io/en/config/metrics.html

policy, stats, api, metrics