forked from mtusi2026/mtusi2026lab4
222 lines
11 KiB
Markdown
222 lines
11 KiB
Markdown
# Лабораторная работа № 4
|
||
## S3-хранилище и вложения
|
||
|
||
Выполнила: Гончаревская Екатерина Александровна
|
||
Группа: БВТ2304
|
||
Целевая оценка: 3
|
||
|
||
---
|
||
|
||
# 1. Цель работы
|
||
|
||
Разделить метаданные вложений и их бинарное содержимое, добавить возможность отправки изображений в сообщениях и обеспечить доступность вложений при переключении между API-репликами.
|
||
|
||
# 2. Постановка задачи
|
||
|
||
Необходимо реализовать S3-совместимое хранилище вложений в инфраструктуре мессенджера.
|
||
|
||
Основные требования:
|
||
|
||
- Метаданные вложений должны храниться в PostgreSQL.
|
||
- Бинарное содержимое файлов должно храниться в отдельном приватном S3-бакете.
|
||
- Загрузка вложения должна возвращать статус готовности только после успешного сохранения файла.
|
||
- Пользователь должен иметь возможность скачать исходный файл без изменения его содержимого.
|
||
- Вложения должны быть связаны с сообщениями через `attachment_ids`.
|
||
- Доступ к вложениям должен предоставляться только участникам соответствующего чата.
|
||
- API должно проверять тип и допустимый размер загружаемых изображений.
|
||
- Доступ к вложениям должен сохраняться при переключении между API-репликами.
|
||
- После перезапуска сервисов с сохранением томов загруженные файлы и метаданные должны оставаться доступными.
|
||
|
||
# 3. Используемые технологии
|
||
|
||
- Python — реализация API.
|
||
- PostgreSQL — хранение метаданных и связей вложений с сообщениями.
|
||
- RustFS — S3-совместимое хранилище бинарных файлов.
|
||
- Valkey — хранение сессий.
|
||
- HAProxy — распределение запросов между API-репликами.
|
||
- Docker и Docker Compose — контейнеризация и запуск инфраструктуры.
|
||
- boto3 — взаимодействие с S3.
|
||
- Pillow — проверка изображений.
|
||
- psycopg — работа с PostgreSQL.
|
||
|
||
# 4. Архитектура решения
|
||
|
||
Схема взаимодействия компонентов:
|
||
|
||
Клиент → HAProxy → API-реплики → PostgreSQL и RustFS.
|
||
|
||
В инфраструктуре используются две API-реплики, работающие с общей базой данных и общим S3-хранилищем.
|
||
|
||
PostgreSQL отвечает за хранение метаданных вложений и связей с сообщениями. Бинарное содержимое размещается в приватном бакете `messenger-attachments`.
|
||
|
||
RustFS предоставляет S3-совместимый интерфейс. API обращается к хранилищу по внутреннему адресу Docker-сети.
|
||
|
||
HAProxy распределяет входящие запросы между API-репликами. Благодаря общему хранилищу и общей базе данных пользователь может получить ранее загруженное вложение через другую API-реплику.
|
||
|
||
Для сохранения данных при перезапуске используются постоянные Docker volumes.
|
||
|
||
# 5. Реализация
|
||
|
||
## 5.1. Загрузка вложений
|
||
|
||
При получении запроса на загрузку API выполняет проверку входных данных и изображения.
|
||
|
||
Реализованы следующие ограничения:
|
||
|
||
- Максимальный размер файла — 10 МиБ.
|
||
- Максимальное количество пикселей — 40 миллионов.
|
||
- Поддерживаемые форматы — PNG и JPEG.
|
||
- MIME-тип проверяется по содержимому файла.
|
||
- Проверяется допустимость имени файла.
|
||
|
||
После проверки бинарное содержимое сохраняется в S3-хранилище. Метаданные регистрируются в PostgreSQL. Вложение получает статус готовности после успешного сохранения файла.
|
||
|
||
## 5.2. Получение вложений
|
||
|
||
При запросе на скачивание API проверяет наличие вложения и права доступа пользователя.
|
||
|
||
Доступ предоставляется только участникам чата, к которому относится вложение.
|
||
|
||
После получения объекта из S3 выполняется проверка целостности данных по контрольной сумме SHA-256.
|
||
|
||
## 5.3. Интеграция с сообщениями
|
||
|
||
Вложения связываются с сообщениями через идентификаторы `attachment_ids`.
|
||
|
||
Это позволяет получать сообщения вместе с информацией о прикреплённых файлах и сохранять связь между сообщениями и вложениями в PostgreSQL.
|
||
|
||
## 5.4. Отказоустойчивость и сохранение данных
|
||
|
||
Для обеспечения доступности вложений используются две API-реплики, общая база PostgreSQL и общее S3-хранилище.
|
||
|
||
При остановке одной API-реплики HAProxy продолжает направлять запросы на доступную реплику.
|
||
|
||
Постоянные тома обеспечивают сохранение данных PostgreSQL и RustFS после перезапуска контейнеров.
|
||
|
||
# 6. Запуск проекта
|
||
|
||
## 6.1. Требования
|
||
|
||
Для запуска необходимы:
|
||
|
||
- Docker Desktop с поддержкой Docker Compose;
|
||
- Python 3;
|
||
- Git;
|
||
- WSL с Linux для запуска сценариев отказоустойчивости в Windows.
|
||
|
||
## 6.2. Подготовка
|
||
|
||
Клонировать репозиторий:
|
||
|
||
```bash
|
||
git clone https://gitea.privcloud.tech/Katarhani/mtusi2026lab4.git
|
||
cd mtusi2026lab4
|
||
```
|
||
|
||
Создать локальные файлы секретов:
|
||
|
||
```bash
|
||
python scripts/init-secrets.py
|
||
```
|
||
|
||
Секреты создаются в каталоге `secrets/`. Их содержимое не должно публиковаться в репозитории.
|
||
|
||
Проверить конфигурацию Docker Compose:
|
||
|
||
```bash
|
||
docker compose config --quiet
|
||
```
|
||
|
||
## 6.3. Запуск инфраструктуры
|
||
|
||
Собрать образы и запустить сервисы:
|
||
|
||
```bash
|
||
docker compose up --build -d
|
||
```
|
||
|
||
Проверить состояние контейнеров:
|
||
|
||
```bash
|
||
docker compose ps
|
||
```
|
||
|
||
В работающей инфраструктуре должны присутствовать:
|
||
|
||
- две API-реплики;
|
||
- HAProxy;
|
||
- PostgreSQL;
|
||
- Valkey;
|
||
- RustFS.
|
||
|
||
## 6.4. Проверка готовности API
|
||
|
||
Проверить endpoint готовности:
|
||
|
||
```bash
|
||
curl http://localhost:8080/health/ready
|
||
```
|
||
|
||
Входящие запросы с компьютера направляются через HAProxy на локальный порт 8080.
|
||
|
||
# 7. Проверка работоспособности
|
||
|
||
## 7.1. Основной сценарий API
|
||
|
||
Запустить smoke-тест:
|
||
|
||
```bash
|
||
python tests/smoke.py --base-url http://localhost:8080
|
||
```
|
||
|
||
Тест проверяет основной публичный сценарий работы API.
|
||
|
||
## 7.2. Проверка сохранности данных
|
||
|
||
Запустить проверку persistence:
|
||
|
||
```bash
|
||
python tests/resilience.py --base-url http://localhost:8080 --mode persistence --action-script scripts/restart.sh
|
||
```
|
||
|
||
Сценарий проверяет сохранение подтверждённых данных и существующей сессии после перезапуска инфраструктуры.
|
||
|
||
## 7.3. Проверка отказоустойчивости
|
||
|
||
Запустить проверку failover:
|
||
|
||
```bash
|
||
python tests/resilience.py --base-url http://localhost:8080 --mode failover --action-script scripts/stop-one.sh
|
||
```
|
||
|
||
Сценарий проверяет продолжение обработки запросов при остановке одной API-реплики и доступность ранее сохранённых данных через оставшуюся реплику.
|
||
|
||
Для запуска сценариев persistence и failover в Windows используется WSL.
|
||
|
||
# 8. Остановка проекта
|
||
|
||
Для остановки контейнеров без удаления сохранённых данных:
|
||
|
||
```bash
|
||
docker compose down
|
||
```
|
||
|
||
Для полного удаления контейнеров и томов с данными:
|
||
|
||
```bash
|
||
docker compose down -v
|
||
```
|
||
|
||
**Внимание:** команда `docker compose down -v` удаляет постоянные тома, в том числе данные PostgreSQL и S3-хранилища. Использовать её следует только при необходимости полного сброса лабораторного стенда.
|
||
|
||
# 9. Результаты
|
||
|
||
В ходе выполнения лабораторной работы реализовано S3-совместимое хранение вложений, разделение метаданных и бинарного содержимого, интеграция вложений с сообщениями и работа с несколькими API-репликами.
|
||
|
||
Выполнены проверки:
|
||
|
||
- основной сценарий API — PASS;
|
||
- сохранение данных после перезапуска — PASS;
|
||
- отказоустойчивость при остановке API-реплики — PASS.
|
||
|
||
Подробные результаты проведённых проверок и сведения об экспериментах приведены в `REPORT.md`. |