628 lines
16 KiB
Markdown
628 lines
16 KiB
Markdown
# 🚀 Ospabhost 8.1 - S3 Object Storage Platform
|
|
|
|
Modern S3-compatible object storage management platform with billing, blog, and support ticketing system.
|
|
|
|
|
|
|
|
|
|
|
|
[🇷🇺 Русская версия](README_ru.md)
|
|
|
|
---
|
|
|
|
## 📋 Table of Contents
|
|
|
|
- [About](#about)
|
|
- [Features](#features)
|
|
- [Tech Stack](#tech-stack)
|
|
- [Quick Start](#quick-start)
|
|
- [Deployment](#deployment)
|
|
- [Project Structure](#project-structure)
|
|
- [API Documentation](#api-documentation)
|
|
- [Contributing](#contributing)
|
|
|
|
---
|
|
|
|
## 🎯 About
|
|
|
|
**Ospabhost 8.1** is a comprehensive S3-compatible object storage management platform built on MinIO, featuring:
|
|
|
|
- 💾 **S3 Object Storage** - Full-featured MinIO-based storage with AWS S3 compatibility
|
|
- 📝 **Blog CMS** - Built-in content management system with Rich Text editor
|
|
- 🎫 **Support Tickets** - Priority-based ticketing system with attachments
|
|
- 💰 **Billing** - Balance management with check verification
|
|
- 🔐 **Authentication** - JWT + OAuth (Google, GitHub, Yandex) + QR auth
|
|
- 🔔 **Notifications** - Web Push and email notifications
|
|
- 🌓 **Dark Theme** - Automatic dark mode with system preference detection
|
|
- 📊 **Admin Panel** - Complete administration dashboard
|
|
|
|
---
|
|
|
|
## 🌟 Features
|
|
|
|
### For Users
|
|
|
|
#### S3 Object Storage
|
|
- **Bucket Management**
|
|
- Create buckets with region selection
|
|
- Custom pricing plans (per GB, bandwidth, requests)
|
|
- Public/private access control
|
|
- Object versioning
|
|
- Presigned URLs for temporary access
|
|
|
|
- **Multiple File Upload Methods**
|
|
- Drag & Drop interface
|
|
- Multiple file selection
|
|
- Folder upload with structure preservation (webkitdirectory)
|
|
- Upload from URI/URL
|
|
- Real-time progress tracking (percentage, speed in MB/s)
|
|
- Upload cancellation
|
|
|
|
- **MinIO Console Access**
|
|
- One-click console credentials (generated weekly)
|
|
- Direct bucket management through MinIO UI
|
|
- Advanced S3 operations
|
|
|
|
#### Blog
|
|
- Read articles and comment
|
|
- URL-based article access
|
|
- View counters
|
|
- RSS feed support
|
|
|
|
#### Support Tickets
|
|
- Create tickets with priority (low/normal/high/urgent) and category
|
|
- File attachments (up to 5 files, 10MB each)
|
|
- Real-time messaging with operators
|
|
- Status tracking: open → in_progress → awaiting_reply → resolved → closed
|
|
- Ticket history
|
|
|
|
#### Account & Security
|
|
- Balance management with check uploads
|
|
- Active session management (IP, device, browser tracking)
|
|
- Login history
|
|
- QR authentication (Telegram Web style)
|
|
- Individual session termination
|
|
|
|
### For Operators
|
|
- View and respond to tickets
|
|
- Automatic ticket assignment
|
|
- Priority and status management
|
|
- Internal notes (invisible to users)
|
|
|
|
### For Administrators
|
|
- **User Management**
|
|
- View all users
|
|
- Edit balance
|
|
- Assign operator role
|
|
- Block/unblock accounts
|
|
|
|
- **Pricing Management**
|
|
- Configure S3 storage plans
|
|
- Custom pricing (per GB, bandwidth, API requests)
|
|
- Tariff categories
|
|
|
|
- **Blog Management**
|
|
- Create/edit articles with Quill.js editor
|
|
- Image uploads
|
|
- Comment moderation
|
|
- SEO settings
|
|
|
|
- **Check Verification**
|
|
- Approve/reject balance top-up requests
|
|
- View uploaded receipts
|
|
|
|
- **Testing Tools**
|
|
- Send test push notifications
|
|
- Send test emails
|
|
- Log monitoring
|
|
|
|
---
|
|
|
|
## 🛠️ Tech Stack
|
|
|
|
### Backend
|
|
- **Node.js 24+** with Express.js
|
|
- **TypeScript 5.x** for type safety
|
|
- **Prisma ORM** with MySQL 8+
|
|
- **MinIO SDK** for S3 operations
|
|
- **JWT** + **Passport.js** for authentication
|
|
- **Multer** for file uploads
|
|
- **web-push** for notifications
|
|
- **Nodemailer** for emails
|
|
- **PM2** for process management
|
|
|
|
### Frontend
|
|
- **React 18** with TypeScript
|
|
- **Vite 7.x** for fast builds
|
|
- **React Router 6** for navigation
|
|
- **Tailwind CSS 3.3** for styling
|
|
- **React Quill** for rich text editing
|
|
- **Axios** for API calls
|
|
- **i18next** for localization (en/ru)
|
|
- **Service Worker** for push notifications
|
|
|
|
### Infrastructure
|
|
- **MySQL 8+** database
|
|
- **MinIO** S3-compatible storage
|
|
- **Nginx** reverse proxy
|
|
- **PM2** process manager
|
|
- **Git** (Gitea + GitHub)
|
|
- **Let's Encrypt** SSL
|
|
|
|
---
|
|
|
|
## 🚀 Quick Start
|
|
|
|
### Prerequisites
|
|
- Node.js 24+
|
|
- MySQL 8+
|
|
- MinIO server
|
|
|
|
### Installation
|
|
|
|
1. **Clone Repository**
|
|
```bash
|
|
git clone http://localhost:4000/ospab/ospab.host.git
|
|
cd ospab.host/ospabhost
|
|
```
|
|
|
|
2. **Backend Setup**
|
|
```bash
|
|
cd backend
|
|
npm install
|
|
|
|
# Copy and configure environment
|
|
cp .env.example .env
|
|
# Edit .env with your settings
|
|
|
|
# Database setup
|
|
npx prisma migrate deploy
|
|
npx prisma generate
|
|
npx prisma db seed
|
|
|
|
# Start development server
|
|
npm run dev
|
|
```
|
|
|
|
3. **Frontend Setup**
|
|
```bash
|
|
cd ../frontend
|
|
npm install
|
|
|
|
# Copy and configure environment
|
|
cp .env.example .env
|
|
# Edit .env with your API URL
|
|
|
|
# Start development server
|
|
npm run dev
|
|
```
|
|
|
|
4. **Access Application**
|
|
- Frontend: http://localhost:5173
|
|
- Backend API: http://localhost:5000
|
|
- Dashboard: http://localhost:5173/dashboard
|
|
|
|
First registered user automatically becomes administrator.
|
|
|
|
---
|
|
|
|
## 🌐 Deployment
|
|
|
|
### Production Setup
|
|
|
|
1. **Install Dependencies**
|
|
```bash
|
|
# Node.js 24
|
|
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
|
|
sudo apt-get install -y nodejs
|
|
|
|
# MySQL and Nginx
|
|
sudo apt install mysql-server nginx
|
|
|
|
# PM2
|
|
sudo npm install -g pm2
|
|
```
|
|
|
|
2. **Backend Deployment**
|
|
```bash
|
|
cd /var/www/ospab.host/ospabhost/backend
|
|
|
|
npm install
|
|
cp .env.example .env
|
|
# Configure .env
|
|
|
|
# Create upload directories
|
|
mkdir -p uploads/{checks,blog,tickets}
|
|
chmod 755 uploads/*
|
|
|
|
# Database migrations
|
|
npx prisma migrate deploy
|
|
npx prisma generate
|
|
|
|
# Build and start
|
|
npm run build
|
|
pm2 start ecosystem.config.js
|
|
pm2 save
|
|
pm2 startup
|
|
```
|
|
|
|
3. **Frontend Build**
|
|
```bash
|
|
cd ../frontend
|
|
npm install
|
|
npm run build
|
|
```
|
|
|
|
4. **Nginx Configuration**
|
|
```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";
|
|
}
|
|
|
|
# Static uploads
|
|
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 Certificate**
|
|
```bash
|
|
sudo certbot --nginx -d ospab.host -d api.ospab.host
|
|
```
|
|
|
|
### Update Deployment
|
|
```bash
|
|
cd /var/www/ospab.host/ospabhost
|
|
|
|
# Pull latest changes
|
|
git pull
|
|
|
|
# Backend update
|
|
cd backend
|
|
npm install
|
|
npx prisma generate
|
|
npm run build
|
|
pm2 restart all
|
|
|
|
# Frontend update
|
|
cd ../frontend
|
|
npm install
|
|
npm run build
|
|
|
|
# Reload Nginx
|
|
sudo systemctl reload nginx
|
|
```
|
|
|
|
---
|
|
|
|
## 📁 Project Structure
|
|
|
|
```
|
|
ospab.host/
|
|
├── ospabhost/
|
|
│ ├── backend/
|
|
│ │ ├── src/
|
|
│ │ │ ├── modules/
|
|
│ │ │ │ ├── auth/ # Authentication (JWT, OAuth, QR)
|
|
│ │ │ │ ├── storage/ # S3 Storage (MinIO)
|
|
│ │ │ │ ├── blog/ # Blog CMS
|
|
│ │ │ │ ├── ticket/ # Support tickets
|
|
│ │ │ │ ├── check/ # Payment checks
|
|
│ │ │ │ ├── notification/ # Push & Email
|
|
│ │ │ │ ├── tariff/ # Pricing plans
|
|
│ │ │ │ ├── session/ # Session management
|
|
│ │ │ │ └── admin/ # Admin panel
|
|
│ │ │ ├── middleware/ # Express middleware
|
|
│ │ │ ├── prisma/ # Prisma client
|
|
│ │ │ ├── routes/ # Route definitions
|
|
│ │ │ ├── utils/ # Utilities
|
|
│ │ │ ├── websocket/ # WebSocket server
|
|
│ │ │ ├── index.ts # Main entry point
|
|
│ │ │ └── server.ts # Express server
|
|
│ │ ├── prisma/
|
|
│ │ │ ├── schema.prisma # Database schema
|
|
│ │ │ ├── migrations/ # DB migrations
|
|
│ │ │ └── seed.ts # Seed data
|
|
│ │ ├── uploads/ # User uploads
|
|
│ │ ├── package.json
|
|
│ │ ├── tsconfig.json
|
|
│ │ └── ecosystem.config.js # PM2 config
|
|
│ │
|
|
│ └── frontend/
|
|
│ ├── src/
|
|
│ │ ├── pages/
|
|
│ │ │ ├── index.tsx # Homepage
|
|
│ │ │ ├── login.tsx # Login
|
|
│ │ │ ├── register.tsx # Registration
|
|
│ │ │ ├── pricing.tsx # Pricing plans
|
|
│ │ │ ├── blog.tsx # Blog list
|
|
│ │ │ ├── blogpost.tsx # Blog post
|
|
│ │ │ └── dashboard/
|
|
│ │ │ ├── mainpage.tsx # Dashboard main
|
|
│ │ │ ├── summary.tsx # Overview
|
|
│ │ │ ├── storage.tsx # Storage buckets
|
|
│ │ │ ├── storage-bucket.tsx # Bucket management
|
|
│ │ │ ├── tickets/ # Ticket system
|
|
│ │ │ ├── billing.tsx # Balance
|
|
│ │ │ ├── settings.tsx # Settings
|
|
│ │ │ ├── notifications.tsx # Notifications
|
|
│ │ │ ├── admin.tsx # Admin panel
|
|
│ │ │ ├── blogadmin.tsx # Blog admin
|
|
│ │ │ └── blogeditor.tsx # Post editor
|
|
│ │ ├── components/
|
|
│ │ │ ├── header.tsx # Site header
|
|
│ │ │ ├── footer.tsx # Site footer
|
|
│ │ │ └── PrivateRoute.tsx # Protected routes
|
|
│ │ ├── context/
|
|
│ │ │ ├── authcontext.tsx # Auth state
|
|
│ │ │ └── ThemeContext.tsx # Theme state
|
|
│ │ ├── services/
|
|
│ │ │ └── apiClient.ts # Axios client
|
|
│ │ ├── i18n/ # Localization
|
|
│ │ ├── App.tsx
|
|
│ │ └── main.tsx
|
|
│ ├── public/
|
|
│ │ ├── service-worker.js # Push notifications
|
|
│ │ └── robots.txt
|
|
│ ├── package.json
|
|
│ ├── vite.config.ts
|
|
│ └── tailwind.config.js
|
|
│
|
|
├── README.md # This file (English)
|
|
└── README_ru.md # Russian version
|
|
```
|
|
|
|
---
|
|
|
|
## 📚 API Documentation
|
|
|
|
### Public Endpoints
|
|
|
|
#### Authentication
|
|
```http
|
|
POST /api/auth/register
|
|
POST /api/auth/login
|
|
GET /api/auth/google
|
|
GET /api/auth/github
|
|
GET /api/auth/yandex
|
|
```
|
|
|
|
#### QR Authentication
|
|
```http
|
|
POST /api/qr-auth/generate # Generate QR code
|
|
GET /api/qr-auth/status/:code # Check status (polling)
|
|
POST /api/qr-auth/confirm # Confirm login (mobile)
|
|
```
|
|
|
|
#### Blog
|
|
```http
|
|
GET /api/blog/posts # List posts
|
|
GET /api/blog/posts/:url # Get post by URL
|
|
POST /api/blog/posts/:id/comments # Add comment
|
|
```
|
|
|
|
#### Storage Plans
|
|
```http
|
|
GET /api/storage/plans # List pricing plans
|
|
```
|
|
|
|
### Protected Endpoints
|
|
|
|
All requests require: `Authorization: Bearer <JWT_TOKEN>`
|
|
|
|
#### S3 Storage
|
|
```http
|
|
GET /api/storage/buckets # List buckets
|
|
POST /api/storage/buckets # Create bucket
|
|
GET /api/storage/buckets/:id # Get bucket info
|
|
DELETE /api/storage/buckets/:id # Delete bucket
|
|
PUT /api/storage/buckets/:id # Update settings
|
|
|
|
GET /api/storage/buckets/:id/objects # List objects
|
|
POST /api/storage/buckets/:id/upload # Upload file
|
|
POST /api/storage/buckets/:id/upload-from-uri # Upload from URL
|
|
POST /api/storage/buckets/:id/upload-directory # Upload folder
|
|
DELETE /api/storage/buckets/:id/objects # Delete objects
|
|
|
|
POST /api/storage/buckets/:id/presign # Generate presigned URL
|
|
POST /api/storage/buckets/:id/console-credentials # Get console access
|
|
```
|
|
|
|
#### Support Tickets
|
|
```http
|
|
GET /api/tickets # List user tickets
|
|
POST /api/tickets # Create ticket
|
|
GET /api/tickets/:id # Get ticket details
|
|
POST /api/tickets/:id/messages # Send message
|
|
PATCH /api/tickets/:id/status # Update status (operators)
|
|
POST /api/tickets/:id/assign # Assign operator
|
|
PATCH /api/tickets/:id/close # Close ticket
|
|
```
|
|
|
|
#### Session Management
|
|
```http
|
|
GET /api/sessions # List active sessions
|
|
GET /api/sessions/history # Login history
|
|
DELETE /api/sessions/:id # Terminate session
|
|
DELETE /api/sessions/others/all # Terminate all other sessions
|
|
```
|
|
|
|
#### Admin Endpoints
|
|
```http
|
|
GET /api/admin/users # List all users
|
|
PUT /api/admin/users/:id # Edit user
|
|
|
|
GET /api/admin/checks # List payment checks
|
|
PUT /api/admin/checks/:id # Approve/reject check
|
|
|
|
GET /api/blog/admin/posts # List all posts
|
|
POST /api/blog/admin/posts # Create post
|
|
PUT /api/blog/admin/posts/:id # Update post
|
|
DELETE /api/blog/admin/posts/:id # Delete post
|
|
POST /api/blog/admin/upload-image # Upload image
|
|
|
|
GET /api/blog/admin/comments # List all comments
|
|
PATCH /api/blog/admin/comments/:id # Moderate comment
|
|
DELETE /api/blog/admin/comments/:id # Delete comment
|
|
|
|
PUT /api/storage/plans/:id # Update pricing plan
|
|
|
|
POST /api/admin/test/push-notification # Test push
|
|
POST /api/admin/test/email-notification # Test email
|
|
```
|
|
|
|
---
|
|
|
|
## 🐛 Troubleshooting
|
|
|
|
### Backend Issues
|
|
|
|
**Prisma Client missing models**
|
|
```bash
|
|
cd backend
|
|
npx prisma generate
|
|
npm run build
|
|
pm2 restart all
|
|
```
|
|
|
|
**OAuth returns 404**
|
|
- Check `.env` for `GOOGLE_CLIENT_ID`, `GITHUB_CLIENT_ID`, `YANDEX_CLIENT_ID`
|
|
- Verify `oauthRoutes` is imported in `index.ts`
|
|
- Restart server
|
|
|
|
**Push notifications not working**
|
|
- Verify VAPID keys in `.env`
|
|
- Ensure `service-worker.js` is registered
|
|
- Use HTTPS in production
|
|
|
|
### Frontend Issues
|
|
|
|
**Session not persisting**
|
|
- Ensure `login()` in `authcontext.tsx` uses async/await
|
|
- Verify JWT token is saved to localStorage
|
|
- Check `bootstrapSession()` is called after login
|
|
|
|
**Dark theme not applying**
|
|
- Verify `ThemeProvider` wraps `App`
|
|
- Check `tailwind.config.js` has `darkMode: 'class'`
|
|
- Ensure components use `dark:` classes
|
|
|
|
**File upload fails**
|
|
- Check directory permissions: `chmod 755 uploads/*`
|
|
- Verify Nginx serves `/uploads`
|
|
- Check Nginx `client_max_body_size 50M;`
|
|
|
|
### S3 Storage Issues
|
|
|
|
**Cannot create bucket**
|
|
- Verify MinIO connection
|
|
- Check MinIO credentials in `.env`
|
|
- Ensure user has sufficient balance
|
|
|
|
**Console credentials don't work**
|
|
- Credentials are valid for 7 days
|
|
- Generate new credentials from dashboard
|
|
- Verify MinIO endpoint is accessible
|
|
|
|
---
|
|
|
|
## 🤝 Contributing
|
|
|
|
We welcome contributions! Please follow these steps:
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch: `git checkout -b feature/AmazingFeature`
|
|
3. Commit changes: `git commit -m 'feat: add amazing feature'`
|
|
4. Push to branch: `git push origin feature/AmazingFeature`
|
|
5. Open a Pull Request
|
|
|
|
### Commit Convention
|
|
|
|
We use [Conventional Commits](https://www.conventionalcommits.org/):
|
|
|
|
```bash
|
|
feat(storage): add folder upload support
|
|
fix(ticket): auto-unassign on close
|
|
docs: update API documentation
|
|
refactor(auth): improve error handling
|
|
```
|
|
|
|
### Development Workflow
|
|
|
|
```bash
|
|
# Backend development
|
|
cd backend
|
|
npm run dev
|
|
|
|
# Frontend development
|
|
cd frontend
|
|
npm run dev
|
|
|
|
# Database migrations
|
|
npx prisma migrate dev --name migration_name
|
|
npx prisma generate
|
|
|
|
# Build for production
|
|
npm run build
|
|
```
|
|
|
|
---
|
|
|
|
## 📄 License
|
|
|
|
MIT License
|
|
|
|
---
|
|
|
|
## 📞 Contact
|
|
|
|
- **Website:** [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
|
|
|
|
---
|
|
|
|
## 🙏 Acknowledgments
|
|
|
|
- [MinIO](https://min.io/) - S3-compatible object storage
|
|
- [Prisma](https://www.prisma.io/) - Next-generation ORM
|
|
- [React](https://react.dev/) - UI library
|
|
- [Tailwind CSS](https://tailwindcss.com/) - CSS framework
|
|
- [Quill](https://quilljs.com/) - Rich text editor
|
|
- [Passport.js](https://www.passportjs.org/) - Authentication middleware
|
|
|
|
---
|
|
|
|
**Version:** 8.1
|
|
**Updated:** January 5, 2026
|
|
**Git:** ospab <ospab@ospab.host>
|