35 KiB
Отчёт — лабораторная работа №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:
- API принимает и проверяет файл.
- Загружает содержимое в S3.
- Создаёт запись метаданных в PostgreSQL.
- Если сохранение метаданных завершается ошибкой, API выполняет rollback и пытается удалить объект из S3.
Для Presigned Upload:
- API проверяет пользователя и членство в чате.
- Создаёт уникальный ключ объекта и запись
pendingв PostgreSQL. - Возвращает временную подписанную ссылку.
- Клиент загружает файл непосредственно в S3.
- Клиент вызывает endpoint завершения загрузки.
- API получает объект из S3, проверяет размер, SHA-256 и содержимое изображения.
- После успешной проверки создаёт запись вложения и переводит загрузку в состояние
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 при работе с крупными вложениями.
Методика эксперимента
Сравнивались два способа загрузки:
- Proxy Upload — клиент передаёт бинарное содержимое файла API, после чего API сохраняет его в S3.
- 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 | Доступ запрещён |
Известные ограничения
- PostgreSQL и S3 не используют общую распределённую транзакцию. Согласованность обеспечивается компенсационными операциями и фоновой очисткой.
- Удаление объекта из S3 является best-effort операцией. При одновременном отказе хранилища и компенсационного удаления может потребоваться повторная проверка состояния.
- Фоновая очистка работает с зарегистрированными незавершёнными загрузками. Объекты, для которых вообще не была создана запись загрузки, требуют отдельного механизма сверки или политики жизненного цикла S3.
- Эксперимент по памяти проводился с периодическим опросом Docker Stats. В параллельном запуске мониторинг успел получить лишь 4–5 измерений, поэтому кратковременные пики могли быть пропущены.
- Эксперименты проведены в локальной Docker-среде, а не в распределённой производственной инфраструктуре. Результаты нельзя автоматически переносить на промышленную нагрузку.
- Для прямой загрузки необходима доступность S3 endpoint со стороны клиента. В локальном окружении используется опубликованный адрес S3 API.
- Фактическое снижение потребления RAM при Presigned Upload экспериментально не подтверждено.
Итоговый вывод
В лабораторной работе реализовано S3-хранилище вложений для приложения обмена сообщениями. Бинарные данные хранятся отдельно от метаданных, которые сохраняются в PostgreSQL.
Реализованы два способа загрузки файлов: Proxy Upload и Presigned Upload. Для прямой загрузки разработан механизм выдачи временных подписанных ссылок и последующей проверки загруженного объекта.
Проведены проверки безопасности, негативные тесты, проверка очистки незавершённых загрузок, компенсации при отказе PostgreSQL, сохранности данных после перезапуска и отказоустойчивости двух API-реплик.
В исследовательском треке 1 подтверждено существенное сокращение объёма данных, передаваемых через API. Для файла размером 5,5 MiB тело запроса к API уменьшилось с 5 769 330 до 159 байт. При этом эксперимент не подтвердил снижение потребления оперативной памяти.
Таким образом, реализация демонстрирует преимущества прямой загрузки в S3, сохраняет совместимость с обязательным Proxy Upload и включает механизмы проверки и обработки ошибок при работе с двумя независимыми хранилищами.