forked from mtusi2026/mtusi2026lab4
273 lines
25 KiB
Markdown
273 lines
25 KiB
Markdown
# Отчёт — лабораторная 4
|
||
|
||
- Автор, группа: Сергей Возжин, БПИ2301.
|
||
- Целевая оценка: 5; выбран трек 2 — согласованность PostgreSQL и S3.
|
||
- Commit/PR: https://gitea.privcloud.tech/mtusi2026/mtusi2026lab4/pulls/70
|
||
- Использованные источники: контракт репозитория, документация Docker Compose, Chainguard Images, MinIO SDK и Pillow.
|
||
- Библиотеки: FastAPI, Uvicorn, SQLAlchemy, asyncpg, Alembic, redis-py, MinIO Python SDK, Pillow, Argon2, pytest.
|
||
- Помощь ИИ: OpenAI Codex использовался для плана, реализации, тестов и оформления отчёта; результат проверен исполняемыми тестами.
|
||
|
||
## Запуск из чистого clone
|
||
|
||
Требуются Docker Engine с Compose v2, Python 3.9+ для публичных тестов и свободный host-порт 8080. Проверенный стенд: Apple M4 Pro, 12 CPU cores, 24 GB RAM, Docker Desktop; API на Python 3.13.15.
|
||
|
||
Закреплённые компоненты:
|
||
|
||
- `python:3.13.15-slim`;
|
||
- `postgres:17.4-alpine`;
|
||
- `redis:7.4.2-alpine`;
|
||
- `haproxy:3.2.26-alpine`;
|
||
- Chainguard MinIO `RELEASE.2026-10-23T20-06-51Z`, OCI index digest `sha256:3c60a2a8c4d33409a9bc7a623a7fcbfb4605adc3d89422d2f53b3f673a6e5597`;
|
||
- Chainguard MinIO Client, вариант `latest-dev`, OCI index digest `sha256:39768db4c3fa811bc8f2e2a3e0add8ea391648b1c980de179985e1c353dc1805` (`mc --version` сообщает upstream build marker `DEVELOPMENT.GOGET`).
|
||
|
||
Готовые образы MinIO и `mc` скачиваются из реестра Chainguard `cgr.dev`; в Compose оба образа закреплены по OCI digest. Сервис `s3` использует минимальный образ `minio` и в учебном стенде запускается с `user: "0"`, чтобы иметь доступ к Docker volume `/data`; его порты на host не публикуются. Для одноразового `s3-bootstrap` используется образ `minio-client` с shell и `sed`, необходимыми для создания bucket, отдельного пользователя API и bucket-scoped policy.
|
||
|
||
Создать локальную конфигурацию и заменить синтетические пароли, не добавляя `.env` в Git:
|
||
|
||
```sh
|
||
cp .env.example .env
|
||
```
|
||
|
||
`S3_BUCKET` допускает изменение: bootstrap при каждом запуске заново применяет ограниченную
|
||
policy с текущим именем bucket. `MINIO_ROOT_*` получает только MinIO и bootstrap; API
|
||
получает отдельные `S3_ACCESS_KEY_ID` и `S3_SECRET_ACCESS_KEY`. Access key и secret
|
||
считаются параметрами первоначальной инициализации пользователя MinIO; их ротация требует
|
||
явной операторской процедуры, а не изменения `.env` на работающем volume.
|
||
|
||
Проверить конфигурацию, собрать образы, применить миграции и дождаться готовности:
|
||
|
||
```sh
|
||
docker compose --env-file .env config --quiet
|
||
docker compose --env-file .env up -d --build --wait
|
||
docker compose --env-file .env ps
|
||
```
|
||
|
||
`migrate` выполняет `alembic upgrade head` отдельно и однократно. `s3-bootstrap` идемпотентно создаёт приватный bucket, отдельного пользователя API и bucket-scoped policy. Две API-реплики стартуют только после миграции, Redis и успешного bootstrap. Единственная публичная точка входа — `http://localhost:8080`; API, PostgreSQL, Redis, S3 API и административная консоль MinIO наружу не публикуются.
|
||
|
||
Основные проверки:
|
||
|
||
```sh
|
||
python3 -m venv .venv
|
||
.venv/bin/python -m pip install -r requirements-dev.txt
|
||
make check
|
||
make validate PYTHON=.venv/bin/python
|
||
make test
|
||
make test-attachments PYTHON=.venv/bin/python
|
||
make test-persistence ACTION_SCRIPT=scripts/restart.sh
|
||
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
|
||
docker compose --env-file .env up -d --wait --wait-timeout 60 api lb
|
||
make test-attachment-failover ACTION_SCRIPT=scripts/stop-one.sh
|
||
docker compose --env-file .env up -d --wait --wait-timeout 60 api lb
|
||
scripts/check-private-bucket.sh
|
||
scripts/check-s3-outage.sh
|
||
.venv/bin/python scripts/measure-upload-memory.py --concurrency 10 --uploads 30
|
||
make reconcile-dry
|
||
make benchmark-reconciler
|
||
```
|
||
|
||
Исправления следует сначала просмотреть через `make reconcile-dry`. Изменяющий данные
|
||
`make reconcile-apply` запускается оператором только после проверки dry-run.
|
||
`make benchmark-reconciler` по умолчанию создаёт 100, 1000 и 10000 изолированных пар
|
||
metadata/object, выполняет по три dry-run для каждого размера и удаляет тестовые данные.
|
||
Набор и число повторов меняются через `SIZES="..."` и `RUNS=...`; старый одиночный
|
||
параметр `SIZE=...` также поддерживается.
|
||
|
||
Каждый failover-тест намеренно оставляет выбранную API-реплику остановленной, поэтому между сценариями и после последнего сценария она явно восстанавливается указанной командой `docker compose up`.
|
||
|
||
Безопасная остановка с сохранением данных:
|
||
|
||
```sh
|
||
docker compose --env-file .env down
|
||
```
|
||
|
||
Намеренное необратимое удаление учебных данных выполняет только оператор:
|
||
|
||
```sh
|
||
docker compose --env-file .env down -v
|
||
```
|
||
|
||
## Архитектура и решения
|
||
|
||
```text
|
||
HTTP client
|
||
|
|
||
v
|
||
HAProxy :8080
|
||
|
|
||
+-- round-robin --> API replica 1 --+--> PostgreSQL: metadata
|
||
| +--> Redis: sessions
|
||
+-- round-robin --> API replica 2 --+--> private MinIO: original bytes
|
||
```
|
||
|
||
Из lab3 сохранены две взаимозаменяемые API-реплики, HAProxy, общие PostgreSQL/Redis, Bearer-сессии, `X-Instance-Id`, общая идемпотентность сообщений, readiness и failover hooks.
|
||
|
||
В lab4 добавлены:
|
||
|
||
- MinIO и persistent `s3_data` volume;
|
||
- таблицы `attachments` и `message_attachments`;
|
||
- синхронный binary upload PNG/JPEG;
|
||
- авторизованные metadata/download endpoints;
|
||
- `attachment_ids` в сообщениях и в области сравнения идемпотентного body;
|
||
- компенсационное удаление объекта и безопасный cleanup старых orphan-объектов;
|
||
- повторяемый reconciler метаданных PostgreSQL и оригиналов S3.
|
||
|
||
PostgreSQL является источником истины для метаданных. В БД не хранятся bytes изображения. MinIO хранит оригинал по серверному ключу `originals/<UUID>`. Пользовательский `filename` хранится только как метаданные и не используется в object key или пути файловой системы.
|
||
|
||
### Upload и лимиты
|
||
|
||
API сначала проверяет сессию, доступ к чату, filename и заявленный MIME. Тело читается чанками в `SpooledTemporaryFile`: до 1 MiB находится в памяти, затем временно сбрасывается на ephemeral disk API. Как только суммарный размер становится больше 10 MiB, запрос отклоняется с 413; превысивший лимит чанк в spool не записывается. Постоянной локальной копии нет.
|
||
|
||
Pillow определяет реальный PNG/JPEG, проверяет совпадение MIME, размеры до декодирования пикселей и целостность изображения через `verify()`. Максимум — 10 485 760 bytes и 40 000 000 пикселей. Пустой, повреждённый или чужой формат возвращает 415; превышение лимита bytes/pixels — 413.
|
||
|
||
S3-вызовы выполняются вне event loop. HTTP client S3 имеет ограниченные connect/read timeout и retry. Readiness проверяет PostgreSQL, Redis и существование bucket.
|
||
|
||
### Транзакционная граница PostgreSQL/S3
|
||
|
||
Атомарной транзакции между S3 и PostgreSQL нет. Для синхронного `201 ready` выбран порядок:
|
||
|
||
1. Полностью проверить ограниченный файл.
|
||
2. Выполнить S3 PUT.
|
||
3. Выполнить транзакцию INSERT метаданных.
|
||
4. Вернуть `201` только после успешного завершения обоих шагов.
|
||
|
||
Если PUT не удался, метаданные не создаются. Если PUT прошёл, а транзакция БД упала, API выполняет best-effort S3 DELETE. Unit-тест с внедрённой ошибкой БД подтверждает компенсацию.
|
||
|
||
Если компенсационное удаление также не удалось, остаётся orphan без метаданных. CLI находит такие объекты:
|
||
|
||
```sh
|
||
docker compose --env-file .env run --rm --no-deps api \
|
||
python -m app.tools.cleanup_orphans --dry-run --grace-seconds 3600
|
||
|
||
docker compose --env-file .env run --rm --no-deps api \
|
||
python -m app.tools.cleanup_orphans --apply --grace-seconds 3600
|
||
```
|
||
|
||
По умолчанию используется grace period один час; CLI запрещает значения меньше 60 секунд. Объекты с существующими метаданными и свежие orphan-объекты не удаляются. Сначала используется `--dry-run`, затем осознанный `--apply`.
|
||
|
||
### Reconciler PostgreSQL/S3 — трек 2
|
||
|
||
Гипотеза эксперимента: полный снимок PostgreSQL и listing MinIO дадут линейную
|
||
асимптотику `O(N)` по времени и памяти. На диапазоне 100–10000 согласованных пар рост
|
||
времени не должен становиться сверхлинейным; абсолютные значения зависят от Docker-host
|
||
и прогрева, поэтому для каждой точки используются три последовательных запуска и медиана.
|
||
|
||
Расширенный reconciler запускается внутри API-контейнера, где уже есть те же настройки и
|
||
ограниченные S3 credentials, что у приложения:
|
||
|
||
```sh
|
||
docker compose exec -T api \
|
||
python -m app.tools.reconcile_attachments --dry-run --grace-seconds 3600
|
||
docker compose exec -T api \
|
||
python -m app.tools.reconcile_attachments --apply --grace-seconds 3600
|
||
```
|
||
|
||
Он читает снимок всех `attachments` и список `originals/`, после чего различает:
|
||
|
||
- `orphan`: объект S3 есть, но ни одной строки с таким `object_key` нет;
|
||
- `missing`: строка в состоянии `ready` есть, а оригинала S3 нет;
|
||
- корректную пару: присутствуют обе стороны;
|
||
- свежее расхождение: возраст меньше grace period, изменять его нельзя.
|
||
|
||
В `--dry-run` выводятся `WOULD_DELETE_ORPHAN` и `WOULD_MARK_MISSING`, но записи и объекты
|
||
не меняются. В `--apply` старый orphan удаляется, а missing-метаданные сохраняются и
|
||
переходят в `status=failed`, `error_code=original_missing`. Сообщение и связь с вложением
|
||
не удаляются. Повторный `--apply` ничего не делает: orphan уже отсутствует, а `failed`
|
||
больше не считается ожидающим оригинал состоянием. При этом строка `failed` по-прежнему
|
||
защищает внезапно появившийся объект с тем же ключом от удаления как orphan.
|
||
|
||
Grace period защищает upload, который ещё выполняется, и запрещён ниже 60 секунд.
|
||
Используемые сообщением вложения не имеют особого исключения: любой известный PostgreSQL
|
||
ключ защищён одинаково, поэтому корректный оригинал связанного сообщения не удаляется.
|
||
Content для `failed` возвращает 409, а привязать такое вложение к новому сообщению нельзя.
|
||
|
||
Начальные снимки могут устареть во время apply. Поэтому перед удалением orphan reconciler
|
||
повторно проверяет отсутствие `object_key` в PostgreSQL, перед маркировкой missing выполняет
|
||
`HEAD/stat` объекта, а SQL `UPDATE` дополнительно сравнивает `id`, `object_key`, `status` и
|
||
исходный `updated_at`. Гонки логируются как `SKIP_*` и учитываются в `race_protected`.
|
||
Общей транзакции между PostgreSQL и S3 всё равно нет: остаётся узкое TOCTOU-окно между
|
||
последней проверкой и действием. Полностью закрыть его можно только протоколом состояний/
|
||
lease или запретом параллельного восстановления на время apply.
|
||
|
||
Операции между двумя хранилищами всё ещё не образуют общей транзакции. Если apply
|
||
прервётся, уже выполненное безопасное удаление orphan не требует отката, условный SQL
|
||
UPDATE меняет только всё ещё `ready` строки, а повторный запуск завершает оставшуюся
|
||
работу.
|
||
|
||
### Доступ и идемпотентность
|
||
|
||
Метаданные и content доступны любому участнику чата. Неизвестный объект и запрос постороннего одинаково возвращают 404. Download идёт через API без redirect. Публичный ответ не раскрывает object key, endpoint или credentials.
|
||
|
||
Сообщение принимает 0–10 уникальных `attachment_ids`. Все вложения должны быть `ready` и относиться к тому же чату. Пустой текст допустим только с вложением. Сравнение идемпотентного запроса включает упорядоченный список attachment ID; отсутствие поля и `[]` считаются одинаковыми.
|
||
|
||
## Доказательства критериев
|
||
|
||
| Критерий README | Команда/сценарий | Наблюдаемый результат | Доказательство |
|
||
| --- | --- | --- | --- |
|
||
| Offline/OpenAPI | `make check`; `make validate PYTHON=.venv/bin/python` | оба PASS | `evidence/results.md` |
|
||
| Публичный smoke | `make test` | `PASS: lab4 public API scenario` | `evidence/results.md` |
|
||
| Негативные сценарии | `make test-attachments PYTHON=.venv/bin/python` | `12 passed` | `tests/test_attachments.py`, `evidence/results.md` |
|
||
| Компенсация S3/БД | unit-тест с ошибкой repository | S3 DELETE вызван для загруженного ключа; `1 passed` | `tests/test_attachment_compensation.py` |
|
||
| Private bucket | `scripts/check-private-bucket.sh` | anonymous GET получил 403 | `evidence/results.md` |
|
||
| Недоступность S3 | `scripts/check-s3-outage.sh` | readiness вернул структурированный 503; стенд восстановлен | `evidence/results.md` |
|
||
| Persistence | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | прежние token, metadata и bytes доступны после restart PostgreSQL/Redis/MinIO/API | `evidence/results.md` |
|
||
| Общий lab3 failover | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` | 111 записей, 1 переходная ошибка, восстановление 2,333 с, файл сохранён | `evidence/results.md` |
|
||
| Точный attachment failover | `make test-attachment-failover ACTION_SCRIPT=scripts/stop-one.sh` | загрузившая реплика остановлена, download через другую за 3,912 с, SHA-256 совпал | `evidence/results.md` |
|
||
| Concurrency/RAM | `scripts/measure-upload-memory.py --concurrency 10 --uploads 30` | 30/30 upload, обе реплики, пики 68,50/68,33 MiB | `evidence/upload-memory.json` |
|
||
| Идемпотентный bootstrap | повторный запуск `docker compose up` после restart/failover | bootstrap повторно завершился с code 0 | `evidence/results.md` |
|
||
| Cleanup dry-run | `cleanup_orphans --dry-run --grace-seconds 60` | 164 известных объекта, удалено 0 | `evidence/results.md` |
|
||
| Reconciler fault injection | реальный PostgreSQL + MinIO: orphan, missing, fresh и три конкурентных изменения | apply исправляет только подтверждённые расхождения; свежие/изменённые данные защищены; повторный apply — 0 действий | `tests/test_reconciler_integration.py`, `evidence/results.md` |
|
||
| Полный тестовый стенд | изолированный Compose, все pytest | `17 passed` | `evidence/results.md` |
|
||
| Стоимость обхода | `SIZES="100 1000 10000" RUNS=3 make benchmark-reconciler` | медианы: 80,712 / 227,467 / 1733,545 мс; Python peak 2,62 / 4,21 / 8,08 MB | `evidence/results.md` |
|
||
|
||
## Эксперименты и отказы
|
||
|
||
Проверяемые ожидания:
|
||
|
||
- остановка загрузившей API-реплики не меняет файл и не лишает вторую реплику доступа;
|
||
- restart обязательных хранилищ с volumes сохраняет метаданные, bytes и сессию;
|
||
- недоступность S3 наблюдаема как 503, а не 500;
|
||
- 10 параллельных upload не приводят к неограниченному росту RAM.
|
||
|
||
Профиль upload: 30 запросов, concurrency 10, fixture 111 817 bytes, closed-loop, без retry. Получено 30 успешных upload за 0,382 с; максимальная latency 0,300 с; задействованы обе API-реплики. Пиковая наблюдаемая RAM: 68,50 MiB и 68,33 MiB при лимите 256 MiB на реплику.
|
||
|
||
Fault injection reconciler выполняется на настоящих PostgreSQL и MinIO. Тест создаёт
|
||
старую `ready` строку без объекта, объект без строки и корректное вложение, уже связанное
|
||
с сообщением. Дополнительно он восстанавливает missing-объект, изменяет `updated_at`
|
||
другой missing-строки и создаёт metadata для orphan уже после получения начальных
|
||
снимков, а также проверяет настоящий свежий orphan.
|
||
Управляемые часы имитируют истечение grace period без минутного ожидания. Apply исправляет
|
||
только подтверждённые расхождения; свежий объект и все три конкурентно изменённые
|
||
сущности защищены. Повторный apply не повторяет исправления, связь сообщения сохраняется.
|
||
|
||
Воспроизводимый benchmark для каждого размера удаляет прежнюю фикстуру, создаёт одинаковое
|
||
число строк `attachments` и объектов MinIO, выполняет три полных dry-run и удаляет данные.
|
||
|
||
| Пар metadata/object | Время, мс (три запуска) | Медиана, мс | Медианный peak Python allocations |
|
||
| ---: | --- | ---: | ---: |
|
||
| 100 | 78,847; 80,712; 82,781 | 80,712 | 2 620 657 bytes |
|
||
| 1 000 | 232,254; 227,467; 226,264 | 227,467 | 4 205 016 bytes |
|
||
| 10 000 | 1701,005; 1792,955; 1733,545 | 1733,545 | 8 075 853 bytes |
|
||
|
||
Измерение включает запрос PostgreSQL, listing MinIO и сравнение снимков; подготовка и
|
||
очистка в `elapsed_ms` не входят. Результат согласуется с гипотезой `O(N)`: после заметной
|
||
фиксированной стоимости время и память монотонно растут, на исследованном диапазоне нет
|
||
признаков сверхлинейного взрыва. Это не доказательство для production-масштаба: измеряется
|
||
Python `tracemalloc`, а не RSS контейнера, и полный снимок всё равно требует памяти `O(N)`.
|
||
|
||
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|
||
| --- | --- | --- | --- |
|
||
| Restart API + PostgreSQL + Redis + MinIO | token, metadata и bytes сохраняются | persistence PASS | потерь нет |
|
||
| Остановка API в общем failover | вторая реплика продолжает чтение/запись | 111 записей, 1 краткая ошибка | 2,333 с; потерь и дублей нет |
|
||
| Остановка загрузившей API | файл скачивается через другую | SHA-256 совпал, разные instance ID | 3,912 с; потерь нет |
|
||
| Остановка MinIO | readiness сообщает отказ зависимости | структурированный 503, после запуска readiness восстановился | потерь нет |
|
||
|
||
## Ограничения и следующие шаги
|
||
|
||
Стенд выдерживает остановку одной API-реплики и штатный restart контейнеров с сохранёнными volumes. Он не выдерживает потерю Docker-host, единственного HAProxy, PostgreSQL, Redis или MinIO volume. Несколько API-процессов не делают единственные хранилища высокодоступными.
|
||
|
||
Upload синхронный, поэтому клиент ждёт S3 и PostgreSQL. `SpooledTemporaryFile` ограничивает RAM одной загрузки, но временный disk API должен иметь достаточный объём и отдельную квоту в production. Reconciler загружает полный список объектов и строк БД в память, поэтому его стоимость O(N), а для большого bucket нужны страничный/потоковый обход, метрики, checkpoint и плановый запуск.
|
||
|
||
Chainguard-образы зафиксированы по digest, поэтому обновляются только явно. Стенд изолирован учебной сетью. Перед production-развёртыванием потребовались бы непривилегированный UID с корректными правами на volume, TLS, внешний secret manager, HA хранилищ, аудит и резервное копирование.
|
||
|
||
Presigned upload, worker, thumbnail и варианты изображений намеренно не реализованы: для выбранного трека 2 они не требуются.
|