Xray VPN-сервер: безопасный preflight перед запуском

Эта инструкция ограничена безопасной предварительной проверкой Xray на собственном Linux VPS. Она не обещает собрать рабочий VPN-сервер из универсального примера и не подменяет protocol-specific configuration reference. Здесь нет готовой конфигурации inbound или outbound, реального UUID, IP-адреса, домена, ключей, параметров REALITY и точных правил firewall. Цель уже: помочь проверить источник установщика, ожидаемые файлы, локальный JSON и способ запуска до того, как процесс начнёт принимать соединения.

Такое ограничение принципиально. Один и тот же бинарный файл Xray может работать с разными конфигурациями, а конкретный сервер требует осознанного выбора протокольной структуры. Если вы ещё не подготовили конфигурацию по официальному справочнику для своего сценария, preflight можно пройти только до этапа статического теста. Не заменяйте отсутствующую конфигурацию случайным примером из статьи или чата.

Граница preflight: что проверяется, а что остаётся за рамками

Официальный XTLS/Xray-install предназначен для операционных систем с systemd; README называет среди них Debian, CentOS и openSUSE. Поэтому сначала подтвердите, что администрируемый VPS относится к подходящей среде и действительно использует systemd. Базовый SSH-доступ не доказывает этого автоматически. Если система инициализации неизвестна или сервером управляет другой человек, остановитесь до любых изменений.

До установки выясните, нет ли на узле уже существующего Xray. Наличие прежнего бинарного файла, каталога JSON или systemd unit меняет характер задачи: вместо чистой установки вы можете затронуть рабочий экземпляр. Не перезаписывайте найденные файлы, пока не установлены их назначение и источник. Без понятного исходного состояния невозможно уверенно связать последующий результат с действиями официального установщика.

Preflight охватывает пять вопросов: тот ли источник вы открыли; совпали ли созданные пути с документацией; какой именно локальный JSON будет проверяться; проходит ли он статический тест без запуска; какой unit и какой фактический ExecStart будут использованы позднее. Настройка конкретного VLESS-сценария сюда не входит. Для выбора клиентской стороны можно отдельно изучить VPN-клиенты для VLESS, не смешивая этот выбор с проверкой сервера.

Официальный установщик: чтение до выполнения

Основанием для установки служит официальный репозиторий XTLS/Xray-install. Безопасный порядок требует сначала проверить адрес репозитория и прочитать содержимое install-release.sh, а уже затем принимать решение о выполнении. Загрузка сетевого ответа и его немедленная передача оболочке лишает вас возможности проверить, что именно будет изменено. Поэтому эта статья не предлагает конструкцию, которая слепо объединяет получение и запуск скрипта.

