194 lines
9.1 KiB
Markdown
194 lines
9.1 KiB
Markdown
# Drop me Files (analog)
|
||
|
||
Аналог сервиса [dropmefiles.com](https://dropmefiles.com) — веб-приложение для временного обмена файлами с прямой загрузкой в S3-совместимое хранилище.
|
||
|
||
Попробовать демо: [dropmefiles.viaproger.ru](https://dropmefiles.viaproger.ru/) (временно не работает 😞)
|
||
|
||
## 📋 Описание
|
||
|
||
Drop-me-files-analog позволяет пользователям:
|
||
- Загружать файлы через веб-интерфейс
|
||
- Получать короткие ссылки для скачивания (6-символьный UUID)
|
||
|
||
Файлы загружаются напрямую в S3-совместимое хранилище (MinIO) с использованием presigned URLs, что снижает нагрузку на backend-сервер. Файлы в S3 хранилище автоматически удаляются с течением времени, и доступ к ним исчезает.
|
||
|
||
## 🏗️ Архитектура
|
||
|
||
Проект построен на микросервисной архитектуре и состоит из нескольких компонентов:
|
||
|
||
**Frontend**: статическое веб-приложение (HTML, CSS, JS), предоставляющее интерфейс для загрузки и скачивания файлов. Взаимодействует с Backend через REST API.
|
||
|
||
**Backend (FastAPI)**: API-шлюз, который генерирует presigned URLs для прямого взаимодействия клиента с S3-хранилищем, управляет метаданными файлов, валидирует запросы и логирует операции.
|
||
|
||
**MinIO**: S3-совместимое хранилище для файлов. Доступ к файлам возможен только через presigned URLs с ограниченным временем жизни.
|
||
|
||
**Redis**: хранилище метаданных файлов. Записи автоматически удаляются по истечении TTL.
|
||
|
||
**Nginx**: служит веб-сервером для раздачи frontend и reverse proxy для backend.
|
||
|
||
|
||
|
||
Процесс работы:
|
||
|
||
1. **Загрузка**: **Frontend** запрашивает токен, передавая метаданные файла. **Backend** генерирует короткий UUID и presigned POST URL для **MinIO**, сохраняет метаданные в **Redis** с TTL и возвращает URL и UUID. Frontend загружает файл напрямую в **MinIO**.
|
||
|
||
2. **Скачивание**: По запросу с UUID **backend** проверяет **Redis**, генерирует presigned GET URL и возвращает его клиенту с метаданными. Файл скачивается напрямую из **MinIO**.
|
||
|
||
3. **Очистка**: По истечении TTL запись удаляется из **Redis**; Файл в **MinIO** удаляется по правилам конфигурации S3 хранилища (в данном проекте, TTL MinIO равен 1 суткам).
|
||
|
||
## 🛠️ Технологический стек
|
||
|
||
### Backend
|
||
- **Python 3.14**
|
||
- **FastAPI** — современный асинхронный веб-фреймворк
|
||
- **Uvicorn** — ASGI сервер
|
||
- **aiobotocore** — асинхронный клиент для S3-совместимых хранилищ
|
||
- **redis** — клиент Redis
|
||
- **Pydantic** — валидация данных
|
||
- **Loguru** — логирование
|
||
|
||
### Frontend
|
||
- **HTML**, **CSS**, **JavaScript** — базовый стек
|
||
|
||
### Инфраструктура
|
||
- **Docker** и **Docker Compose** — для быстрой развертки сервисов
|
||
- **MinIO** — S3-совместимое хранилище
|
||
- **Redis** — кэш и хранилище метаданных
|
||
- **Nginx** — веб-сервер
|
||
|
||
## 📦 Установка и запуск
|
||
|
||
### Предварительные требования
|
||
|
||
- **Docker** и **Docker Compose** — для запуска MinIO и Redis
|
||
- **Python 3.14** — для локальной разработки backend
|
||
- **UV** пакетный менеджер (рекомендуется)
|
||
|
||
### Установка
|
||
|
||
1. **Клонируйте репозиторий:**
|
||
```bash
|
||
git clone https://github.com/IgorVolochay/Drop-me-files-analog.git
|
||
cd Drop-me-files-analog
|
||
```
|
||
|
||
2. **Создайте файл `.env`** на основе примера:
|
||
```bash
|
||
cp app/.env-example app/.env
|
||
cp docker/.env-example docker/.env
|
||
```
|
||
Затем отредактируйте `.env` и укажите необходимые значения (см. раздел "Конфигурация").
|
||
|
||
3. **Запустите сервисы (MinIO и Redis) через Docker Compose:**
|
||
```bash
|
||
cd docker
|
||
docker-compose up -d
|
||
```
|
||
|
||
Это запустит:
|
||
- MinIO на указанных портах 9000 (API) и 9001 (Веб-интерфейс)
|
||
- Автоматическую инициализацию бакета MinIO и TTL
|
||
- Redis на порту 6380
|
||
|
||
|
||
4. **Установите зависимости и запустите backend:**
|
||
```bash
|
||
cd ../app
|
||
uv sync # или pip install ..
|
||
uv run main.py
|
||
```
|
||
|
||
Backend будет доступен на `http://localhost:8000` (или порт из `BACKEND_PORT` в `.env`).
|
||
|
||
5. **Запустите frontend:**
|
||
|
||
В режиме разработки используйте любой статический сервер:
|
||
|
||
```bash
|
||
cd frontend
|
||
python -m http.server 8080
|
||
# или
|
||
npx serve .
|
||
```
|
||
|
||
В production настройте Nginx для раздачи статических файлов из `frontend/` и проксирования API запросов на backend.
|
||
|
||
|
||
## ⚙️ Конфигурация
|
||
|
||
### Переменные окружения
|
||
|
||
В проекте есть пример файла конфигурации `app/.env-example`. Скопируйте его и создайте файл `.env` в корне проекта или в папке `app/` со следующими переменными:
|
||
|
||
```python
|
||
DISABLE_DOCS=false # Отключение базового FastAPI endpoint /docs
|
||
BACKEND_PORT=8000 # Сетевой порт FastAPI Backend
|
||
|
||
LOGS_PATH=./logs # Директория для хранения логов
|
||
|
||
FILES_TTL=86400 # Время хранения файла (указан 1 день)
|
||
MAX_FILES_SIZE=1073741824 # Максимальный размер файла в байтах (указан 1 GB)
|
||
|
||
# Переменные для подключения к S3 хранилищу
|
||
S3_ACCESS_KEY_ID=Some_username
|
||
S3_SECRET_ACCESS_KEY=Some_password
|
||
S3_ENDPOINT_URL=Some_url
|
||
BUCKET_NAME=drop-me-files
|
||
|
||
# Переменные для подключения к Redis
|
||
REDIS_ADDRESS=Some_url
|
||
REDIS_PORT=6379
|
||
REDIS_USERNAME=Some_username
|
||
REDIS_PASSWORD=Some_password
|
||
```
|
||
|
||
|
||
## 🔧 Разработка
|
||
|
||
### Структура проекта
|
||
|
||
```
|
||
Drop-me-files-analog/
|
||
├── app/ # Backend приложение
|
||
│ ├── main.py # Главный файл FastAPI приложения
|
||
│ ├── s3_worker.py # Обработчик S3/MinIO
|
||
│ ├── redis_worker.py # Обработчик Redis
|
||
│ ├── schemas/ # Pydantic схемы
|
||
│ │ └── api_schemas.py
|
||
│ └── pyproject.toml # Зависимости проекта
|
||
├── frontend/ # Frontend приложение
|
||
│ ├── index.html
|
||
│ ├── script.js
|
||
│ └── style.css
|
||
├── docker/
|
||
│ └── docker-compose.yml # Docker конфигурация для запуска MinIO и Redis
|
||
└── README.md # Этот файл
|
||
```
|
||
|
||
### Логирование
|
||
|
||
Логи сохраняются в файл: `{LOGS_PATH}/dmf-logs.log` (ротация при 1 MB, сжатие zip)
|
||
|
||
|
||
## 🤝 Вклад
|
||
|
||
Вклад в проект приветствуется! Пожалуйста:
|
||
|
||
1. Создайте fork проекта
|
||
2. Создайте ветку для новой функции (`git checkout -b feature/AmazingFeature`)
|
||
3. Зафиксируйте изменения (`git commit -m 'Add some AmazingFeature'`)
|
||
4. Отправьте в ветку (`git push origin feature/AmazingFeature`)
|
||
5. Откройте Pull Request
|
||
|
||
## 📞 Контакты
|
||
|
||
- **GitHub проекта:** [IgorVolochay/Drop-me-files-analog](https://github.com/IgorVolochay/Drop-me-files-analog)
|
||
- **Автор:** Игорь Волочай
|
||
|
||
Если нашли баг или уязвимость, пишите на почту (pseudo.developer.ru@gmail.com) или открывайте **Issues** на GitHub!
|
||
|
||
## 🙏 Благодарности
|
||
|
||
- Проект вдохновлён сервисом [dropmefiles.com](https://dropmefiles.com)
|
||
- Использует открытые технологии: [FastAPI](https://github.com/fastapi/fastapi), [MinIO](https://github.com/minio/minio), [Redis](https://github.com/redis/redis)
|