report.md

This commit is contained in:
2026-11-11 21:52:00 +03:00
parent 2d18329ed1
commit 067b2d866f
+46 -15
View File
@@ -1,37 +1,68 @@
# Отчёт — лабораторная 5
- Автор, группа: TODO
- Целевая оценка; выбранный трек 5, если нужен: TODO
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: TODO
- Автор, группа: Максимова Снежана, БПИ2302
- Целевая оценка: 4
- Commit/PR: <ссылка на PR появится после пуша>
- Использованные источники, библиотеки и помощь ИИ: FastAPI, SQLAlchemy, boto3, Pillow, pika, RabbitMQ, MinIO. ИИ использовался для генерации черновиков конфигураций и кода, финальная проверка и отладка проводились вручную.
## Запуск из чистого clone
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
Для запуска требуются Docker, Docker Compose и Python.
```sh
git clone https://gitea.privcloud.tech/kleprer/mtusi2026lab5.git
cd mtusi2026lab5
# кроссплатформенное копирование .env (на Windows вместо python3 используйте python)
python3 -c "import shutil; shutil.copy('.env.example', '.env')"
docker compose up -d --build --scale api=2
```
Безопасная остановка (с сохранением данных в БД и S3):
```sh
docker compose down
```
Намеренное удаление учебных данных:
```sh
docker compose down -v
```
## Архитектура и решения
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab4, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
**Схема процессов:**
Клиент → Nginx → API-реплики (FastAPI) → RabbitMQ (очередь задач).
Фоновый Worker ← RabbitMQ → S3 (MinIO) / PostgreSQL.
**Что изменено по сравнению с lab4:**
1. **Асинхронная обработка:** При загрузке файла API сохраняет оригинал в S3 и запись в БД со статусом `queued`, возвращая `202 Accepted`. После этого задача публикуется в RabbitMQ.
2. **Фоновый Worker:** Отдельный процесс (контейнер), который читает задачи из RabbitMQ, генерирует варианты изображения и обновляет статус в БД на `ready`.
3. **Генерация вариантов:** Используется библиотека `Pillow`. Создаются 3 файла: `thumbnail` (JPEG, вписан в 256x256), `crop` (JPEG, центрированный 128x128) и `optimized` (WebP, вписан в 1280x1280). Метаданные (размер, хэш, разрешение) сохраняются в JSONB-поле `variants`.
4. **Идемпотентность воркера:** Если RabbitMQ доставит задачу повторно, воркер проверит статус в БД и не будет создавать дубликаты файлов.
5. **Лимиты ресурсов:** В `compose.yaml` для API и Worker заданы ограничения CPU и RAM (через `deploy.resources.limits`).
## Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | make test | TODO | TODO |
| Остальные пункты уровня 3 | TODO | TODO | TODO |
| Все пункты уровня 4, если заявлен | TODO | TODO | TODO |
| Выбранный трек 5, если заявлен | TODO | TODO | TODO |
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
| Публичный smoke (уровень 3/4) | `python tests/smoke.py` | PASS. Тест проверяет загрузку (202), статус `queued`, генерацию всех 3 вариантов и скачивание с проверкой хэшей. | вывод консоли |
| Асинхронность | `curl.exe -i -X POST ...` | Код ответа `202 Accepted`, статус в JSON `queued`. API не блокируется на время обработки. | вывод консоли |
| Генерация вариантов (уровень 4) | `GET /api/v1/attachments/{id}` | В ответе `status: ready`, массив `variants` содержит 3 элемента (thumbnail, crop, optimized). | лог теста |
| Работа RabbitMQ | `http://localhost:15672` (Web UI) | Очередь `attachment_tasks` принимает и отдает сообщения (Publish/Deliver rates > 0). | скриншот консоли |
| Идемпотентность воркера | Повторный вызов воркера с тем же ID | Воркер видит `status=ready` и пропускает обработку (дубликаты не создаются). | код `app/worker.py` |
| Лимиты ресурсов | `docker inspect` / `compose.yaml` | У контейнеров `api` и `worker` прописаны лимиты `cpus` и `memory`. | `compose.yaml` |
## Эксперименты и отказы
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
В рамках лабораторной не заявлен трек на оценку 5, поэтому эксперименты с RPS и saturation point не проводились. Были проверены сценарии отказоустойчивости и корректности обработки.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| TODO | TODO | TODO | TODO |
| Одновременная загрузка нескольких файлов | API не падает, все задачи попадают в очередь | Все файлы получили `202`, воркер обработал их по очереди (prefetch_count=1) | — |
| Перезапуск контейнера Worker во время обработки | Задача не теряется (подтверждение `basic_ack` происходит только после успеха) | RabbitMQ возвращает задачу в очередь и передает новому воркеру | Без потери данных |
| Скачивание файла, который еще в `queued` | Ошибка `409 Conflict` | API корректно возвращает ошибку, не пытаясь отдать пустой файл из S3 | — |
## Ограничения и следующие шаги
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
- **Отсутствие DLQ (Dead Letter Queue):** Если воркер столкнется с системной ошибкой (например, упадет S3), задача просто останется в очереди и будет бесконечно переотправляться, так как мы не настроили Dead Letter Exchange для изоляции "ядовитых" сообщений.
- **Синхронное чтение при загрузке:** В API файл читается в память (`await request.body()`) перед отправкой в S3. Это допустимо для лимита в 10 МБ, но для больших файлов потребовалась бы потоковая передача.
- **Единый экземпляр RabbitMQ и MinIO:** В текущей конфигурации используется один узел для брокера и хранилища. При их падении обработка файлов остановится (SPOF).