10 KiB
10 KiB
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 |
🚀 Начало работы
Для главного сайта
- Скачайте
FOR_MAIN_SITE_DEVELOPER.md - Скопируйте пример сервиса из документации
- Адаптируйте под свой код
- Добавьте в
.envпеременные - Протестируйте через curl
Для панели управления
✅ Уже готово! API эндпоинт /api/vps/sync уже работает
Просто убедитесь что:
- В
.envустановленVPS_SYNC_API_KEY - Go сервер запущен на корректном порту
- БД доступна и миграции применены
🧪 Тестирование
Тест создания VPS
# Отправить запрос
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 в Панели
- Откройте Панель управления: http://localhost:3000
- Зайдите под пользователем с ID = 5
- Перейдите в "Мои серверы"
- Должен появиться 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
Статус: Готово к интеграции ✅