forked from mtusi2026/mtusi2026lab4
108 lines
8.9 KiB
Markdown
108 lines
8.9 KiB
Markdown
# Отчёт — лабораторная 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 содержит инструкцию именно моего решения. |