Files
mtusi2026lab4/REPORT.md

492 lines
35 KiB
Markdown
Raw Permalink 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
- **Автор, группа:** Перевалова Виктория, БПИ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 и включает механизмы проверки и обработки ошибок при работе с двумя независимыми хранилищами.