ospab/ospab.host

Fork 0

Files

Georgiy Syralev d45baf2260 sitemap и тд

2025-11-01 12:29:46 +03:00

12 KiB

Raw Blame History

📦 VPS Интеграция - Решение

✅ Что было сделано

1. API Эндпоинт для синхронизации

✅ Путь: POST /api/vps/sync
✅ Защита: API ключ в заголовке X-API-Key
✅ Методы: create, update, delete

Файлы изменены:

internal/api/vps_handlers.go - добавлена функция SyncVPS
internal/core/vps/service.go - добавлена функция SyncVPS сервиса
internal/api/router.go - зарегистрирован новый маршрут

2. База данных

✅ Таблица vps уже создана миграцией
✅ Все необходимые поля для синхронизации
✅ Связь с таблицей users по user_id

Таблица содержит:

id              INT PRIMARY KEY
name            VARCHAR(255)
status          VARCHAR(20)
ip_address      VARCHAR(45)
cpu             INT
ram             INT (в MB)
disk            INT (в GB)
os              VARCHAR(100)
user_id         INT (FK)
hypervisor      VARCHAR(20)
created_at      TIMESTAMP
updated_at      TIMESTAMP

3. Переменные окружения

✅ Добавлена в .env:

VPS_SYNC_API_KEY=your_secret_api_key_here_min_32_chars_change_this

4. Документация

Созданы 5 документов для разработчиков:

📄 `VPS_INTEGRATION_README.md`

Главный README с обзором всей интеграции

Архитектура системы
Документация по файлам
Workflow процессов
Таблица соответствия полей

📄 `FOR_MAIN_SITE_DEVELOPER.md` ⭐ ЧИТАТЬ В ПЕРВУЮ ОЧЕРЕДЬ

Инструкция для разработчика главного сайта (ospab.host)

Пошаговая настройка
Готовый TypeScript сервис (копировать-вставить)
Примеры использования в Express
Обработка ошибок
Тестирование через curl
FAQ

📄 `CLIENT_VPS_INTEGRATION.md`

Полная техническая документация API

Описание таблицы VPS
Все API эндпоинты
Примеры запросов/ответов
Безопасность
Примеры операций

📄 `VPS_SYNC_EXAMPLES.md`

Примеры кода на разных языках

Node.js / TypeScript
Python
curl для тестирования
Workflow примеры
Решение проблем

📄 `VPS_SYNC_QUICK_START.md`

Быстрый старт (5 минут)

Минимальный пример
Ключевые моменты
Таблица параметров
Проверка что работает

📄 `INTEGRATION_CHECKLIST.md`

Чек-лист для главного сайта

По фазам: подготовка → код → тестирование → production
80+ пунктов для проверки
Примеры команд
График работ

🚀 Как использовать?

Для разработчика главного сайта

Прочитайте: FOR_MAIN_SITE_DEVELOPER.md (15 минут)
Скопируйте: TypeScript сервис из документации
Адаптируйте: Под вашу структуру проекта
Протестируйте: Используя примеры curl
Интегрируйте: В процесс создания VPS
Проверяйте: По чек-листу INTEGRATION_CHECKLIST.md

Для разработчика панели управления

✅ Уже готово! Просто убедитесь:

В .env установлен VPS_SYNC_API_KEY
Эндпоинт работает (тестируется через curl)
БД миграции применены

📊 API Маршруты

Для клиентов панели (JWT авторизация)

GET  /api/vps
     - Получить список всех VPS пользователя
     - Заголовок: Authorization: Bearer <jwt_token>

GET  /api/vps/{id}
     - Получить информацию о конкретном VPS

POST /api/vps/{id}/start
     - Запустить VPS

POST /api/vps/{id}/stop
     - Остановить VPS

POST /api/vps/{id}/restart
     - Перезагрузить VPS

POST /api/vps/{id}/reboot
     - Мягкая перезагрузка ОС

GET  /api/vps/{id}/stats
     - Получить статистику использования

Для главного сайта (API Key авторизация)

POST /api/vps/sync
     - Синхронизировать VPS (create, update, delete)
     - Заголовок: X-API-Key: <secret_key>

🔐 Безопасность

Что	Как	Где
API Key	32+ символа	`.env` → `VPS_SYNC_API_KEY`
JWT Token	Bearer token	Браузер → Панель
User ID	Фильтр в запросах	БД: `WHERE user_id = ?`
HTTPS	Обязателен	Production
Изоляция	Каждый пользователь видит только свои VPS	Service layer

📋 Пример интеграции

На главном сайте (ospab.host)

// 1. Импортируем сервис
import vpsSync from './services/ospab-vps-sync';

// 2. Когда пользователь создает заказ
const order = await createOrder({
  user_id: 5,
  cpu: 4,
  ram: 8,
  disk: 100,
  os: 'Ubuntu 22.04 LTS'
});

