Files

Untone b876564f4a 📚 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! 📖✨

2025-09-02 12:32:15 +03:00

6.6 KiB

Raw Blame History

🚀 Как работает Quoter

Quoter - это высокопроизводительный файловый сервис с автоматическим ресайзингом изображений, системой квот и многоуровневой защитой.

📋 Архитектура системы

1. 🔐 Аутентификация и безопасность

JWT валидация: Проверка токенов с валидацией формата, длины и подписи
Rate limiting: Ограничение запросов по IP с Redis-хранением
Request validation: Проверка размера, заголовков и подозрительных паттернов
Session management: Получение данных пользователя из Redis сессий

2. 📤 Процесс загрузки файлов

Клиент → [Auth] → [Quota Check] → [Upload] → [Thumbnail Generation] → [S3 Storage]

Этапы обработки:

Валидация токена: JWT проверка + извлечение user_id
Проверка квот: Текущая квота пользователя (лимит 12 ГБ)
Стриминг загрузка: Чтение файла по частям с проверкой лимитов
MIME детекция: Автоматическое определение типа файла
Генерация UUID: Уникальное имя файла
Загрузка в Storj: Основное хранилище
Асинхронная генерация миниатюр: Для изображений

3. 🖼️ Система миниатюр

Предопределенные размеры:

10px - микро-превью
40px - аватары
110px - маленькие превью
300px - средние изображения
600px - стандартные изображения
800px - большие изображения
1400px - максимальный размер

Lazy Generation:

Миниатюры создаются по первому запросу
Оригинал возвращается пока генерируется миниатюра
Асинхронная обработка в фоне
Кэширование в S3

4. 📂 Система файлов (Multi-Cloud)

┌─ Storj S3 (primary) ─┐    ┌─ AWS S3 (fallback) ─┐
│ • Новые файлы        │    │ • Legacy файлы       │
│ • Миниатюры          │    │ • Backup             │
│ • Основное хранилище │    │ • Migration source   │
└─────────────────────┘    └──────────────────────┘

Логика обслуживания:

Проверка в Storj (основное хранилище)
Fallback на AWS S3 (legacy файлы)
Автоматическая миграция AWS → Storj при запросе
Поддержка различных путей (production/image/, etc.)

5. 🔍 Обслуживание файлов (GET)

Request → [Security] → [Cache Check] → [File Lookup] → [Resize] → [Response]

Процесс:

Security проверки: Rate limits, подозрительные пути
ETag кэширование: HTTP 304 для неизмененных файлов
Path parsing: Извлечение имени файла и размера
File lookup: Поиск в базе путей или по паттерну
Resize logic: Выбор ближайшего размера или генерация
Cached response: Оптимизированные заголовки

6. 💾 Управление квотами

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. 🛡️ Система безопасности

Уровни защиты:

Network: Security headers, CORS, payload limits
Application: Rate limiting, request validation
Authentication: JWT validation, session management
Monitoring: Логирование атак, метрики

Rate Limits:

Общие запросы: 100/мин (блокировка 5 мин)
Загрузка файлов: 10/5мин (блокировка 10 мин)
Аутентификация: 20/15мин (блокировка 30 мин)

🔄 Поток данных

Загрузка файла

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

Получение файла

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 события

6.6 KiB Raw Blame History Unescape Escape