sitemap и тд

2025-11-01 12:29:46 +03:00
parent 727785c7a0
commit d45baf2260
80 changed files with 9811 additions and 748 deletions
--- a/Manuals/VPS_INTEGRATION_README.md
+++ b/Manuals/VPS_INTEGRATION_README.md
@@ -0,0 +1,274 @@
+# 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  
+**Статус:** Готово к интеграции ✅