This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

MC Panel - Полная документация проекта

Версия: 1.0.0
Дата: 15 января 2026

О проекте

MC Panel - это современная веб-панель для управления Minecraft серверами с полным набором функций.

Основные возможности

🖥️ Управление серверами - запуск, остановка, мониторинг
📁 Файловый менеджер - полное управление файлами сервера
💬 Консоль - отправка команд и просмотр логов в реальном времени
📊 Статистика - мониторинг CPU, RAM, диска
🎫 Система тикетов - поддержка пользователей
👥 Управление пользователями - роли и права доступа
🔐 OpenID Connect - интеграция с ZITADEL
🎨 6 тем оформления - включая современную темную тему
🔔 Система уведомлений - информирование о всех событиях
👤 Личный кабинет - управление профилем и статистика

Технологии

Backend:

FastAPI (Python)
JWT аутентификация
WebSocket для консоли
Authlib для OpenID Connect

Frontend:

React 18
Tailwind CSS
Axios для API запросов
Lucide React для иконок

Быстрый старт

Шаг 1: Установка зависимостей

Backend:

cd backend
pip install -r requirements.txt

Frontend:

cd frontend
npm install

Шаг 2: Настройка окружения

Создайте файл .env в корне проекта:

# ZITADEL OpenID Connect
ZITADEL_ISSUER=https://your-instance.zitadel.cloud
ZITADEL_CLIENT_ID=your_client_id
ZITADEL_CLIENT_SECRET=your_client_secret

# URLs
BASE_URL=http://localhost:8000
FRONTEND_URL=http://localhost:3000

Шаг 3: Запуск

Backend:

cd backend
python main.py

Сервер запустится на http://localhost:8000

Frontend:

cd frontend
npm run dev

Интерфейс будет доступен на http://localhost:3000

Шаг 4: Первый вход

Откройте http://localhost:3000
Зарегистрируйтесь (первый пользователь получит роль admin)
Создайте свой первый сервер
Загрузите server.jar в папку сервера
Запустите сервер!

Учетные данные по умолчанию:

Логин: Root
Пароль: Admin

Установка и настройка

Требования

Python 3.8+
Node.js 16+
npm или yarn
Git

Полная установка

1. Клонирование репозитория

git clone <repository-url>
cd mc-panel

2. Установка Backend

cd backend
pip install -r requirements.txt

Зависимости:

fastapi - веб-фреймворк
uvicorn - ASGI сервер
python-jose - JWT токены
passlib - хеширование паролей
python-multipart - загрузка файлов
psutil - мониторинг системы
authlib - OpenID Connect
httpx - HTTP клиент
python-dotenv - переменные окружения

3. Установка Frontend

cd frontend
npm install

Зависимости:

react - UI библиотека
react-dom - рендеринг React
axios - HTTP клиент
lucide-react - иконки
tailwindcss - CSS фреймворк

4. Настройка ZITADEL (опционально)

Если хотите использовать OpenID Connect:

Создайте аккаунт на ZITADEL
Создайте новое приложение (Application)
Выберите тип "Web"
Настройте Redirect URIs:
- http://localhost:8000/api/auth/oidc/zitadel/callback
Скопируйте Client ID и Client Secret
Добавьте в .env файл

5. Структура проекта

mc-panel/
├── backend/
│   ├── main.py              # Главный файл FastAPI
│   ├── oidc_config.py       # Конфигурация OpenID Connect
│   ├── requirements.txt     # Python зависимости
│   ├── users.json          # База пользователей
│   ├── tickets.json        # База тикетов
│   └── servers/            # Папка с серверами
├── frontend/
│   ├── src/
│   │   ├── App.jsx         # Главный компонент
│   │   ├── components/     # React компоненты
│   │   ├── themes.js       # Темы оформления
│   │   └── config.js       # Конфигурация
│   ├── package.json        # npm зависимости
│   └── vite.config.js      # Конфигурация Vite
├── .env                    # Переменные окружения
└── ДОКУМЕНТАЦИЯ.md         # Этот файл

Функциональность

Управление серверами

Создание сервера

Нажмите кнопку "+" в боковой панели
Заполните форму:
- Имя папки - только латиница, цифры, _ и -
- Отображаемое имя - любое название
- Команда запуска - команда для запуска сервера
Нажмите "Создать"

Запуск и остановка

