📚 Complete documentation overhaul
### New Documentation: - **URL Format Guide**: Complete guide for image resizer URL patterns - **Hybrid Architecture**: Vercel Edge + Quoter integration strategy - **Updated How-it-works**: Comprehensive system architecture with diagrams - **Enhanced Configuration**: Security settings, troubleshooting, Vercel integration ### Documentation Structure: 📋 Architecture & Principles: - 🚀 How Quoter Works (detailed system architecture) - 🔀 Hybrid Architecture (Vercel + Quoter best practices) - 📐 URL Format (complete resizer URL guide) 🛡️ Security & Configuration: - 🔒 Security & DDoS Protection (comprehensive guide) - ⚙️ Configuration (updated with new settings) - 🚀 Deployment & 📊 Monitoring 🎨 Integrations: - Vercel OG Integration guides - Edge Function examples ### Key Features Documented: - Complete URL patterns for image resizing - Security rate limiting configuration - Hybrid upload (Quoter) + download (Vercel) strategy - JWT validation and session management - Multi-cloud storage (Storj + AWS fallback) - Performance optimization techniques - Production deployment strategies All documentation is now production-ready and includes practical examples! 📖✨
This commit is contained in:
@@ -1,22 +1,145 @@
|
||||
### Как это работает
|
||||
# 🚀 Как работает Quoter
|
||||
|
||||
1. **Аутентификация**:
|
||||
- Клиент отправляет файл на сервер с заголовком `Authorization`, содержащим токен. Сервер проверяет наличие и валидность токена через API ядра, определяя пользователя.
|
||||
Quoter - это высокопроизводительный файловый сервис с автоматическим ресайзингом изображений, системой квот и многоуровневой защитой.
|
||||
|
||||
2. **Загрузка файлов**:
|
||||
- Сервер обрабатывает все загружаемые файлы. Если файл является изображением, создается его миниатюра. И миниатюра, и оригинальное изображение загружаются в S3. Для остальных файлов выполняется простая загрузка в S3 без создания миниатюр.
|
||||
## 📋 Архитектура системы
|
||||
|
||||
3. **Создание миниатюр**:
|
||||
- Для всех загружаемых изображений сервер автоматически создает миниатюры различных размеров (10, 40, 110, 300, 600, 800, 1400 пикселей по ширине). Миниатюры сохраняются как отдельные файлы в том же S3 bucket, что и оригинальные изображения.
|
||||
### 1. 🔐 Аутентификация и безопасность
|
||||
- **JWT валидация**: Проверка токенов с валидацией формата, длины и подписи
|
||||
- **Rate limiting**: Ограничение запросов по IP с Redis-хранением
|
||||
- **Request validation**: Проверка размера, заголовков и подозрительных паттернов
|
||||
- **Session management**: Получение данных пользователя из Redis сессий
|
||||
|
||||
4. **Определение MIME-типа и расширения файла**:
|
||||
- MIME-тип и расширение файла определяются автоматически на основе имени файла и его содержимого с использованием библиотеки `mime_guess`.
|
||||
### 2. 📤 Процесс загрузки файлов
|
||||
```
|
||||
Клиент → [Auth] → [Quota Check] → [Upload] → [Thumbnail Generation] → [S3 Storage]
|
||||
```
|
||||
|
||||
5. **Загрузка файлов в S3**:
|
||||
- Все файлы, включая миниатюры и оригиналы изображений, загружаются в указанный S3 bucket. Сформированные URL-адреса файлов возвращаются клиенту.
|
||||
**Этапы обработки:**
|
||||
1. **Валидация токена**: JWT проверка + извлечение user_id
|
||||
2. **Проверка квот**: Текущая квота пользователя (лимит 12 ГБ)
|
||||
3. **Стриминг загрузка**: Чтение файла по частям с проверкой лимитов
|
||||
4. **MIME детекция**: Автоматическое определение типа файла
|
||||
5. **Генерация UUID**: Уникальное имя файла
|
||||
6. **Загрузка в Storj**: Основное хранилище
|
||||
7. **Асинхронная генерация миниатюр**: Для изображений
|
||||
|
||||
6. **Управление квотами**:
|
||||
- Для каждого пользователя устанавливается общая квота на загрузку данных, которая составляет 5 ГБ. Перед загрузкой каждого нового файла проверяется, не превысит ли его размер текущую квоту пользователя. Если квота будет превышена, загрузка файла будет отклонена. После успешной загрузки файл и его размер регистрируются в Redis, и квота пользователя обновляется.
|
||||
### 3. 🖼️ Система миниатюр
|
||||
**Предопределенные размеры:**
|
||||
- `10px` - микро-превью
|
||||
- `40px` - аватары
|
||||
- `110px` - маленькие превью
|
||||
- `300px` - средние изображения
|
||||
- `600px` - стандартные изображения
|
||||
- `800px` - большие изображения
|
||||
- `1400px` - максимальный размер
|
||||
|
||||
7. **Сохранение информации о загруженных файлах в Redis**:
|
||||
- Имя каждого загруженного файла сохраняется в Redis для отслеживания загруженных пользователем файлов. Это позволяет учитывать квоты и управлять пространством, занимаемым файлами.
|
||||
**Lazy Generation:**
|
||||
- Миниатюры создаются по первому запросу
|
||||
- Оригинал возвращается пока генерируется миниатюра
|
||||
- Асинхронная обработка в фоне
|
||||
- Кэширование в S3
|
||||
|
||||
### 4. 📂 Система файлов (Multi-Cloud)
|
||||
```
|
||||
┌─ Storj S3 (primary) ─┐ ┌─ AWS S3 (fallback) ─┐
|
||||
│ • Новые файлы │ │ • Legacy файлы │
|
||||
│ • Миниатюры │ │ • Backup │
|
||||
│ • Основное хранилище │ │ • Migration source │
|
||||
└─────────────────────┘ └──────────────────────┘
|
||||
```
|
||||
|
||||
**Логика обслуживания:**
|
||||
1. Проверка в Storj (основное хранилище)
|
||||
2. Fallback на AWS S3 (legacy файлы)
|
||||
3. Автоматическая миграция AWS → Storj при запросе
|
||||
4. Поддержка различных путей (`production/image/`, etc.)
|
||||
|
||||
### 5. 🔍 Обслуживание файлов (GET)
|
||||
```
|
||||
Request → [Security] → [Cache Check] → [File Lookup] → [Resize] → [Response]
|
||||
```
|
||||
|
||||
**Процесс:**
|
||||
1. **Security проверки**: Rate limits, подозрительные пути
|
||||
2. **ETag кэширование**: HTTP 304 для неизмененных файлов
|
||||
3. **Path parsing**: Извлечение имени файла и размера
|
||||
4. **File lookup**: Поиск в базе путей или по паттерну
|
||||
5. **Resize logic**: Выбор ближайшего размера или генерация
|
||||
6. **Cached response**: Оптимизированные заголовки
|
||||
|
||||
### 6. 💾 Управление квотами
|
||||
**Redis структуры:**
|
||||
```redis
|
||||
quota:user:{user_id} # Текущая квота (bytes)
|
||||
files:user:{user_id} # Список файлов пользователя
|
||||
file_info:{filename} # MIME-type и метаданные
|
||||
rate_limit:{type}:{ip} # Счетчики rate limiting
|
||||
```
|
||||
|
||||
**Проверки:**
|
||||
- Превентивная проверка перед загрузкой
|
||||
- Streaming проверка по частям
|
||||
- Atomic обновление после успешной загрузки
|
||||
- Лимит: 12 ГБ на пользователя
|
||||
|
||||
### 7. 🛡️ Система безопасности
|
||||
**Уровни защиты:**
|
||||
1. **Network**: Security headers, CORS, payload limits
|
||||
2. **Application**: Rate limiting, request validation
|
||||
3. **Authentication**: JWT validation, session management
|
||||
4. **Monitoring**: Логирование атак, метрики
|
||||
|
||||
**Rate Limits:**
|
||||
- Общие запросы: 100/мин (блокировка 5 мин)
|
||||
- Загрузка файлов: 10/5мин (блокировка 10 мин)
|
||||
- Аутентификация: 20/15мин (блокировка 30 мин)
|
||||
|
||||
## 🔄 Поток данных
|
||||
|
||||
### Загрузка файла
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
Client->>+Quoter: POST / (multipart)
|
||||
Quoter->>+Redis: Validate session
|
||||
Redis-->>-Quoter: User data
|
||||
Quoter->>+Redis: Check quota
|
||||
Redis-->>-Quoter: Current usage
|
||||
Quoter->>+Storj: Upload file
|
||||
Storj-->>-Quoter: Success
|
||||
Quoter->>+Background: Generate thumbnails
|
||||
Quoter->>+Redis: Update quota
|
||||
Quoter-->>-Client: File URL
|
||||
```
|
||||
|
||||
### Получение файла
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
Client->>+Quoter: GET /file_300.jpg
|
||||
Quoter->>+Cache: Check ETag
|
||||
Cache-->>-Quoter: 304 or miss
|
||||
Quoter->>+Storj: Get thumbnail
|
||||
alt Thumbnail exists
|
||||
Storj-->>Quoter: File data
|
||||
else Thumbnail missing
|
||||
Storj-->>Quoter: Original file
|
||||
Quoter->>Background: Generate thumbnail
|
||||
end
|
||||
Quoter-->>-Client: Image + headers
|
||||
```
|
||||
|
||||
## 📊 Производительность
|
||||
|
||||
### Оптимизации
|
||||
- **HTTP кэширование**: ETag, immutable cache headers
|
||||
- **Lazy thumbnail generation**: Генерация по требованию
|
||||
- **Асинхронная обработка**: Неблокирующие операции
|
||||
- **Local + Redis cache**: Многоуровневое кэширование
|
||||
- **Streaming uploads**: Обработка больших файлов по частям
|
||||
|
||||
### Мониторинг
|
||||
- Время обработки запросов
|
||||
- Статистика генерации миниатюр
|
||||
- Метрики rate limiting
|
||||
- Использование квот по пользователям
|
||||
- Ошибки и security события
|
||||
Reference in New Issue
Block a user