Add Notification and new mini desing
This commit is contained in:
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