При чтении сопоставляйте действия скрипта с опубликованной структурой файлов. Для стандартного варианта ожидаются бинарный файл /usr/local/bin/xray, JSON в /usr/local/etc/xray/*.json, unit /etc/systemd/system/xray.service и шаблонный unit /etc/systemd/system/xray@.service. Совпадение этих ориентиров не доказывает корректность будущей протокольной настройки, но позволяет проверить, что результат установки соответствует заявленному layout.

Если источник ведёт на зеркало, сокращённый адрес или изменённую копию, не пытайтесь компенсировать неопределённость дополнительными командами. То же правило действует, если содержимое недоступно для чтения либо создаваемые пути расходятся с официальным описанием. Сначала объясните расхождение. Только понятный источник позволяет интерпретировать появившиеся на сервере файлы.

Quick Start годится как общий ориентир, но сама официальная страница предупреждает, что давно не обновлялась, и рекомендует считать configuration reference более актуальной. Поэтому старый пример не следует переносить целиком только потому, что он находится в Quick Start. Для каждого конфигурационного поля нужен актуальный раздел справочника, относящийся к выбранному сценарию.

Файлы установки и точный смысл журналов

Стандартный Xray-install создаёт /var/log/xray/access.log и /var/log/xray/error.log. Это отдельный факт от фактической записи событий. README установщика прямо отмечает, что Xray по умолчанию не пишет в /var/log/xray/*.log; чтобы направить вывод в эти файлы, соответствующие пути нужно задать в секции log конфигурации.

Поэтому пустой access.log или error.log после стандартной установки не является сам по себе признаком сбоя. Файл может существовать, но не использоваться процессом. И наоборот, отсутствие диагностических записей нельзя объяснять отсутствием файла, пока не проверены оба уровня: создан ли ожидаемый объект и включает ли выбранный JSON запись по этому пути. Не меняйте права и не создавайте новые каталоги наугад, если конфигурация вообще не направляет туда журнал.

При инвентаризации разделяйте бинарный файл, конфигурацию, units и журналы. Наличие /usr/local/bin/xray подтверждает только размещение программы. JSON в /usr/local/etc/xray/ ещё нужно связать с конкретным способом запуска. Unit-файл показывает предполагаемый запуск, но его фактическая команда может учитывать drop-in настройки. Журналы существуют как назначенные файлы, однако запись определяется секцией log.

UUID и конфигурация: подготовка без универсального шаблона

Официальная документация требует уникальный UUID, который можно сгенерировать через xray uuid или uuidgen. Сервер и клиент должны использовать одинаковое значение. UUID из публичного примера не подходит в качестве собственного идентификатора, а новое значение, созданное только на клиенте, нарушит соответствие сторон.

Не публикуйте UUID в вопросе, снимке экрана или открытом отчёте. При переносе сравнивайте значение точно: без пропущенных символов, лишних пробелов и незаметной замены. Материал о том, как обращаться с VLESS-кодами и параметрами доступа, поможет отделить формат данных от конкретного секрета и выбрать безопасный способ передачи на клиент.

В этой статье намеренно нет «минимального рабочего JSON». Evidence подтверждает расположение файлов, UUID и способы проверки, но не фиксирует один протокольный сценарий и его обязательные поля. Публикация псевдоуниверсального шаблона создала бы ложное обещание. Подготовьте собственный локальный JSON по актуальной configuration reference для выбранного сценария, не добавляя REALITY и другие неподтверждённые здесь параметры.

Перед статическим тестом назовите один конкретный файл. Для установки через официальный скрипт типичным расположением является /usr/local/etc/xray/; общая документация для Linux также упоминает /etc/xray/. Само наличие двух известных каталогов не разрешает неоднозначность. Проверять нужно тот локальный путь, который действительно выбран для будущего запуска.

Статический тест через run -test не равен запуску run -c

Официальная страница Command Line Parameters различает обычный запуск и проверку. Подкоманда run с параметром -c или -config выбирает файл конфигурации и запускает Xray. Дополнительный флаг -test меняет назначение операции: Xray проверяет конфигурационные файлы без запуска сервера.

Для стандартного single-file пути предварительная проверка выглядит так: /usr/local/bin/xray run -test -c /usr/local/etc/xray/config.json. Здесь используется локальный файл, а не удалённый URL или поток из сети. Смысл команды ограничен статической проверкой конфигурации. Она не должна запускать listener и не подтверждает, что будущий клиент сможет установить соединение.

Не убирайте -test, считая, что обычный run -c является более полной проверкой. Без -test это уже запуск процесса с выбранной конфигурацией. Если статический тест сообщает об ошибке, не переходите к systemd, сетевой политике или клиенту. Исправляйте только локальный JSON и повторяйте тот же тест, чтобы не добавлять новые переменные.

Если будущий запуск использует другой файл, замените путь в тесте только на тот локальный путь, который подтверждён для вашего unit. Не проверяйте один JSON, а затем не запускайте другой. При нескольких файлах или специальном каталоге конфигураций сначала установите фактическую команду запуска; статья не предполагает, что single-file пример автоматически описывает multi-config режим.

Обычный unit и шаблон xray@.service

Установщик создаёт обычный xray.service и шаблонный xray@.service. Файл с символом @ без имени — это template, а не запущенный экземпляр. Экземпляр обозначается в форме xray@NAME.service, где NAME подставляется вместо systemd-идентификатора %i.

В стандартном single-file режиме шаблон установщика связывает xray@NAME.service с /usr/local/etc/xray/NAME.json. Например, смысл имени определяется подстановкой NAME в имя файла, но эта статья не предлагает конкретное рабочее имя. Установщик также умеет задавать другой ExecStart для режима каталога с несколькими конфигурациями. Поэтому перед выводом о mapping нужно посмотреть фактический эффективный ExecStart, включая возможные drop-in настройки.

Последовательность после успешного статического теста состоит из отдельных этапов. Сначала определите, нужен обычный unit или именованный экземпляр шаблона. Затем подтвердите, какой файл либо каталог указан в его фактическом ExecStart. Только после этого запускайте выбранную службу через systemd и отдельно проверяйте, сохраняет ли она ожидаемое состояние. Сам факт отправки команды запуска ещё не доказывает стабильную работу.

Точные firewall-команды исключены: evidence не фиксирует дистрибутив, текущую сетевую политику и параметры VPS. Не отключайте защиту для обхода локальной ошибки. К сетевому доступу можно переходить только после успешного run -test, однозначного ExecStart и стабильного состояния выбранного unit.

Диагностика по слоям и условия остановки

Если после preflight клиент не подключается, сохраняйте порядок проверки. Сначала источник и созданные файлы, затем конкретный локальный JSON, результат run -test, фактический ExecStart, выбранный systemd unit и совпадение UUID между сервером и клиентом. Сетевой слой рассматривается после локальных подтверждений. Одновременная замена UUID, JSON, unit и сетевой политики уничтожает диагностическую последовательность.

Не используйте пустые access.log и error.log как единственное доказательство отсутствия событий: запись в эти файлы должна быть включена в log-конфигурации. Не называйте xray@.service работающим экземпляром. Не принимайте обычный run -c за безопасный config-test. Эти три различия позволяют понять, на каком именно слое расходятся ожидание и состояние сервера.

Для клиентской стороны используйте отдельный разбор «v2RayTun не подключается», не раскрывая UUID и не меняя проверенную серверную конфигурацию во время одного диагностического шага. Preflight завершён, когда источник понятен, ожидаемые файлы учтены, локальный JSON проходит run -test, unit связан с тем же источником конфигурации и после отдельного запуска сохраняет стабильное состояние. Это граница проверки, а не обещание готового подключения.