Files
mtusi2026lab4/REPORT.md

35 KiB
Raw Permalink Blame History

Отчёт — лабораторная работа №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. Клонирование проекта

git clone https://gitea.privcloud.tech/perevalova/mtusi2026lab4.git
cd mtusi2026lab4

Для перехода на ветку с реализацией:

git checkout solution/lab4-implementation

3. Подготовка конфигурации

Создать локальный файл .env на основе предоставленного примера:

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. Проверка конфигурации и сборка

docker compose config --quiet
docker compose build

5. Запуск инфраструктуры и приложения

docker compose up -d --build --scale api=2

В проекте предусмотрены следующие компоненты:

  • PostgreSQL;
  • Redis;
  • S3-compatible storage;
  • сервис первоначальной настройки S3;
  • Alembic migrations;
  • две реплики API;
  • Traefik.

Миграции выполняются отдельным сервисом migrate перед запуском API.

6. Ожидание готовности

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

docker compose ps

Проверить readiness API:

Invoke-RestMethod http://localhost:8080/health/ready

Ожидаемый результат:

{
  "status": "ok"
}

7. Проверка приложения

Проверка структуры и контракта:

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.

Проверка синтаксиса:

python -X utf8 -m compileall -q app migrations

Публичный smoke-тест:

python -X utf8 tests/smoke.py --base-url http://localhost:8080

Дополнительные проверки:

python -X utf8 scripts/test_presigned_upload.py
python -X utf8 scripts/test_presigned_negative.py

В Dockerfile вспомогательные каталоги scripts/, tests/, contracts/ и файл lab.json должны копироваться в образ API. После пересборки тест очистки незавершённых загрузок выполняется внутри API-контейнера:

docker compose exec -T api python /app/scripts/test_attachment_cleanup.py

Тест компенсационного удаления при отказе PostgreSQL выполняется внутри API-контейнера:

docker compose exec -T api python /app/scripts/test_s3_db_compensation.py

8. Остановка проекта

Безопасная остановка контейнеров с сохранением данных:

docker compose down

Повторный запуск:

docker compose up -d --build --scale api=2

Внимание: намеренное удаление учебных данных выполняется отдельно:

docker compose down -v

Эта команда удаляет Docker volumes, включая данные PostgreSQL, Redis и S3-хранилища. Использовать её следует только при осознанном сбросе учебного окружения.


Архитектура и решения

1. Общая архитектура

Система состоит из нескольких взаимодействующих компонентов.

                 Клиент
                    |
                    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

Для проверки сохранности данных использовался сценарий перезапуска:

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 и включает механизмы проверки и обработки ошибок при работе с двумя независимыми хранилищами.