`log`: логи Xray

Цель

Объяснить блок log в Xray JSON: какие типы логов существуют, как они помогают диагностике и какие риски безопасности возникают при избыточном логировании.

Теория

Блок log управляет тем, как Xray выводит логи. В официальной документации описаны два основных типа: access logs и error logs. Их можно настраивать независимо.

Access logs помогают понять, какие подключения проходят через Xray. Error logs показывают runtime-состояние, предупреждения и ошибки. Для диагностики это один из первых блоков, но для приватности и безопасности он требует аккуратности.

История

По мере усложнения Xray-конфигураций логи стали не просто техническим дополнением, а частью эксплуатационной модели. Без них сложно отличить ошибку сети, inbound, TLS, routing, outbound или DNS.

Архитектура

LogObject соответствует верхнеуровневому ключу log.

Типовая структура:

{
  "log": {
    "access": "/var/log/xray/access.log",
    "error": "/var/log/xray/error.log",
    "loglevel": "warning",
    "dnsLog": false,
    "maskAddress": "half"
  }
}

Настройка

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

Базовый подход:

1. На этапе настройки использовать достаточно подробные error logs. 2. После стабилизации снизить детализацию. 3. При передаче логов наружу включать маскирование IP. 4. Не отключать все логи до завершения диагностики.

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

Параметр	Назначение	Практический комментарий
`access`	путь к access log	специальное значение `none` отключает access log
`error`	путь к error log	специальное значение `none` отключает error log
`loglevel`	уровень error log	`debug`, `info`, `warning`, `error`, `none`
`dnsLog`	логирование DNS-запросов	полезно для диагностики DNS, но чувствительно для приватности
`maskAddress`	маскирование IP в логах	помогает безопаснее делиться логами

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

отключить error log и потерять диагностический контекст;
включить debug и забыть вернуть безопасный уровень;
публиковать логи без маскирования адресов;
считать отсутствие ошибок в панели 3x-ui доказательством, что Xray работает;
искать DNS-проблему без dnsLog или без отдельной проверки DNS.

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

Логи могут содержать чувствительную информацию: IP-адреса, домены, email-метки, порты, последовательность событий и признаки активности пользователей. Production-конфигурация должна включать политику хранения, ротации, доступа и маскирования логов.

Чек-лист

Понятно, где находятся access и error logs.
loglevel соответствует этапу: настройка, диагностика или production.
DNS-логи включаются только при необходимости.
При передаче логов используется маскирование.
Логи доступны только администраторам.
Ошибки Xray проверяются отдельно от ошибок панели 3x-ui.

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

Project X: Log Configuration — https://xtls.github.io/en/config/log.html

log: логи Xray