Files
mtusi2026lab4/REPORT.md
T
2026-11-11 21:16:29 +03:00

108 lines
8.9 KiB
Markdown
Raw 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
- Целевая оценка: 4
- Commit/PR: <ссылка на PR появится после пуша>
- Использованные источники, библиотеки и помощь ИИ: FastAPI, SQLAlchemy, boto3, Pillow, MinIO. ИИ использовался для генерации черновиков конфигураций и кода, финальная проверка и отладка проводились вручную.
## Запуск из чистого clone
Для запуска требуются Docker, Docker Compose и Python.
```sh
git clone https://gitea.privcloud.tech/kleprer/mtusi2026lab4.git
cd mtusi2026lab4
# кроссплатформенное копирование .env
python -c "import shutil; shutil.copy('.env.example', '.env')"
docker compose up -d --build --scale api=2
```
Безопасная остановка (с сохранением данных):
```sh
docker compose down
```
Намеренное удаление учебных данных (БД, кэша, файлов):
```sh
docker compose down -v
```
## Архитектура и решения
**Схема процессов:**
Клиент → Nginx (порт 8080) → API-реплики (FastAPI) → PostgreSQL (метаданные, пользователи, сессии), Redis (сессии), MinIO (S3-хранилище для файлов).
**Что изменено по сравнению с lab3:**
1. **S3-хранилище (MinIO):** В `compose.yaml` добавлен сервис `minio`. Приватный бакет `attachments` создаётся автоматически при старте приложения.
2. **Метаданные файлов:** В PostgreSQL добавлена таблица `attachments` (хранит размер, хэш SHA-256, MIME-тип, путь в S3) и связующая таблица `message_attachments`.
3. **Валидация изображений:** Перед отправкой в S3 файл проверяется через библиотеку `Pillow` на корректность формата (только JPEG/PNG) и ограничения (до 10 МБ, до 40 млн пикселей).
4. **Безопасность:** Файлы нельзя скачать напрямую из MinIO. API проверяет, является ли текущий пользователь участником чата, к которому привязан файл (иначе возвращается 404).
5. **Контракт Lab4:** В ответах API добавлены обязательные поля `variants: []`, `attachment_ids` (для сообщений) и `updated_at` (для вложений).
## Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke (уровень 3/4) | `python tests/smoke.py` | PASS. Тест загружает картинку, прикрепляет к сообщению, проверяет скачивание по SHA-256 и блокировку доступа для посторонних. | вывод консоли |
| Persistence (перезапуск) | `python tests/resilience.py --mode persistence --action-script scripts/restart.cmd` | PASS. Метаданные и файлы выживают после перезапуска контейнеров. | лог теста |
| Работа MinIO | `http://localhost:9001` (Web UI) | В бакете `attachments` видны загруженные файлы. | скриншот консоли |
| Защита от чужих | `python tests/smoke.py` | От лица `eve` запрос `GET /attachments/{id}` возвращает 404 (она не в чате). | лог теста |
## Ограничения и следующие шаги
- **Нет фоновой обработки:** В рамках оценки 4 реализована только синхронная загрузка оригинального файла. Создание миниатюр (thumbnail), ресайз и фоновая обработка через брокер сообщений (worker) запланированы для лабораторной 5.
- **Нет репликации MinIO:** В текущей конфигурации используется один инстанс MinIO. При его падении загрузка и скачивание файлов станут недоступны (SPOF).
- **Хранение файлов в оперативной памяти при загрузке:** Файл целиком считывается в память (`await request.body()`) перед отправкой в S3, что допустимо для лимита в 10 МБ, но не масштабируется для больших объемов.
====================================================================
НИЖЕ ТЕКСТ ДЛЯ ОПИСАНИЯ ПУЛЛ РЕКВЕСТА
====================================================================
## Лабораторная 4
Автор / группа: Максимова Снежана Игоревна / БПИ2302
Целевая оценка (3/4/5): 4
Трек 5, если заявлен: не заявлен
**Что реализовано и что перенесено**
Реализовано:
- Приватное S3-совместимое хранилище MinIO (конфигурация в Docker Compose).
- Загрузка, получение метаданных и скачивание вложений.
- Строгая валидация изображений (проверка MIME по содержимому через Pillow, лимит 10 МБ, лимит пикселей).
- Ограничение доступа: скачать файл может только участник чата.
- Привязка вложений к сообщениям через `attachment_ids` (таблица `message_attachments`).
- Добавлены обязательные поля контракта: `variants: []`, `updated_at` для вложений.
Перенесено из предыдущей работы (lab3):
- API на FastAPI, Nginx, миграции Alembic.
- Горизонтальное масштабирование, идемпотентность.
**Команды запуска из чистого clone**
```sh
git clone https://gitea.privcloud.tech/kleprer/mtusi2026lab4.git
cd mtusi2026lab4
git checkout solution/БПИ2302-Максимова
python -c "import shutil; shutil.copy('.env.example', '.env')"
docker compose up -d --build --scale api=2
```
**Результаты проверок и ссылка на REPORT.md**
- `python tests/smoke.py` — PASS (тест сам загружает файл, проверяет права доступа и скачивает с проверкой хэша).
- `python tests/resilience.py --mode persistence` — PASS (файлы и БД переживают перезапуск).
- Сервис MinIO успешно инициализирует бакет и принимает файлы.
- Ссылка на подробный анализ: REPORT.md
**Ограничения / известные ошибки**
- Для оценки 4 (базовый уровень) создание миниатюр/thumbnail не реализовано, так как это относится к требованиям лабораторной 5.
- В текущей конфигурации MinIO запущен в одном экземпляре (без репликации).
- Из-за проблем с официальным реестром Docker Hub, образ MinIO подтягивается из публичного зеркала `dappros/minio`.
**Источники и использование ИИ**
FastAPI, SQLAlchemy, boto3, Pillow, MinIO, Nginx. ИИ использовался для генерации черновиков конфигураций и скриптов, финальный код проверен вручную.
- [x] Весь обязательный минимум текущей и предыдущих работ сохранён с объявленными переходами.
- [x] Контракт и публичные тесты не ослаблены.
- [x] make check и make test выполнены; приложен реальный вывод.
- [x] Сценарии отказов/безопасности своего уровня воспроизведены (загрузка, проверка доступа).
- [x] Все секреты и приватные ключи находятся вне Git; отчёт не содержит tokens.
- [x] README задания сохранён, REPORT.md содержит инструкцию именно моего решения.