275 lines
10 KiB
Markdown
275 lines
10 KiB
Markdown
# VPS Интеграция между Главным сайтом и Панелью управления
|
||
|
||
## 📋 Документация
|
||
|
||
### Для разработчика главного сайта
|
||
**Файл:** `FOR_MAIN_SITE_DEVELOPER.md`
|
||
|
||
Читайте этот файл если вы разработчик **ospab.host** (главный сайт)
|
||
|
||
Содержит:
|
||
- ✅ Как установить переменные окружения
|
||
- ✅ Готовый TypeScript сервис для синхронизации
|
||
- ✅ Примеры использования в Express
|
||
- ✅ Обработка ошибок и retry logic
|
||
- ✅ Тестирование через curl
|
||
|
||
### Для разработчика панели управления
|
||
**Файл:** `CLIENT_VPS_INTEGRATION.md`
|
||
|
||
Читайте этот файл если вы разработчик **ospab-panel** (панель управления)
|
||
|
||
Содержит:
|
||
- ✅ Полную архитектуру и диаграммы
|
||
- ✅ Описание таблицы VPS в БД
|
||
- ✅ Все API эндпоинты и их параметры
|
||
- ✅ Схему авторизации (JWT + API Key)
|
||
- ✅ Примеры запросов
|
||
- ✅ Таблицу соответствия полей
|
||
|
||
### Для интеграции (кроссплатформенное)
|
||
**Файл:** `VPS_SYNC_EXAMPLES.md`
|
||
|
||
Примеры кода на разных языках:
|
||
- ✅ Node.js / TypeScript
|
||
- ✅ Python
|
||
- ✅ curl для тестирования
|
||
|
||
Примеры операций:
|
||
- ✅ Создание VPS
|
||
- ✅ Обновление статуса
|
||
- ✅ Удаление VPS
|
||
|
||
### Быстрый старт
|
||
**Файл:** `VPS_SYNC_QUICK_START.md`
|
||
|
||
TL;DR версия - что нужно сделать прямо сейчас (5 минут на прочтение)
|
||
|
||
## 🏗️ Архитектура
|
||
|
||
```
|
||
┌──────────────────────────────┐
|
||
│ Главный сайт │
|
||
│ (ospab.host) │
|
||
│ │
|
||
│ - Каталог тарифов │
|
||
│ - Оплата │
|
||
│ - Создание VPS │
|
||
└────────────┬─────────────────┘
|
||
│
|
||
│ POST /api/vps/sync
|
||
│ (X-API-Key: secret)
|
||
│
|
||
▼
|
||
┌──────────────────────────────────┐
|
||
│ Панель управления │
|
||
│ (ospab-panel) │
|
||
│ │
|
||
│ POST /api/vps/sync │
|
||
│ - Создать VPS │
|
||
│ - Обновить статус │
|
||
│ - Удалить VPS │
|
||
│ │
|
||
│ GET /api/vps │
|
||
│ - Получить список VPS │
|
||
│ (требует JWT токен) │
|
||
│ │
|
||
└────────────┬─────────────────────┘
|
||
│
|
||
▼
|
||
┌────────────────┐
|
||
│ MySQL БД │
|
||
│ (VPS table) │
|
||
└────────────────┘
|
||
```
|
||
|
||
## 🔄 Workflow
|
||
|
||
### Создание VPS
|
||
|
||
```
|
||
1. Пользователь на главном сайте выбирает тариф
|
||
↓
|
||
2. Оплачивает заказ
|
||
↓
|
||
3. Главный сайт создает VPS на Proxmox/VMware
|
||
↓
|
||
4. Главный сайт отправляет POST /api/vps/sync (action: create)
|
||
с параметрами: user_id, name, cpu, ram, disk, os
|
||
↓
|
||
5. Панель управления сохраняет VPS в БД
|
||
↓
|
||
6. Главный сайт обновляет статус на "running" (action: update)
|
||
↓
|
||
7. Клиент видит VPS в Панели управления и может им управлять
|
||
```
|
||
|
||
### Изменение статуса VPS
|
||
|
||
```
|
||
1. Администратор меняет статус VPS на хостинге
|
||
↓
|
||
2. Главный сайт получает информацию об изменении
|
||
↓
|
||
3. Главный сайт отправляет POST /api/vps/sync (action: update)
|
||
с параметрами: id, status
|
||
↓
|
||
4. Панель управления обновляет запись в БД
|
||
↓
|
||
5. Клиент видит актуальный статус в Панели управления
|
||
```
|
||
|
||
### Удаление VPS
|
||
|
||
```
|
||
1. Клиент отменяет услугу на главном сайте
|
||
↓
|
||
2. Главный сайт удаляет VPS с хостинга
|
||
↓
|
||
3. Главный сайт отправляет POST /api/vps/sync (action: delete)
|
||
с параметром: id
|
||
↓
|
||
4. Панель управления удаляет запись из БД
|
||
↓
|
||
5. VPS исчезает из списка в Панели управления
|
||
```
|
||
|
||
## 🔐 Безопасность
|
||
|
||
### API Key (для главного сайта)
|
||
|
||
```
|
||
Запрос:
|
||
POST /api/vps/sync
|
||
X-API-Key: your_secret_api_key_here
|
||
|
||
Проверка:
|
||
- Ключ должен быть в переменной VPS_SYNC_API_KEY на Панели
|
||
- Ключи на главном сайте и Панели должны совпадать
|
||
- Минимум 32 символа
|
||
```
|
||
|
||
### JWT Token (для клиентов панели)
|
||
|
||
```
|
||
Запрос:
|
||
GET /api/vps
|
||
Authorization: Bearer <jwt_token>
|
||
|
||
Проверка:
|
||
- Токен должен быть в заголовке Authorization
|
||
- Панель проверяет токен и извлекает user_id
|
||
- Возвращаются только VPS этого пользователя
|
||
```
|
||
|
||
## 📊 Таблица соответствия
|
||
|
||
| Главный сайт | Панель управления | Тип | Примечание |
|
||
|--------------|-------------------|-----|-----------|
|
||
| userId | user_id | int | ID пользователя из SSO |
|
||
| name | name | string | Имя VPS |
|
||
| cpu | cpu | int | Количество ядер |
|
||
| ram (GB) | ram (MB) | int | **Конвертируется: ×1024** |
|
||
| disk | disk | int | Объем диска в GB |
|
||
| os | os | string | ОС: Ubuntu 22.04, CentOS 7, etc |
|
||
| hypervisor | hypervisor | string | proxmox, vmware, hyperv, kvm, xen |
|
||
| status | status | string | creating, running, stopped, suspended |
|
||
|
||
## 🚀 Начало работы
|
||
|
||
### Для главного сайта
|
||
|
||
1. Скачайте `FOR_MAIN_SITE_DEVELOPER.md`
|
||
2. Скопируйте пример сервиса из документации
|
||
3. Адаптируйте под свой код
|
||
4. Добавьте в `.env` переменные
|
||
5. Протестируйте через curl
|
||
|
||
### Для панели управления
|
||
|
||
✅ Уже готово! API эндпоинт `/api/vps/sync` уже работает
|
||
|
||
Просто убедитесь что:
|
||
- В `.env` установлен `VPS_SYNC_API_KEY`
|
||
- Go сервер запущен на корректном порту
|
||
- БД доступна и миграции применены
|
||
|
||
## 🧪 Тестирование
|
||
|
||
### Тест создания VPS
|
||
|
||
```bash
|
||
# Отправить запрос
|
||
curl -X POST http://localhost:5050/api/vps/sync \
|
||
-H "Content-Type: application/json" \
|
||
-H "X-API-Key: your_secret_api_key_here_min_32_chars_change_this" \
|
||
-d '{
|
||
"action": "create",
|
||
"vps": {
|
||
"user_id": 5,
|
||
"name": "test-vps-01",
|
||
"status": "creating",
|
||
"cpu": 2,
|
||
"ram": 2048,
|
||
"disk": 50,
|
||
"os": "Ubuntu 22.04 LTS",
|
||
"hypervisor": "proxmox"
|
||
}
|
||
}'
|
||
|
||
# Ожидаемый ответ (201):
|
||
# {
|
||
# "status": "success",
|
||
# "message": "VPS synced successfully",
|
||
# "vps": {
|
||
# "id": 1,
|
||
# "name": "test-vps-01",
|
||
# "status": "creating",
|
||
# ...
|
||
# }
|
||
# }
|
||
```
|
||
|
||
### Проверить что VPS в Панели
|
||
|
||
1. Откройте Панель управления: http://localhost:3000
|
||
2. Зайдите под пользователем с ID = 5
|
||
3. Перейдите в "Мои серверы"
|
||
4. Должен появиться VPS "test-vps-01"
|
||
|
||
## 📝 Статус реализации
|
||
|
||
- ✅ API эндпоинт `/api/vps/sync` реализован
|
||
- ✅ Методы: create, update, delete готовы
|
||
- ✅ Таблица VPS создана в БД
|
||
- ✅ Документация написана
|
||
- ✅ Примеры кода готовы
|
||
- ⏳ Интеграция с главным сайтом (в процессе)
|
||
|
||
## ❓ Часто задаваемые вопросы
|
||
|
||
**Q: Почему два разных способа авторизации?**
|
||
A: API Key используется для сервер-сервер коммуникации (главный сайт → панель), JWT используется для клиент-сервер (браузер → панель)
|
||
|
||
**Q: Что если главный сайт отправил неправильные данные?**
|
||
A: Панель валидирует все данные и возвращает ошибку 400 Bad Request с описанием проблемы
|
||
|
||
**Q: Может ли клиент создать VPS через панель напрямую?**
|
||
A: Нет, панель только отображает VPS синхронизированные с главного сайта. Создание происходит только через главный сайт.
|
||
|
||
**Q: Что такое status "creating"?**
|
||
A: VPS только что был создан, но еще не полностью готов. После установки ОС статус обновляется на "running"
|
||
|
||
## 📞 Контакты
|
||
|
||
- Документация: смотрите файлы в репозитории
|
||
- Вопросы по API: читайте `CLIENT_VPS_INTEGRATION.md`
|
||
- Примеры: читайте `VPS_SYNC_EXAMPLES.md`
|
||
- Для главного сайта: читайте `FOR_MAIN_SITE_DEVELOPER.md`
|
||
|
||
---
|
||
|
||
**Версия:** 1.0
|
||
**Дата:** 27 октября 2025
|
||
**Статус:** Готово к интеграции ✅
|