Запустить - зеленая кнопка "Запустить"
Остановить - серая кнопка "Сброс"
Статус отображается цветным индикатором

Консоль

Просмотр логов в реальном времени
Отправка команд серверу
Цветная подсветка:
- 🟢 INFO - зеленый
- 🟡 WARN - желтый
- 🔴 ERROR - красный
- ⚪ Время - серый

Статистика

CPU - использование процессора (%)
RAM - использование памяти (МБ)
Disk - размер файлов сервера (МБ)
Обновление каждые 5 секунд

Настройки

Изменение отображаемого имени
Изменение команды запуска
Удаление сервера (только админ)

Система уведомлений

Описание

Полноценная система уведомлений с автоматическим исчезновением через 5 секунд.

Типы уведомлений

🟢 Success - успешные операции
🔴 Error - ошибки
🟡 Warning - предупреждения
🔵 Info - информационные сообщения

Где используются

Управление серверами

✅ Сервер запущен
ℹ️ Сервер остановлен
❌ Ошибки запуска/остановки

Файловый менеджер

✅ Файл/папка создан(а)
✅ Файл загружен/удален/сохранен
✅ Файл переименован/перемещен
❌ Ошибки операций

Тикеты

✅ Тикет создан
✅ Сообщение отправлено
ℹ️ Новое сообщение (от других, каждые 3 сек)
✅ Статус изменён (действие)
ℹ️ Статус изменён (просмотр)
❌ Ошибки

Особенности тикетов:

Автообновление каждые 3 секунды
Превью сообщений (50 символов)
Не показываются для собственных действий

Личный кабинет

✅ Имя изменено
✅ Пароль изменён
❌ Ошибки

Создание сервера

✅ Сервер создан
❌ Ошибка создания

Технические детали

Компонент: frontend/src/components/NotificationSystem.jsx

Использование:

import { notify } from './components/NotificationSystem';

notify('success', 'Заголовок', 'Сообщение');
notify('error', 'Ошибка', 'Описание');
notify('warning', 'Внимание', 'Предупреждение');
notify('info', 'Информация', 'Сообщение');

Анимация: slide-in-right (0.3 сек)

Дизайн и темы

Доступные темы

Modern (Современная) - по умолчанию
- Цвета: #0f1115, #1a1d24, #23262e
- Акцент: зеленый
- Градиент: зеленый → изумрудный
Dark (Тёмная)
- Цвета: черный, темно-серый
- Акцент: синий
- Градиент: синий → фиолетовый
Light (Светлая)
- Цвета: белый, светло-серый
- Акцент: синий
- Градиент: синий → фиолетовый
Purple (Фиолетовая)
- Цвета: темный с фиолетовым оттенком
- Акцент: фиолетовый
- Градиент: фиолетовый → розовый
Blue (Синяя)
- Цвета: темный с синим оттенком
- Акцент: синий
- Градиент: голубой → синий
Green (Зелёная)
- Цвета: темный с зеленым оттенком
- Акцент: зеленый
- Градиент: изумрудный → зеленый

Переключение темы

Кнопка в правом верхнем углу → выбор темы из списка

Особенности дизайна

Цветная консоль (INFO, WARN, ERROR)
Кнопки с тенями и hover эффектами
Плавные переходы и анимации
Адаптивный дизайн
Современные иконки (Lucide React)

Файловый менеджер

Возможности

Просмотр файлов

Список файлов и папок
6 колонок: Имя, Тип, Размер, Изменение, Разрешение, Действия
Поиск по названию
Навигация по папкам

Создание

Файл - кнопка "Новый" → "Создать файл"
Папка - кнопка "Новый" → "Создать папку"
Ввод имени и Enter

Загрузка и скачивание

Загрузить - зеленая кнопка, выбор файла
Скачать - иконка скачивания у файла

Редактирование

Просмотр - иконка глаза
Редактирование - иконка карандаша
Сохранение изменений

Переименование

Двойной клик по имени файла
Ввод нового имени
Enter для сохранения

Перемещение файлов

Cut/Paste (Вырезать/Вставить):

Выберите файлы чекбоксами
Нажмите "Вырезать" (оранжевая кнопка)
Перейдите в нужную папку
Нажмите "Вставить" (фиолетовая кнопка)

Особенности:

