Добавить API
531
API.md
Normal file
531
API.md
Normal file
@@ -0,0 +1,531 @@
|
|||||||
|
# MC Panel API - Полная документация
|
||||||
|
|
||||||
|
**Версия:** 1.0.0
|
||||||
|
**Дата:** 15 января 2026
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📋 Содержание
|
||||||
|
|
||||||
|
1. [Базовая информация](#базовая-информация)
|
||||||
|
2. [Быстрый старт](#быстрый-старт)
|
||||||
|
3. [Аутентификация](#аутентификация)
|
||||||
|
4. [Управление пользователями](#управление-пользователями)
|
||||||
|
5. [Личный кабинет](#личный-кабинет)
|
||||||
|
6. [Управление серверами](#управление-серверами)
|
||||||
|
7. [Управление файлами](#управление-файлами)
|
||||||
|
8. [Тикеты](#тикеты)
|
||||||
|
9. [OpenID Connect](#openid-connect)
|
||||||
|
10. [Коды ошибок](#коды-ошибок)
|
||||||
|
11. [Примеры интеграции](#примеры-интеграции)
|
||||||
|
12. [Postman коллекция](#postman-коллекция)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Базовая информация
|
||||||
|
|
||||||
|
**Base URL:** `http://localhost:8000`
|
||||||
|
|
||||||
|
**Формат данных:** JSON
|
||||||
|
|
||||||
|
**Аутентификация:** Bearer Token (JWT)
|
||||||
|
|
||||||
|
Все защищенные эндпоинты требуют заголовок:
|
||||||
|
```
|
||||||
|
Authorization: Bearer <token>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Заголовки запросов
|
||||||
|
```
|
||||||
|
Content-Type: application/json
|
||||||
|
Authorization: Bearer <token>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Формат ответов
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"message": "Success message",
|
||||||
|
"data": {}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Быстрый старт
|
||||||
|
|
||||||
|
### 1. Регистрация
|
||||||
|
```bash
|
||||||
|
curl -X POST http://localhost:8000/api/auth/register \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-d '{"username":"admin","password":"password123"}'
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Вход
|
||||||
|
```bash
|
||||||
|
curl -X POST http://localhost:8000/api/auth/login \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-d '{"username":"admin","password":"password123"}'
|
||||||
|
```
|
||||||
|
|
||||||
|
**Ответ:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"access_token": "eyJhbGc...",
|
||||||
|
"token_type": "bearer",
|
||||||
|
"username": "admin",
|
||||||
|
"role": "admin"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Использование токена
|
||||||
|
```bash
|
||||||
|
TOKEN="your_token_here"
|
||||||
|
|
||||||
|
curl http://localhost:8000/api/servers \
|
||||||
|
-H "Authorization: Bearer $TOKEN"
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Аутентификация
|
||||||
|
|
||||||
|
### POST /api/auth/register
|
||||||
|
Регистрация нового пользователя.
|
||||||
|
|
||||||
|
**Body:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"username": "string",
|
||||||
|
"password": "string"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response (200):**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"access_token": "string",
|
||||||
|
"token_type": "bearer",
|
||||||
|
"username": "string",
|
||||||
|
"role": "admin|user"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### POST /api/auth/login
|
||||||
|
Вход в систему.
|
||||||
|
|
||||||
|
**Body:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"username": "string",
|
||||||
|
"password": "string"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response (200):**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"access_token": "string",
|
||||||
|
"token_type": "bearer",
|
||||||
|
"username": "string",
|
||||||
|
"role": "admin|user|support|banned"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Errors:**
|
||||||
|
- `401` - Неверные учетные данные
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### GET /api/auth/me
|
||||||
|
Получить информацию о текущем пользователе.
|
||||||
|
|
||||||
|
**Headers:** `Authorization: Bearer <token>`
|
||||||
|
|
||||||
|
**Response (200):**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"username": "string",
|
||||||
|
"role": "admin|user|support|banned",
|
||||||
|
"servers": ["server1", "server2"]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Управление пользователями
|
||||||
|
|
||||||
|
### GET /api/users
|
||||||
|
Список всех пользователей.
|
||||||
|
|
||||||
|
### PUT /api/users/{username}/role
|
||||||
|
Изменить роль пользователя (admin only).
|
||||||
|
**Body:** `{"role": "admin|user|support|banned"}`
|
||||||
|
|
||||||
|
### PUT /api/users/{username}/servers
|
||||||
|
Управление доступом к серверам.
|
||||||
|
**Body:** `{"servers": ["server1", "server2"]}`
|
||||||
|
|
||||||
|
### DELETE /api/users/{username}
|
||||||
|
Удалить пользователя (admin only).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Личный кабинет
|
||||||
|
|
||||||
|
### GET /api/profile/stats
|
||||||
|
Статистика текущего пользователя.
|
||||||
|
|
||||||
|
### GET /api/profile/stats/{username}
|
||||||
|
Статистика другого пользователя (admin/support).
|
||||||
|
|
||||||
|
### PUT /api/profile/username
|
||||||
|
Изменить имя пользователя.
|
||||||
|
**Body:** `{"new_username": "string", "password": "string"}`
|
||||||
|
|
||||||
|
### PUT /api/profile/password
|
||||||
|
Изменить пароль.
|
||||||
|
**Body:** `{"old_password": "string", "new_password": "string"}`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Управление серверами
|
||||||
|
|
||||||
|
### GET /api/servers
|
||||||
|
Список серверов пользователя.
|
||||||
|
|
||||||
|
### POST /api/servers/create
|
||||||
|
Создать новый сервер.
|
||||||
|
**Body:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"name": "server1",
|
||||||
|
"displayName": "My Server",
|
||||||
|
"startCommand": "java -Xmx2G -jar server.jar nogui"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### GET /api/servers/{server}/config
|
||||||
|
Получить конфигурацию сервера.
|
||||||
|
|
||||||
|
### PUT /api/servers/{server}/config
|
||||||
|
Обновить конфигурацию сервера.
|
||||||
|
|
||||||
|
### DELETE /api/servers/{server}
|
||||||
|
Удалить сервер (admin only).
|
||||||
|
|
||||||
|
### POST /api/servers/{server}/start
|
||||||
|
Запустить сервер.
|
||||||
|
|
||||||
|
### POST /api/servers/{server}/stop
|
||||||
|
Остановить сервер.
|
||||||
|
|
||||||
|
### POST /api/servers/{server}/command
|
||||||
|
Отправить команду серверу.
|
||||||
|
**Body:** `{"command": "say Hello"}`
|
||||||
|
|
||||||
|
### GET /api/servers/{server}/stats
|
||||||
|
Получить статистику сервера (CPU, RAM, Disk).
|
||||||
|
|
||||||
|
### WS /ws/servers/{server}/console
|
||||||
|
WebSocket для консоли сервера (логи в реальном времени).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Управление файлами
|
||||||
|
|
||||||
|
### GET /api/servers/{server}/files?path={path}
|
||||||
|
Список файлов в директории.
|
||||||
|
|
||||||
|
### POST /api/servers/{server}/files/create
|
||||||
|
Создать файл или папку.
|
||||||
|
**Body:** `{"type": "file|folder", "name": "string", "path": "string"}`
|
||||||
|
|
||||||
|
### POST /api/servers/{server}/files/upload?path={path}
|
||||||
|
Загрузить файл (multipart/form-data).
|
||||||
|
|
||||||
|
### GET /api/servers/{server}/files/download?path={path}
|
||||||
|
Скачать файл.
|
||||||
|
|
||||||
|
### GET /api/servers/{server}/files/content?path={path}
|
||||||
|
Получить содержимое текстового файла.
|
||||||
|
|
||||||
|
### PUT /api/servers/{server}/files/content?path={path}
|
||||||
|
Сохранить содержимое файла.
|
||||||
|
**Body:** `{"content": "string"}`
|
||||||
|
|
||||||
|
### PUT /api/servers/{server}/files/rename?old_path={path}&new_name={name}
|
||||||
|
Переименовать файл.
|
||||||
|
|
||||||
|
### POST /api/servers/{server}/files/move
|
||||||
|
Переместить файл.
|
||||||
|
**Body:** `{"source": "path", "destination": "path"}`
|
||||||
|
|
||||||
|
### DELETE /api/servers/{server}/files?path={path}
|
||||||
|
Удалить файл или папку.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Тикеты
|
||||||
|
|
||||||
|
### GET /api/tickets
|
||||||
|
Список тикетов (свои или все для admin/support).
|
||||||
|
|
||||||
|
### POST /api/tickets/create
|
||||||
|
Создать новый тикет.
|
||||||
|
**Body:** `{"title": "string", "description": "string"}`
|
||||||
|
|
||||||
|
### GET /api/tickets/{id}
|
||||||
|
Получить тикет по ID.
|
||||||
|
|
||||||
|
### POST /api/tickets/{id}/message
|
||||||
|
Добавить сообщение в тикет.
|
||||||
|
**Body:** `{"text": "string"}`
|
||||||
|
|
||||||
|
### PUT /api/tickets/{id}/status
|
||||||
|
Изменить статус тикета (admin/support).
|
||||||
|
**Body:** `{"status": "pending|in_progress|closed"}`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## OpenID Connect
|
||||||
|
|
||||||
|
### GET /api/auth/oidc/providers
|
||||||
|
Список доступных OIDC провайдеров.
|
||||||
|
|
||||||
|
### GET /api/auth/oidc/{provider}/login
|
||||||
|
Начать аутентификацию через OIDC (redirect).
|
||||||
|
|
||||||
|
### GET /api/auth/oidc/{provider}/callback
|
||||||
|
Callback от OIDC провайдера (redirect).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Коды ошибок
|
||||||
|
|
||||||
|
| Код | Описание | Решение |
|
||||||
|
|-----|----------|---------|
|
||||||
|
| 200 | Успешно | - |
|
||||||
|
| 400 | Неверный запрос | Проверьте формат данных |
|
||||||
|
| 401 | Не авторизован | Войдите в систему |
|
||||||
|
| 403 | Доступ запрещен | Недостаточно прав |
|
||||||
|
| 404 | Не найдено | Проверьте URL |
|
||||||
|
| 500 | Ошибка сервера | Обратитесь к администратору |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Примеры интеграции
|
||||||
|
|
||||||
|
### Python
|
||||||
|
```python
|
||||||
|
import requests
|
||||||
|
|
||||||
|
class MCPanelAPI:
|
||||||
|
def __init__(self, base_url, username, password):
|
||||||
|
self.base_url = base_url
|
||||||
|
self.token = None
|
||||||
|
self.login(username, password)
|
||||||
|
|
||||||
|
def login(self, username, password):
|
||||||
|
r = requests.post(f"{self.base_url}/api/auth/login",
|
||||||
|
json={"username": username, "password": password})
|
||||||
|
self.token = r.json()["access_token"]
|
||||||
|
|
||||||
|
def get_headers(self):
|
||||||
|
return {"Authorization": f"Bearer {self.token}"}
|
||||||
|
|
||||||
|
def get_servers(self):
|
||||||
|
r = requests.get(f"{self.base_url}/api/servers",
|
||||||
|
headers=self.get_headers())
|
||||||
|
return r.json()
|
||||||
|
|
||||||
|
def start_server(self, server_name):
|
||||||
|
r = requests.post(
|
||||||
|
f"{self.base_url}/api/servers/{server_name}/start",
|
||||||
|
headers=self.get_headers())
|
||||||
|
return r.json()
|
||||||
|
|
||||||
|
# Использование
|
||||||
|
api = MCPanelAPI("http://localhost:8000", "admin", "password")
|
||||||
|
servers = api.get_servers()
|
||||||
|
api.start_server("survival")
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### JavaScript
|
||||||
|
```javascript
|
||||||
|
class MCPanelAPI {
|
||||||
|
constructor(baseURL) {
|
||||||
|
this.baseURL = baseURL;
|
||||||
|
this.token = null;
|
||||||
|
}
|
||||||
|
|
||||||
|
async login(username, password) {
|
||||||
|
const response = await fetch(`${this.baseURL}/api/auth/login`, {
|
||||||
|
method: 'POST',
|
||||||
|
headers: {'Content-Type': 'application/json'},
|
||||||
|
body: JSON.stringify({username, password})
|
||||||
|
});
|
||||||
|
const data = await response.json();
|
||||||
|
this.token = data.access_token;
|
||||||
|
}
|
||||||
|
|
||||||
|
getHeaders() {
|
||||||
|
return {
|
||||||
|
'Authorization': `Bearer ${this.token}`,
|
||||||
|
'Content-Type': 'application/json'
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
async getServers() {
|
||||||
|
const response = await fetch(`${this.baseURL}/api/servers`, {
|
||||||
|
headers: this.getHeaders()
|
||||||
|
});
|
||||||
|
return await response.json();
|
||||||
|
}
|
||||||
|
|
||||||
|
async startServer(serverName) {
|
||||||
|
const response = await fetch(
|
||||||
|
`${this.baseURL}/api/servers/${serverName}/start`,
|
||||||
|
{method: 'POST', headers: this.getHeaders()}
|
||||||
|
);
|
||||||
|
return await response.json();
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// Использование
|
||||||
|
const api = new MCPanelAPI('http://localhost:8000');
|
||||||
|
await api.login('admin', 'password');
|
||||||
|
const servers = await api.getServers();
|
||||||
|
await api.startServer('survival');
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### cURL примеры
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Вход
|
||||||
|
TOKEN=$(curl -s -X POST http://localhost:8000/api/auth/login \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-d '{"username":"admin","password":"pass"}' \
|
||||||
|
| jq -r '.access_token')
|
||||||
|
|
||||||
|
# Список серверов
|
||||||
|
curl http://localhost:8000/api/servers \
|
||||||
|
-H "Authorization: Bearer $TOKEN"
|
||||||
|
|
||||||
|
# Создать сервер
|
||||||
|
curl -X POST http://localhost:8000/api/servers/create \
|
||||||
|
-H "Authorization: Bearer $TOKEN" \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-d '{"name":"survival","displayName":"Survival","startCommand":"java -jar server.jar"}'
|
||||||
|
|
||||||
|
# Запустить сервер
|
||||||
|
curl -X POST http://localhost:8000/api/servers/survival/start \
|
||||||
|
-H "Authorization: Bearer $TOKEN"
|
||||||
|
|
||||||
|
# Отправить команду
|
||||||
|
curl -X POST http://localhost:8000/api/servers/survival/command \
|
||||||
|
-H "Authorization: Bearer $TOKEN" \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-d '{"command":"say Hello"}'
|
||||||
|
|
||||||
|
# Список файлов
|
||||||
|
curl "http://localhost:8000/api/servers/survival/files?path=plugins" \
|
||||||
|
-H "Authorization: Bearer $TOKEN"
|
||||||
|
|
||||||
|
# Создать тикет
|
||||||
|
curl -X POST http://localhost:8000/api/tickets/create \
|
||||||
|
-H "Authorization: Bearer $TOKEN" \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-d '{"title":"Problem","description":"Details"}'
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Postman коллекция
|
||||||
|
|
||||||
|
### Импорт коллекции
|
||||||
|
1. Откройте Postman
|
||||||
|
2. File → Import
|
||||||
|
3. Выберите файл `MC_Panel_API.postman_collection.json`
|
||||||
|
4. Коллекция готова к использованию
|
||||||
|
|
||||||
|
### Настройка переменных
|
||||||
|
В коллекции настройте переменные:
|
||||||
|
- `baseUrl` = `http://localhost:8000`
|
||||||
|
- `serverName` = `survival` (или имя вашего сервера)
|
||||||
|
- `token` = автоматически сохраняется после Login
|
||||||
|
|
||||||
|
### Использование
|
||||||
|
1. Выполните запрос "Login" для получения токена
|
||||||
|
2. Токен автоматически сохранится в переменную `token`
|
||||||
|
3. Все остальные запросы будут использовать этот токен
|
||||||
|
4. Используйте любые эндпоинты из коллекции
|
||||||
|
|
||||||
|
### Структура коллекции
|
||||||
|
- **Authentication** - регистрация, вход, получение пользователя
|
||||||
|
- **Users** - управление пользователями
|
||||||
|
- **Servers** - управление серверами
|
||||||
|
- **Files** - операции с файлами
|
||||||
|
- **Tickets** - система тикетов
|
||||||
|
- **Profile** - личный кабинет
|
||||||
|
- **OpenID Connect** - OIDC провайдеры
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Безопасность
|
||||||
|
|
||||||
|
### JWT Токены
|
||||||
|
- Срок действия: 7 дней
|
||||||
|
- Алгоритм: HS256
|
||||||
|
- Хранение: localStorage (фронтенд)
|
||||||
|
|
||||||
|
### Рекомендации
|
||||||
|
1. Используйте HTTPS в production
|
||||||
|
2. Измените SECRET_KEY в `backend/main.py`
|
||||||
|
3. Используйте сильные пароли (минимум 6 символов)
|
||||||
|
4. Регулярно обновляйте зависимости
|
||||||
|
5. Ограничьте CORS для конкретных доменов
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Лимиты и ограничения
|
||||||
|
|
||||||
|
- **Размер файла:** не ограничен (зависит от сервера)
|
||||||
|
- **Количество запросов:** не ограничено
|
||||||
|
- **Длина сообщения:** не ограничена
|
||||||
|
- **Количество серверов:** не ограничено
|
||||||
|
- **Срок хранения логов:** 1000 последних строк
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Changelog
|
||||||
|
|
||||||
|
### 1.0.0 (15.01.2026)
|
||||||
|
- ✨ Первый релиз API
|
||||||
|
- ✅ 37 эндпоинтов
|
||||||
|
- ✅ JWT аутентификация
|
||||||
|
- ✅ OpenID Connect
|
||||||
|
- ✅ WebSocket консоль
|
||||||
|
- ✅ Полное управление серверами
|
||||||
|
- ✅ Файловый менеджер
|
||||||
|
- ✅ Система тикетов
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Поддержка
|
||||||
|
|
||||||
|
- **Документация проекта:** ДОКУМЕНТАЦИЯ.md
|
||||||
|
- **Postman коллекция:** MC_Panel_API.postman_collection.json
|
||||||
|
- **Тикеты:** Используйте систему тикетов в панели
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Версия API:** 1.0.0
|
||||||
|
**Дата обновления:** 15 января 2026
|
||||||
|
|
||||||
|
**Спасибо за использование MC Panel API!** 🚀
|
||||||
Reference in New Issue
Block a user