306 lines
9.8 KiB
Markdown
306 lines
9.8 KiB
Markdown
# Чек-лист интеграции для главного сайта (ospab.host)
|
||
|
||
## 📋 Подготовка к интеграции
|
||
|
||
### Фаза 1: Координация (1 день)
|
||
|
||
- [ ] **Получить API ключ** от администратора панели управления
|
||
- Контакт: Свяжитесь с разработчиком панели
|
||
- Ключ должен быть минимум 32 символа
|
||
- Пример: `your_secret_api_key_here_min_32_chars_change_this`
|
||
|
||
- [ ] **Запросить URL панели управления**
|
||
- Production: `https://panel.ospab.host`
|
||
- Development/Testing: `http://localhost:5050`
|
||
|
||
- [ ] **Получить таблицу соответствия user ID**
|
||
- Как мап ID пользователей главного сайта на ID в OSPAB Panel
|
||
- Возможно используется SSO система
|
||
|
||
### Фаза 2: Подготовка кода (1-2 дня)
|
||
|
||
- [ ] **1. Создать файл с переменными окружения**
|
||
|
||
```bash
|
||
# .env файл добавить:
|
||
OSPAB_PANEL_URL=https://panel.ospab.host
|
||
VPS_SYNC_API_KEY=your_secret_api_key_here_min_32_chars_change_this
|
||
```
|
||
|
||
- [ ] **2. Создать сервис синхронизации**
|
||
|
||
Файл: `services/ospab-vps-sync.ts` (или аналогичный)
|
||
|
||
Использовать пример из `FOR_MAIN_SITE_DEVELOPER.md`
|
||
|
||
```typescript
|
||
// Методы:
|
||
// - createVPS(data) // Создать VPS
|
||
// - updateVPSStatus(id, status) // Обновить статус
|
||
// - deleteVPS(id) // Удалить VPS
|
||
```
|
||
|
||
- [ ] **3. Интегрировать в маршруты**
|
||
|
||
В файлах где обрабатывается создание/удаление VPS:
|
||
|
||
```typescript
|
||
// После успешного создания на хостинге:
|
||
await vpsSync.createVPS({ user_id, name, cpu, ram, disk, os });
|
||
|
||
// Когда VPS готов:
|
||
await vpsSync.updateVPSStatus(vpsId, 'running');
|
||
|
||
// При удалении:
|
||
await vpsSync.deleteVPS(vpsId);
|
||
```
|
||
|
||
- [ ] **4. Обработка ошибок**
|
||
|
||
```typescript
|
||
try {
|
||
await vpsSync.createVPS(data);
|
||
} catch (error) {
|
||
// Логировать ошибку
|
||
console.error('VPS sync failed:', error);
|
||
|
||
// НЕ прерывать создание VPS на хостинге
|
||
// Добавить в очередь для повторной попытки (bull, rsmq, etc)
|
||
}
|
||
```
|
||
|
||
### Фаза 3: Тестирование локально (1-2 дня)
|
||
|
||
- [ ] **1. Запустить панель управления локально**
|
||
|
||
```bash
|
||
# На компьютере разработчика панели:
|
||
go run ./cmd/server/main.go
|
||
# API доступен на: http://localhost:5050
|
||
# Web доступен на: http://localhost:3000
|
||
```
|
||
|
||
- [ ] **2. Обновить .env в главном сайте**
|
||
|
||
```env
|
||
OSPAB_PANEL_URL=http://localhost:5050
|
||
VPS_SYNC_API_KEY=your_secret_api_key_here_min_32_chars_change_this
|
||
```
|
||
|
||
- [ ] **3. Тестовый запрос через curl**
|
||
|
||
```bash
|
||
# Создание 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",
|
||
"cpu": 2,
|
||
"ram": 2048,
|
||
"disk": 50,
|
||
"os": "Ubuntu 22.04 LTS",
|
||
"status": "creating",
|
||
"hypervisor": "proxmox"
|
||
}
|
||
}'
|
||
|
||
# Ожидаемый ответ: HTTP 200, JSON с ID VPS
|
||
```
|
||
|
||
- [ ] **4. Проверить что VPS появился в панели**
|
||
|
||
1. Откройте http://localhost:3000 в браузере
|
||
2. Зайдите под пользователем с user_id = 5
|
||
3. Перейдите в "Мои серверы"
|
||
4. Должен быть VPS "test-vps"
|
||
|
||
- [ ] **5. Тесты с разными операциями**
|
||
|
||
```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":"update","vps":{"id":1,"status":"running"}}'
|
||
|
||
# Удаление
|
||
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":"delete","vps":{"id":1}}'
|
||
```
|
||
|
||
- [ ] **6. Интегрировать в процесс создания заказа**
|
||
|
||
Вставить вызовы `vpsSync` в основной workflow:
|
||
|
||
```typescript
|
||
// В файле обработки заказов:
|
||
|
||
1. Пользователь платит
|
||
2. createOrderInDB()
|
||
3. createVPSOnHypervisor() ← Создать на хостинге
|
||
4. vpsSync.createVPS() ← НОВОЕ: Синхронизировать с панелью
|
||
5. updateOrderStatus('completed') ← Помечить заказ как выполненный
|
||
```
|
||
|
||
### Фаза 4: Staging тестирование (1-2 дня)
|
||
|
||
- [ ] **1. Обновить .env на staging сервере**
|
||
|
||
```env
|
||
OSPAB_PANEL_URL=https://panel-staging.ospab.host
|
||
# или
|
||
OSPAB_PANEL_URL=https://panel.ospab.host (если production панель)
|
||
VPS_SYNC_API_KEY=production_api_key_from_admin
|
||
```
|
||
|
||
- [ ] **2. Развернуть новый код главного сайта на staging**
|
||
|
||
```bash
|
||
git push
|
||
# Deploy на staging сервер
|
||
```
|
||
|
||
- [ ] **3. Создать тестовый VPS через staging**
|
||
|
||
1. Откройте staging главного сайта
|
||
2. Создайте тестовый заказ на VPS
|
||
3. Оплатите
|
||
4. Проверьте что VPS появился в панели управления
|
||
|
||
- [ ] **4. Проверить все операции**
|
||
|
||
- [ ] Создание VPS
|
||
- [ ] Обновление статуса
|
||
- [ ] Удаление VPS
|
||
- [ ] Обработка ошибок (отключить панель, проверить retry logic)
|
||
|
||
- [ ] **5. Нагрузочное тестирование**
|
||
|
||
Создать 10-100 VPS одновременно, проверить стабильность
|
||
|
||
### Фаза 5: Production (1 день)
|
||
|
||
- [ ] **1. Финальная проверка перед production**
|
||
|
||
- [ ] Обновить .env на production
|
||
- [ ] Все переменные установлены правильно
|
||
- [ ] Логирование настроено
|
||
- [ ] Мониторинг настроен
|
||
- [ ] Бэкапы БД на месте
|
||
|
||
- [ ] **2. Развернуть на production**
|
||
|
||
```bash
|
||
# Merge в main
|
||
git merge develop
|
||
git push
|
||
|
||
# Deploy на production сервер
|
||
./deploy.sh
|
||
```
|
||
|
||
- [ ] **3. Мониторить первые часы**
|
||
|
||
- [ ] Проверять логи на ошибки
|
||
- [ ] Проверять что новые VPS создаются корректно
|
||
- [ ] Быть готовым к rollback если что-то пойдет не так
|
||
|
||
- [ ] **4. Уведомить клиентов**
|
||
|
||
Если нужно, отправить уведомление что интеграция с панелью завершена
|
||
|
||
### Фаза 6: После deployment (ongoing)
|
||
|
||
- [ ] **1. Мониторинг**
|
||
|
||
- [ ] Проверять что все VPS синхронизируются
|
||
- [ ] Отслеживать ошибки синхронизации
|
||
- [ ] Проверять производительность
|
||
|
||
- [ ] **2. Документация**
|
||
|
||
- [ ] Обновить README проекта
|
||
- [ ] Задокументировать процесс синхронизации
|
||
- [ ] Создать runbook для операций
|
||
|
||
- [ ] **3. Обучение команды**
|
||
|
||
- [ ] Объяснить команде как работает интеграция
|
||
- [ ] Показать как отладить проблемы
|
||
- [ ] Показать как мониторить синхронизацию
|
||
|
||
---
|
||
|
||
## 🔧 Инструменты и зависимости
|
||
|
||
### Необходимые пакеты (Node.js)
|
||
|
||
```bash
|
||
npm install
|
||
# Уже должны быть установлены:
|
||
# - express
|
||
# - dotenv (для загрузки .env)
|
||
# - typescript (если используется)
|
||
```
|
||
|
||
### Необходимы знания
|
||
|
||
- REST API
|
||
- TypeScript или JavaScript
|
||
- Environment variables
|
||
- Error handling
|
||
- Async/await
|
||
|
||
## ⏱️ Примерный график
|
||
|
||
```
|
||
Неделя 1:
|
||
Пн: Фаза 1 (координация)
|
||
Вт-Чт: Фаза 2 (подготовка кода)
|
||
Пт: Фаза 3 (локальное тестирование)
|
||
|
||
Неделя 2:
|
||
Пн-Ср: Фаза 4 (staging)
|
||
Чт: Финальная проверка
|
||
Пт: Фаза 5 (production)
|
||
|
||
Неделя 3+:
|
||
Мониторинг и поддержка
|
||
```
|
||
|
||
## 🚨 Критичные моменты
|
||
|
||
⚠️ **ОБЯЗАТЕЛЬНО проверить:**
|
||
|
||
1. **RAM конвертация** - `ram * 1024` (GB → MB)
|
||
2. **User ID** - должен совпадать с ID в системе OSPAB Panel
|
||
3. **API Key** - должен быть правильный и минимум 32 символа
|
||
4. **Error handling** - панель может быть недоступна, не прерывать создание VPS
|
||
5. **Retry logic** - добавить повторные попытки при сбое синхронизации
|
||
|
||
## 📞 Поддержка
|
||
|
||
Если что-то не работает:
|
||
|
||
1. Проверьте переменные окружения
|
||
2. Проверьте логи панели управления
|
||
3. Попробуйте curl запрос (как в чек-листе)
|
||
4. Свяжитесь с разработчиком панели
|
||
|
||
Документация:
|
||
- `FOR_MAIN_SITE_DEVELOPER.md` - подробная инструкция
|
||
- `CLIENT_VPS_INTEGRATION.md` - описание API
|
||
- `VPS_SYNC_EXAMPLES.md` - примеры кода
|
||
|
||
---
|
||
|
||
**Статус:** Готово к интеграции ✅
|
||
**Дата:** 27 октября 2025
|
||
**Версия:** 1.0
|