Files
mtusi2026lab4-fork/REPORT.md
T

30 KiB
Raw Blame History

Отчёт — лабораторная работа №4

Автор: Ляхонов Сергей, группа БВТ2301. Дата: 30 октября 2026 года. Целевая оценка: 5, выбран трек 2 — согласованность двух хранилищ. Пользователь выбрал трек до реализации. Ветка: solution/BVT2301-lyakhonov. Только локальные русскоязычные коммиты; push и PR не выполнялись.

Запуск из чистого clone

Нужны Docker Engine/Compose с Linux-контейнерами, Python 3.12+ на хосте и make (самим публичным тестам достаточно Python 3.9+) (либо прямые эквивалентные Python-команды ниже). Проверено: Windows, Python хоста 3.13.7, Docker Engine 28.5.1 / Docker Desktop, i5-1340P, 16 логических CPU и 16 GB RAM. Docker VM: 16 CPU, 8 126 664 704 bytes RAM. См. CPU, RAM, Docker. Для сборки исходников S3 и всех экспериментов разумно выделить Docker около 8 GB RAM и иметь около 10 GB свободного диска под build cache/образы/учебные данные. Постоянные runtime-лимиты стенда: суммарно 4 CPU и 2816 MiB; генератор и одноразовые сервисы требуют дополнительного ресурса. Это лимиты, а не гарантированное фактическое потребление.

PowerShell, из корня лабораторной 4:

$env:PYTHONUTF8='1'
python scripts/bootstrap.py
docker compose --env-file .env config --quiet
docker compose --env-file .env build api s3
docker compose --env-file .env up -d
python scripts/wait_ready.py --base-url http://localhost:8084 --replicas 2
make check test PYTHON=python BASE_URL=http://localhost:8084
python -m venv .venv
.venv/Scripts/python -m pip install -r requirements-research.txt
make validate PYTHON=.venv/Scripts/python

Bootstrap создаёт случайные DB/S3 secrets и .env из lab4.env.example только при отсутствии; существующие файлы сохраняются. Пароли и ключи не выводятся и не попадают в Git. Отдельный migrate применяет версии 001–003 под advisory lock до старта API. Bucket-init создаёт приватный bucket и ограниченного пользователя приложения; повтор безопасен. Все зависимости запускаются из этого репозитория; установленные ранее БД/S3 не используются.

Реестр отказал в скачивании официальных образов MinIO/mc (Docker Hub denied, Quay 401), поэтому окончательный стенд собирает S3 из исходников через Dockerfile.s3: MinIO commit 07c3a429bfed433e49018cb0f78a52145d4bedeb (исходники RELEASE.2025-09-07T16-13-09Z), mc RELEASE.2025-04-16T18-13-26Z. Оба архива закреплены SHA-256 в ADD; Go и Debian закреплены digest, Go-зависимости проверяются go.sum. Первичная сборка реально прошла, повтор использует build cache. Нужен доступ к GitHub, Docker Hub и Go module proxy; наличие локального старого MinIO-образа не требуется. Версия самосборного бинарника может выводиться как DEVELOPMENT.GOGET; точная идентичность задаётся commit и архивом, не этой строкой. Лицензии MinIO/mc AGPL включены в образ. Контрольные суммы, рецепт.

Остановка без удаления данных: docker compose down. Стенд №3 не затрагивается. Только при намеренном удалении собственных учебных данных: docker compose down --volumes. Последняя команда необратима; в проверках основного стенда она не используется. Одноразовый стенд проверки чистого экспорта удаляет только собственные вновь созданные scratch volumes. Внешние volumes и чужие Compose projects не удаляются. На POSIX использовать python3 и executable .sh hooks (chmod +x scripts/restart.sh scripts/stop-one.sh).

Чистый Git-экспорт коммита 6c87ed2 отдельно проверен скриптом python scripts/verify_clean_export.py: новые secrets, уникальные project/images/volumes и свободный loopback-порт; сборка API/S3, две готовые реплики и публичный smoke прошли. Основные стенды не изменялись. После проверки одноразовые контейнеры/сеть/тома удалены. Результат, сборка.

Архитектура и конфигурация

