532 lines
14 KiB
Markdown
532 lines
14 KiB
Markdown
# 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!** 🚀
|