Files
mtusi2026lab4/README..md
T

222 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Лабораторная работа № 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`.