Arkon/NeveTimePanel
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
77b857d1d1c9212b993a72e22606a80074cfb71e
NeveTimePanel/ДОКУМЕНТАЦИЯ.md

33 KiB
Raw Blame History

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

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

📋 Содержание

  1. О проекте
  2. Быстрый старт
  3. Установка и настройка
  4. Функциональность
  5. Система уведомлений
  6. Дизайн и темы
  7. Файловый менеджер
  8. Система тикетов
  9. Личный кабинет
  10. OpenID Connect
  11. Роли пользователей
  12. Безопасность
  13. Troubleshooting

О проекте

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: Первый вход

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

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

  • Логин: 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:

  1. Создайте аккаунт на ZITADEL
  2. Создайте новое приложение (Application)
  3. Выберите тип "Web"
  4. Настройте Redirect URIs:
    • http://localhost:8000/api/auth/oidc/zitadel/callback
  5. Скопируйте Client ID и Client Secret
  6. Добавьте в .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         # Этот файл

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

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

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

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

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

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

Консоль

  • Просмотр логов в реальном времени
  • Отправка команд серверу
  • Цветная подсветка:
    • 🟢 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 сек)

Дизайн и темы

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

  1. Modern (Современная) - по умолчанию

    • Цвета: #0f1115, #1a1d24, #23262e
    • Акцент: зеленый
    • Градиент: зеленый → изумрудный

  2. Dark (Тёмная)

    • Цвета: черный, темно-серый
    • Акцент: синий
    • Градиент: синий → фиолетовый

  3. Light (Светлая)

    • Цвета: белый, светло-серый
    • Акцент: синий
    • Градиент: синий → фиолетовый

  4. Purple (Фиолетовая)

    • Цвета: темный с фиолетовым оттенком
    • Акцент: фиолетовый
    • Градиент: фиолетовый → розовый

  5. Blue (Синяя)

    • Цвета: темный с синим оттенком
    • Акцент: синий
    • Градиент: голубой → синий

  6. Green (Зелёная)

    • Цвета: темный с зеленым оттенком
    • Акцент: зеленый
    • Градиент: изумрудный → зеленый

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

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

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

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

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

Возможности

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

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

Создание

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

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

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

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

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

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

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

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

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

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

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

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

Удаление

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

Выбор файлов

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

Интерфейс

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

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

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

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

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

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

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

Просмотр

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

Чат

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

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

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

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

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

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

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

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

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

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

При ошибках:

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

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

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

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

Доступ

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

Разделы

Обзор

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

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

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

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

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

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

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

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

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

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

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

Доступ:

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

OpenID Connect

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

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

Настройка ZITADEL

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

  1. Зарегистрируйтесь на ZITADEL
  2. Создайте новый проект
  3. Добавьте приложение (Application)
  4. Выберите тип "Web"
  5. Настройте Redirect URIs: 
    http://localhost:8000/api/auth/oidc/zitadel/callback
https://your-domain.com/api/auth/oidc/zitadel/callback

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

  1. Скопируйте Client ID
  2. Создайте и скопируйте Client Secret
  3. Скопируйте 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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Нет доступа:

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

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

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

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

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

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

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

JWT Токены

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

Пароли

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

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

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

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

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

Рекомендации для production

1. Измените SECRET_KEY

В backend/main.py:

SECRET_KEY = "your-very-long-random-secret-key-here"

2. Используйте HTTPS

BASE_URL=https://your-domain.com
FRONTEND_URL=https://your-domain.com

3. Настройте CORS

В backend/main.py:

app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://your-domain.com"],  # Конкретный домен
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

4. Используйте базу данных

Замените users.json и tickets.json на PostgreSQL/MySQL

5. Настройте firewall

  • Ограничьте доступ к портам
  • Разрешите только необходимые IP

6. Регулярные обновления

pip install --upgrade -r requirements.txt
npm update

7. Логирование

Включите подробное логирование для отслеживания действий

8. Backup

Регулярно создавайте резервные копии:

  • users.json
  • tickets.json
  • Папка servers/

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"

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

  1. Проверьте документацию - возможно, ответ уже есть
  2. Проверьте логи - backend и frontend
  3. Создайте тикет - опишите проблему подробно
  4. 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 - Обновить страницу

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

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

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

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

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

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

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

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

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

Ограничения

  • Максимальный размер файла: зависит от настроек сервера
  • Количество серверов: не ограничено (зависит от ресурсов)
  • Количество пользователей: не ограничено
  • Длина сообщения в тикете: не ограничена
  • Срок хранения логов: 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

Reference in New Issue View Git Blame Copy Permalink