3x-ui/MULTI_NODE_ARCHITECTURE.md

Multi-Node Architecture для 3x-ui

📋 Обзор

Реализована поддержка multi-node архитектуры для панели 3x-ui с возможностью переключения между режимами работы:

• single-mode (по умолчанию) - полностью совместим с текущей логикой
• multi-mode - распределённая архитектура с отдельными нодами

🏗️ Архитектура

Single-Mode (по умолчанию)

• Используется встроенный XRAY Core на том же сервере, что и панель
• Все инбаунды работают локально
• Полная совместимость с существующим функционалом

Multi-Mode

• Панель становится центральным сервером управления (Master)
• XRAY Core больше не используется локально
• Реальные XRAY инстансы работают на отдельных нодах (Workers)
• Панель хранит:
  • Пользователей
  • Инбаунды
  • Правила маршрутизации
  • Соответствие inbound → node
• Панель генерирует подписки с endpoint'ами нод

📦 Компоненты

1. Node-сервис (Worker)

Отдельный сервис, запускаемый в Docker на каждой ноде.

Расположение: node/

Функциональность:

• REST API для управления XRAY Core
• Применение конфигураций от панели
• Перезагрузка XRAY без остановки контейнера
• Проверка статуса и здоровья

API Endpoints:

• GET /health - проверка здоровья (без аутентификации)
• POST /api/v1/apply-config - применить конфигурацию XRAY
• POST /api/v1/reload - перезагрузить XRAY
• GET /api/v1/status - получить статус XRAY

Запуск:

cd node
NODE_API_KEY=your-secure-api-key docker-compose up -d

2. Изменения в панели

База данных

Добавлены новые модели:

• Node - информация о ноде (id, name, address, api_key, status)
• InboundNodeMapping - соответствие inbound → node

Сервисы

SettingService:

• GetMultiNodeMode() - получить режим работы
• SetMultiNodeMode(enabled) - установить режим работы

NodeService:

• Управление нодами (CRUD)
• Проверка здоровья нод
• Назначение инбаундов нодам
• Отправка конфигураций на ноды

XrayService:

• Автоматическое определение режима работы
• В single-mode: работает как раньше
• В multi-mode: отправляет конфигурации на ноды вместо запуска локального XRAY

SubService:

• В multi-mode: генерирует подписки с endpoint'ами нод
• В single-mode: работает как раньше

Контроллеры

NodeController:

• GET /panel/node/list - список нод
• GET /panel/node/get/:id - получить ноду
• POST /panel/node/add - добавить ноду
• POST /panel/node/update/:id - обновить ноду
• POST /panel/node/del/:id - удалить ноду
• POST /panel/node/check/:id - проверить здоровье ноды
• POST /panel/node/checkAll - проверить все ноды
• GET /panel/node/status/:id - получить статус ноды

🔄 Как это работает

Single-Mode

1. Пользователь создаёт/изменяет инбаунд
2. Панель генерирует конфигурацию XRAY
3. Локальный XRAY Core перезапускается с новой конфигурацией
4. Подписки генерируются с endpoint панели

Multi-Mode

1. Пользователь создаёт/изменяет инбаунд
2. Пользователь назначает инбаунд ноде (через UI)
3. Панель генерирует конфигурацию XRAY для этой ноды
4. Конфигурация отправляется на ноду через REST API
5. Нода применяет конфигурацию и перезапускает свой XRAY Core
6. Подписки генерируются с endpoint ноды

🚀 Установка и настройка

1. Настройка панели

1. Включите multi-node mode в настройках панели (UI тумблер)
2. Добавьте ноды через UI (вкладка "Nodes")
3. Назначьте инбаунды нодам

2. Настройка ноды

1. Скопируйте папку node/ на сервер ноды
2. Установите XRAY Core в bin/ директорию
3. Настройте docker-compose.yml:

   environment:
     - NODE_API_KEY=your-secure-api-key
   

4. Запустите:

   docker-compose up -d
   

3. Добавление ноды в панель

1. Перейдите в раздел "Nodes"
2. Нажмите "Add Node"
3. Заполните:
   • Name: имя ноды (например, "Node-1")
   • Address: адрес API ноды (например, "http://192.168.1.100:8080")
   • API Key: ключ, указанный в NODE_API_KEY на ноде
4. Сохраните

4. Назначение инбаунда ноде

1. Перейдите в раздел "Inbounds"
2. Откройте инбаунд для редактирования
3. В выпадающем списке "Node" выберите ноду
4. Сохраните

📝 Структура файлов

3x-ui/
├── node/                          # Node-сервис (worker)
│   ├── main.go                    # Точка входа
│   ├── api/
│   │   └── server.go              # REST API сервер
│   ├── xray/
│   │   └── manager.go             # Управление XRAY процессом
│   ├── Dockerfile                 # Docker образ
│   ├── docker-compose.yml         # Docker Compose конфигурация
│   └── README.md                  # Документация ноды
├── database/
│   └── model/
│       └── model.go               # + Node, InboundNodeMapping
├── web/
│   ├── service/
│   │   ├── setting.go             # + GetMultiNodeMode, SetMultiNodeMode
│   │   ├── node.go                # NodeService (новый)
│   │   ├── xray.go                # + поддержка multi-mode
│   └── controller/
│       ├── node.go                # NodeController (новый)
│       └── xui.go                 # + маршрут /nodes
└── sub/
    └── subService.go              # + поддержка multi-mode для подписок

⚠️ Важные замечания

1. Совместимость: Все изменения минимально инвазивны и сохраняют полную совместимость с single-mode
2. Миграция: При переключении в multi-mode существующие инбаунды остаются без назначенных нод - их нужно назначить вручную
3. Безопасность: API ключи нод должны быть надёжными и храниться в безопасности
4. Сеть: Ноды должны быть доступны с панели по указанным адресам

🔧 Разработка

Запуск Node-сервиса в режиме разработки

cd node
go run main.go -port 8080 -api-key test-key

Тестирование

1. Запустите панель в multi-mode
2. Добавьте тестовую ноду
3. Создайте инбаунд и назначьте его ноде
4. Проверьте, что конфигурация отправляется на ноду
5. Проверьте, что подписки содержат правильный endpoint

📚 API Документация

Node Service API

Все запросы (кроме /health) требуют заголовок:

Authorization: Bearer <api-key>

Apply Config

POST /api/v1/apply-config
Content-Type: application/json

{
  "log": {...},
  "inbounds": [...],
  "outbounds": [...],
  ...
}

Reload

POST /api/v1/reload

Status

GET /api/v1/status

Response:
{
  "running": true,
  "version": "1.8.0",
  "uptime": 3600
}

🐛 Troubleshooting

Нода не отвечает

1. Проверьте, что нода запущена: docker ps
2. Проверьте логи: docker logs 3x-ui-node
3. Проверьте доступность: curl http://node-address:8080/health
4. Проверьте API ключ в настройках панели

Конфигурация не применяется

1. Проверьте логи ноды
2. Проверьте, что XRAY Core установлен в bin/
3. Проверьте формат конфигурации

Подписки не работают

1. Убедитесь, что инбаунд назначен ноде
2. Проверьте, что endpoint ноды доступен из сети
3. Проверьте, что порт инбаунда открыт на ноде