From 73ff0b05e1502dd7f781f76a13303fdc5e029848 Mon Sep 17 00:00:00 2001 From: Arkon Date: Thu, 15 Jan 2026 20:32:00 +0700 Subject: [PATCH] =?UTF-8?q?=D0=94=D0=BE=D0=B1=D0=B0=D0=B2=D0=B8=D1=82?= =?UTF-8?q?=D1=8C=20API?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- API.md | 531 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 531 insertions(+) create mode 100644 API.md diff --git a/API.md b/API.md new file mode 100644 index 0000000..fecb5d2 --- /dev/null +++ b/API.md @@ -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 +``` + +### Заголовки запросов +``` +Content-Type: application/json +Authorization: Bearer +``` + +### Формат ответов +```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 ` + +**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!** 🚀