PasarGuard
Панель

Конфигурация ядра

Валидация конфигурации XRay, значения по умолчанию и документация API

Документация по конфигурации XRay

Этот документ объясняет, как PasarGuard проверяет и обрабатывает файлы конфигурации XRay, включая процесс валидации, значения по умолчанию и ограничения API.

Содержание

  1. Обзор
  2. Валидация конфигурации
  3. Значения по умолчанию
  4. Поддерживаемые протоколы
  5. Типы сетей
  6. Настройки безопасности
  7. Просмотр подключенных IP
  8. Частые ошибки валидации

Обзор

Класс XRayConfig отвечает за:

  • Валидацию JSON-файлов конфигурации XRay
  • Извлечение значений по умолчанию из конфигурации
  • Обработку настроек входящих и исходящих соединений
  • Обработку специальных конфигураций, таких как fallback и TLS/Reality

Когда вы создаете или изменяете конфигурацию ядра через API, PasarGuard автоматически проверяет вашу конфигурацию XRay с помощью этого класса.


Валидация конфигурации

Обязательные поля

Ваша конфигурация XRay должна включать:

  1. inbounds - Массив конфигураций входящих соединений

    • Не может быть пустым или отсутствовать
    • Каждый inbound должен иметь уникальный tag
    • Каждый inbound должен иметь поле protocol
  2. outbounds - Массив конфигураций исходящих соединений

    • Не может быть пустым или отсутствовать
    • Каждый outbound должен иметь уникальный tag

Правила тегов входящих соединений

Теги входящих соединений имеют строгие правила:

  • Должны быть уникальными - Никакие два inbound не могут иметь одинаковый тег
  • Должны присутствовать - Каждый inbound требует тег
  • Не могут содержать запятую (,) - Символ , не допускается
  • Не могут содержать <=> - Эта последовательность зарезервирована для обработки fallback
{
  "inbounds": [
    {
      "tag": "vless-ws-443",
      "port": 443,
      "protocol": "vless"
    },
    {
      "tag": "trojan-tls-8443",
      "port": 8443,
      "protocol": "trojan"
    },
    {
      "tag": "vmess-grpc",
      "port": 443,
      "protocol": "vmess"
    }
  ]
}
{
  "inbounds": [
    {
      "tag": "inbound,fallback",  // ❌ Содержит запятую
      "port": 443,
      "protocol": "vless"
    },
    {
      "tag": "inbound<=>fallback",  // ❌ Содержит <=>
      "port": 8443,
      "protocol": "trojan"
    }
  ]
}

Требования к портам

Большинство inbound должны иметь поле port. Единственное исключение - когда:

  • Inbound используется как назначение fallback (ссылается настройками fallback другого inbound)
  • Inbound имеет свой собственный массив fallbacks в настройках

Требование к порту

Большинство inbound требуют поля port. Только fallback inbound (те, на которые ссылаются другие inbound или которые имеют свой собственный массив fallbacks) могут пропустить порт.

Пример:

{
  "tag": "main-inbound",
  "port": 443,  // ✅ Требуется для большинства inbound
  "protocol": "vless"
}

Значения по умолчанию

При обработке вашей конфигурации PasarGuard извлекает и устанавливает значения по умолчанию для различных настроек. Вот что устанавливается автоматически:

Базовые настройки (Все Inbound)

Эти значения по умолчанию применяются к каждому inbound:

ПолеЗначение по умолчаниюОписание
network"tcp"Тип транспортной сети
tls"none"Тип безопасности/шифрования
sni[]Список Server Name Indication (пустой массив)
host[]Список заголовков Host (пустой массив)
path""Строка пути (пустая)
header_type""Тип заголовка (пустая строка)
is_fallbackfalseЯвляется ли это fallback inbound
fallbacks[]Конфигурации fallback (пустой массив)
portNoneНомер порта (должен быть указан в конфигурации)

Значения по умолчанию для конкретных протоколов

