Как включить Hot Reload для Xray Core

Xray Core поддерживает горячую перезагрузку конфигурации через API и специальные CLI команды, что позволяет добавлять и удалять пользователей без перезапуска сервиса и обрыва соединений. Основной подход включает использование gRPC API для динамического управления inbound’ами и пользователями.

Содержание

• Основные методы горячей перезагрузки
• Настройка gRPC API для управления пользователями
• Использование CLI команд для динамического управления
• Оптимизация для большого количества inbounds
• Автоматизация процессов управления
• Заключение и рекомендации

Основные методы горячей перезагрузки

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

1. Через gRPC API - основной метод для динамического управления
2. Через CLI команды - для добавления/удаления inbound’ов и пользователей
3. Через внешние скрипты - для автоматизации процессов

Важно отметить, что Xray Core изначально планировал поддерживать функцию “Certificate Hot Update”, которая автоматически идентифицирует обновления сертификатов и перезагружает их без ручного перезапуска [source]. Эта концепция может быть расширена и для других аспектов конфигурации.

Настройка gRPC API для управления пользователями

Для использования горячей перезагрузки необходимо сначала включить gRPC API в конфигурации Xray:

{
  "inbounds": [...],
  "outbounds": [...],
  "api": {
    "services": [
      "HandlerService",
      "LoggerService",
      "StatsService"
    ]
  },
  "stats": {}
}

После настройки API можно использовать различные методы управления:

Добавление пользователя через API

# Используя CLI команду
xray api adduser --email user@example.com --inbound-tag your-inbound-tag --user-id 12345678-1234-1234-1234-123456789012

Удаление пользователя через API

xray api removeuser --email user@example.com --inbound-tag your-inbound-tag

Как отмечается в обсуждениях GitHub, можно добавлять новых пользователей через API без перезагрузки, используя метод добавления во временный inbound, а затем замены активного inbound’а [source].

Использование CLI команд для динамического управления

Xray Core предоставляет набор CLI команд для управления конфигурацией без перезапуска:

Для управления пользователями существуют специализированные команды:

# Добавление пользователя
xray api inbounduseradd --email newuser@example.com --inbound-tag main-inbound --user-id $(uuidgen)

# Удаление пользователя  
xray api inbounduserremove --email olduser@example.com --inbound-tag main-inbound

# Получение списка пользователей
xray api inbounduserlist --inbound-tag main-inbound

Эти команды позволяют динамически управлять пользователями в работающем экземпляре Xray без необходимости перезапуска сервиса.

Оптимизация для большого количества inbounds

При работе с 25 inbound’ами по 9 пользователей каждый (всего ~225 пользователей) рекомендуется следующий подход:

1. Группировка пользователей по inbound’ам

{
  "inbounds": [
    {
      "tag": "users-group-1",
      "listen": "0.0.0.0", 
      "port": 443,
      "protocol": "vless",
      "settings": {
        "clients": [
          {"id": "user1-id", "email": "user1@example.com"},
          {"id": "user2-id", "email": "user2@example.com"},
          ...
        ]
      }
    }
  ]
}

2. Использование скриптов для массового управления

#!/bin/bash
# Скрипт для добавления пользователя без перезапуска

EMAIL=$1
USER_ID=$(uuidgen)
INBOUND_TAG="users-group-1"

# Добавление пользователя через API
xray api inbounduseradd --email $EMAIL --inbound-tag $INBOUND_TAG --user-id $USER_ID

echo "Пользователь $EMAIL добавлен в $INBOUND_TAG с ID: $USER_ID"

3. Стратегия миграции пользователей

При необходимости массовых изменений рекомендуется:

1. Создать новый inbound с обновленной конфигурацией
2. Мигрировать пользователей в новый inbound через API
3. Перенаправить трафик на новый inbound
4. Удалить старый inbound

Автоматизация процессов управления

Для удобства управления можно использовать Python библиотеку xtlsapi:

from xtlsapi import XrayClient

# Инициализация клиента
xray_client = XrayClient('localhost', 10085)  # порт gRPC API

# Добавление пользователя
user = xray_client.add_client('main-inbound', 'user-id', 'user@example.com')

# Удаление пользователя  
xray_client.remove_client('main-inbound', 'user@example.com')

# Перезапуск логгера
xray_client.restart_logger()

Также можно использовать systemd таймеры для автоматического обновления конфигурации:

# /etc/systemd/system/xray-user-update.timer
[Unit]
Description=Update Xray users automatically

[Timer]
OnCalendar=daily
Persistent=true

[Install]
WantedBy=timers.target

Заключение и рекомендации

Для решения проблемы с обрывом соединений при добавлении/удалении пользователей в Xray Core рекомендуется:

1. Включить gRPC API в конфигурации для возможности динамического управления
2. Использовать CLI команды inbounduseradd и inbounduserremove вместо редактирования config.json
3. Разработать скрипты автоматизации для управления пользователями через API
4. Для массовых изменений использовать стратегию миграции через временные inbound’ы
5. Мониторить статистику с помощью встроенных сервисов статистики Xray

При правильной настройке API и использовании соответствующих CLI команд можно полностью избежать перезапуска сервиса Xray Core при управлении пользователями, что гарантирует непрерывность работы для всех клиентов.

Источники

1. Обсуждение GitHub - Reload configuration without restart
2. Официальная документация - Command Parameters
3. Официальная документация - Xray Server
4. Python библиотека xtlsapi
5. Go packages - inbound management
6. Issue 1378 - Add user to inbound via api in xray cli