628 lines
23 KiB
Markdown
628 lines
23 KiB
Markdown
# 🚀 Ospabhost 8.1 - Платформа S3 Объектного Хранилища
|
||
|
||
Современная платформа управления S3-совместимым объектным хранилищем с системой биллинга, блогом и тикетами поддержки.
|
||
|
||
|
||
|
||
|
||
|
||
[🇬🇧 English version](README.md)
|
||
|
||
---
|
||
|
||
## 📋 Содержание
|
||
|
||
- [О проекте](#о-проекте)
|
||
- [Возможности](#возможности)
|
||
- [Технологии](#технологии)
|
||
- [Быстрый старт](#быстрый-старт)
|
||
- [Развёртывание](#развёртывание)
|
||
- [Структура проекта](#структура-проекта)
|
||
- [API документация](#api-документация)
|
||
- [Участие в разработке](#участие-в-разработке)
|
||
|
||
---
|
||
|
||
## 🎯 О проекте
|
||
|
||
**Ospabhost 8.1** — это комплексная платформа управления S3-совместимым объектным хранилищем на базе MinIO, включающая:
|
||
|
||
- 💾 **S3 Хранилище** - Полнофункциональное хранилище на базе MinIO с совместимостью AWS S3
|
||
- 📝 **CMS Блога** - Встроенная система управления контентом с Rich Text редактором
|
||
- 🎫 **Тикеты Поддержки** - Система тикетов с приоритетами и вложениями
|
||
- 💰 **Биллинг** - Управление балансом с проверкой чеков
|
||
- 🔐 **Авторизация** - JWT + OAuth (Google, GitHub, Yandex) + QR-авторизация
|
||
- 🔔 **Уведомления** - Web Push и email уведомления
|
||
- 🌓 **Тёмная Тема** - Автоматическая тёмная тема с определением системных настроек
|
||
- 📊 **Админ Панель** - Полная панель администрирования
|
||
|
||
---
|
||
|
||
## 🌟 Возможности
|
||
|
||
### Для пользователей
|
||
|
||
#### S3 Объектное Хранилище
|
||
- **Управление бакетами**
|
||
- Создание бакетов с выбором региона
|
||
- Кастомные тарифные планы (за GB, трафик, запросы)
|
||
- Контроль публичного/приватного доступа
|
||
- Версионирование объектов
|
||
- Presigned URL для временного доступа
|
||
|
||
- **Множественная загрузка файлов**
|
||
- Drag & Drop интерфейс
|
||
- Выбор множественных файлов
|
||
- Загрузка папок с сохранением структуры (webkitdirectory)
|
||
- Загрузка по URI/URL
|
||
- Отслеживание прогресса в реальном времени (проценты, скорость в MB/s)
|
||
- Отмена загрузки
|
||
|
||
- **Доступ к консоли MinIO**
|
||
- Учётные данные в один клик (генерируются раз в неделю)
|
||
- Прямое управление бакетами через UI MinIO
|
||
- Расширенные S3 операции
|
||
|
||
#### Блог
|
||
- Чтение статей и комментирование
|
||
- Доступ к статьям по URL
|
||
- Счётчики просмотров
|
||
- Поддержка RSS
|
||
|
||
#### Тикеты Поддержки
|
||
- Создание тикетов с приоритетом (низкий/обычный/высокий/срочный) и категорией
|
||
- Вложения файлов (до 5 файлов по 10MB)
|
||
- Обмен сообщениями с операторами в реальном времени
|
||
- Отслеживание статуса: открыт → в работе → ожидает ответа → решён → закрыт
|
||
- История тикетов
|
||
|
||
#### Аккаунт и Безопасность
|
||
- Управление балансом с загрузкой чеков
|
||
- Управление активными сессиями (отслеживание IP, устройства, браузера)
|
||
- История входов
|
||
- QR-авторизация (как в Telegram Web)
|
||
- Завершение отдельных сессий
|
||
|
||
### Для операторов
|
||
- Просмотр и ответы на тикеты
|
||
- Автоматическое назначение тикетов
|
||
- Управление приоритетом и статусом
|
||
- Внутренние заметки (невидимы для пользователей)
|
||
|
||
### Для администраторов
|
||
- **Управление пользователями**
|
||
- Просмотр всех пользователей
|
||
- Редактирование баланса
|
||
- Назначение роли оператора
|
||
- Блокировка/разблокировка аккаунтов
|
||
|
||
- **Управление ценами**
|
||
- Настройка тарифных планов S3
|
||
- Кастомные цены (за GB, трафик, API запросы)
|
||
- Категории тарифов
|
||
|
||
- **Управление блогом**
|
||
- Создание/редактирование статей с редактором Quill.js
|
||
- Загрузка изображений
|
||
- Модерация комментариев
|
||
- SEO настройки
|
||
|
||
- **Проверка чеков**
|
||
- Одобрение/отклонение заявок на пополнение
|
||
- Просмотр загруженных чеков
|
||
|
||
- **Инструменты тестирования**
|
||
- Отправка тестовых push-уведомлений
|
||
- Отправка тестовых email
|
||
- Мониторинг логов
|
||
|
||
---
|
||
|
||
## 🛠️ Технологии
|
||
|
||
### Backend
|
||
- **Node.js 24+** с Express.js
|
||
- **TypeScript 5.x** для типобезопасности
|
||
- **Prisma ORM** с MySQL 8+
|
||
- **MinIO SDK** для S3 операций
|
||
- **JWT** + **Passport.js** для авторизации
|
||
- **Multer** для загрузки файлов
|
||
- **web-push** для уведомлений
|
||
- **Nodemailer** для email
|
||
- **PM2** для управления процессами
|
||
|
||
### Frontend
|
||
- **React 18** с TypeScript
|
||
- **Vite 7.x** для быстрой сборки
|
||
- **React Router 6** для навигации
|
||
- **Tailwind CSS 3.3** для стилизации
|
||
- **React Quill** для rich text редактирования
|
||
- **Axios** для API запросов
|
||
- **i18next** для локализации (en/ru)
|
||
- **Service Worker** для push-уведомлений
|
||
|
||
### Инфраструктура
|
||
- **MySQL 8+** база данных
|
||
- **MinIO** S3-совместимое хранилище
|
||
- **Nginx** reverse proxy
|
||
- **PM2** менеджер процессов
|
||
- **Git** (Gitea + GitHub)
|
||
- **Let's Encrypt** SSL
|
||
|
||
---
|
||
|
||
## 🚀 Быстрый старт
|
||
|
||
### Требования
|
||
- Node.js 24+
|
||
- MySQL 8+
|
||
- MinIO сервер
|
||
|
||
### Установка
|
||
|
||
1. **Клонирование репозитория**
|
||
```bash
|
||
git clone http://localhost:4000/ospab/ospab.host.git
|
||
cd ospab.host/ospabhost
|
||
```
|
||
|
||
2. **Настройка Backend**
|
||
```bash
|
||
cd backend
|
||
npm install
|
||
|
||
# Скопировать и настроить окружение
|
||
cp .env.example .env
|
||
# Отредактировать .env с вашими настройками
|
||
|
||
# Настройка базы данных
|
||
npx prisma migrate deploy
|
||
npx prisma generate
|
||
npx prisma db seed
|
||
|
||
# Запуск dev сервера
|
||
npm run dev
|
||
```
|
||
|
||
3. **Настройка Frontend**
|
||
```bash
|
||
cd ../frontend
|
||
npm install
|
||
|
||
# Скопировать и настроить окружение
|
||
cp .env.example .env
|
||
# Отредактировать .env с URL вашего API
|
||
|
||
# Запуск dev сервера
|
||
npm run dev
|
||
```
|
||
|
||
4. **Доступ к приложению**
|
||
- Frontend: http://localhost:5173
|
||
- Backend API: http://localhost:5000
|
||
- Панель управления: http://localhost:5173/dashboard
|
||
|
||
Первый зарегистрированный пользователь автоматически становится администратором.
|
||
|
||
---
|
||
|
||
## 🌐 Развёртывание
|
||
|
||
### Production установка
|
||
|
||
1. **Установка зависимостей**
|
||
```bash
|
||
# Node.js 24
|
||
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
|
||
sudo apt-get install -y nodejs
|
||
|
||
# MySQL и Nginx
|
||
sudo apt install mysql-server nginx
|
||
|
||
# PM2
|
||
sudo npm install -g pm2
|
||
```
|
||
|
||
2. **Развёртывание Backend**
|
||
```bash
|
||
cd /var/www/ospab.host/ospabhost/backend
|
||
|
||
npm install
|
||
cp .env.example .env
|
||
# Настроить .env
|
||
|
||
# Создать директории для загрузок
|
||
mkdir -p uploads/{checks,blog,tickets}
|
||
chmod 755 uploads/*
|
||
|
||
# Миграции базы данных
|
||
npx prisma migrate deploy
|
||
npx prisma generate
|
||
|
||
# Сборка и запуск
|
||
npm run build
|
||
pm2 start ecosystem.config.js
|
||
pm2 save
|
||
pm2 startup
|
||
```
|
||
|
||
3. **Сборка Frontend**
|
||
```bash
|
||
cd ../frontend
|
||
npm install
|
||
npm run build
|
||
```
|
||
|
||
4. **Конфигурация Nginx**
|
||
```nginx
|
||
server {
|
||
listen 80;
|
||
server_name ospab.host;
|
||
|
||
# Frontend
|
||
location / {
|
||
root /var/www/ospab.host/ospabhost/frontend/dist;
|
||
try_files $uri $uri/ /index.html;
|
||
}
|
||
|
||
# Backend API
|
||
location /api {
|
||
proxy_pass http://localhost:5000;
|
||
proxy_set_header Host $host;
|
||
proxy_set_header X-Real-IP $remote_addr;
|
||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||
}
|
||
|
||
# WebSocket
|
||
location /ws {
|
||
proxy_pass http://localhost:5000;
|
||
proxy_http_version 1.1;
|
||
proxy_set_header Upgrade $http_upgrade;
|
||
proxy_set_header Connection "upgrade";
|
||
}
|
||
|
||
# Статические загрузки
|
||
location /uploads {
|
||
alias /var/www/ospab.host/ospabhost/backend/uploads;
|
||
expires 30d;
|
||
add_header Cache-Control "public, immutable";
|
||
}
|
||
|
||
client_max_body_size 50M;
|
||
}
|
||
```
|
||
|
||
5. **SSL сертификат**
|
||
```bash
|
||
sudo certbot --nginx -d ospab.host -d api.ospab.host
|
||
```
|
||
|
||
### Обновление развёртывания
|
||
```bash
|
||
cd /var/www/ospab.host/ospabhost
|
||
|
||
# Получить последние изменения
|
||
git pull
|
||
|
||
# Обновление backend
|
||
cd backend
|
||
npm install
|
||
npx prisma generate
|
||
npm run build
|
||
pm2 restart all
|
||
|
||
# Обновление frontend
|
||
cd ../frontend
|
||
npm install
|
||
npm run build
|
||
|
||
# Перезагрузить Nginx
|
||
sudo systemctl reload nginx
|
||
```
|
||
|
||
---
|
||
|
||
## 📁 Структура проекта
|
||
|
||
```
|
||
ospab.host/
|
||
├── ospabhost/
|
||
│ ├── backend/
|
||
│ │ ├── src/
|
||
│ │ │ ├── modules/
|
||
│ │ │ │ ├── auth/ # Авторизация (JWT, OAuth, QR)
|
||
│ │ │ │ ├── storage/ # S3 хранилище (MinIO)
|
||
│ │ │ │ ├── blog/ # CMS блога
|
||
│ │ │ │ ├── ticket/ # Тикеты поддержки
|
||
│ │ │ │ ├── check/ # Проверка чеков
|
||
│ │ │ │ ├── notification/ # Push и Email
|
||
│ │ │ │ ├── tariff/ # Тарифные планы
|
||
│ │ │ │ ├── session/ # Управление сессиями
|
||
│ │ │ │ └── admin/ # Админ панель
|
||
│ │ │ ├── middleware/ # Express middleware
|
||
│ │ │ ├── prisma/ # Prisma клиент
|
||
│ │ │ ├── routes/ # Определения маршрутов
|
||
│ │ │ ├── utils/ # Утилиты
|
||
│ │ │ ├── websocket/ # WebSocket сервер
|
||
│ │ │ ├── index.ts # Главная точка входа
|
||
│ │ │ └── server.ts # Express сервер
|
||
│ │ ├── prisma/
|
||
│ │ │ ├── schema.prisma # Схема базы данных
|
||
│ │ │ ├── migrations/ # Миграции БД
|
||
│ │ │ └── seed.ts # Начальные данные
|
||
│ │ ├── uploads/ # Загрузки пользователей
|
||
│ │ ├── package.json
|
||
│ │ ├── tsconfig.json
|
||
│ │ └── ecosystem.config.js # PM2 конфиг
|
||
│ │
|
||
│ └── frontend/
|
||
│ ├── src/
|
||
│ │ ├── pages/
|
||
│ │ │ ├── index.tsx # Главная страница
|
||
│ │ │ ├── login.tsx # Вход
|
||
│ │ │ ├── register.tsx # Регистрация
|
||
│ │ │ ├── pricing.tsx # Тарифные планы
|
||
│ │ │ ├── blog.tsx # Список статей
|
||
│ │ │ ├── blogpost.tsx # Статья блога
|
||
│ │ │ └── dashboard/
|
||
│ │ │ ├── mainpage.tsx # Главная дашборда
|
||
│ │ │ ├── summary.tsx # Обзор
|
||
│ │ │ ├── storage.tsx # Бакеты хранилища
|
||
│ │ │ ├── storage-bucket.tsx # Управление бакетом
|
||
│ │ │ ├── tickets/ # Система тикетов
|
||
│ │ │ ├── billing.tsx # Баланс
|
||
│ │ │ ├── settings.tsx # Настройки
|
||
│ │ │ ├── notifications.tsx # Уведомления
|
||
│ │ │ ├── admin.tsx # Админ панель
|
||
│ │ │ ├── blogadmin.tsx # Админ блога
|
||
│ │ │ └── blogeditor.tsx # Редактор статей
|
||
│ │ ├── components/
|
||
│ │ │ ├── header.tsx # Шапка сайта
|
||
│ │ │ ├── footer.tsx # Футер сайта
|
||
│ │ │ └── PrivateRoute.tsx # Защищённые маршруты
|
||
│ │ ├── context/
|
||
│ │ │ ├── authcontext.tsx # Состояние авторизации
|
||
│ │ │ └── ThemeContext.tsx # Состояние темы
|
||
│ │ ├── services/
|
||
│ │ │ └── apiClient.ts # Axios клиент
|
||
│ │ ├── i18n/ # Локализация
|
||
│ │ ├── App.tsx
|
||
│ │ └── main.tsx
|
||
│ ├── public/
|
||
│ │ ├── service-worker.js # Push-уведомления
|
||
│ │ └── robots.txt
|
||
│ ├── package.json
|
||
│ ├── vite.config.ts
|
||
│ └── tailwind.config.js
|
||
│
|
||
├── README.md # Английская версия
|
||
└── README_ru.md # Этот файл (Русский)
|
||
```
|
||
|
||
---
|
||
|
||
## 📚 API документация
|
||
|
||
### Публичные эндпоинты
|
||
|
||
#### Авторизация
|
||
```http
|
||
POST /api/auth/register
|
||
POST /api/auth/login
|
||
GET /api/auth/google
|
||
GET /api/auth/github
|
||
GET /api/auth/yandex
|
||
```
|
||
|
||
#### QR-авторизация
|
||
```http
|
||
POST /api/qr-auth/generate # Генерация QR-кода
|
||
GET /api/qr-auth/status/:code # Проверка статуса (polling)
|
||
POST /api/qr-auth/confirm # Подтверждение входа (мобильный)
|
||
```
|
||
|
||
#### Блог
|
||
```http
|
||
GET /api/blog/posts # Список статей
|
||
GET /api/blog/posts/:url # Получить статью по URL
|
||
POST /api/blog/posts/:id/comments # Добавить комментарий
|
||
```
|
||
|
||
#### Тарифные планы
|
||
```http
|
||
GET /api/storage/plans # Список тарифных планов
|
||
```
|
||
|
||
### Защищённые эндпоинты
|
||
|
||
Все запросы требуют: `Authorization: Bearer <JWT_TOKEN>`
|
||
|
||
#### S3 Хранилище
|
||
```http
|
||
GET /api/storage/buckets # Список бакетов
|
||
POST /api/storage/buckets # Создать бакет
|
||
GET /api/storage/buckets/:id # Информация о бакете
|
||
DELETE /api/storage/buckets/:id # Удалить бакет
|
||
PUT /api/storage/buckets/:id # Обновить настройки
|
||
|
||
GET /api/storage/buckets/:id/objects # Список объектов
|
||
POST /api/storage/buckets/:id/upload # Загрузить файл
|
||
POST /api/storage/buckets/:id/upload-from-uri # Загрузить по URL
|
||
POST /api/storage/buckets/:id/upload-directory # Загрузить папку
|
||
DELETE /api/storage/buckets/:id/objects # Удалить объекты
|
||
|
||
POST /api/storage/buckets/:id/presign # Создать presigned URL
|
||
POST /api/storage/buckets/:id/console-credentials # Получить доступ к консоли
|
||
```
|
||
|
||
#### Тикеты Поддержки
|
||
```http
|
||
GET /api/tickets # Список тикетов пользователя
|
||
POST /api/tickets # Создать тикет
|
||
GET /api/tickets/:id # Детали тикета
|
||
POST /api/tickets/:id/messages # Отправить сообщение
|
||
PATCH /api/tickets/:id/status # Обновить статус (операторы)
|
||
POST /api/tickets/:id/assign # Назначить оператора
|
||
PATCH /api/tickets/:id/close # Закрыть тикет
|
||
```
|
||
|
||
#### Управление сессиями
|
||
```http
|
||
GET /api/sessions # Список активных сессий
|
||
GET /api/sessions/history # История входов
|
||
DELETE /api/sessions/:id # Завершить сессию
|
||
DELETE /api/sessions/others/all # Завершить все другие сессии
|
||
```
|
||
|
||
#### Админ эндпоинты
|
||
```http
|
||
GET /api/admin/users # Список всех пользователей
|
||
PUT /api/admin/users/:id # Редактировать пользователя
|
||
|
||
GET /api/admin/checks # Список чеков на оплату
|
||
PUT /api/admin/checks/:id # Одобрить/отклонить чек
|
||
|
||
GET /api/blog/admin/posts # Список всех статей
|
||
POST /api/blog/admin/posts # Создать статью
|
||
PUT /api/blog/admin/posts/:id # Обновить статью
|
||
DELETE /api/blog/admin/posts/:id # Удалить статью
|
||
POST /api/blog/admin/upload-image # Загрузить изображение
|
||
|
||
GET /api/blog/admin/comments # Список всех комментариев
|
||
PATCH /api/blog/admin/comments/:id # Модерировать комментарий
|
||
DELETE /api/blog/admin/comments/:id # Удалить комментарий
|
||
|
||
PUT /api/storage/plans/:id # Обновить тарифный план
|
||
|
||
POST /api/admin/test/push-notification # Тест push
|
||
POST /api/admin/test/email-notification # Тест email
|
||
```
|
||
|
||
---
|
||
|
||
## 🐛 Решение проблем
|
||
|
||
### Проблемы Backend
|
||
|
||
**Prisma Client не имеет моделей**
|
||
```bash
|
||
cd backend
|
||
npx prisma generate
|
||
npm run build
|
||
pm2 restart all
|
||
```
|
||
|
||
**OAuth возвращает 404**
|
||
- Проверьте `.env` на наличие `GOOGLE_CLIENT_ID`, `GITHUB_CLIENT_ID`, `YANDEX_CLIENT_ID`
|
||
- Убедитесь, что `oauthRoutes` импортирован в `index.ts`
|
||
- Перезапустите сервер
|
||
|
||
**Push-уведомления не работают**
|
||
- Проверьте VAPID ключи в `.env`
|
||
- Убедитесь, что `service-worker.js` зарегистрирован
|
||
- Используйте HTTPS в production
|
||
|
||
### Проблемы Frontend
|
||
|
||
**Сессия не сохраняется**
|
||
- Убедитесь, что `login()` в `authcontext.tsx` использует async/await
|
||
- Проверьте, что JWT токен сохраняется в localStorage
|
||
- Проверьте, что `bootstrapSession()` вызывается после логина
|
||
|
||
**Тёмная тема не применяется**
|
||
- Убедитесь, что `ThemeProvider` оборачивает `App`
|
||
- Проверьте, что в `tailwind.config.js` указан `darkMode: 'class'`
|
||
- Убедитесь, что компоненты используют классы `dark:`
|
||
|
||
**Загрузка файлов не работает**
|
||
- Проверьте права директорий: `chmod 755 uploads/*`
|
||
- Убедитесь, что Nginx раздаёт `/uploads`
|
||
- Проверьте Nginx `client_max_body_size 50M;`
|
||
|
||
### Проблемы S3 хранилища
|
||
|
||
**Не удаётся создать бакет**
|
||
- Проверьте подключение к MinIO
|
||
- Убедитесь, что MinIO credentials корректны в `.env`
|
||
- Проверьте, что у пользователя достаточно средств
|
||
|
||
**Учётные данные консоли не работают**
|
||
- Учётные данные действительны 7 дней
|
||
- Сгенерируйте новые учётные данные из дашборда
|
||
- Убедитесь, что MinIO endpoint доступен
|
||
|
||
---
|
||
|
||
## 🤝 Участие в разработке
|
||
|
||
Мы приветствуем вклад! Пожалуйста, следуйте этим шагам:
|
||
|
||
1. Форкните репозиторий
|
||
2. Создайте feature ветку: `git checkout -b feature/AmazingFeature`
|
||
3. Закоммитьте изменения: `git commit -m 'feat: add amazing feature'`
|
||
4. Запушьте в ветку: `git push origin feature/AmazingFeature`
|
||
5. Откройте Pull Request
|
||
|
||
### Соглашение о коммитах
|
||
|
||
Мы используем [Conventional Commits](https://www.conventionalcommits.org/ru/):
|
||
|
||
```bash
|
||
feat(storage): добавить поддержку загрузки папок
|
||
fix(ticket): авто-снятие при закрытии
|
||
docs: обновить API документацию
|
||
refactor(auth): улучшить обработку ошибок
|
||
```
|
||
|
||
### Рабочий процесс разработки
|
||
|
||
```bash
|
||
# Разработка Backend
|
||
cd backend
|
||
npm run dev
|
||
|
||
# Разработка Frontend
|
||
cd frontend
|
||
npm run dev
|
||
|
||
# Миграции базы данных
|
||
npx prisma migrate dev --name migration_name
|
||
npx prisma generate
|
||
|
||
# Сборка для production
|
||
npm run build
|
||
```
|
||
|
||
---
|
||
|
||
## 📄 Лицензия
|
||
|
||
MIT License
|
||
|
||
---
|
||
|
||
## 📞 Контакты
|
||
|
||
- **Сайт:** [ospab.host](https://ospab.host)
|
||
- **Email:** support@ospab.host
|
||
- **Telegram:** [@ospab](https://t.me/ospab)
|
||
- **Gitea:** http://localhost:4000/ospab/ospab.host
|
||
- **GitHub:** https://github.com/ospab/ospabhost8.1
|
||
|
||
---
|
||
|
||
## 🙏 Благодарности
|
||
|
||
- [MinIO](https://min.io/) - S3-совместимое объектное хранилище
|
||
- [Prisma](https://www.prisma.io/) - ORM нового поколения
|
||
- [React](https://react.dev/) - UI библиотека
|
||
- [Tailwind CSS](https://tailwindcss.com/) - CSS фреймворк
|
||
- [Quill](https://quilljs.com/) - Rich text редактор
|
||
- [Passport.js](https://www.passportjs.org/) - Middleware авторизации
|
||
|
||
---
|
||
|
||
**Версия:** 8.1
|
||
**Обновлено:** 5 января 2026
|
||
**Git:** ospab <ospab@ospab.host>
|