# 🚀 Ospabhost 8.1 - Платформа S3 Объектного Хранилища

Современная платформа управления S3-совместимым объектным хранилищем с системой биллинга, блогом и тикетами поддержки.

![Version](https://img.shields.io/badge/version-8.1-blue)
![Node.js](https://img.shields.io/badge/node.js-v24+-green)
![TypeScript](https://img.shields.io/badge/typescript-5.x-blue)

[🇬🇧 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>