// 3. Создаем VPS на хостинге
const proxmoxVPS = await createVPSOnProxmox(order);

// 4. Синхронизируем с панелью управления
const panelVPS = await vpsSync.createVPS({
  user_id: order.user_id,
  name: order.name,
  cpu: order.cpu,
  ram: order.ram,
  disk: order.disk,
  os: order.os
});

console.log('VPS создан с ID:', panelVPS.id);

// 5. После того как VPS готов
setTimeout(async () => {
  await vpsSync.updateVPSStatus(panelVPS.id, 'running');
}, 60000); // 1 минута

На Панели управления (ospab-panel)

Пользователь заходит в Панель
    ↓
Видит GET /api/vps endpoint
    ↓
Отправляет запрос с JWT токеном
    ↓
Получает список всех своих VPS (синхронизированных с главного сайта)
    ↓
Может управлять VPS (start, stop, restart, etc)

✨ Ключевые возможности

✅ Синхронизация в реальном времени - данные появляются в панели сразу
✅ Надежность - поддержка retry и обработка ошибок
✅ Безопасность - API Key + JWT + User ID изоляция
✅ Масштабируемость - готово для 1000+ пользователей
✅ Гибкость - поддержка разных гипервизоров (Proxmox, VMware, и т.д.)

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

Быстрый тест (2 минуты)

# Создать 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","cpu":2,"ram":2048,"disk":50,"os":"Ubuntu 22.04","status":"creating","hypervisor":"proxmox"}}'

# Проверить что VPS создан
curl -X GET http://localhost:5050/api/vps \
  -H "Authorization: Bearer your_jwt_token"

📚 Файлы для ознакомления (в порядке важности)

FOR_MAIN_SITE_DEVELOPER.md ⭐ НАЧНИТЕ ОТСЮДА
- Для: Разработчик главного сайта
- Время: 30 минут
- Что: Полная инструкция с примерами
VPS_SYNC_QUICK_START.md ⭐ ДЛЯ БЫСТРОГО СТАРТА
- Для: Всех
- Время: 5 минут
- Что: TL;DR версия
CLIENT_VPS_INTEGRATION.md
- Для: Все разработчики
- Время: 20 минут
- Что: Техническая архитектура
VPS_SYNC_EXAMPLES.md
- Для: Разработчики Node.js, Python
- Время: 15 минут
- Что: Примеры кода
INTEGRATION_CHECKLIST.md
- Для: PM или Lead разработчик
- Время: 1 час (для выполнения)
- Что: Пошаговая проверка
VPS_INTEGRATION_README.md
- Для: Всем на справку
- Время: 10 минут
- Что: Обзор и диаграммы

🎯 Статус реализации

Панель управления (ospab-panel): ✅ ГОТОВО

✅ API эндпоинт /api/vps/sync работает
✅ Методы create/update/delete реализованы
✅ БД таблица создана и готова
✅ Все документы написаны
✅ Примеры кода готовы

Главный сайт (ospab.host): ⏳ В ПРОЦЕССЕ ИНТЕГРАЦИИ

⏳ Нужно скопировать сервис синхронизации
⏳ Нужно интегрировать в процесс создания VPS
⏳ Нужно протестировать
⏳ Нужно развернуть на production

🚀 Следующие шаги

Для главного сайта

Прочитать FOR_MAIN_SITE_DEVELOPER.md (30 мин)
Скопировать сервис синхронизации (15 мин)
Адаптировать под проект (1 день)
Интегрировать в процесс (1 день)
Протестировать (1 день)
Развернуть (1 день)

Итого: 4-5 дней работы одного разработчика

Возможные расширения

Webhook для автоматических обновлений статуса
Batch API для синхронизации множества VPS
WebSocket для real-time обновлений
Интеграция с мониторингом
Интеграция с биллингом

💡 Советы для успешной интеграции

Начните с тестирования - используйте curl примеры перед кодированием
Добавьте логирование - каждый запрос должен логироваться
Обработайте ошибки - панель может быть недоступна
Используйте retry - добавьте очередь для повторных попыток
Мониторьте - отслеживайте ошибки синхронизации
Документируйте - оставляйте комментарии в коде

📞 Контакты и поддержка

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

Все файлы находятся в корне репозитория
Начните с VPS_SYNC_QUICK_START.md
Подробности в FOR_MAIN_SITE_DEVELOPER.md

Вопросы:

Про API: смотрите CLIENT_VPS_INTEGRATION.md
Про примеры: смотрите VPS_SYNC_EXAMPLES.md
Про интеграцию: смотрите INTEGRATION_CHECKLIST.md

Версия: 1.0
Дата: 27 октября 2025
Статус: ✅ Готово к использованию

Успехов в интеграции! 🚀

12 KiB Raw Blame History Unescape Escape