flowchart LR
    Client[Клиент] --> LB[HAProxy localhost:8084]
    LB --> API1[API 1]
    LB --> API2[API 2]
    API1 --> DB[(PostgreSQL: метаданные и сессии)]
    API2 --> DB
    API1 --> S3[(MinIO: приватные оригиналы)]
    API2 --> S3
    API1 --> Redis[(Redis: необязательный кэш профилей)]
    API2 --> Redis
    Reconciler[Периодическая сверка] --> DB
    Reconciler --> S3
Роль → service Версия / CPU / RAM Готовность / durable state / доступ
API → api ×2 Python 3.11.10, lock dependencies; 0.5 CPU / 512 MiB каждая /health/ready: PostgreSQL + S3; без durable локальных оригиналов; только внутренняя сеть
БД → db PostgreSQL 16.6-alpine; 1 CPU / 512 MiB pg_isready; отдельный postgres_data; порт не опубликован
S3 → s3 Собственная сборка из закреплённых исходников; 1 CPU / 768 MiB bootstrap ждёт S3; API проверяет LIST рабочего prefix; отдельный s3_data; без внешних портов
LB → lb HAProxy 3.0.6-alpine; 0.5 CPU / 128 MiB HTTP readiness API; только 127.0.0.1:8084
Кэш → redis Redis 7.4.1-alpine; 0.25 CPU / 128 MiB Необязателен; профили, без сессий/истории; persistence отключён
Миграции → migrate Тот же исходный образ; 0.5 CPU / 512 MiB Одноразовый exit 0 до API, schema_migrations
Bucket bootstrap → bucket-init Тот же S3-образ, mc; 0.25 CPU / 128 MiB Одноразовый exit 0; приватность и политика; root secrets доступны только здесь и S3
Сверка → reconciler Тот же исходный образ; 0.25 CPU / 256 MiB Apply каждые 300 с, grace 3600 с; отдельный процесс, restart unless-stopped

