Cloud File Storage

Многопользовательское облачное хранилище файлов, вдохновлённое Google Drive. Пользователи могут зарегистрироваться, авторизоваться и управлять своими файлами и папками: загружать, просматривать, скачивать, перемещать, переименовывать, удалять и искать их.

Проект выполнен в учебных целях в рамках курса Java Backend Learning Course.

Возможности

Пользователи

• Регистрация с созданием пользовательской сессии
• Авторизация и выход из аккаунта
• Получение данных текущего авторизованного пользователя
• Изоляция данных: пользователь имеет доступ только к собственным файлам

Файлы и папки

• Загрузка одного или нескольких файлов
• Загрузка папок вместе со вложенной структурой
• Создание пустых папок
• Просмотр информации о файле или папке
• Просмотр содержимого директории
• Скачивание файлов
• Скачивание папок в ZIP-архиве
• Перемещение и переименование файлов и папок
• Удаление ресурсов
• Поиск файлов и папок

Технологии

• Java 21
• Spring Boot
• Spring Web
• Spring Security
• Spring Session
• Spring Data JPA
• Maven
• PostgreSQL 16
• Redis 7
• MinIO — S3-совместимое файловое хранилище
• Flyway — миграции базы данных
• Docker и Docker Compose
• JUnit 5 и Testcontainers — интеграционные тесты
• Swagger / OpenAPI — документация API

Архитектура

Приложение состоит из следующих компонентов:

• Spring Boot-приложение реализует REST API, бизнес-логику и авторизацию пользователей
• PostgreSQL хранит данные пользователей и другие реляционные данные приложения
• Redis используется для хранения HTTP-сессий
• MinIO хранит пользовательские файлы в S3-совместимом объектном хранилище

Каждый пользователь работает только со своим набором ресурсов. Внутреннее устройство файлового хранилища не раскрывается через API.

API

Все API-эндпоинты доступны по префиксу /api.

Swagger UI доступен после запуска приложения по адресу: http://localhost:8081/swagger-ui/index.html.

Аутентификация

Метод	Эндпоинт	Описание
POST	/api/auth/sign-up	Регистрация пользователя
POST	/api/auth/sign-in	Авторизация пользователя
POST	/api/auth/sign-out	Завершение текущей сессии
GET	/api/user/me	Получение текущего пользователя

Ресурсы

Метод	Эндпоинт	Описание
GET	/api/resource?path={path}	Получение информации о файле или папке
DELETE	/api/resource?path={path}	Удаление файла или папки
GET	/api/resource/download?path={path}	Скачивание файла или папки
GET	/api/resource/move?from={from}&to={to}	Перемещение или переименование ресурса
GET	/api/resource/search?query={query}	Поиск файлов и папок
POST	/api/resource?path={path}	Загрузка файлов или папок
GET	/api/directory?path={path}	Получение содержимого папки
POST	/api/directory?path={path}	Создание пустой папки

Пути передаются в URL-encoded виде. Путь к папке должен оканчиваться на /, например: documents/photos/.

Формат ошибок

При ошибке API возвращает JSON с сообщением:

{
  "message": "Текст ошибки"
}

Запуск

Предварительные требования

Для запуска необходимы:

• JDK 21
• Maven Wrapper или установленный Maven
• Docker и Docker Compose

Сборка JAR-файла

Dockerfile копирует JAR-файл из директории target/, поэтому перед запуском контейнеров необходимо собрать приложение:

./mvnw clean package -DskipTests

После успешной сборки Maven создаст исполняемый JAR в директории target/.

Запуск через Docker Compose

Docker Compose запускает PostgreSQL, Redis, MinIO и само Spring Boot-приложение. Контейнер app собирается из Dockerfile и использует JAR-файл, подготовленный на предыдущем шаге.

docker compose up --build -d

Проверить состояние контейнеров:

docker compose ps

Просмотреть логи приложения:

docker compose logs -f app

Остановить сервисы:

docker compose down

Чтобы остановить сервисы и удалить данные PostgreSQL и MinIO из Docker volumes:

docker compose down -v

После запуска приложение доступно по адресу http://localhost:8081. Веб-консоль MinIO доступна по адресу http://localhost:9001.

Профили приложения

Приложение поддерживает три Spring-профиля:

Профиль	Назначение
dev	Локальная разработка
test	Запуск и выполнение тестов
prod	Запуск приложения в production-окружении

Активный профиль задаётся переменной окружения SPRING_PROFILES_ACTIVE в файле .env:

SPRING_PROFILES_ACTIVE=prod

Для запуска с другим профилем укажите нужное значение:

SPRING_PROFILES_ACTIVE=dev

При использовании профиля test запускаются только контейнеры PostgreSQL и Redis. Контейнер MinIO для тестового профиля не используется.

Тестирование

Для тестирования используются JUnit 5 и Testcontainers. Интеграционные тесты запускают необходимые зависимости в Docker-контейнерах и проверяют взаимодействие приложения с реальной инфраструктурой.

Запуск тестов:

./mvnw test

Структура проекта

.
├── src/
│   ├── main/
│   │   ├── java/                 # Исходный код приложения
│   │   └── resources/            # Конфигурация и миграции
│   └── test/                     # Модульные и интеграционные тесты
├── Dockerfile                    # Образ Spring Boot-приложения
├── docker-compose.yml            # Локальная инфраструктура и приложение
├── pom.xml                       # Maven-конфигурация
└── .env.example                  # Пример переменных окружения