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

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

Содержание

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

Обзор

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

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

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

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

Ваша конфигурация 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 в настройках

Пример:

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

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

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

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

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

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

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

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

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

Типы сетей

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

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

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

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

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

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

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

{
  "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
  ]
}

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

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

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

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

Вот полный пример конфигурации с включенным разделом 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"
    }
  ]
}

Ограничения и ограничения API

При создании или изменении конфигураций ядра через API применяются следующие ограничения:

Ограничения полей

Специальные правила

1. Защита ядра по умолчанию

   • Конфигурация ядра с id = 1 не может быть удалена
   • Это конфигурация ядра по умолчанию/системная

2. Длина строки тегов

   • Когда exclude_inbound_tags и fallbacks_inbound_tags объединяются в строку, разделенную запятыми, общая длина не должна превышать 2048 символов
   • Пример: Если у вас 100 тегов по 20 символов каждый, это 2000 символов (плюс 99 запятых = 2099), что превысит лимит

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

   • Словарь config не может быть пустым {}
   • Должен пройти все правила валидации XRay (inbounds, outbounds, теги и т.д.)

Конечные точки API

Следующие конечные точки доступны для управления конфигурацией ядра:

• POST /api/core - Создать новую конфигурацию ядра
• GET /api/core/{core_id} - Получить конфигурацию ядра по ID
• PUT /api/core/{core_id} - Изменить существующую конфигурацию ядра
• DELETE /api/core/{core_id} - Удалить конфигурацию ядра (кроме id=1)
• GET /api/cores - Список всех конфигураций ядра
• POST /api/core/{core_id}/restart - Перезапустить узлы, использующие это ядро

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

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

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

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

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

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

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

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

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

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

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

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

Резюме

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