Add Notification and new mini desing
This commit is contained in:
998
ДОКУМЕНТАЦИЯ.md
Normal file
998
ДОКУМЕНТАЦИЯ.md
Normal file
@@ -0,0 +1,998 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user