# Лабораторная работа № 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`.