Файлы подсвечиваются оранжевым
Счетчик вырезанных файлов
Кнопка "Отмена" для отмены операции
Drag & Drop отключен

Удаление

Иконка корзины
Подтверждение удаления
Удаление файлов и папок

Выбор файлов

Чекбокс в заголовке - выбрать все
Чекбоксы у файлов - выбор отдельных
Кнопка "Обновить" - обновить список

Интерфейс

Поиск с иконкой
Кнопки: Загрузить (зеленая), Обновить (серая), Новый (синяя)
Кнопки перемещения: Вырезать (оранжевая), Вставить (фиолетовая), Отмена (серая)
Таблица с hover эффектами
"No data" при пустой папке

Система тикетов

Создание тикета

Кнопка "Тикеты" в шапке
Кнопка "+" для создания
Заполните:
- Заголовок - краткое описание
- Описание - подробности проблемы
Нажмите "Создать"

Статусы тикетов

🟡 На рассмотрении (pending) - новый тикет
🔵 В работе (in_progress) - тикет взят в работу
🟢 Закрыт (closed) - проблема решена

Работа с тикетами

Просмотр

Список всех тикетов
Фильтр по статусу (цветные индикаторы)
Информация: автор, дата, статус

Чат

Отправка сообщений
Просмотр истории
Автообновление каждые 3 секунды
Уведомления о новых сообщениях

Изменение статуса (админ/поддержка)

Кнопки статусов в шапке тикета
Автоматическое системное сообщение
Уведомление всем участникам

Уведомления в тикетах

При отправке сообщения:

✅ "Сообщение отправлено"

При получении сообщения:

ℹ️ "Новое сообщение: {автор}: {превью}..."
Только от других пользователей
Превью 50 символов

При изменении статуса:

✅ "Статус изменён: Тикет #X теперь: {статус}" (действие)
ℹ️ "Статус изменён: Тикет #X: {статус}" (просмотр)

При ошибках:

❌ "Ошибка отправки" / "Ошибка изменения статуса"

Права доступа

Пользователи - видят только свои тикеты
Админы - видят все тикеты, могут менять статус
Поддержка - видят все тикеты, могут менять статус

Личный кабинет

Доступ

Кнопка "Личный кабинет" в правом верхнем углу

Разделы

Обзор

Имя пользователя и роль
Статистика:
- Мои серверы (созданные)
- Доступные серверы (общие)
- Тикеты (всего, по статусам)
- Общее количество серверов

Безопасность

Изменение имени пользователя:

Введите новое имя (минимум 3 символа)
Введите текущий пароль
Нажмите "Изменить имя"
Получите новый токен

Изменение пароля:

Введите старый пароль
Введите новый пароль (минимум 6 символов)
Подтвердите новый пароль
Нажмите "Изменить пароль"

Показ/скрытие паролей:

Иконка глаза для переключения видимости

Просмотр чужих профилей (админ/поддержка)

Админы и техподдержка могут просматривать профили других пользователей:

Статистика пользователя
Список серверов
Тикеты пользователя
Индикатор "Просмотр профиля: {username}"

Доступ:

Раздел "Пользователи"
Кнопка "Профиль" у пользователя

OpenID Connect

Поддерживаемые провайдеры

ZITADEL - основной провайдер

Настройка ZITADEL

1. Создание приложения

Зарегистрируйтесь на ZITADEL
Создайте новый проект
Добавьте приложение (Application)
Выберите тип "Web"

Настройте Redirect URIs:

http://localhost:8000/api/auth/oidc/zitadel/callback
https://your-domain.com/api/auth/oidc/zitadel/callback

2. Получение учетных данных

