# Отчёт — лабораторная работа №4 - **Автор, группа:** Перевалова Виктория, БПИ2302. - **Целевая оценка:** 5. - **Выбранный трек:** Track 1 — Presigned Upload (прямая загрузка в S3). - **Основная гипотеза:** прямая загрузка файлов в S3-compatible хранилище по временной подписанной ссылке позволяет уменьшить объём данных, проходящих через API, и сократить время обработки больших файлов на стороне API. - **Commit/PR:** будет указан после итогового commit и публикации изменений в Gitea. - **Использованные источники, библиотеки и помощь ИИ:** исходный репозиторий лабораторной работы и материалы преподавателя; Python 3, FastAPI, SQLAlchemy, Alembic, PostgreSQL, Redis, boto3, Pillow, Docker Compose, S3-compatible object storage. ChatGPT использовался для анализа требований, проектирования отдельных компонентов, подготовки тестов, диагностики ошибок и оформления отчёта. Реализация и результаты проверялись запуском приложения и тестовых сценариев. --- ## Запуск из чистого clone ### 1. Требования к окружению Для запуска проекта необходимы: - Git; - Docker Desktop с поддержкой Docker Compose; - Python 3.13 для локального запуска вспомогательных тестовых скриптов; - PowerShell (для Windows) или совместимая командная оболочка; - доступ к Gitea и возможность клонировать репозиторий. Основные сервисы запускаются в Docker Compose: | Компонент | Используемая версия | |---|---| | PostgreSQL | 16.6-bookworm | | Redis | 7.4.2-bookworm | | S3-compatible storage (Silo) | RELEASE.2026-10-26T00-00-00Z | | Traefik | 3.6.2 | | API | Docker image проекта | ### 2. Клонирование проекта ```powershell git clone https://gitea.privcloud.tech/perevalova/mtusi2026lab4.git cd mtusi2026lab4 ``` Для перехода на ветку с реализацией: ```powershell git checkout solution/lab4-implementation ``` ### 3. Подготовка конфигурации Создать локальный файл `.env` на основе предоставленного примера: ```powershell Copy-Item .env.compose.example .env ``` Перед запуском необходимо проверить соответствие переменных конфигурации требованиям `compose.yaml`. Для работы инфраструктуры необходимо задать следующие переменные: - `POSTGRES_PASSWORD` — пароль PostgreSQL; - `MINIO_ROOT_USER` — административный пользователь S3-хранилища; - `MINIO_ROOT_PASSWORD` — административный пароль S3-хранилища; - `S3_ACCESS_KEY_ID` — отдельный пользователь приложения для доступа к S3; - `S3_SECRET_ACCESS_KEY` — секретный ключ пользователя приложения; - `S3_REGION` — регион S3; - `S3_BUCKET` — имя bucket. Дополнительные параметры ограничений загрузки и фоновой очистки имеют значения по умолчанию в Compose: - `MAX_UPLOAD_BYTES` — 10 MiB; - `MAX_IMAGE_PIXELS` — 40 000 000; - `ATTACHMENT_CLEANUP_INTERVAL_SECONDS` — 60 секунд; - `ATTACHMENT_CLEANUP_GRACE_SECONDS` — 600 секунд; - `ATTACHMENT_CLEANUP_BATCH_SIZE` — 100 записей. Секреты должны храниться только в локальном `.env`. Файл не должен попадать в Git. Файл `.env.compose.example` содержит имена переменных, используемые непосредственно в `compose.yaml`. После копирования необходимо заменить все демонстрационные значения `CHANGE_ME` локальными секретами. Сам `.env` не добавляется в Git. ### 4. Проверка конфигурации и сборка ```powershell docker compose config --quiet docker compose build ``` ### 5. Запуск инфраструктуры и приложения ```powershell docker compose up -d --build --scale api=2 ``` В проекте предусмотрены следующие компоненты: - PostgreSQL; - Redis; - S3-compatible storage; - сервис первоначальной настройки S3; - Alembic migrations; - две реплики API; - Traefik. Миграции выполняются отдельным сервисом `migrate` перед запуском API. ### 6. Ожидание готовности Проверить состояние контейнеров: ```powershell docker compose ps ``` Проверить readiness API: ```powershell Invoke-RestMethod http://localhost:8080/health/ready ``` Ожидаемый результат: ```json { "status": "ok" } ``` ### 7. Проверка приложения Проверка структуры и контракта: ```powershell python -X utf8 scripts/check_contract.py python -X utf8 scripts/validate_openapi.py ``` Для полной валидации OpenAPI установите dev-зависимости: `python -m pip install -r requirements-dev.txt`. Затем выполните `python -X utf8 scripts/validate_openapi.py`. Проверка синтаксиса: ```powershell python -X utf8 -m compileall -q app migrations ``` Публичный smoke-тест: ```powershell python -X utf8 tests/smoke.py --base-url http://localhost:8080 ``` Дополнительные проверки: ```powershell python -X utf8 scripts/test_presigned_upload.py python -X utf8 scripts/test_presigned_negative.py ``` В Dockerfile вспомогательные каталоги `scripts/`, `tests/`, `contracts/` и файл `lab.json` должны копироваться в образ API. После пересборки тест очистки незавершённых загрузок выполняется внутри API-контейнера: ```powershell docker compose exec -T api python /app/scripts/test_attachment_cleanup.py ``` Тест компенсационного удаления при отказе PostgreSQL выполняется внутри API-контейнера: ```powershell docker compose exec -T api python /app/scripts/test_s3_db_compensation.py ``` ### 8. Остановка проекта Безопасная остановка контейнеров с сохранением данных: ```powershell docker compose down ``` Повторный запуск: ```powershell docker compose up -d --build --scale api=2 ``` **Внимание:** намеренное удаление учебных данных выполняется отдельно: ```powershell docker compose down -v ``` Эта команда удаляет Docker volumes, включая данные PostgreSQL, Redis и S3-хранилища. Использовать её следует только при осознанном сбросе учебного окружения. --- ## Архитектура и решения ### 1. Общая архитектура Система состоит из нескольких взаимодействующих компонентов. ```text Клиент | v Traefik | ---------------- | | v v API-1 API-2 | | --------------------------- | | | v v v PostgreSQL Redis S3 Storage (метаданные) (кэш) (файлы) ``` Дополнительно используются: - Alembic для управления миграциями; - отдельный bootstrap-сервис для первоначальной настройки S3; - фоновая задача очистки незавершённых загрузок, работающая в API-репликах. **Примечание о выборе S3-сервера.** В Compose закреплён образ `pgsty/silo:RELEASE.2026-10-26T00-00-00Z`, совместимый с S3 API. В формулировке задания прямо перечислены MinIO, SeaweedFS и RustFS; Silo в этом перечне не назван. Замена сервера не выполнялась, поскольку текущий стенд и доказательства собраны на Silo. Это потенциальное формальное отклонение, которое следует согласовать с преподавателем. ### 2. Назначение компонентов **API (FastAPI)** Обрабатывает запросы пользователей, проверяет авторизацию и членство в чатах, выполняет загрузку и скачивание вложений, проверяет метаданные и взаимодействует с хранилищами. **PostgreSQL** Является источником истины для метаданных вложений и незавершённых загрузок. В базе хранятся: - идентификатор вложения; - идентификатор чата; - идентификатор владельца; - имя файла; - MIME-тип; - размер; - SHA-256; - ключ объекта в S3; - статус обработки; - даты создания и изменения. Для presigned-загрузок дополнительно сохраняются ожидаемые размер и контрольная сумма, срок действия и состояние загрузочной сессии. **Redis** Используется для кэширования истории сообщений и связанных с ней операций. Не является источником истины для вложений. **S3-compatible storage** Хранит бинарное содержимое файлов. Bucket `messenger-attachments` настроен как приватный. API обращается к S3 по внутреннему адресу Docker-сети. Клиент использует публичный адрес S3 для прямой загрузки по подписанной ссылке. **Traefik** Распределяет запросы между двумя экземплярами API. ### 3. Источник истины и транзакционные границы PostgreSQL хранит сведения о вложениях, а S3 — бинарные данные. Между PostgreSQL и S3 нет общей атомарной транзакции. Поэтому согласованность обеспечивается последовательностью операций и компенсационными действиями. Для Proxy Upload: 1. API принимает и проверяет файл. 2. Загружает содержимое в S3. 3. Создаёт запись метаданных в PostgreSQL. 4. Если сохранение метаданных завершается ошибкой, API выполняет rollback и пытается удалить объект из S3. Для Presigned Upload: 1. API проверяет пользователя и членство в чате. 2. Создаёт уникальный ключ объекта и запись `pending` в PostgreSQL. 3. Возвращает временную подписанную ссылку. 4. Клиент загружает файл непосредственно в S3. 5. Клиент вызывает endpoint завершения загрузки. 6. API получает объект из S3, проверяет размер, SHA-256 и содержимое изображения. 7. После успешной проверки создаёт запись вложения и переводит загрузку в состояние `completed`. При ошибках проверки загрузка переводится в `failed`, а объект удаляется из S3 при успешном выполнении компенсационного действия. Для незавершённых загрузок используется фоновая очистка с периодической проверкой просроченных записей. Для конкурентной работы нескольких API-реплик применяется блокировка PostgreSQL `FOR UPDATE SKIP LOCKED`. ### 4. Ограничения загрузки и безопасность Поддерживаются PNG и JPEG. Ограничения: - максимальный размер файла — 10 MiB; - максимальное количество пикселей — 40 000 000; - проверяется фактический формат содержимого; - проверяется соответствие MIME-типа; - проверяется SHA-256; - используется безопасное имя файла; - тело запроса читается потоково; - для больших файлов применяется временный файл вместо неограниченного хранения в RAM; - скачивание доступно только авторизованным участникам соответствующего чата. S3 bucket закрыт для анонимного доступа. Для приложения создан отдельный S3-пользователь с отдельной политикой доступа. Административная консоль S3 не опубликована на хостовой машине. --- ## Доказательства критериев В таблице приведены выполненные сценарии и фактические результаты. | Критерий | Команда / сценарий | Наблюдаемый результат | Файл доказательства | |---|---|---|---| | Проверка структуры проекта | `python -X utf8 scripts/check_contract.py` | PASS: структура, локальные ссылки и синтаксис | `evidence/check-contract.txt` (если сохранён; иначе вывод команды) | | Валидация OpenAPI | `python -X utf8 scripts/validate_openapi.py` | PASS: OpenAPI 3.1 и JSON Schema | Вывод команды | | Публичный smoke | `python -X utf8 tests/smoke.py --base-url http://localhost:8080` | PASS: публичный API-сценарий; повторно подтверждён после исправления маршрутизации Traefik | `evidence/smoke.txt` | | Готовность API | `Invoke-RestMethod http://localhost:8080/health/ready` | `status: ok` | Вывод команды | | Две API-реплики | `docker compose ps` | Обе реплики имеют статус healthy | `evidence/persistence-before.txt`, `evidence/failover-before.txt` | | Хранение бинарных данных в S3 | Proxy Upload и проверка скачивания | Файл сохраняется и возвращается с совпадающим SHA-256 | `evidence/track1-results.csv` | | Метаданные в PostgreSQL | Загрузка и получение вложения | Сохраняются владелец, чат, размер, MIME, SHA-256 и статус | `evidence/track1-results.csv` | | Ограничение размера | Загрузка файла больше 10 MiB | HTTP 413 | `evidence/negative-tests-results.txt` | | Повреждённое изображение | Загрузка некорректных байтов | HTTP 415 | `evidence/negative-tests-results.txt` | | Несовпадение MIME | PNG с `image/jpeg` | HTTP 415 | `evidence/negative-tests-results.txt` | | Проверка SHA-256 | Неверная ожидаемая контрольная сумма | HTTP 409 | `evidence/negative-tests-results.txt` | | Проверка размера | Неверный ожидаемый размер | HTTP 409 | `evidence/negative-tests-results.txt` | | Защита от чужой загрузки | Чужой пользователь вызывает complete | HTTP 404 | `evidence/negative-tests-results.txt` | | Защита метаданных | Неучастник чата запрашивает вложение | HTTP 404 | `evidence/negative-tests-results.txt` | | Защита скачивания | Неучастник чата скачивает вложение | HTTP 404 | `evidence/negative-tests-results.txt` | | Запрет межчатового прикрепления | Вложение из одного чата отправляется в другой | HTTP 404 | `evidence/negative-tests-results.txt` | | Идемпотентность завершения | Повторное завершение загрузки | Возвращается существующее вложение | Вывод `scripts/test_presigned_upload.py` | | Прямой Presigned Upload | Создание ссылки, PUT в S3, complete | Последний повторный запуск: PASS; загрузка завершена, SHA-256 совпадает | Вывод `scripts/test_presigned_upload.py` | | Очистка незавершённых загрузок | Ожидание фонового cleanup | Статус `expired`, объект удалён из S3 | `evidence/attachment-cleanup-results.txt` | | Компенсация Proxy Upload | Искусственная ошибка PostgreSQL после S3 PUT | HTTP 503, объект удалён из S3 | `evidence/s3-db-compensation-results.txt` | | Приватность bucket | `curl.exe -i http://localhost:9000/messenger-attachments/` без авторизации | HTTP 403 Forbidden (`AccessDenied`) | `evidence/s3-security-results.txt` | | Недоступность S3 Console | `docker compose port minio 9001` | Порт 9001 не опубликован на хост | `evidence/s3-security-results.txt` | | Сохранность данных | Перезапуск PostgreSQL, Redis, S3 и API без удаления volumes | Подтверждённые данные и существующая сессия сохранены | `evidence/persistence-results.txt` | | Отказоустойчивость API | Остановка одной API-реплики | 108 успешных записей, 1 неуспешная попытка, первое восстановление за 2,607 с (общий сценарий сообщений) | `evidence/failover-results.txt` | | Отказоустойчивость вложений | Остановка именно API-реплики, обслужившей Proxy Upload; скачивание через оставшуюся реплику | 2 реплики до отказа; 87 успешных записей, 4 неуспешные попытки; первое восстановление за 4,597 с; вложение скачано побайтно идентичным | `evidence/attachment-failover-results.txt` | | Недоступность S3 | Остановка S3-сервиса | Readiness сообщил `Required storage unavailable`; после запуска S3 обе API-реплики восстановили readiness | `evidence/s3-unavailable-results.txt` | | Эксперимент Track 1 | Сравнение Proxy и Presigned | Измерены полное время, время API и размер тела запросов | `evidence/track1-results.csv` | | Параллельная загрузка | 10 одновременных Proxy и 10 Presigned загрузок | 10/10 успешных в обоих режимах | `evidence/concurrent-upload-results.txt`, `evidence/concurrent-upload-results.csv` | ### Подтверждение инфраструктурных hook Для проверки сохранности данных использовался сценарий перезапуска: ```sh docker compose restart postgres redis minio api ``` Таким образом, перезапускались: - PostgreSQL; - Redis; - S3-compatible storage; - API. Docker volumes при этом не удалялись. Для общего сценария отказоустойчивости API останавливался один из двух экземпляров API. Наблюдаемый результат: 108 успешных записей, 1 неуспешная попытка и первое восстановление за 2,607 секунды (`evidence/failover-results.txt`). Отдельно проверялся отказ именно той API-реплики, которая обслужила загрузку вложения. Тест получил идентификатор обслужившей реплики из ответа API, остановил именно её, продолжил работу через оставшуюся реплику и скачал вложение. Результат: 87 успешных записей, 4 неуспешные попытки, первое восстановление за 4,597 секунды; содержимое вложения совпало побайтно (`evidence/attachment-failover-results.txt`). --- ## Эксперименты и отказы ### Исследовательский трек 1 — Presigned Upload #### Гипотеза Прямая загрузка файлов из клиента в S3-compatible хранилище по временной подписанной ссылке позволяет существенно сократить объём данных, передаваемых через API. Предполагается, что это уменьшит объём передаваемых через API данных и время обработки запроса на стороне API при работе с крупными вложениями. #### Методика эксперимента Сравнивались два способа загрузки: 1. **Proxy Upload** — клиент передаёт бинарное содержимое файла API, после чего API сохраняет его в S3. 2. **Presigned Upload** — API выдаёт временную подписанную ссылку, клиент загружает файл непосредственно в S3, затем вызывает endpoint завершения загрузки. Использовались два PNG-файла: - `sample.png` — 111 817 байт (0,11 MiB); - `sample_large.png` — 5 769 330 байт (5,50 MiB). Для каждого сочетания способа загрузки и размера файла выполнено по три повтора. Всего проведено 12 измерений. Среда эксперимента: Docker Compose, два экземпляра API, PostgreSQL 16.6, Redis 7.4.2, Silo S3-compatible storage. API-контейнеры имели ограничение памяти 512 MiB. #### Результаты | Способ загрузки | Размер файла | Среднее полное время | Среднее время запросов к API | Тело запросов к API | |---|---:|---:|---:|---:| | Proxy | 111 817 Б | 0,0786 с | 0,0785 с | 111 817 Б | | Presigned | 111 817 Б | 0,1296 с | 0,0826 с | 158 Б | | Proxy | 5 769 330 Б | 0,2666 с | 0,2665 с | 5 769 330 Б | | Presigned | 5 769 330 Б | 0,2564 с | 0,1275 с | 159 Б | При загрузке большого файла объём тела запросов клиента к API сократился примерно на 99,997%. При загрузке небольшого файла сокращение составило около 99,86%. Полное время загрузки большого файла при Presigned Upload оказалось примерно на 3,8% меньше, чем при Proxy Upload. Суммарное время запросов к API сократилось примерно на 52,2%. #### Параллельная загрузка Дополнительно проведён эксперимент с десятью одновременными загрузками файла размером 5 769 330 байт. Для каждого способа загрузки выполнялось по десять параллельных операций. | Показатель | Proxy | Presigned | |---|---:|---:| | Количество загрузок | 10 | 10 | | Успешные загрузки | 10 | 10 | | Ошибки | 0 | 0 | | Общее время | 3,996 с | 4,941 с | | Пиковая суммарная RAM API | 220,2 MiB | 304,4 MiB | | Прирост RAM относительно базового уровня | 16,1 MiB | 84,2 MiB | Параллельный эксперимент подтвердил, что оба способа справляются с десятью одновременными загрузками без ошибок. При этом в данном запуске Presigned Upload показал более высокий пик памяти. Поэтому утверждать, что прямая загрузка снижает потребление RAM, нельзя. #### Потребление памяти в последовательном эксперименте В ходе последовательного эксперимента фиксировалась память API-контейнеров с помощью `docker stats`. Измерения выполнялись с интервалом около 100 мс. Зафиксированные максимальные значения среди API-реплик: - Proxy, маленький файл — 103,4 MiB; - Presigned, маленький файл — 112,7 MiB; - Proxy, большой файл — 109,2 MiB; - Presigned, большой файл — 128,9 MiB. Результаты не подтверждают снижение RAM при Presigned Upload в текущем эксперименте. Измерения ограничены интервалом опроса Docker Stats и не позволяют исключить кратковременные пики между замерами. #### Вывод Гипотеза о сокращении объёма данных, передаваемых через API, подтверждена. Presigned Upload позволяет передавать содержимое файла непосредственно в S3, оставляя API операции выдачи временной ссылки, проверки загрузки и сохранения метаданных. Уменьшение времени обработки запросов API для большого файла также наблюдалось. Однако снижение общего времени загрузки небольших файлов не подтверждено, а снижение потребления RAM требует дополнительного исследования. **Файлы с исходными измерениями:** - `evidence/track1-results.csv`; - `evidence/concurrent-upload-results.csv`; - `evidence/concurrent-upload-results.txt`. ### Проверка отказов и восстановления | Воздействие | Что ожидалось | Что наблюдалось | Время восстановления / потеря данных | |---|---|---|---| | Перезапуск PostgreSQL, Redis, S3 и API | Сохранение подтверждённых данных при сохранении volumes | Подтверждённые сообщения, вложения и существующая сессия сохранились | Данные не потеряны | | Остановка одной API-реплики (общий сценарий) | Продолжение работы через оставшуюся реплику | 108 успешных записей, 1 неуспешная попытка | Первое восстановление — 2,607 с | | Остановка реплики, обслужившей загрузку вложения | Доступность вложения через другую реплику | 87 успешных записей, 4 неуспешные попытки; вложение скачано побайтно идентичным | Первое восстановление — 4,597 с | | Незавершённая Presigned Upload | Удаление просроченного объекта и обновление статуса | Запись получила статус `expired`, объект удалён | Ожидание фоновой очистки | | Недоступность S3 | Остановка S3-сервиса | Readiness сообщил `Required storage unavailable`; после восстановления S3 readiness снова `ok` | Сервис восстановлен без пересоздания API | | Ошибка PostgreSQL после загрузки в S3 через Proxy | Компенсационное удаление объекта | HTTP 503, объект отсутствует в S3 | Объект удалён | | Ошибка проверки SHA-256 | Отклонение загрузки и удаление некорректного объекта | HTTP 409 | Ошибка обработана | | Несовпадение размера файла | Отклонение загрузки | HTTP 409 | Ошибка обработана | | Повреждённое изображение | Отклонение содержимого | HTTP 415 | Ошибка обработана | | Превышение лимита размера | Отклонение загрузки до неограниченного чтения | HTTP 413 | Ошибка обработана | | Несовпадение MIME-типа | Отклонение файла | HTTP 415 | Ошибка обработана | | Чужой пользователь завершает загрузку | Запрет доступа | HTTP 404 | Доступ запрещён | | Попытка прикрепить вложение из другого чата | Запрет межчатового доступа | HTTP 404 | Доступ запрещён | ### Известные ограничения 1. PostgreSQL и S3 не используют общую распределённую транзакцию. Согласованность обеспечивается компенсационными операциями и фоновой очисткой. 2. Удаление объекта из S3 является best-effort операцией. При одновременном отказе хранилища и компенсационного удаления может потребоваться повторная проверка состояния. 3. Фоновая очистка работает с зарегистрированными незавершёнными загрузками. Объекты, для которых вообще не была создана запись загрузки, требуют отдельного механизма сверки или политики жизненного цикла S3. 4. Эксперимент по памяти проводился с периодическим опросом Docker Stats. В параллельном запуске мониторинг успел получить лишь 4–5 измерений, поэтому кратковременные пики могли быть пропущены. 5. Эксперименты проведены в локальной Docker-среде, а не в распределённой производственной инфраструктуре. Результаты нельзя автоматически переносить на промышленную нагрузку. 6. Для прямой загрузки необходима доступность S3 endpoint со стороны клиента. В локальном окружении используется опубликованный адрес S3 API. 7. Фактическое снижение потребления RAM при Presigned Upload экспериментально не подтверждено. ### Итоговый вывод В лабораторной работе реализовано S3-хранилище вложений для приложения обмена сообщениями. Бинарные данные хранятся отдельно от метаданных, которые сохраняются в PostgreSQL. Реализованы два способа загрузки файлов: Proxy Upload и Presigned Upload. Для прямой загрузки разработан механизм выдачи временных подписанных ссылок и последующей проверки загруженного объекта. Проведены проверки безопасности, негативные тесты, проверка очистки незавершённых загрузок, компенсации при отказе PostgreSQL, сохранности данных после перезапуска и отказоустойчивости двух API-реплик. В исследовательском треке 1 подтверждено существенное сокращение объёма данных, передаваемых через API. Для файла размером 5,5 MiB тело запроса к API уменьшилось с 5 769 330 до 159 байт. При этом эксперимент не подтвердил снижение потребления оперативной памяти. Таким образом, реализация демонстрирует преимущества прямой загрузки в S3, сохраняет совместимость с обязательным Proxy Upload и включает механизмы проверки и обработки ошибок при работе с двумя независимыми хранилищами.