Добавить Docs
998
Docs.md
Normal file
998
Docs.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