# 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!** 🚀