forked from mtusi2026/mtusi2026lab4
176 lines
17 KiB
Markdown
176 lines
17 KiB
Markdown
# Отчёт — лабораторная 4
|
||
|
||
Автор: Шурман А.Р., БПИ2302. Целевая оценка: **4**. Исследовательские треки на 5 не выполнялись.
|
||
|
||
## Статус проверки
|
||
|
||
Полный прогон выполнен **12 ноября 2026 года** на macOS arm64 / Docker Desktop.
|
||
`make check`, полная валидация OpenAPI, 5 unit-тестов и весь `scripts/verify.py`
|
||
прошли. Реальные результаты находятся в `evidence/`: smoke, негативные сценарии,
|
||
приватность bucket, безопасная очистка, обрыв upload, отказ S3, повторный bootstrap,
|
||
persistence, failover и нагрузка. Контракт и публичные тесты не изменены.
|
||
Первоначальный `evidence/offline.txt` сохранён как историческая проверка до запуска Docker.
|
||
|
||
## Запуск
|
||
|
||
Нужны Docker с Compose, Python 3.9+ на хосте (для memory/unit — Pillow).
|
||
API работает на Python 3.12.7. Новый стенд использует порт **8084**, отдельные volumes
|
||
и Compose project `mtusi-lab4`, поэтому не занимает порт предыдущих работ.
|
||
|
||
```sh
|
||
cd mtusi2026lab4-fork
|
||
python3 -m venv .venv
|
||
.venv/bin/pip install -r requirements-dev.txt Pillow==11.1.0
|
||
python3 scripts/bootstrap.py
|
||
docker compose config --quiet
|
||
docker compose up -d --build --wait
|
||
BASE_URL=http://localhost:8084 .venv/bin/python scripts/verify.py
|
||
make validate PYTHON=.venv/bin/python
|
||
```
|
||
|
||
Команды выполняются из корня этой лабораторной. Если репозиторий склонирован отдельно,
|
||
первую команду замените на переход в его каталог. `bootstrap.py` генерирует локальные
|
||
секреты, не выводит и не перезаписывает их. Повторный запуск сохраняет данные.
|
||
Для локальных тестов при отсутствии Pillow: отдельное venv и `pip install Pillow==11.1.0`.
|
||
Полная проверка OpenAPI: `pip install -r requirements-dev.txt`, затем `make validate`.
|
||
|
||
API: http://localhost:8084; Swagger: http://localhost:8084/docs.
|
||
Остановка без потери данных: `docker compose down` (без `-v`).
|
||
Возобновление: `docker compose up -d --wait`.
|
||
|
||
Готовые образы `minio/minio` и `minio/mc` оказались недоступны при проверке
|
||
12 ноября 2026 года (Docker Hub: pull access denied; Quay: 401).
|
||
Поэтому `infra/s3/Dockerfile` собирает официальные исходники закреплённых релизов
|
||
[MinIO RELEASE.2025-04-22T22-12-26Z](https://github.com/minio/minio/tree/RELEASE.2025-04-22T22-12-26Z)
|
||
и [mc RELEASE.2025-04-16T18-13-26Z](https://github.com/minio/mc/tree/RELEASE.2025-04-16T18-13-26Z)
|
||
в Go 1.24.2. Лицензии включены в образы. Первый запуск требует интернет и время
|
||
на скачивание Go-зависимостей и компиляцию; следующие сборки используют Docker cache.
|
||
|
||
## Архитектура
|
||
|
||
HAProxy → две FastAPI-реплики → общий PostgreSQL и приватный MinIO.
|
||
Valkey кэширует публичные профили; сессии проверяются в PostgreSQL при каждом запросе.
|
||
Исходная основа — собственная лабораторная 2: модели пользователей/чатов,
|
||
аутентификация, SQL-хранилище и мигратор. Возможности лабораторной 3 добавлены здесь:
|
||
балансировка, `X-Instance-Id`, общая таблица идемпотентности.
|
||
Контракт и публичные тесты skeleton не изменены.
|
||
|
||
Каждая реплика возвращает `api1` или `api2`. HAProxy проверяет readiness каждую секунду,
|
||
исключает реплику после двух неудач. Он не повторяет POST автоматически. При потере ответа
|
||
клиент повторяет сообщение с тем же `Idempotency-Key`. Advisory lock в PostgreSQL
|
||
сериализует один ключ пользователя/чата, вставка сообщения и результата атомарны.
|
||
Повтор в течение 24 часов возвращает исходный объект; другой текст/список вложений — 409.
|
||
Отсутствующий список вложений и `[]` равны. Просроченная запись ключа заменяется при повторном использовании.
|
||
История читается из primary без кэша. Keyset cursor не обеспечивает snapshot между страницами.
|
||
|
||
Метаданные Attachment находятся в PostgreSQL, байты — только в S3. Временный файл API
|
||
существует исключительно во время приёма и проверки запроса и закрывается по выходу.
|
||
Имя пользователя не используется как S3 key. Ключ — `originals/<UUID>`.
|
||
Скачивание идёт через API после проверки членства, без redirect и публичных URL.
|
||
|
||
## Валидация и ресурсы
|
||
|
||
Загрузка принимает сырые PNG/JPEG, максимум 10 MiB. Content-Length проверяется заранее,
|
||
но фактические байты также считаются во время потока. Общий срок приёма — 30 секунд.
|
||
Pillow проверяет формат, MIME, структуру и декодирование. Размер не выше 40 млн пикселей
|
||
проверяется до загрузки пикселей. Анимированные PNG в этой реализации отклоняются.
|
||
Оригинал сохраняется без преобразования; SHA-256 и размер вычисляются при чтении.
|
||
Пустые/опасные filename, MIME-подмена и чужие вложения имеют ошибки контракта.
|
||
|
||
Одновременно каждая реплика обрабатывает максимум две загрузки. Ожидание слота до 0.5 s,
|
||
затем явный 503. Две реплики ограничены по 768 MiB и 1 CPU. На диск пишется максимум
|
||
10 MiB на активную загрузку, декодирование занимает ограниченную память до размера
|
||
изображения. S3: connect timeout 2 s, read timeout 10 s, автоматических повторов нет.
|
||
Download читает S3 чанками по 64 KiB. Оригинал не загружается целиком в RAM при скачивании.
|
||
|
||
## Согласованность S3 и БД
|
||
|
||
1. API принимает и проверяет временный файл.
|
||
2. Отдельная транзакция сохраняет `pending` и назначенный object key до S3 PUT.
|
||
3. Новая транзакция блокирует строку, выполняет PUT и переводит её в `ready`.
|
||
4. Ответ 201 отправляется только после COMMIT. `pending` не показывается публично.
|
||
|
||
При обрыве передачи клиента до PUT остаётся только автоматически закрываемый временный
|
||
файл. При сбое PUT, падении процесса или неуспешном COMMIT остаётся учтённый `pending`.
|
||
Фоновый cleaner раз в минуту выбирает pending старше **1 часа**, блокируя строку
|
||
`FOR UPDATE SKIP LOCKED`, удаляет соответствующий S3 key и затем запись БД. Активная
|
||
транзакция пропускается. При ошибке S3 строка сохраняется для следующего прохода.
|
||
При сбое COMMIT очистка повторит безопасный DELETE отсутствующего объекта.
|
||
`ready` никогда не выбирается. Часовой grace period значительно больше таймаутов загрузки.
|
||
Это не распределённая транзакция: некоторое время возможны pending-метаданные и лишние байты.
|
||
Объекты, вручную записанные администратором без intent, вне модели очистки.
|
||
|
||
## Приватность и запуск хранилища
|
||
|
||
MinIO, PostgreSQL, Valkey и API не публикуют порты на хост. Только HAProxy доступен
|
||
на loopback. Консоль MinIO слушает 127.0.0.1 внутри его контейнера.
|
||
Идемпотентный `s3-init` создаёт bucket, запрещает anonymous и назначает отдельному API user
|
||
политику: ListBucket одного bucket и Get/Put/Delete исключительно в `originals/*`.
|
||
Root credentials доступны только MinIO и init, API их не получает.
|
||
Readiness зависит от PostgreSQL и MinIO. Valkey имеет fallback в PostgreSQL.
|
||
Секреты находятся в исключённом из Git каталоге `secrets/`.
|
||
|
||
| Роль / service | Версия | Готовность | Постоянные данные | Доступ / credentials |
|
||
|---|---|---|---|---|
|
||
| LB / `lb` | HAProxy 3.0.8-alpine | HTTP `/health/ready` обеих API | нет | только `127.0.0.1:8084` |
|
||
| API / `api1`, `api2` | Python 3.12.7; `app/requirements.txt` | PostgreSQL + MinIO | нет | внутренняя сеть; DB/S3 через secrets |
|
||
| БД / `postgres` | PostgreSQL 16.6-bookworm | `pg_isready` | `postgres-data` | внутренняя сеть; password secret |
|
||
| Кэш / `valkey` | Valkey 8.0.2-alpine | некритичен, fallback в БД | `valkey-data` (AOF) | внутренняя сеть |
|
||
| S3 / `s3` | MinIO RELEASE.2025-04-22T22-12-26Z | `/minio/health/live` | `s3-data` | внутренняя сеть; root secrets |
|
||
| Bootstrap / `s3-init` | mc RELEASE.2025-04-16T18-13-26Z | успешное завершение | bucket/policy в S3 | root + API secrets |
|
||
| Миграции / `migrate` | образ API | успешное завершение | `schema_migrations` в БД | secrets, advisory lock, checksum миграций |
|
||
| Очистка / `cleaner` | образ API | повтор каждые 60 s | pending в БД | ограниченные API S3 credentials |
|
||
|
||
Все сервисы находятся в отдельной Compose-сети `mtusi-lab4_default`.
|
||
Повторный `bootstrap.py` сохраняет секреты; повторные `migrate` и `s3-init`
|
||
не удаляют данные и выполняются при `docker compose up`.
|
||
|
||
## Проверки и доказательства
|
||
|
||
| Критерий | Проверка | Результат 12.11.2026 |
|
||
|---|---|---|
|
||
| Структура и синтаксис | `make check`, AST всех новых Python-файлов | выполнено |
|
||
| Конфигурация | `docker compose config --quiet` | выполнено |
|
||
| Реальные PNG/JPEG, MIME, повреждение, пиксели | `python3 student-tests/unit.py` | 5 тестов пройдено |
|
||
| Обязательный API и checksum | `make test BASE_URL=http://localhost:8084` | PASS; вывод в `evidence/` |
|
||
| Ошибки файлов и ACL, конкуренция ключа | `BASE_URL=http://localhost:8084 python3 student-tests/verify.py` | PASS; вывод в `evidence/` |
|
||
| Приватность bucket и безопасная очистка | `student-tests/storage_checks.py` внутри API через общий runner | PASS; вывод в `evidence/` |
|
||
| Обрыв загрузки и отказ S3 | `student-tests/outage.py` | PASS; вывод в `evidence/` |
|
||
| Повторный bootstrap | повтор `docker compose run --rm s3-init` | PASS; вывод в `evidence/` |
|
||
| Перезапуск всех сервисов | persistence + `scripts/restart.sh` | PASS; вывод в `evidence/` |
|
||
| Остановка обслужившей реплики | failover + `scripts/stop-one.sh` | PASS; 89 записей, 3 неудачные попытки, восстановление 2.8 s |
|
||
| Остановка именно загрузившей реплики | `student-tests/attachment_failover.py` | PASS; upload api1 → download api2; bytes совпадают |
|
||
| 10 одновременных загрузок и RSS | `student-tests/memory.py` | 8 × 201, 2 × 503; пик RSS 132796 / 133912 KiB |
|
||
|
||
`.venv/bin/python scripts/verify.py` выполняет проверки и сохраняет реальные результаты в evidence,
|
||
останавливаясь при первом провале. Тест очистки создаёт только синтетические строки и объекты,
|
||
моделирует rollback финализации после PUT, проверяет grace period и сохранность ready.
|
||
Он удаляет только свои синтетические данные. До запуска убедитесь, что это учебный стенд.
|
||
|
||
Memory-тест создаёт PNG примерно 9 MiB и одновременно запускает 10 запросов.
|
||
Он пишет коды ответов, длительность, выборки VmRSS процессов API и измеренный максимум.
|
||
Отказы 503 из-за ограничения слотов учитываются явно; они не записываются как успешные загрузки.
|
||
Последовательная выборка `/proc/1/status` может пропустить короткий пик, поэтому результат —
|
||
максимум наблюдений, а не гарантированный абсолютный пик. Фактический эксперимент: 10 одновременных запросов по 9 201 866 байт,
|
||
8 ответов 201 и 2 ответа 503; время ответа 0.427–0.680 s. Наблюдаемый пик RSS:
|
||
api1 — 132 796 KiB (129.7 MiB), api2 — 133 912 KiB (130.8 MiB), при лимите
|
||
768 MiB на реплику. Полные выборки сохранены в `evidence/memory.json`.
|
||
Это проверка ограниченности ресурсов, а не обещание принять любую конкуренцию без 503.
|
||
|
||
## Ограничения
|
||
|
||
Один host, HAProxy, PostgreSQL и MinIO остаются точками отказа. Это отказоустойчивость
|
||
к остановке одной API-реплики, не полноценная HA-система. При отказе S3 readiness
|
||
становится 503; после восстановления новые обращения повторяются клиентом.
|
||
Обрыв S3 посреди уже начатого download закрывает поток, поэтому клиент проверяет длину/checksum.
|
||
Нет UI, обработки изображений в очереди, presigned URL и исследовательских треков.
|
||
Проверка реальных контейнеров выполнена; при переносе на другую машину её нужно повторить.
|
||
|
||
## Источники и использование ИИ
|
||
|
||
Основа — собственные предыдущие лабораторные и skeleton преподавателя;
|
||
API и критерии взяты из `contracts/` и `README.md`. MinIO/mc собираются из официальных
|
||
исходников по ссылкам выше. При проверке и исправлении работы использован Codex:
|
||
анализ кода, исправление сборки S3, дополнительные тесты, запуск стенда и оформление
|
||
фактических результатов. Результаты получены запуском, а не сгенерированы.
|