Compose project lyakhonov-lab4, собственные сеть, lyakhonov-lab4_postgres_data, lyakhonov-lab4_s3_data, образы lyakhonov-messenger:lab4 и lyakhonov-storage:lab4. Нет container_name и наружных портов API/БД/S3/Redis. Консоль MinIO слушает только loopback самого S3-контейнера. Пароли передаются через read-only Compose secrets files. Приложение имеет S3 LIST только своего bucket/prefix и Get/Put/Delete только attachments/originals/*; не имеет административного доступа, list buckets, delete bucket или записи вне prefix. Bucket — attachments, публичного чтения нет. API работает без root. Единственные PostgreSQL, S3, LB и Docker-host остаются SPOF.

lab4.env.example задаёт реальные пользовательские параметры LAB4_PORT, API_REPLICAS, API_CPUS, API_MEMORY, POOL_SIZE, SESSION_TTL_SECONDS и OPTIMIZED_WRITES. Исходный .env.example skeleton сохранён как список логических интерфейсов: APP_HOST/APP_PORT соответствуют фиксированному listener 0.0.0.0:8080; APP_ENV не используется; SESSION_STORE=postgres фиксирован; CACHE_URL_FILE заменён внутренним CACHE_URL=redis://redis:6379/0; DATABASE_URL_FILE совпадает. S3_ENDPOINT и регион совпадают; S3_BUCKET в решении фиксирован attachments вместо предложенного messenger-attachments. S3_ACCESS_KEY_ID_FILE/S3_SECRET_ACCESS_KEY_FILE отображаются на внутренние S3_ACCESS_KEY_FILE/S3_SECRET_KEY_FILE. IDEMPOTENCY_TTL_SECONDS=86400, MAX_UPLOAD_BYTES=10485760, MAX_IMAGE_PIXELS=40000000 — обязательные фиксированные лимиты, не произвольные пользовательские настройки. Изменение старого .env.example не меняет эти внутренние значения.

Перенос и границы транзакций

Источник: собственная лабораторная №3, HEAD 374c43e, только чтение. Оба рабочих дерева до начала были чистыми. Перенесены исходники, миграции, зависимости, Dockerfile и необходимые конфигурации/scripts. README, COURSE, обязательные contracts, публичные tests и fixture лабораторной №4 сохранены. Не переносились .git, .env, secrets, volumes, venv, старые измерения/графики. Акт переноса.

Сохранены PostgreSQL-сессии, Argon2id, ACL чатов, пагинация, две реплики и общая транзакционная идемпотентность. В отличие от lab3, Message теперь всегда содержит attachment_ids; допускает пустой текст с вложениями. Ключ сравнивает полный нормализованный body, включая порядок ID; отсутствующее attachment_ids равно []. Результат ключа, Message и связи вложений фиксируются атомарно. Конкурентные повторы сериализуются общей блокировкой. Миграция 003 переносит старые текстовые результаты ключей в JSON и добавляет Attachment/message_attachments. Обратное смешивание lab3/lab4 API после этой миграции не поддерживается: требуется согласованный переход. В этой работе использован новый отдельный volume, исходная БД lab3 не изменялась.

Upload: авторизация/ACL → bounded temporary spool → MIME/размер/пиксели/verify/load → уникальный S3 PUT → INSERT → COMMIT → 201 ready. Оригинал сохраняется побайтно. Приём <=10 MiB, <=40 млн px; один декодер на реплику, <=20 с на body, <=25 с ожидания слота. Только временный spool живёт локально до PUT; download читает S3 блоками 64 KiB без redirect. S3 timeout connect=2/read=5 с и без retry, LB client=60/server=45 с и без повторов POST. Неопределённый COMMIT не вызывает слепое удаление объекта. Подробный протокол и инварианты: infra/reconciliation.md.

Доказательства критериев

Критерий Команда/сценарий Реальный результат / доказательство
Обязательная база lab3 и контракт lab4 make check/test/validate PASS: make, validate
Upload 201 ready, сообщение, checksum, ACL публичный smoke PASS: smoke; PNG/JPEG неизменны
≥2 API, остановка именно загрузившей реплики python student-tests/test_operations.py Обе разные реальные реплики остановлены по очереди; другой процесс вернул оригинал: JSON
Retry и сохранность при failover публичный resilience --mode failover PASS, ошибки перехода учтены: 1, 2
Рестарт с volumes и прежней сессией публичный persistence + test_operations.py PASS, реальные StartedAt до/после API/БД/Redis/S3/LB: persistence, operations
S3 недоступен / восстановлен test_operations.py Ограниченный 503, после восстановления те же bytes и сессия
Bytes/пиксели/MIME/filename/повреждения test_attachments.py PASS, включая chunked body >10 MiB, >40 млн px и допустимые ровно 40 млн px: negative suite
Чужой ID, другой чат, дубли ID test_attachments.py 404/400, без 500
Обрыв body реальный TCP disconnect Постоянный объект не создан
Сбой после PUT до INSERT ограниченный synthetic DB trigger Получен 500, объект найден сверкой как orphan; trigger снят в finally
Ограничение RAM при ≥10 загрузках python scripts/run_upload_load.py 60/60 успешно, два размера, cgroup peak и Docker stats: raw, CSV
Приватность и минимальные S3-права unsigned GET + запрещённые S3 API 403; отдельные credentials приложения: suite
Идемпотентный bucket bootstrap docker compose run --rm --no-deps bucket-init Повтор exit 0: вывод
Orphan/missing/corrupt test_reconcile.py Найдены; old orphan удалены; missing/corrupt изолированы без удаления метаданных
Dry-run, повтор и конкуренция test_reconcile.py Все метаданные до/после dry-run совпали; блокировка/свежесть/ссылки сохранены; два прохода безопасны
Безопасное восстановление неверный, затем правильный оригинал Неверные bytes не вернули ready; проверенный оригинал восстановил его: исследование
Стоимость обхода 0/50/200 дополнительных объектов ×3 Время, LIST/HEAD/GET и bytes измерены, график ниже

Эксперимент загрузки и память

Фиксированный seed, PNG RGB 1024² и 1792², один прогрев на размер. Три партии по 10 клиентов на размер через LB, прозрачных retry нет. Клиенты готовы до начала измерительного окна; все одновременно отпускаются event. Суммарное timed elapsed для шести партий — 6.966 с; это короткий опыт, не steady-state soak test. Elapsed включает завершение всех запросов, не подготовку клиентов и не последующее скачивание подтверждённых оригиналов. p50/p95/p99 интерполируются линейно по успешным запросам; при 10 наблюдениях хвост оценён грубо. Генератор — отдельный контейнер с 0.5 CPU / 512 MiB. API пересозданы перед замером; фоновая сверка остановлена и затем восстановлена. Не менялись ресурсы/версии между размерами. Это closed-loop партии, без контроля arrival rate и с coordinated omission; универсальная максимальная пропускная способность не заявляется. Ранние пилоты с подготовкой клиента внутри окна заменены этой серией.

Размер PNG, bytes Успехи / попытки RPS, медиана p50 / p95 / p99, с (медианы)
3151219 30 / 30 16.73 0.408 / 0.585 / 0.591
9648062 30 / 30 5.63 1.061 / 1.716 / 1.764

Скорость и задержка загрузки

Память API

Docker stats показывает выборочный working set, cgroup memory.peak — kernel high-water mark за жизнь новых API-контейнеров (включает старт, прогрев, загрузки и проверку скачивания). Эти два показателя различаются учётом cache и частотой наблюдения.

  • API 68ab8db39c84: kernel peak 167.95 MiB при лимите 512 MiB.
  • API a6106479affd: kernel peak 156.98 MiB при лимите 512 MiB.

Для CPU 100% Docker stats означает одно логическое ядро. Сырые CPU%/RAM, временные метки и cpu.stat сохранены в upload-load.json; sampled memory для API ниже лимита. Выборки включают прогрев, подготовку клиентов и скачивание, поэтому это не интеграл CPU только внутри timed batches.

Служба CPU%, медиана / максимум выборок
lyakhonov-lab4-api-1 7.90 / 49.68
lyakhonov-lab4-api-2 7.60 / 51.60
lyakhonov-lab4-db-1 1.54 / 4.78
lyakhonov-lab4-lb-1 2.25 / 12.86
lyakhonov-lab4-s3-1 1.21 / 27.30

Это не доказательство нулевых аллокаций: декодер допустимого 40 MP изображения может занять порядка 160 MB дополнительно; одновременно декодируется одна картинка на процесс.

Исследование согласованности: гипотеза и результаты

Гипотеза: PostgreSQL/S3 нельзя объединить обычным локальным COMMIT; безопасная периодическая сверка с общей блокировкой и защитным интервалом убирает orphan и отмечает missing, сохраняя свежие и используемые вложения. Цена — обход всех объектов/строк и чтение подтверждаемых bytes, поэтому она растёт с числом объектов и объёмом оригиналов.

Методика: реальный INSERT отказал после PUT; отдельно удалён S3-оригинал уже привязанного к сообщению вложения. Созданы старый orphan, свежий orphan и объект под удерживаемой общей блокировкой (имитация окна upload до COMMIT). Dry-run сверяет полный снимок id/state/updated_at; apply удаляет только безопасные orphan и ставит missing. Следующий проход не дублирует изменение state. После снятия блокировки/истечения grace ранее защищённые orphan могут быть удалены — это ожидаемое продолжение очистки, а не ошибка идемпотентности. Существующие строки Attachment защищаются независимо от возраста и наличия сообщения. Два конкурентных reconciler пропускают занятые ключи. Неверные bytes оставляют missing; корректные bytes возвращают ready; связь с исходным сообщением сохраняется. Тестовый grace=5 с, ожидание старения=6 с; рабочий default=3600 с. Полные агрегаты, сценарий.

Измерение стоимости: фиксированный набор метаданных и оригиналов, добавляются 0/50/200 неучтённых объектов по 1 KiB. По три dry-run на точку, page_size=50; сервис периодической сверки остановлен, другая нагрузка не запускается. Порядок 0→50→200; cache состояния не сбрасывался. Выигрыш/регрессию оптимизации этот опыт не измеряет.

Всего объектов Время, медиана [min; max], с LIST / HEAD / GET Проверено bytes за проход
221 4.964 [4.835; 5.073] 5 / 221 / 221 1193831654
271 5.185 [4.994; 5.314] 6 / 271 / 221 1193831654
421 6.356 [6.225; 6.826] 9 / 421 / 221 1193831654

Стоимость сверки

В этой серии GET/проверенные bytes постоянны, рост дополнительных orphan увеличивает HEAD и LIST. Это подтверждает рост цены обхода; три повтора и небольшой bucket не доказывают асимптотическую производительность большой инсталляции. Чтение всех оригиналов ради проверки SHA-256 может доминировать над числом объектов. RAM ограничена страницей и chunk 64 KiB, но трафик и общее время не являются константными. Между страницами нет общего snapshot: проход eventually consistent, новые записи/пропуски блокировок проверяются следующим запуском.

Воспроизведение и отказы

docker compose stop reconciler
docker compose run --rm --no-deps -T -v "${PWD}:/suite:ro" -w /suite api python student-tests/test_attachments.py
docker compose run --rm --no-deps -T -v "${PWD}:/suite:ro" -w /suite api python student-tests/test_reconcile.py
docker compose start reconciler
python student-tests/test_operations.py
python tests/resilience.py --mode persistence --action-script scripts/restart.cmd --base-url http://localhost:8084
python tests/resilience.py --mode failover --action-script scripts/stop-one.cmd --base-url http://localhost:8084
docker compose start api
docker compose up -d --no-deps --force-recreate api
python scripts/wait_ready.py --base-url http://localhost:8084 --replicas 2
python scripts/run_upload_load.py
.venv/Scripts/python scripts/plot_results.py
# Dry-run вручную:
docker compose run --rm --no-deps api python -m src.reconcile

Собственные suites создают данные; повтор увеличивает набор и меняет результаты времени, это не фиксированный golden benchmark. Графики Matplotlib 3.10.7 построены из сохранённых JSON, PNG и SVG лежат в evidence/figures. Отключённый сервис после ручных опытов следует восстановить; нагрузочный runner делает это в finally. Подробности, включая временный DB trigger и восстановление после аварийного завершения suite: student-tests/README.md.

Воздействие Наблюдение Сохранность / граница
Остановлена lyakhonov-lab4-api-1 Download через другую API за 1.286 с от начала действия SHA-256 совпал, target реально остановлен
Остановлена lyakhonov-lab4-api-2 Download через другую API за 1.406 с от начала действия SHA-256 совпал, target реально остановлен
Остановка S3 Первый 503 за 4.043 с После восстановления прежние bytes/сессия; при исключении обеих API весь LB недоступен
Рестарт API/БД/Redis/S3/LB StartedAt изменились у всех Подтверждённые данные и прежний токен сохранены
PUT прошёл, INSERT отказал 500 + orphan Reconciler удалил после grace; слепой rollback S3 не применяется
Утрата/порча используемого оригинала missing / API 503 Метаданные/ссылки не удалены; нужен правильный оригинал из backup

В ранних публичных failover-прогонах: 109 подтверждённых записей в каждом, 2 и 3 ошибки перехода, первая успешная запись после начала hook через 2.439 и 2.442 с. Пользовательские операции не выдаются за мгновенный failover. Публичный hook выбирает заданный процесс; отдельный test_operations доказывает остановку обеих именно загрузивших реплик.

Ограничения и источники

Сверка обнаруживает утрату и возвращает состояние после восстановления из внешней копии, но не создаёт потерянные bytes из hash. HTTP только localhost и синтетические данные. Ключевые инварианты предполагают, что все писатели рабочего S3 namespace соблюдают общий протокол блокировки; администратор с root credentials может его нарушить. Обрыв download после отправки headers может оборвать поток: 200 headers сами по себе не гарантируют полный файл, клиент проверяет длину/checksum. Нагрузочные результаты зависят от Docker Desktop, CPU-квот, клиента и dataset; SLA и максимальные RPS не заявляются. Добавлен отдельный application workflow без production secrets/privileged PR trigger.

Использованы собственная лабораторная 3 и материалы курса; FastAPI/Uvicorn/Pydantic, psycopg, Redis, Argon2, boto3/botocore, Pillow (версии в requirements.lock.txt), Matplotlib для графиков. Реализация, проверки, анализ и отчёт подготовлены с помощью Codex. Исходный контракт и публичные проверки преподавателя не ослаблялись.

Первичные источники: Pillow Image / verify / pixel limits, S3 PUT и условная запись, LIST pagination, исходники MinIO, исходники mc, PostgreSQL advisory locks.

Этапы истории: 2e5f5bf — перенос; 4f85fb9 — обязательный минимум; 9dded97 — уровень 4; 6c87ed2 — трек 2, графики и отчёт; последующий коммит сохраняет проверку чистого экспорта и заключительный аудит. Манифест source-файлов использует UTF-8/LF, чтобы перенос строк Windows/Linux не менял контрольные суммы.