sitemap и тд
This commit is contained in:
Georgiy Syralev
419
Manuals/FOR_MAIN_SITE_DEVELOPER.md
Normal file
419
Manuals/FOR_MAIN_SITE_DEVELOPER.md
Normal file
@@ -0,0 +1,419 @@
|
||||
# Инструкция для разработчика главного сайта
|
||||
|
||||
## 📌 Контекст
|
||||
|
||||
**Главный сайт** (ospab.host):
|
||||
- Каталог тарифов VPS
|
||||
- Система оплаты
|
||||
- Создание/удаление VPS на хостинге (Proxmox, VMware и т.д.)
|
||||
|
||||
**Панель управления** (ospab-panel):
|
||||
- Клиентская зона для управления своими VPS
|
||||
- Получает данные о VPS с главного сайта через API
|
||||
- Пользователи видят актуальный статус своих серверов
|
||||
|
||||
## 🔗 Как они соединяются?
|
||||
|
||||
```
|
||||
Главный сайт Панель управления
|
||||
│ │
|
||||
├─ Пользователь платит ←──┤
|
||||
├─ Создается VPS на Proxmox
|
||||
│ │
|
||||
└─ POST /api/vps/sync ──────────────→ Сохраняет в БД
|
||||
(отправляет данные) │
|
||||
Клиент видит VPS
|
||||
```
|
||||
|
||||
## 🚀 Что нужно сделать на главном сайте
|
||||
|
||||
### Шаг 1: Установить переменные окружения
|
||||
|
||||
Добавить в `.env`:
|
||||
|
||||
```bash
|
||||
# URL Панели управления OSPAB
|
||||
OSPAB_PANEL_URL=https://panel.ospab.host
|
||||
# При локальной разработке:
|
||||
# OSPAB_PANEL_URL=http://localhost:5050
|
||||
|
||||
# API ключ для синхронизации VPS
|
||||
# ⚠️ ДОЛЖЕН СОВПАДАТЬ с VPS_SYNC_API_KEY на Панели!
|
||||
VPS_SYNC_API_KEY=your_secret_api_key_here_min_32_chars_change_this
|
||||
```
|
||||
|
||||
### Шаг 2: Получить значение VPS_SYNC_API_KEY
|
||||
|
||||
**Вариант 1: Сгенерировать свой ключ**
|
||||
```bash
|
||||
# Linux/Mac
|
||||
openssl rand -hex 16
|
||||
# Результат: 6c8a4f2e9b1d3c5a7f9e2b4c6a8d0f1e
|
||||
# Добавить prefix и получится: 6c8a4f2e9b1d3c5a7f9e2b4c6a8d0f1e6c8a4f2e
|
||||
```
|
||||
|
||||
**Вариант 2: Использовать готовый ключ**
|
||||
- Свяжитесь с администратором панели
|
||||
- Он установит ключ на своей стороне в `.env`
|
||||
|
||||
### Шаг 3: Создать сервис для синхронизации VPS
|
||||
|
||||
Создайте файл `services/ospab-vps-sync.ts`:
|
||||
|
||||
```typescript
|
||||
/**
|
||||
* VPS Sync Service - синхронизация с Панелью управления OSPAB
|
||||
* Отправляет информацию о VPS через REST API
|
||||
*/
|
||||
|
||||
interface VPSSyncData {
|
||||
user_id: number; // ID пользователя в системе OSPAB
|
||||
name: string; // Имя VPS (например: web-server-01)
|
||||
cpu: number; // Количество ядер (1, 2, 4, 8, etc)
|
||||
ram: number; // ОЗУ в GB (1, 2, 4, 8, 16, 32, etc)
|
||||
disk: number; // Диск в GB (10, 50, 100, 500, 1000, etc)
|
||||
os: string; // Операционная система (Ubuntu 22.04 LTS, CentOS 7, Debian 11, etc)
|
||||
hypervisor?: string; // Тип гипервизора (proxmox по умолчанию, может быть vmware, hyperv, kvm, xen)
|
||||
}
|
||||
|
||||
class VPSSyncService {
|
||||
private panelUrl: string;
|
||||
private apiKey: string;
|
||||
|
||||
constructor() {
|
||||
this.panelUrl = process.env.OSPAB_PANEL_URL || '';
|
||||
this.apiKey = process.env.VPS_SYNC_API_KEY || '';
|
||||
|
||||
if (!this.panelUrl || !this.apiKey) {
|
||||
throw new Error('Missing OSPAB_PANEL_URL or VPS_SYNC_API_KEY environment variables');
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Создать новый VPS на Панели управления
|
||||
* Вызывается сразу после создания VPS на хостинге
|
||||
*/
|
||||
async createVPS(data: VPSSyncData) {
|
||||
console.log(`[VPS Sync] Creating VPS: ${data.name} for user ${data.user_id}`);
|
||||
|
||||
const response = await fetch(`${this.panelUrl}/api/vps/sync`, {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Content-Type': 'application/json',
|
||||
'X-API-Key': this.apiKey,
|
||||
},
|
||||
body: JSON.stringify({
|
||||
action: 'create',
|
||||
vps: {
|
||||
user_id: data.user_id,
|
||||
name: data.name,
|
||||
status: 'creating',
|
||||
cpu: data.cpu,
|
||||
ram: data.ram * 1024, // 🔴 ВАЖНО: конвертируем GB в MB!
|
||||
disk: data.disk,
|
||||
os: data.os,
|
||||
hypervisor: data.hypervisor || 'proxmox',
|
||||
},
|
||||
}),
|
||||
});
|
||||
|
||||
if (!response.ok) {
|
||||
const error = await response.json();
|
||||
throw new Error(`[VPS Sync] Create failed: ${error.message}`);
|
||||
}
|
||||
|
||||
const result = await response.json();
|
||||
console.log(`[VPS Sync] VPS created successfully, ID: ${result.vps.id}`);
|
||||
return result.vps;
|
||||
}
|
||||
|
||||
/**
|
||||
* Обновить статус VPS
|
||||
* Вызывается после изменения статуса (например, VPS запущен, остановлен, и т.д.)
|
||||
*/
|
||||
async updateVPSStatus(vpsId: number, status: string) {
|
||||
console.log(`[VPS Sync] Updating VPS ${vpsId} status to: ${status}`);
|
||||
|
||||
const response = await fetch(`${this.panelUrl}/api/vps/sync`, {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Content-Type': 'application/json',
|
||||
'X-API-Key': this.apiKey,
|
||||
},
|
||||
body: JSON.stringify({
|
||||
action: 'update',
|
||||
vps: {
|
||||
id: vpsId,
|
||||
status: status,
|
||||
},
|
||||
}),
|
||||
});
|
||||
|
||||
if (!response.ok) {
|
||||
const error = await response.json();
|
||||
throw new Error(`[VPS Sync] Update failed: ${error.message}`);
|
||||
}
|
||||
|
||||
const result = await response.json();
|
||||
console.log(`[VPS Sync] VPS ${vpsId} status updated to: ${status}`);
|
||||
return result.vps;
|
||||
}
|
||||
|
||||
/**
|
||||
* Удалить VPS
|
||||
* Вызывается когда клиент отменил услугу
|
||||
*/
|
||||
async deleteVPS(vpsId: number) {
|
||||
console.log(`[VPS Sync] Deleting VPS ${vpsId}`);
|
||||
|
||||
const response = await fetch(`${this.panelUrl}/api/vps/sync`, {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Content-Type': 'application/json',
|
||||
'X-API-Key': this.apiKey,
|
||||
},
|
||||
body: JSON.stringify({
|
||||
action: 'delete',
|
||||
vps: {
|
||||
id: vpsId,
|
||||
},
|
||||
}),
|
||||
});
|
||||
|
||||
if (!response.ok) {
|
||||
const error = await response.json();
|
||||
throw new Error(`[VPS Sync] Delete failed: ${error.message}`);
|
||||
}
|
||||
|
||||
console.log(`[VPS Sync] VPS ${vpsId} deleted successfully`);
|
||||
return true;
|
||||
}
|
||||
}
|
||||
|
||||
export default new VPSSyncService();
|
||||
```
|
||||
|
||||
### Шаг 4: Использовать сервис в основном коде
|
||||
|
||||
**Пример в Express маршруте (создание VPS):**
|
||||
|
||||
```typescript
|
||||
import vpsSync from './services/ospab-vps-sync';
|
||||
|
||||
router.post('/api/vps/create', async (req, res) => {
|
||||
try {
|
||||
const { user_id, name, cpu, ram, disk, os } = req.body;
|
||||
|
||||
// 1️⃣ Создать VPS на хостинге (Proxmox, VMware, etc)
|
||||
console.log('Creating VPS on Proxmox...');
|
||||
const proxmoxVPS = await createVPSOnProxmox({
|
||||
name,
|
||||
cpu,
|
||||
ram: ram * 1024, // GB to MB for Proxmox
|
||||
disk,
|
||||
os,
|
||||
});
|
||||
|
||||
console.log('VPS created on Proxmox:', proxmoxVPS.id);
|
||||
|
||||
// 2️⃣ Синхронизировать с Панелью управления
|
||||
console.log('Syncing with OSPAB Panel...');
|
||||
const panelVPS = await vpsSync.createVPS({
|
||||
user_id,
|
||||
name,
|
||||
cpu,
|
||||
ram,
|
||||
disk,
|
||||
os,
|
||||
});
|
||||
|
||||
console.log('VPS synced with panel, ID:', panelVPS.id);
|
||||
|
||||
// 3️⃣ Обновить статус когда VPS готов (через несколько минут)
|
||||
// Рекомендуется использовать job queue (bull, rsmq, etc)
|
||||
setTimeout(async () => {
|
||||
try {
|
||||
await vpsSync.updateVPSStatus(panelVPS.id, 'running');
|
||||
console.log('VPS status updated to running');
|
||||
} catch (err) {
|
||||
console.error('Failed to update VPS status:', err);
|
||||
}
|
||||
}, 60000); // 1 минута
|
||||
|
||||
res.json({
|
||||
success: true,
|
||||
vps_id: panelVPS.id,
|
||||
message: 'VPS created successfully',
|
||||
});
|
||||
} catch (error) {
|
||||
console.error('Error creating VPS:', error);
|
||||
res.status(500).json({
|
||||
success: false,
|
||||
message: error.message,
|
||||
});
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
**Пример для удаления VPS:**
|
||||
|
||||
```typescript
|
||||
router.post('/api/vps/delete', async (req, res) => {
|
||||
try {
|
||||
const { vps_id, proxmox_id } = req.body;
|
||||
|
||||
// 1️⃣ Удалить с хостинга
|
||||
await deleteVPSFromProxmox(proxmox_id);
|
||||
console.log('VPS deleted from Proxmox');
|
||||
|
||||
// 2️⃣ Удалить из Панели
|
||||
await vpsSync.deleteVPS(vps_id);
|
||||
console.log('VPS deleted from panel');
|
||||
|
||||
res.json({
|
||||
success: true,
|
||||
message: 'VPS deleted successfully',
|
||||
});
|
||||
} catch (error) {
|
||||
console.error('Error deleting VPS:', error);
|
||||
res.status(500).json({
|
||||
success: false,
|
||||
message: error.message,
|
||||
});
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
## ⚠️ Важные моменты
|
||||
|
||||
### 1. Конвертация единиц
|
||||
|
||||
| Параметр | Главный сайт | Панель | Конвертация |
|
||||
|----------|--------------|-------|-------------|
|
||||
| RAM | GB | MB | ×1024 |
|
||||
| Disk | GB | GB | ×1 |
|
||||
| CPU | cores | cores | ×1 |
|
||||
|
||||
```typescript
|
||||
// ❌ НЕПРАВИЛЬНО (забыли конвертировать)
|
||||
vpsSync.createVPS({ ram: 8 }); // Панель получит 8 MB вместо 8 GB
|
||||
|
||||
// ✅ ПРАВИЛЬНО
|
||||
vpsSync.createVPS({ ram: 8 * 1024 }); // Панель получит 8192 MB = 8 GB
|
||||
```
|
||||
|
||||
### 2. User ID
|
||||
|
||||
`user_id` должен быть **ID из SSO системы** Панели управления:
|
||||
|
||||
```typescript
|
||||
// ❌ НЕПРАВИЛЬНО (локальный ID главного сайта)
|
||||
const userId = req.user.id; // 123 в БД главного сайта
|
||||
|
||||
// ✅ ПРАВИЛЬНО (ID из SSO)
|
||||
const userId = req.user.sso_id; // 5 в системе OSPAB Panel
|
||||
```
|
||||
|
||||
### 3. Обработка ошибок
|
||||
|
||||
```typescript
|
||||
try {
|
||||
await vpsSync.createVPS(vpsData);
|
||||
} catch (error) {
|
||||
// Важно логировать ошибку!
|
||||
console.error('Failed to sync VPS:', error.message);
|
||||
|
||||
// Но НЕ прерывать создание VPS на хостинге
|
||||
// VPS может быть создан, даже если панель недоступна
|
||||
|
||||
// Вариант: сохранить попытку синхронизации в БД
|
||||
// и повторить попытку позже через job queue
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Статусы VPS
|
||||
|
||||
```typescript
|
||||
// Возможные статусы
|
||||
'creating' // VPS создается
|
||||
'running' // VPS запущен и готов
|
||||
'stopped' // VPS остановлен
|
||||
'suspended' // VPS приостановлен (например, за неоплату)
|
||||
```
|
||||
|
||||
## 🧪 Тестирование
|
||||
|
||||
### Локальное тестирование
|
||||
|
||||
1. Запустить Панель управления локально:
|
||||
```bash
|
||||
go run ./cmd/server/main.go
|
||||
# Будет доступна на http://localhost:5050
|
||||
```
|
||||
|
||||
2. В `.env` главного сайта:
|
||||
```env
|
||||
OSPAB_PANEL_URL=http://localhost:5050
|
||||
VPS_SYNC_API_KEY=your_secret_api_key_here_min_32_chars_change_this
|
||||
```
|
||||
|
||||
3. Тестировать создание VPS через API главного сайта
|
||||
|
||||
### Тест через curl
|
||||
|
||||
```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",
|
||||
"cpu": 2,
|
||||
"ram": 2048,
|
||||
"disk": 50,
|
||||
"os": "Ubuntu 22.04 LTS",
|
||||
"status": "creating",
|
||||
"hypervisor": "proxmox"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
Ожидаемый ответ:
|
||||
```json
|
||||
{
|
||||
"status": "success",
|
||||
"message": "VPS synced successfully",
|
||||
"vps": {
|
||||
"id": 1,
|
||||
"name": "test-vps",
|
||||
"status": "creating",
|
||||
"created_at": "2025-10-27T10:30:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 📚 Дополнительно
|
||||
|
||||
- Полная документация: `CLIENT_VPS_INTEGRATION.md`
|
||||
- Примеры кода: `VPS_SYNC_EXAMPLES.md`
|
||||
- Быстрый старт: `VPS_SYNC_QUICK_START.md`
|
||||
|
||||
## ❓ Часто задаваемые вопросы
|
||||
|
||||
**Q: Что если панель недоступна?**
|
||||
A: VPS все равно создастся на хостинге. Добавьте retry logic и job queue (bull/rsmq) для повторных попыток синхронизации.
|
||||
|
||||
**Q: Может ли быть несовпадение данных?**
|
||||
A: Да, если синхронизация сорвалась. Рекомендуется периодически проверять консистентность и добавить маршрут для ручной синхронизации.
|
||||
|
||||
**Q: Как обновлять IP адрес VPS?**
|
||||
A: Текущий API синхронизирует только основные параметры. IP адрес может быть добавлен позже через расширение API.
|
||||
|
||||
**Q: Нужна ли двусторонняя синхронизация?**
|
||||
A: Нет, панель только получает данные. Главный сайт - источник истины.
|
||||
|
||||
---
|
||||
|
||||
**Вопросы?** Смотрите документацию выше или свяжитесь с разработчиком панели.
|
||||
Reference in New Issue
Block a user