25 KiB
Отчёт — лабораторная 4
- Автор, группа: Сергей Возжин, БПИ2301.
- Целевая оценка: 5; выбран трек 2 — согласованность PostgreSQL и S3.
- Commit/PR: TODO после публикации.
- Использованные источники: контракт репозитория, документация 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 digestsha256:3c60a2a8c4d33409a9bc7a623a7fcbfb4605adc3d89422d2f53b3f673a6e5597; - Chainguard MinIO Client, вариант
latest-dev, OCI index digestsha256:39768db4c3fa811bc8f2e2a3e0add8ea391648b1c980de179985e1c353dc1805(mc --versionсообщает upstream build markerDEVELOPMENT.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:
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.
Проверить конфигурацию, собрать образы, применить миграции и дождаться готовности:
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 наружу не публикуются.
Основные проверки:
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.
Безопасная остановка с сохранением данных:
docker compose --env-file .env down
Намеренное необратимое удаление учебных данных выполняет только оператор:
docker compose --env-file .env down -v
Архитектура и решения
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_datavolume; - таблицы
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 выбран порядок:
- Полностью проверить ограниченный файл.
- Выполнить S3 PUT.
- Выполнить транзакцию INSERT метаданных.
- Вернуть
201только после успешного завершения обоих шагов.
Если PUT не удался, метаданные не создаются. Если PUT прошёл, а транзакция БД упала, API выполняет best-effort S3 DELETE. Unit-тест с внедрённой ошибкой БД подтверждает компенсацию.
Если компенсационное удаление также не удалось, остаётся orphan без метаданных. CLI находит такие объекты:
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, что у приложения:
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 они не требуются.