При `xray config error` не перезапускайте работающий процесс, пока новый файл не прошёл `xray run -test -c /путь/config.json`. Команда проверяет конфигурацию без запуска сервера. Сначала также выполните `xray version`: документация Xray отслеживает свежие версии, а установленный бинарник может ещё не поддерживать скопированное поле.

Если service уже упал, сохраните stderr и журнал unit, верните последнюю известную рабочую конфигурацию и только затем разбирайте изменение. Не выкладывайте полный config в чат: UUID, privateKey, shortId, пароли и адреса внутренних узлов нужно заменить безопасными заглушками.

Сообщение ошибки определяет первый слой

Фрагмент ошибкиВероятная границаСледующий шаг
invalid character / unexpected endНевалидный JSONПроверить запятую, кавычки и закрывающие скобки
unknown fieldПоле отсутствует в этой версииСверить xray version и документацию модуля
failed to load configНеверный path или праваСравнить ExecStart и доступ пользователя service
address already in useConfig прочитан, но порт занятНайти слушающий процесс и inbound port
failed to find an available destinationRuntime, DNS или routingВключить безопасный log и проверить outbound
handshake errorСтороны не согласовали transport/TLSСверить network, security, SNI и flow на обоих концах

Синтаксический валидатор JSON видит запятую, но не знает схему Xray. Поэтому обычного `jq` недостаточно: окончательное слово остаётся за тем же Xray Core, который будет запускать service.

Проверяйте те же файлы, что читает unit

xray version
xray run -test -c /etc/xray/config.json
xray run -dump -c /etc/xray/config.json

# Если unit использует каталог:
xray run -test -confdir /etc/xray/conf.d
xray run -dump -confdir /etc/xray/conf.d

`-dump` показывает итог после объединения нескольких источников. Просматривайте результат только локально: в нём остаются секретные поля. Если ручная команда проходит, а systemd нет, сравните binary path, WorkingDirectory, аргументы ExecStart, environment и права пользователя.

Merge может изменить смысл валидных фрагментов

При `-confdir` несколько файлов объединяются. Два отдельно корректных фрагмента могут переопределить массивы, tags или routing не так, как ожидалось. Дайте каждому inbound/outbound уникальный tag и проверьте merged output перед рестартом.

  • Не смешивайте конфигурации разных клиентов Xray/V2Ray без сверки схемы.
  • Проверяйте регистр protocol, network и security values.
  • Сверяйте ссылочные tags в routing и balancers с реально объявленными объектами.
  • Путь к geoip/geosite проверяйте от имени пользователя service.
  • Меняйте по одному слою: protocol, затем transport, затем routing.

Transport должен совпасть на двух сторонах

Project X описывает transport как отдельный слой: RAW, WebSocket, gRPC и другие варианты требуют совместимых настроек peer. Валидный серверный JSON не гарантирует соединение, если клиент ожидает другой network, path, serviceName, TLS или REALITY.

После успешного `-test` поднимите копию на отдельном порту или staging-узле и проверьте один контрольный запрос. Только затем перезапускайте production и сразу смотрите журнал запуска, listening ports и handshake.

Откат должен занимать одну проверяемую операцию

Храните предыдущий config с версией, но не в публичном репозитории. Процедура: проверить backup командой `-test`, атомарно заменить файл, перезапустить service и подтвердить контрольный запрос. Если изменение содержит новую схему, откатывайте вместе с бинарником только по заранее проверенному плану.

Для совместного разбора подготовьте `xray version`, точную команду запуска, обезличенную ошибку и минимальный config, воспроизводящий сбой. Private keys, UUID и реальные домены замените до передачи.

Проверенные источники