При `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 use | Config прочитан, но порт занят | Найти слушающий процесс и inbound port |
| failed to find an available destination | Runtime, 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 и реальные домены замените до передачи.