Значения по умолчанию протокола VLESS:

  • flow: "" (пустая строка) - Настройка управления потоком
  • encryption: "none" - Метод шифрования
  • decryption: "none" - Метод расшифровки

Если decryption не равен "none", то encryption также должен быть указан.

Значения по умолчанию протокола Shadowsocks:

  • method: "" - Метод шифрования (должен быть указан)
  • is_2022: false - Используются ли методы 2022-blake3
  • password: Должен быть валидной строкой base64 (для методов 2022-blake3)

Ограничения Shadowsocks

  • ❌ Метод 2022-blake3-chacha20-poly1305 не поддерживается
  • ✅ Поддерживаются только методы 2022-blake3-aes-*-gcm

Значения по умолчанию безопасности Reality:

ПолеЗначение по умолчаниюОписание
fp"chrome"Тип отпечатка
tls"reality"Тип безопасности
sniИз serverNames в realitySettingsИмена серверов
pbkВычисляется из privateKeyПубличный ключ (генерируется автоматически)
sidsИз shortIds в realitySettingsКороткие ID (обязательно)
spx""Настройка SpiderX (необязательно)
mldsa65VerifyИз realitySettingsПроверка MLDSA65

Обязательные настройки Reality:

  • privateKey - Должен быть указан
  • shortIds - Должен быть определен хотя бы один короткий ID
  • serverNames - Используется для SNI

Поддерживаемые протоколы

PasarGuard обрабатывает и проверяет эти протоколы:

  1. Vmess
  2. Vless
  3. Trojan
  4. Shadowsocks

Другие протоколы в вашей конфигурации (например, socks, http) будут игнорироваться во время обработки, но не вызовут ошибок.


Типы сетей

Поддерживаются следующие типы сетей/транспорта:

Тип сетиОписаниеСпециальная обработка
tcpTCP транспортТип сети по умолчанию
rawСырой TCPТа же обработка, что и TCP
wsWebSocketpath и host должны быть строками
grpcgRPCИспользует serviceName как path
gungUNТо же, что и gRPC
quicQUICИспользует key как path
httpupgradeHTTP UpgradeСтандартная обработка path/host
splithttpSplit HTTPВключает настройку mode
xhttpXHTTPВключает настройку mode
kcpKCPИспользует seed как path
httpHTTP/1.1Стандартный HTTP
h2HTTP/2Стандартный HTTP
h3HTTP/3Стандартный HTTP

Правила для конкретных сетей

Сети TCP/Raw:

  • path и host в заголовках должны быть массивами (не строками)
  • Если path является массивом, используется только первый элемент
  • host может быть массивом значений host

Пример:

{
  "streamSettings": {
    "network": "tcp",
    "tcpSettings": {
      "header": {
        "type": "http",
        "request": {
          "path": ["/path"],  // ✅ Массив
          "headers": {
            "Host": ["example.com"]  // ✅ Массив
          }
        }
      }
    }
  }
}

WebSocket (WS):

  • path и host должны быть строками (не массивами)
  • host внутренне преобразуется в массив с одним элементом

Пример:

{
  "streamSettings": {
    "network": "ws",
    "wsSettings": {
      "path": "/path",  // ✅ Строка
      "host": "example.com"  // ✅ Строка
    }
  }
}

gRPC:

  • path извлекается из serviceName
  • host извлекается из authority

Пример:

{
  "streamSettings": {
    "network": "grpc",
    "grpcSettings": {
      "serviceName": "my-service",  // Используется как path
      "authority": "example.com"     // Используется как host
    }
  }
}

Настройки безопасности

None (Без безопасности)

  • Тип безопасности по умолчанию
  • Без шифрования или TLS
  • Используется для обычных соединений или когда шифрование обрабатывается на уровне приложения

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

При использовании безопасности TLS:

Обработка сертификатов:

  • Сертификаты могут быть предоставлены через:
    • certificateFile - Путь к файлу сертификата (требует keyFile)
    • certificate - Прямое содержимое сертификата (строка или массив)
  • Если используется certificateFile, вы должны также предоставить keyFile
  • SNI (Server Name Indication) автоматически извлекается из сертификатов

