forked from mtusi2026/mtusi2026lab4
201 lines
19 KiB
Markdown
201 lines
19 KiB
Markdown
# Отчёт — лабораторная 4
|
||
|
||
- Автор, группа: **Каменский Андрей, БПИ2301**
|
||
- Целевая оценка: **5**, трек 2 «Согласованность двух хранилищ»; обязательный минимум и уровень 4 сохранены.
|
||
- Использованы исходное задание lab4, контракт и публичные проверки предоставленного skeleton.
|
||
|
||
## Запуск из чистого клона
|
||
|
||
```sh
|
||
python3 scripts/setup-env.py
|
||
docker compose config --quiet
|
||
docker compose up -d --build --wait
|
||
python3 tests/smoke.py
|
||
python3 -m venv .venv
|
||
.venv/bin/python -m pip install -r requirements-student.txt
|
||
make -f student.mk verify-lab4 PYTHON=.venv/bin/python
|
||
```
|
||
|
||
Генератор создаёт локальный `.env` с новыми hex-паролями и правами 0600, значения
|
||
не печатает, существующий файл не перезаписывает. Для обновления сохранить прежние
|
||
пароли и volumes. Если ранее owner MinIO был записан в `S3_ACCESS_KEY_ID` /
|
||
`S3_SECRET_ACCESS_KEY`, перенести его в `MINIO_ROOT_USER` / `MINIO_ROOT_PASSWORD`,
|
||
а для API задать отдельного пользователя. Для стенда с прежними значениями по
|
||
умолчанию перенос не нужен. Уже существующий пароль администратора не меняется автоматически.
|
||
|
||
`docker compose down` сохраняет данные. `docker compose down --volumes` — отдельная
|
||
команда осознанного удаления учебных данных; сценарии сохранности её не используют.
|
||
Clean-start удаляет только собственный UUID-проект с временными volumes.
|
||
|
||
Версии закреплены: Python 3.13.0, PostgreSQL 16.6-bookworm, Redis 7.4.2-bookworm,
|
||
HAProxy 3.0.12-alpine, SQLAlchemy 2.0.44, asyncpg 0.30.0, Alembic 1.17.0,
|
||
minio-py 7.2.20, Pillow 13.0.0. MinIO community собирается из commit
|
||
`9e49d5e7a648f00e26f2246f4dc28e6b07f8c84a` релиза RELEASE.2025-10-15T17-29-55Z;
|
||
готовый официальный образ не требуется. Первый build занимает несколько минут.
|
||
|
||
## Архитектура и данные
|
||
|
||
Клиент → HAProxy → API × 2 → PostgreSQL + Redis + приватный MinIO.
|
||
Отдельный reconciler обращается к PostgreSQL и S3; bootstrap и migration —
|
||
завершающиеся задачи до запуска API. Публикуется только `127.0.0.1:8080` LB;
|
||
у API, PostgreSQL, Redis и MinIO нет опубликованных портов. Консоль S3 выключена.
|
||
|
||
| Компонент | Назначение | Постоянные данные / права |
|
||
| --- | --- | --- |
|
||
| PostgreSQL | Пользователи, чаты, сообщения, Attachment, идемпотентность, журнал и наблюдения | postgres_data |
|
||
| Redis | Сессии с абсолютным expiry, AOF appendfsync always, кэш профиля | redis_data; TTL после рестарта не продлевается |
|
||
| MinIO | Неизменённые оригиналы PNG/JPEG | minio_data; приватный bucket messenger-attachments |
|
||
| API | Авторизация, проверка картинок, синхронный upload и авторизованный download | Get/Put своего префикса; нет удаления и администрирования S3 |
|
||
| Reconciler | Обнаружение orphan/missing и повторяемые исправления | List/Get/Delete своего bucket/prefix; нет PutObject и admin |
|
||
| Migration / bootstrap | Миграции до 008, bucket, пользователи и политики | Owner credentials только в bootstrap/MinIO |
|
||
|
||
Обязательная основа API включает Bearer-сессии, PostgreSQL/Redis, два API за LB, X-Request-Id,
|
||
X-Instance-Id, пагинация, доступ к чатам и атомарная идемпотентность на 24 часа.
|
||
Идемпотентность теперь сравнивает текст и упорядоченный список вложений.
|
||
|
||
Миграция 007 создаёт `attachments` и `message_attachments`, разрешает пустой текст
|
||
при вложении. Связи с чатом защищены составными FK. Позиции 0–9 с UNIQUE на сообщение
|
||
ограничивают число файлов десятью, повтор ID запрещён. Вложение можно повторно
|
||
использовать в сообщениях того же чата. Миграция 008 добавляет `upload_intents`,
|
||
`storage_findings` и внутреннюю отметку `storage_missing_since`.
|
||
|
||
S3 object key назначает сервер, filename используется только для отображения.
|
||
API отдаёт оригинал побайтно, без redirect и перекодирования. MIME сравнивается
|
||
с определённым форматом; проверяются целостность и декодирование после раннего
|
||
лимита в 40 млн пикселей. Ограничение тела — 10 MiB, включая chunked-передачу.
|
||
Приём ограничен временем и параллелизмом; декодирование — одно на API-процесс.
|
||
Временный файл находится в tmpfs 64 MiB и закрывается после запроса. Скачивание
|
||
читает S3 порциями. Метаданные не раскрывают внутренний ключ или credentials.
|
||
|
||
## Согласованность PostgreSQL и S3
|
||
|
||
До PUT отдельным COMMIT фиксируется pending-намерение. Перед PUT загрузчик берёт
|
||
транзакционный advisory lock на ключ и повторно проверяет состояние. Он удерживает
|
||
блокировку до общего COMMIT Attachment и committed-намерения. Только после этого
|
||
возвращается 201 ready. При обрыве клиента до PUT постоянного объекта ещё нет.
|
||
|
||
Reconciler каждые 300 секунд перечисляет только наш bucket под originals/ с
|
||
пагинацией ListObjectsV2. На ключ берёт неблокирующий advisory lock: занятый
|
||
пропускается. Attachment защищает файл даже без сообщения. Старый pending без
|
||
Attachment закрывается; бесхозный объект удаляется после проверки возраста
|
||
объекта/намерения. Запас — 300 секунд, настраивается. Дополнительного ожидания
|
||
после первого обнаружения нет.
|
||
|
||
Ошибка DELETE не фиксируется как завершённая очистка: транзакция откатывается,
|
||
объект остаётся кандидатом при следующем проходе. Потерянный ответ DELETE также
|
||
безопасен для повторного запуска. При неизвестном результате COMMIT файл немедленно
|
||
не удаляется — это мог бы быть оригинал уже подтверждённого вложения.
|
||
|
||
Обратный проход HEAD обнаруживает Attachment без оригинала. Сообщения, связи и
|
||
метаданные сохраняются, чтение получает 503, новые ссылки — 409. Повтор уже
|
||
подтверждённого сообщения сохраняет прежний результат идемпотентности. После
|
||
восстановления файла размер и фактический SHA-256 должны совпасть. ETag не заменяет
|
||
SHA-256. Бесследное восстановление байтов из метаданных не обещается: нужна копия.
|
||
|
||
Dry-run выполняет проверки без записей и удаления. Apply перепроверяет условия
|
||
под блокировкой; параллельные изменения учитываются. Недоступность БД/S3, AccessDenied
|
||
или потеря bucket прерывают проход, а не объявляют все файлы отсутствующими.
|
||
Алгоритм, команды и ограничения подробно описаны в `LAB4_RECONCILIATION.md`.
|
||
|
||
## Готовность и ограничение ожидания
|
||
|
||
Liveness проверяет процесс. Readiness проверяет схему PostgreSQL, Redis и bucket;
|
||
бюджет ответа — 2 секунды, незавершённая отмена драйвера не задерживает HTTP.
|
||
Обычные бизнес-запросы имеют бюджет 5 секунд до заголовков. Таймаут не ждёт
|
||
зависшего rollback: обработчик отменяется, его слот сохраняется до реального
|
||
завершения. Предел незавершённых обработчиков — 64 на процесс. Это ограничивает
|
||
накопление работ при замороженной БД. Upload имеет отдельный бюджет приёма 30 секунд
|
||
и суммарный предел до заголовков 45 секунд; сокеты S3 ограничены 5 секундами.
|
||
|
||
Исправление проверено на действительно выполняющемся запросе: сначала история
|
||
удерживается SQL-блокировкой messages, наличие ожидающего SELECT подтверждается
|
||
через pg_stat_activity, затем PostgreSQL замораживается. История возвращает 503
|
||
примерно за 5 секунд, readiness — за 2 секунды; после unpause оба восстанавливаются
|
||
без перезапуска API. Одна проверка подключения не доказывала бы этот сценарий.
|
||
|
||
## Доказательства критериев
|
||
|
||
| Критерий | Повторяемая проверка | Результат / доказательство |
|
||
| --- | --- | --- |
|
||
| Контракт и прежнее API | make -f student.mk check validate; tests/smoke.py | lab4-final-structure/openapi/public-smoke.txt |
|
||
| PNG/JPEG, оригинал, SHA-256, ACL и 10 вложений | tests/attachments.py | lab4-final-attachments.txt |
|
||
| Отказ принявшей файл API | tests/attachment_failover.py | lab4-final-uploader-failover.txt |
|
||
| Restart API и всех хранилищ с прежним токеном | scripts/test-persistence.py | lab4-final-persistence-proof.txt: StartedAt до/после всех работающих ролей |
|
||
| Чистый build и пустые volumes | scripts/test-clean-lab4.py | lab4-clean-start.json, lab4-final-clean-start.txt: snapshot, build, миграция 008, smoke, вложения |
|
||
| Большой/повреждённый файл, MIME, чужой чат | tests/attachments.py; tests/lab4_review.py | lab4-final-attachments/reviewer-cases.txt |
|
||
| Обрыв, ошибка S3 PUT, COMMIT и DELETE, повтор очистки | tests/reconciliation.py | lab4-final-reconciliation.txt |
|
||
| 10 одновременных загрузок, пик RAM | tests/upload_memory.py | lab4-final-upload-memory.txt |
|
||
| Приватность S3, ограниченные роли, повторяемый bootstrap | tests/reconciliation.py; clean-start | unsigned GET 403; API не удаляет/не создаёт чужой bucket; reconciler не загружает |
|
||
| Полный трек 2: orphan/missing, dry-run, свежие/занятые файлы | tests/reconciliation.py | snapshot до/после, контролируемые сбои, повторный apply |
|
||
| Стоимость обхода, включая >1000 объектов | tests/reconciliation.py | 10/100/1005 объектов, три прогона, LIST/HEAD/SQL и время |
|
||
| Замечания преподавателя и восстановление после pause | tests/lab4_review.py; tests/request_deadline.py | lab4-final-reviewer-cases/request-deadline.txt; LAB4_AUDIT.md |
|
||
|
||
Имена файлов в таблице относятся к `evidence/`. Сводка всех команд и exit codes —
|
||
`evidence/lab4-final-summary.json`. Подробные наблюдения и исходные результаты
|
||
экспериментов — в JSON-строках соответствующих txt-файлов.
|
||
|
||
## Исследование и результаты
|
||
|
||
Гипотеза: журнал до PUT, единая блокировка и сверка устраняют бесхозные объекты
|
||
после частичных сбоев, сохраняя свежие и используемые файлы. Стоимость последовательного
|
||
обхода растёт примерно линейно по числу объектов. Проверки выполняются на отдельной
|
||
UUID-схеме PostgreSQL и приватном UUID-bucket; реальные данные текущего стенда не
|
||
удаляются. Используются реальные операции MinIO и аварийное завершение настоящего
|
||
кода загрузки после PUT. Дополнительно моделируются отказы БД, S3, потерянный ответ
|
||
удаления и публикация между dry-run и apply.
|
||
|
||
Стоимость dry-run измеряется для 10/100/1005 свежих бесхозных объектов по три раза.
|
||
Это metadata-профиль: LIST и HEAD, без чтения оригиналов. Для 1005 объектов нужны
|
||
две страницы LIST. Текущая реализация делает около пяти SQL statements на бесхозный
|
||
объект; для удалённой БД это заметная стоимость. Измерения итогового прогона приведены в таблице результатов ниже. Hash-проверка восстановления дополнительно
|
||
читает исходник и учитывается отдельно.
|
||
|
||
В опыте RAM временно допускаются пять загрузок на реплику при одном декодировании.
|
||
Две реплики принимают 10 одновременных PNG для двух размеров, затем проверяются
|
||
SHA-256 и скачанные байты. Cgroup memory.current измеряется каждые 20 мс, включая
|
||
tmpfs. После опыта восстанавливается обычный лимит одной загрузки на реплику.
|
||
Короткие пики между отсчётами могут быть пропущены; два размера не покрывают все
|
||
возможные картинки в 40 млн пикселей. Это не benchmark максимальных RPS.
|
||
|
||
## Итоговые измерения
|
||
|
||
Все 16 этапов `make -f student.mk verify-lab4` завершились с exit code 0. Интеграционный
|
||
набор сверки содержит 15 проверок, включая отказ DELETE до удаления
|
||
и прямой unsigned GET существующего объекта с результатом 403.
|
||
|
||
| Объектов | Медиана 3 обходов, с | LIST | HEAD | SQL statements |
|
||
| --- | --- | --- | --- | --- |
|
||
| 10 | 0.0181 | 1 | 10 | 53 |
|
||
| 100 | 0.1559 | 1 | 100 | 503 |
|
||
| 1005 | 1.9679 | 2 | 1005 | 5028 |
|
||
|
||
Оба профиля по 10 одновременных загрузок завершились без отказов: 20 ответов 201,
|
||
все SHA-256 и скачанные оригиналы совпали. Пики RAM: **124.71 / 128.91 MiB**
|
||
при 512 MiB на реплику. Размеры PNG: 197105 и
|
||
4923446 байт. Обычный UPLOAD_CONCURRENCY=1 восстановлен.
|
||
|
||
При замороженной PostgreSQL уже выполнявшаяся история вернула 503 за
|
||
**5.0988 с**, readiness — за **2.1109 с**.
|
||
После unpause восстановились 200 без рестарта API. Пустой стенд дошёл до миграции
|
||
008; API build --no-cache занял 32.829 с. Временный проект,
|
||
volumes и его теги образов удалены; действующие данные сохранены.
|
||
|
||

|
||
|
||
Усы на графике — min/max трёх запусков, не доверительный интервал.
|
||
Указанная RAM — максимум отсчётов, а не доказанный абсолютный пик между ними.
|
||
|
||
## Ограничения
|
||
|
||
Поддерживается один неверсионируемый bucket; worker отказывается работать с Enabled
|
||
или Suspended versioning. Все штатные писатели обязаны соблюдать блокировки;
|
||
прямые административные операции в S3 обходят эту координацию. Backup/restore
|
||
потерянных байтов не реализованы. PostgreSQL, Redis, MinIO, LB и Docker host остаются
|
||
едиными точками отказа. Не обещается отсутствие переходных ошибок при отказах.
|
||
Старые журнал и наблюдения пока сохраняются без автоматического сокращения истории.
|
||
|
||
Тест чистого запуска использует полный снимок рабочего каталога, включая новые
|
||
файлы, отдельные образы и пустые volumes; API строится с --no-cache. Кэш сборки
|
||
закреплённого MinIO может использоваться. Это проверка исходников сдачи, а не
|
||
утверждение, что текущий Git HEAD уже содержит все локальные изменения.
|