mirror of
https://github.com/MHSanaei/3x-ui.git
synced 2026-01-15 10:09:34 +00:00
264 lines
9.8 KiB
Markdown
264 lines
9.8 KiB
Markdown
# 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. Проверьте, что порт инбаунда открыт на ноде
|