999 lines
33 KiB
Markdown
999 lines
33 KiB
Markdown
# MC Panel - Полная документация проекта
|
||
|
||
**Версия:** 1.0.0
|
||
**Дата:** 15 января 2026
|
||
|
||
---
|
||
|
||
## 📋 Содержание
|
||
|
||
1. [О проекте](#о-проекте)
|
||
2. [Быстрый старт](#быстрый-старт)
|
||
3. [Установка и настройка](#установка-и-настройка)
|
||
4. [Функциональность](#функциональность)
|
||
5. [Система уведомлений](#система-уведомлений)
|
||
6. [Дизайн и темы](#дизайн-и-темы)
|
||
7. [Файловый менеджер](#файловый-менеджер)
|
||
8. [Система тикетов](#система-тикетов)
|
||
9. [Личный кабинет](#личный-кабинет)
|
||
10. [OpenID Connect](#openid-connect)
|
||
11. [Роли пользователей](#роли-пользователей)
|
||
12. [Безопасность](#безопасность)
|
||
13. [Troubleshooting](#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:**
|
||
```bash
|
||
cd backend
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
**Frontend:**
|
||
```bash
|
||
cd frontend
|
||
npm install
|
||
```
|
||
|
||
### Шаг 2: Настройка окружения
|
||
|
||
Создайте файл `.env` в корне проекта:
|
||
|
||
```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:**
|
||
```bash
|
||
cd backend
|
||
python main.py
|
||
```
|
||
Сервер запустится на `http://localhost:8000`
|
||
|
||
**Frontend:**
|
||
```bash
|
||
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. Клонирование репозитория
|
||
```bash
|
||
git clone <repository-url>
|
||
cd mc-panel
|
||
```
|
||
|
||
#### 2. Установка Backend
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
cd frontend
|
||
npm install
|
||
```
|
||
|
||
**Зависимости:**
|
||
- react - UI библиотека
|
||
- react-dom - рендеринг React
|
||
- axios - HTTP клиент
|
||
- lucide-react - иконки
|
||
- tailwindcss - CSS фреймворк
|
||
|
||
#### 4. Настройка ZITADEL (опционально)
|
||
|
||
Если хотите использовать OpenID Connect:
|
||
|
||
1. Создайте аккаунт на [ZITADEL](https://zitadel.com)
|
||
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`
|
||
|
||
**Использование:**
|
||
```javascript
|
||
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](https://zitadel.com)
|
||
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
|
||
```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`:
|
||
```python
|
||
SECRET_KEY = "your-very-long-random-secret-key-here"
|
||
```
|
||
|
||
#### 2. Используйте HTTPS
|
||
```env
|
||
BASE_URL=https://your-domain.com
|
||
FRONTEND_URL=https://your-domain.com
|
||
```
|
||
|
||
#### 3. Настройте CORS
|
||
В `backend/main.py`:
|
||
```python
|
||
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. Регулярные обновления
|
||
```bash
|
||
pip install --upgrade -r requirements.txt
|
||
npm update
|
||
```
|
||
|
||
#### 7. Логирование
|
||
Включите подробное логирование для отслеживания действий
|
||
|
||
#### 8. Backup
|
||
Регулярно создавайте резервные копии:
|
||
- `users.json`
|
||
- `tickets.json`
|
||
- Папка `servers/`
|
||
|
||
---
|
||
|
||
## Troubleshooting
|
||
|
||
### Проблемы с запуском
|
||
|
||
#### Backend не запускается
|
||
```bash
|
||
# Проверьте Python версию
|
||
python --version # Должно быть 3.8+
|
||
|
||
# Переустановите зависимости
|
||
pip install --upgrade -r requirements.txt
|
||
|
||
# Проверьте порт 8000
|
||
netstat -ano | findstr :8000
|
||
```
|
||
|
||
#### Frontend не запускается
|
||
```bash
|
||
# Проверьте 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 не работает
|
||
```bash
|
||
# Проверьте .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
|
||
|
||
### Проблемы с производительностью
|
||
|
||
#### Медленная работа
|
||
```bash
|
||
# Проверьте использование ресурсов
|
||
# Windows:
|
||
tasklist | findstr python
|
||
tasklist | findstr node
|
||
|
||
# Проверьте количество серверов
|
||
# Каждый сервер потребляет ресурсы
|
||
```
|
||
|
||
#### Высокое использование CPU
|
||
- Много запущенных серверов
|
||
- Частые обновления статистики
|
||
- **Решение:** Остановите неиспользуемые серверы
|
||
|
||
### Логи и отладка
|
||
|
||
#### Включить подробные логи (Backend)
|
||
В `backend/main.py`:
|
||
```python
|
||
import logging
|
||
logging.basicConfig(level=logging.DEBUG)
|
||
```
|
||
|
||
#### Просмотр логов (Frontend)
|
||
Откройте консоль браузера (F12) → Console
|
||
|
||
#### Проверка API
|
||
```bash
|
||
# Проверьте доступность 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
|
||
```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
|
||
```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 (в папке сервера)
|
||
```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
|