Требования к сертификатам

Если используется certificateFile, вы должны также предоставить keyFile. Оба файла обязательны.

Пример:

{
  "streamSettings": {
    "security": "tls",
    "tlsSettings": {
      "certificates": [{
        "certificateFile": "/path/to/cert.pem",
        "keyFile": "/path/to/key.pem"
      }]
    }
  }
}

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

При использовании безопасности Reality:

Обязательные поля:

  • privateKey - Приватный ключ для X25519
  • shortIds - Массив с хотя бы одним коротким ID (может быть пустой строкой "")
  • serverNames - Массив имен серверов для SNI

Необязательные поля:

  • SpiderX - Конфигурация SpiderX
  • mldsa65Verify - Настройка проверки MLDSA65

Обязательные настройки Reality

  • privateKey - Должен быть указан
  • shortIds - Должен быть определен хотя бы один короткий ID (может быть пустой строкой)
  • serverNames - Используется для SNI

Пример:

{
  "streamSettings": {
    "security": "reality",
    "realitySettings": {
      "serverNames": ["example.com"],
      "privateKey": "your-private-key-here",
      "shortIds": [""]
    }
  }
}

Просмотр подключенных IP

Вы можете включить отслеживание статистики онлайн-пользователей, чтобы видеть последние IP-адреса, подключенные к вашему ядру. Эта функция позволяет вам отслеживать, какие IP-адреса в настоящее время подключены к вашему ядру XRay.

Включение статистики онлайн-пользователей

Чтобы включить эту функцию, вам нужно добавить раздел policy в корень вашего JSON-файла конфигурации XRay. Добавьте следующую конфигурацию:

{
  "policy": {
    "levels": {
      "0": {
        "statsUserOnline": true
      }
    }
  },
  "inbounds": [
    // ... ваши конфигурации inbound
  ],
  "outbounds": [
    // ... ваши конфигурации outbound
  ]
}

Конфигурация Policy

Раздел policy должен быть добавлен на корневом уровне вашего JSON-файла конфигурации, вместе с inbounds и outbounds. Настройка statsUserOnline: true включает отслеживание статистики подключений пользователей.

Просмотр подключенных IP

После включения policy statsUserOnline и перезапуска вашего узла:

  1. Требуется первое подключение: Отслеживание IP начнет работать после установления первого подключения пользователя
  2. Доступ к статистике: После включения и после первого подключения вы можете просматривать последние подключенные IP через интерфейс статистики вашей панели

Требуется перезапуск

После добавления конфигурации policy вы должны перезапустить ваше ядро, чтобы изменения вступили в силу.

Полный пример

Вот полный пример конфигурации с включенным разделом policy:

{
  "policy": {
    "levels": {
      "0": {
        "statsUserOnline": true
      }
    }
  },
  "inbounds": [
    {
      "tag": "vless-ws-443",
      "port": 443,
      "protocol": "vless",
      "settings": {
        "clients": []
      },
      "streamSettings": {
        "network": "ws",
        "wsSettings": {
          "path": "/path"
        }
      }
    }
  ],
  "outbounds": [
    {
      "tag": "direct",
      "protocol": "freedom"
    }
  ]
}

Частые ошибки валидации

Вот частые ошибки, с которыми вы можете столкнуться, и способы их исправления:

Ошибка: "config doesn't have inbounds"

Проблема: В вашей конфигурации отсутствует массив inbounds.

Решение:

{
  "inbounds": [
    {
      "tag": "my-inbound",
      "port": 443,
      "protocol": "vless"
    }
  ],
  "outbounds": []
}

Ошибка: "all inbounds must have a unique tag"

Проблема: Два или более inbound имеют одинаковое значение тега.

Решение: Убедитесь, что каждый inbound имеет уникальный тег:

{
  "inbounds": [
    {"tag": "inbound-1", "port": 443, "protocol": "vless"},
    {"tag": "inbound-2", "port": 8443, "protocol": "trojan"}  // ✅ Разный тег
  ]
}

