update README.md

2026-01-05 20:30:26 +03:00
parent 9bbf88a8f7
commit 501e858c06
151 changed files with 1084 additions and 31525 deletions
--- a/README_ru.md
+++ b/README_ru.md
@@ -0,0 +1,627 @@
+# 🚀 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>