Скопируйте Client ID
Создайте и скопируйте Client Secret
Скопируйте Issuer URL (например: https://your-instance.zitadel.cloud)

3. Настройка .env

ZITADEL_ISSUER=https://your-instance.zitadel.cloud
ZITADEL_CLIENT_ID=your_client_id_here
ZITADEL_CLIENT_SECRET=your_client_secret_here
BASE_URL=http://localhost:8000
FRONTEND_URL=http://localhost:3000

Использование

Вход через ZITADEL

На странице входа нажмите кнопку "ZITADEL"
Авторизуйтесь на странице ZITADEL
Разрешите доступ приложению
Автоматическое перенаправление в панель

Создание пользователя

При первом входе автоматически создается пользователь
Имя пользователя берется из email (до @)
Роль: user (обычный пользователь)
Пароль не требуется (используется OIDC)

Связывание аккаунтов

Каждый OIDC аккаунт уникален
Повторный вход использует существующего пользователя
ID хранится в формате: zitadel:{sub}

Безопасность

Токены обновляются автоматически
Используется PKCE для защиты
Все данные передаются через HTTPS (в production)

Роли пользователей

Admin (Администратор)

Полный доступ ко всем функциям:

✅ Все серверы (создание, удаление, управление)
✅ Все тикеты (просмотр, изменение статуса)
✅ Управление пользователями (роли, доступ, удаление)
✅ Просмотр всех профилей
✅ Изменение настроек серверов

Получение роли:

Первый зарегистрированный пользователь
Назначение другим админом

User (Пользователь)

Стандартные права:

✅ Свои серверы (создание, управление)
✅ Серверы с предоставленным доступом
✅ Свои тикеты (создание, просмотр)
✅ Свой профиль
❌ Управление другими пользователями
❌ Удаление серверов
❌ Просмотр чужих тикетов

Support (Техподдержка)

Права поддержки:

✅ Все тикеты (просмотр, ответы, изменение статуса)
✅ Просмотр профилей пользователей
✅ Свои серверы
❌ Управление пользователями
❌ Удаление серверов
❌ Изменение ролей

Banned (Заблокирован)

Нет доступа:

❌ Вход в систему запрещен
❌ API запросы отклоняются
❌ Все функции недоступны

Изменение ролей

Только админы могут:

Раздел "Пользователи"
Выбрать пользователя
Кнопка "Изменить роль"
Выбрать новую роль
Подтвердить

Ограничения:

Нельзя изменить свою роль
Нельзя удалить себя

Безопасность

JWT Токены

Алгоритм: HS256
Срок действия: 7 дней
Хранение: localStorage (фронтенд)
Передача: Bearer Token в заголовке Authorization

Пароли

Хеширование: bcrypt
Минимальная длина: 6 символов
Проверка: при каждом входе
Изменение: требует старый пароль

Файловая безопасность

Все пути проверяются на выход за пределы папки сервера
Запрещены операции с файлами вне servers/
Проверка прав доступа к серверу

API безопасность

Все эндпоинты требуют авторизацию (кроме login/register)
Проверка роли для админских функций
Валидация входных данных
Защита от SQL injection (используется JSON)

Troubleshooting

Проблемы с запуском

Backend не запускается

# Проверьте Python версию
python --version  # Должно быть 3.8+

# Переустановите зависимости
pip install --upgrade -r requirements.txt

# Проверьте порт 8000
netstat -ano | findstr :8000

Frontend не запускается

# Проверьте Node.js версию
node --version  # Должно быть 16+

# Очистите кэш и переустановите
rm -rf node_modules package-lock.json
npm install

# Проверьте порт 3000
netstat -ano | findstr :3000

Проблемы с аутентификацией

"Неверный токен"

Токен истек (7 дней)
Измененный SECRET_KEY
Решение: Выйдите и войдите снова

"Требуется авторизация"

Токен не передан
Неверный формат токена
Решение: Проверьте заголовок Authorization

OpenID Connect не работает

# Проверьте .env файл
cat .env

# Проверьте переменные
echo $ZITADEL_ISSUER
echo $ZITADEL_CLIENT_ID

# Проверьте Redirect URI в ZITADEL
# Должен быть: http://localhost:8000/api/auth/oidc/zitadel/callback

Проблемы с серверами

Сервер не запускается

Проверьте наличие server.jar
Проверьте команду запуска
Проверьте логи в консоли
Проверьте права доступа к файлам

Консоль пустая

Сервер еще не запущен
WebSocket не подключен
Решение: Перезапустите сервер

Статистика показывает 0

Сервер остановлен
Процесс завершился
Решение: Запустите сервер

Проблемы с файлами

"Файл не найден"

Неверный путь
Файл удален
Нет прав доступа
Решение: Проверьте путь и права

Не удается загрузить файл

Файл слишком большой
Нет места на диске
Решение: Освободите место

Не удается переместить файл

Файл открыт процессом
Нет прав доступа
Решение: Остановите сервер

Проблемы с тикетами

Не приходят уведомления

Проверьте интервал обновления (3 сек)
Откройте консоль браузера (F12)
Проверьте ошибки JavaScript

Сообщения не отправляются

Проверьте подключение к интернету
Проверьте токен авторизации
Проверьте логи backend

Проблемы с производительностью

Медленная работа

# Проверьте использование ресурсов
# Windows:
tasklist | findstr python
tasklist | findstr node

# Проверьте количество серверов
# Каждый сервер потребляет ресурсы

Высокое использование CPU

Много запущенных серверов
Частые обновления статистики
Решение: Остановите неиспользуемые серверы

Логи и отладка

Включить подробные логи (Backend)

В backend/main.py:

import logging
logging.basicConfig(level=logging.DEBUG)

Просмотр логов (Frontend)

Откройте консоль браузера (F12) → Console

Проверка API

# Проверьте доступность API
curl http://localhost:8000/api/auth/oidc/providers

# Проверьте токен
curl http://localhost:8000/api/auth/me \
  -H "Authorization: Bearer YOUR_TOKEN"

Получение помощи

Проверьте документацию - возможно, ответ уже есть
Проверьте логи - backend и frontend
Создайте тикет - опишите проблему подробно
GitHub Issues - для багов и предложений

Дополнительная информация

Структура базы данных

users.json

{
  "username": {
    "username": "string",
    "password": "hashed_password",
    "role": "admin|user|support|banned",
    "servers": ["server1", "server2"],
    "oidc_id": "provider:sub",
    "email": "user@example.com",
    "name": "User Name",
    "picture": "https://...",
    "provider": "zitadel",
    "created_at": "2026-01-15T10:00:00"
  }
}

tickets.json

{
  "1": {
    "id": "1",
    "title": "Проблема",
    "description": "Описание",
    "author": "username",
    "status": "pending|in_progress|closed",
    "created_at": "2026-01-15T10:00:00",
    "updated_at": "2026-01-15T11:00:00",
    "messages": [
      {
        "author": "username",
        "text": "Сообщение",
        "timestamp": "2026-01-15T10:00:00"
      }
    ]
  }
}

panel_config.json (в папке сервера)

{
  "name": "server1",
  "displayName": "My Server",
  "startCommand": "java -Xmx2G -jar server.jar nogui",
  "owner": "username"
}

Горячие клавиши

Ctrl + K - Поиск (в файловом менеджере)
Enter - Отправить сообщение (в тикете)
Esc - Закрыть модальное окно
F5 - Обновить страницу

Советы и трюки

Быстрое создание сервера

Создайте сервер через панель
Загрузите server.jar через файловый менеджер
Создайте eula.txt с содержимым eula=true
Запустите сервер

Массовое перемещение файлов

Выберите все файлы (чекбокс в заголовке)
Нажмите "Вырезать"
Перейдите в папку назначения
Нажмите "Вставить"

Мониторинг нескольких серверов

Откройте панель в нескольких вкладках браузера для одновременного мониторинга

Быстрый доступ к консоли

Добавьте панель в закладки браузера для быстрого доступа

Ограничения

Максимальный размер файла: зависит от настроек сервера
Количество серверов: не ограничено (зависит от ресурсов)
Количество пользователей: не ограничено
Длина сообщения в тикете: не ограничена
Срок хранения логов: 1000 последних строк

Roadmap (Планы развития)

Поддержка нескольких OIDC провайдеров
Расписание запуска/остановки серверов
Автоматические бэкапы
Графики статистики
Плагин-менеджер
Мобильное приложение
Push-уведомления
Двухфакторная аутентификация
Темная тема для консоли
Экспорт логов

Changelog

Версия 1.0.0 (15.01.2026)

✨ Первый релиз
✅ Управление серверами
✅ Файловый менеджер
✅ Система тикетов
✅ Личный кабинет
✅ OpenID Connect (ZITADEL)
✅ 6 тем оформления
✅ Система уведомлений
✅ Управление пользователями
✅ Роли и права доступа
✅ WebSocket консоль
✅ Мониторинг ресурсов

Лицензия

MIT License - свободное использование

Контакты и поддержка

Документация: Этот файл
API Документация: API.md
Тикеты: Используйте систему тикетов в панели
GitHub: [Ссылка на репозиторий]

Спасибо за использование MC Panel! 🎮

Версия документации: 1.0.0
Дата обновления: 15 января 2026