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

**Запуск:**
```bash
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`:
   ```yaml
   environment:
     - NODE_API_KEY=your-secure-api-key
   ```
4. Запустите:
   ```bash
   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-сервиса в режиме разработки

```bash
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
```http
POST /api/v1/apply-config
Content-Type: application/json

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

#### Reload
```http
POST /api/v1/reload
```

#### Status
```http
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. Проверьте, что порт инбаунда открыт на ноде