Ошибка: "character «,» is not allowed in inbound tag"

Проблема: Тег вашего inbound содержит запятую или <=>.

Решение: Удалите запятые и <=> из тегов:

{
  "inbounds": [
    {
      "tag": "inbound,fallback",  // ❌ Невалидно
      "port": 443,
      "protocol": "vless"
    },
    {
      "tag": "inbound-fallback",  // ✅ Валидно
      "port": 443,
      "protocol": "vless"
    }
  ]
}

Ошибка: "{tag} inbound doesn't have port"

Проблема: У inbound отсутствует обязательное поле port.

Решение: Добавьте номер порта:

{
  "tag": "my-inbound",
  "port": 443,  // ✅ Добавьте это
  "protocol": "vless"
}

Ошибка: "only 2022-blake3-aes-*-gcm methods are supported"

Проблема: Вы используете неподдерживаемый метод Shadowsocks.

Решение: Используйте поддерживаемый метод:

{
  "protocol": "shadowsocks",
  "settings": {
    "method": "2022-blake3-aes-128-gcm"  // ✅ Поддерживается
    // "method": "2022-blake3-chacha20-poly1305"  // ❌ Не поддерживается
  }
}

Ошибка: "Shadowsocks password must be a valid base64 string"

Проблема: Для методов 2022-blake3 пароль должен быть в формате base64.

Решение: Убедитесь, что пароль является валидным base64:

{
  "settings": {
    "method": "2022-blake3-aes-128-gcm",
    "password": "base64-encoded-password-here"  // ✅ Должен быть base64
  }
}

Ошибка: "You need to provide privateKey in realitySettings"

Проблема: В конфигурации Reality отсутствует приватный ключ.

Решение:

{
  "streamSettings": {
    "security": "reality",
    "realitySettings": {
      "privateKey": "your-private-key-here",  // ✅ Обязательно
      "shortIds": [""],
      "serverNames": ["example.com"]
    }
  }
}

Ошибка: "You need to define at least one shortID in realitySettings"

Проблема: В настройках Reality отсутствует или пуст массив shortIds.

Решение:

{
  "realitySettings": {
    "shortIds": [""],  // ✅ Хотя бы один элемент (может быть пустой строкой)
    // "shortIds": []  // ❌ Пустой массив не допускается
  }
}

Ошибка: "Settings of {tag} for path and host must be list, not str"

Проблема: Для сетей TCP/raw path и host в заголовках должны быть массивами.

Решение:

{
  "streamSettings": {
    "network": "tcp",
    "tcpSettings": {
      "header": {
        "type": "http",
        "request": {
          "path": ["/path"],  // ✅ Массив, а не строка
          "headers": {
            "Host": ["example.com"]  // ✅ Массив, а не строка
          }
        }
      }
    }
  }
}

Ошибка: "Settings for path and host must be str, not list"

Проблема: Для WebSocket path и host должны быть строками.

Решение:

{
  "streamSettings": {
    "network": "ws",
    "wsSettings": {
      "path": "/path",  // ✅ Строка, а не массив
      "host": "example.com"  // ✅ Строка, а не массив
    }
  }
}

Резюме

Лучшие практики

  • ✅ Всегда включайте массивы inbounds и outbounds
  • ✅ Убедитесь, что все inbound и outbound имеют уникальные теги
  • ✅ Избегайте запятых и <=> в тегах inbound
  • ✅ Указывайте номера портов для inbound (если не используете fallback)
  • ✅ Используйте поддерживаемые протоколы: vmess, vless, trojan, shadowsocks
  • ✅ Следуйте правилам для конкретных сетей для форматов path/host
  • ✅ Указывайте обязательные поля для безопасности TLS и Reality
  • ✅ Держите строки тегов под 2048 символов в общей сложности
  • ✅ Ядро по умолчанию (id=1) нельзя удалить

Для получения дополнительной информации о формате конфигурации XRay обратитесь к официальной документации XRay.