forked from mtusi2026/mtusi2026lab5
report.md
This commit is contained in:
@@ -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).
|
||||
Reference in New Issue
Block a user