27 KiB
Отчёт — лабораторная 4
- Автор, группа: Черненко, БПИ2301.
- Целевая оценка: 5, трек 2 — согласованность двух хранилищ.
- Ветка:
solution/bpi2301-chernenko, основана на исходномmain(ec540a1). В удалённом репозитории отдельной ветки skeleton нет. PR создаёт автор вручную; готовый текст —.github/pull_request_template.md. Commit:git rev-parse HEAD. - Дата испытаний: 6 ноября 2026. Использованы Python/FastAPI, psycopg, boto3, Pillow, Argon2id, PostgreSQL, HAProxy и MinIO. Исходники и инструкции подготовлены с помощью Codex; тесты выполнены на настоящем Docker Compose стенде. Предыдущее личное решение lab3 не предоставлялось: необходимый минимум lab1–3 реализован заново по контракту текущего skeleton, чужой код решения не переносился.
Запуск из чистого clone
Нужны Docker Engine/Desktop в режиме Linux containers, Compose v2 с --wait,
доступ в Интернет для первой сборки и Python 3.9+ на host для управляющего скрипта.
На Windows используется py -X utf8, на Linux/macOS — python3.
Для первой сборки MinIO из исходников желательно 4+ GiB доступной Docker RAM.
Версии: Python 3.12.10, PostgreSQL 17.5-alpine, HAProxy 3.0.11-alpine;
MinIO RELEASE.2025-04-22T22-12-26Z, mc RELEASE.2025-04-16T18-13-26Z,
Go 1.24.2-alpine, Alpine 3.21.3. Прямые Python-зависимости закреплены в
requirements.txt; установленные версии сохраняются в evidence/python-packages.txt.
Официальные готовые образы MinIO/mc при проверке были недоступны, поэтому
infra/Dockerfile.minio и infra/Dockerfile.mc собирают фиксированные upstream tags
через Go module proxy с проверкой Go checksum database.
git clone https://gitea.privcloud.tech/quzzqq/mtusi2026lab4.git
cd mtusi2026lab4
git switch solution/bpi2301-chernenko
python3 scripts/setup.py
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --wait --wait-timeout 180
docker compose exec -T api1 make check validate PYTHON=python
docker compose exec -T api1 make test PYTHON=python BASE_URL=http://lb:8080
python3 scripts/run-all.py
Windows: заменить вызовы python3 ... на py -X utf8 ....
Если секреты создавались контейнером со старыми правами, повторить setup в контейнере:
docker run --rm --mount "type=bind,source=$($PWD.Path),target=/app" -w /app python:3.12.10-slim python scripts/setup.py
setup.py создаёт локальные случайные secrets и .env, не печатает значения,
не заменяет существующие секреты. Каталог secrets закрыт для других host-users,
отдельные файлы доступны непривилегированному пользователю контейнера через mounts.
Ни .env, ни secrets не входят в Git или Docker build context.
Не подменять setup простым копированием логического .env.example: сначала нужны secrets.
Публикуется только LB на loopback. Порт по умолчанию 8080; при конфликте добавить
в .env HOST_PORT=18084 и повторить docker compose up -d. При наших испытаниях
использовался 18084, так как 8080 занят посторонним сервисом. run-all.py
автоматически узнаёт фактический порт через docker compose port lb 8080.
API, PostgreSQL, S3 и административная консоль не публикуют host-порты.
Миграции выполняет одноразовый migrate до API; SQL идемпотентен и защищён
advisory lock. bootstrap создаёт приватный bucket, отдельного S3-пользователя
и ограниченную policy. Повторный запуск bootstrap сохраняет данные и проходит успешно.
Оператор ждёт --wait и HTTP readiness. Первая компиляция MinIO может занять несколько минут.
Полный run-all.py выполняет check/validate/smoke, собственные проверки,
persistence, остановку каждой API, публичный failover, отказы S3 и PostgreSQL,
исследование, загрузки и 30-секундную нагрузку сообщений. Он останавливает только
сервисы Compose project chernenko-lab4, восстанавливает их после испытаний и
сохраняет обезличенные результаты в evidence/. Повтор создаёт новые синтетические данные.
Отдельные публичные сценарии (Linux/macOS; Python на host, Docker CLI доступен):
chmod +x scripts/restart.sh scripts/stop-one.sh
make test-persistence PYTHON=python3 BASE_URL=http://localhost:18084 ACTION_SCRIPT=scripts/restart.sh
docker compose start api1 api2
make test-failover PYTHON=python3 BASE_URL=http://localhost:18084 ACTION_SCRIPT=scripts/stop-one.sh
docker compose start api1 api2
На Windows run-all.py выбирает .cmd hooks. Они делают те же реальные Docker-действия.
restart перезапускает PostgreSQL, MinIO, обе API и LB с volumes; stop-one по
TARGET_INSTANCE_ID останавливает именно соответствующую реплику и оставляет её выключенной.
Для ручного запуска public tests на Windows задайте BASE_URL и используйте
py -X utf8 tests/resilience.py --mode persistence --action-script scripts/restart.cmd.
Безопасная остановка: docker compose down (данные и сессии остаются в volumes).
Восстановление: прежний docker compose up -d --wait с теми же secrets.
Намеренное удаление всех учебных данных этого стенда: docker compose down --volumes.
Эту последнюю команду не использовать для проверки persistence.
Архитектура и решения
Клиент → HAProxy → api1/api2 → PostgreSQL + MinIO. Один uvicorn process на реплику;
балансировка round-robin с HTTP /health/ready каждую секунду. Live проверяет
только процесс; ready — PostgreSQL и доступ к приватному bucket. Оба хранилища
критичны для обязательного синхронного пути. При их общем отказе LB не обещает
обслуживание текстовых операций через исключённые API.
PostgreSQL — источник истины для users, sessions, chats/members, messages, message_attachments, attachments и idempotency. Сессии переживают рестарт, TTL=3600 не продлевается при чтении/рестарте, logout удаляет hash токена. Токен имеет 256 бит случайности, в БД хранится его SHA-256. Пароли — Argon2id (time_cost=2, memory_cost=19456 KiB, parallelism=1), plaintext не сохраняется.
Сообщение, связи и idempotency результат фиксируются атомарно в PostgreSQL.
Advisory lock по user/chat/key исключает дубли между процессами; 24 часа
отсчитываются от успешной записи. Другой body даёт 409, отсутствие attachment_ids
равно пустому массиву. Неопределённый POST messages повторяется с прежним ключом.
Чтение идёт в общую БД без устаревающего кэша. Пагинация keyset по (created_at,id);
cursor содержит ресурс, время, UUID. Snapshot между запросами не гарантируется.
Оригиналы — только messenger-attachments/originals/<UUID>. Filename не образует
путь и не раскрывается как S3 key. Byte-stream ограничен 10 MiB до накопления,
spool после 256 KiB переносится в ограниченный tmpfs; на API допускаются 2 загрузки
и 1 декодирование одновременно. На приём body отведено 20 секунд, очередь
загрузок ждёт до 15 секунд, connect/read S3 — 2/5 секунд без прозрачных retry;
SQL connect=3 секунды, statement=15, lock=10. HAProxy client/server timeout=30 секунд.
Изображение проверяется по формату и полностью декодируется после проверки
40 млн пикселей; оригинал не перекодируется. Download передаёт по 64 KiB через API.
Tmpfs — временная копия для проверки, после запроса не используется для download.
Граница upload: проверка ACL → приём/проверка → shared DB advisory lock → S3 PUT → INSERT Attachment → COMMIT → 201 ready. Общей транзакции S3/SQL нет. При любой неопределённости COMMIT синхронное удаление S3 не выполняется: оно могло бы стереть уже зафиксированный оригинал. Дальнейшая компенсация — операторская сверка.
Reconciler по умолчанию dry-run; запуск:
docker compose exec -T api1 python -m src.reconcile
docker compose exec -T api1 python -m src.reconcile --apply
Оператор сначала оценивает dry-run, затем применяет. Grace по умолчанию 3600 секунд,
минимум 60 — только для контролируемого теста. Полный LIST prefix выполняется до
исправлений, с пагинацией. Exclusive advisory lock согласует сверку с PUT/COMMIT
и привязкой сообщений. Любая запись Attachment защищает объект, даже без Message.
Orphan после grace повторно проверяется через HEAD и SQL и удаляется; missing
старше grace проверяется HEAD 404, метаданные и ссылки сохраняются, внутренний
статус становится failed/missing_object. Неуспех LIST/HEAD/DB прерывает проход.
Повторный запуск безопасен. Восстановление оригинала из копии проверяется по
размеру и SHA-256 перед ready. Сверка сама не восстанавливает потерянные байты.
Публичные успешные Attachment остаются ready согласно контракту; внутренний
failed доступен через 409, после проверки ACL. Детали: contracts/extensions.md.
Соответствие .env.example: APP_HOST/APP_PORT реализованы аргументами uvicorn
0.0.0.0:8080, APP_ENV — только логическое описание; API_REPLICAS=2 реализовано
двумя сервисами; SESSION_STORE=postgres, CACHE_URL_FILE не используется — Redis
не обязателен для минимума предыдущих лабораторных. SESSION_TTL_SECONDS реально
передаётся из .env. IDEMPOTENCY_TTL_SECONDS фиксирован контрактными 86400 секундами.
DATABASE_URL_FILE и оба S3 credential FILE смонтированы как secrets. S3_ENDPOINT,
S3_BUCKET, MAX_UPLOAD_BYTES/MAX_IMAGE_PIXELS заданы в Compose; S3_REGION=us-east-1
берётся по умолчанию. Лимиты можно только уменьшить относительно обязательных максимумов.
Дополнительный HOST_PORT — host-порт LB. Другие логические переменные примера
не выдаются за изменяемые Compose-настройки.
Доказательства критериев
Каждый пункт ниже проверяется python3 scripts/run-all.py; отдельные команды
для app/student-tests выполняются через docker compose exec -T api1 python ....
- Целостность skeleton, OpenAPI:
make check validate PYTHON=pythonвнутри API. Обе проверки PASS —evidence/check-validate.txt. Контракт, README задания, COURSE, CONTRIBUTING и публичные tests не изменялись. - Минимум lab1–3 и обязательный lab4 API:
make test PYTHON=python BASE_URL=http://lb:8080. PASS, включая PNG checksum, attachment-only message, второго участника, 404 для третьего, сессии, пагинацию, idempotency —evidence/smoke.txt. - Реальные PNG/JPEG, лимиты, MIME и filename:
student-tests/acceptance.py. PASS: повреждённые bytes и подмена MIME → 415, >10 MiB и 42 млн пикселей → 413, опасные имена → 400, корректный JPEG скачивается без изменений —evidence/acceptance.json. - Чужой attachment_id и файл другого чата: тот же сценарий, 404. Неверный cursor, UUID, sender_id — 400; 12 одновременных idempotency повторов → 1 Message.
- Потеря API загрузившей реплики: остановка каждой API с последующим download
и записью через вторую. SHA-256/байты совпадают —
evidence/replica-directions.json. - Публичный failover с параллельными POST:
tests/resilience.py --mode failoverс собственным hook. PASS; восстановление ≤10 секунд, нет дубликатов/потерь, остановленная реплика отсутствует в конце —evidence/failover.txt,evidence/after-failover.jsonиevidence/after-failover-started.txt. - Рестарт API и PostgreSQL/MinIO/LB:
tests/resilience.py --mode persistence. PASS, прежняя сессия, сообщения и оригинал сохранены.evidence/persistence.txt,before-restart-started.txt/after-restart-started.txtдоказывают изменение StartedAt всех пяти реальных контейнеров. Volumes не удалялись. - Отказ S3 и PostgreSQL:
student-tests/storage_outage.pyпри реальной остановке зависимости управляющим скриптом. Live=200, ready/upload/download=503, reconciler прекращает работу, после возврата хранилища исходные bytes совпадают —evidence/s3-outage.json,evidence/postgres-outage.json. - Прерванная загрузка: raw TCP request с неполным Content-Length и закрытием
соединения, отсутствие новых метаданных —
evidence/acceptance.json. - Сбой PUT → SQL:
student-tests/research.pyвременно ставит trigger на тестовый filename, реальный API PUT проходит, INSERT падает, HTTP 500 не раскрывает SQL, остаётся ровно один orphan. После grace он обнаруживается и удаляется —evidence/research.json. Trigger удаляется в finally; production failpoints нет. - RAM при ≥10 загрузках: отдельный генератор, 2 размера, по 3 серии × 10,
20 ms cgroup/RSS sampling обеих API и Docker CPU stats —
evidence/uploads.json,evidence/memory-peaks.json,evidence/memory.json. - Private bucket, scoped S3 credentials, закрытая консоль: анонимный GET существующего
объекта → 403; API-пользователь не может создать bucket —
evidence/acceptance.json. Публикация только LB подтверждаетсяcompose.yamlиevidence/final-state.json. Bootstrap выполнен повторно без удаления данных; вывод —evidence/bootstrap.txt. - Законченный трек 2: dry-run не меняет orphan, apply удаляет старый orphan,
свежий и используемый оригиналы сохраняются, повтор не повторяет удаление,
missing не выдаётся как ready, неверная копия не публикуется, правильная
восстанавливается с прежними bytes, >1000 объектов обходятся несколькими LIST —
evidence/research.json. Стоимость измерена, ограничения приведены ниже.
Эксперименты и отказы
Гипотеза трека 2: shared/exclusive DB locks, повторная проверка и grace позволяют безопасно убрать неучтённые старые S3-объекты и пометить missing без удаления живых метаданных; повторный проход не порождает новые повреждения.
Методика: создать synthetic chat и ready-вложения, одно привязать к Message. Внедрить SQL-ошибку в реальный upload после PUT и отдельно удалить оригинал второго ready-вложения. Проверить fresh orphan до grace, выждать настоящие 62 секунды S3-времени, создать ещё один свежий orphan, сравнить dry-run/apply/repeat. Missing-метаданные искусственно состарены на 2 часа SQL-командой в тесте, S3 LastModified не подделывается. Затем проверить плохую/правильную резервную копию. Добавить 1005 fresh keys по одному байту для проверки LIST pagination, замерить время и число запросов, убрать только точные служебные ключи этого сценария. Используемое вложение сохраняется побайтно после каждого ремонта.
Результаты трека, нагрузки и памяти записаны отдельным воспроизводимым
численным итогом в evidence/SUMMARY.md; исходные JSON остаются рядом.
Это измерения конкретного локального стенда, а не обещание производительности.
Окружение: Docker Desktop Linux VM, 16 vCPU, 7 950 495 744 bytes RAM,
API по 1 CPU / 512 MiB, /tmp по 64 MiB, PostgreSQL и MinIO по 512 MiB,
LB 64 MiB. Host Python — 3.14.3, внутри контейнеров — 3.12.10.
Перед тестами readiness подтверждена, изображения прогреваются одной загрузкой
каждого размера. PNG генерируются из случайных RGB bytes (размеры приблизительно
0,75 MiB и 9,28 MiB; точные bytes в JSON). По 3 closed-loop burst-серии на размер,
concurrency=10, всего 60 измеряемых успешных загрузок плюс 2 прогревочных.
Генератор работает отдельным временным контейнером migrate, его RAM не входит
в измеряемые API. Duration, successful RPS, errors и p50/p95/p99 каждой серии
находятся в uploads.json. При n=10 p95 и p99 — максимальная задержка серии.
Память: memory-peaks.json содержит baseline, максимум memory.current с шагом
20 ms, RSS PID 1 и kernel memory.peak до/после. Последний — максимум за всё время
жизни контейнера, включая предыдущие тесты; его нельзя выдавать за чистый пик
только загрузок. Sampling может пропустить короткий всплеск. Небольшой probe
работает в том же cgroup и добавляет собственный overhead. docker stats
из memory.json содержит CPU и контрольный замер RAM с более редким шагом.
Отдельно tests/load.py --duration 30 --concurrency 4 измеряет POST messages,
не изображения. JSON включает successful RPS, долю ошибок, p50/p95/p99 успешных
ответов. Этот closed-loop тест имеет coordinated omission и ограничения клиента;
не определяет максимальную мощность сервера. Запуски добавляют данные, поэтому
размер набора растёт; для сравнения на чистом наборе нужен отдельный volume.
Отказы: API-восстановление ожидается за ≤10 секунд; public test подтвердил это. Рестарт всех сервисов сохраняет подтверждённые данные и действующий токен. S3/PostgreSQL outages честно дают 503 до ручного возврата зависимости, без обещания HA. Orphan исправляется только явным запуском после grace; missing требует backup. В эксперименте не потеряны подтверждённые сообщения или исходные bytes, кроме специально удалённого S3-объекта, который восстановлен из тестовой копии.
Ограничения и следующие шаги
Один host, один PostgreSQL, один MinIO и один LB — единые точки отказа. Нет репликации БД/S3, автоматических резервных копий и восстановления потерянного диска; API failover не доказывает устойчивость ко всем инфраструктурным отказам. HTTP допустим только локально с синтетическими данными; для удалённого показа нужен TLS. UI, presigned flow, thumbnail/worker lab5 не входят в выбранную работу.
Reconciler удерживает exclusive lock на время полного прохода, хранит метаданные и LIST в RAM: стоимость O(A+O), время LIST ≈ceil(O/1000), дополнительные HEAD только для кандидатов. Восстановление failed читает файл для проверки checksum. На большом bucket это мешает записи; statement/lock timeout ограничивает ожидание, но весь проход не имеет отдельного wall-clock SLA. Для production нужна пакетная сверка с журналом/lease, отдельными правами оператора и метриками. Этого улучшения данные опыта не доказывают. Внешний root-оператор S3 может обойти DB lock: ручное восстановление согласовывать с обслуживанием.
Сверка не ищет побитовую порчу уже ready-файлов и не удаляет корректные, но давно не привязанные вложения. Это сознательные границы orphan/missing-трека. Глобальная корректность конкурентной истории при коррекции часов не гарантируется: между страницами нет snapshot, поздний COMMIT может попасть до cursor. Expired sessions и неиспользуемые просроченные idempotency rows не очищаются периодическим job; это следующий эксплуатационный шаг, expiry при доступе действует. Попытки входа не rate-limit-ятся. Полная защита lab7 здесь не заявляется.
Источники и подготовка к защите
- Нормативная семантика skeleton, COURSE.md.
- Psycopg: транзакции и context manager.
- MinIO upstream tags и исходники.
- MinIO: policy create/attach.
- Pillow: ограничения декодирования.
- S3: загрузка объектов.
Развёрнутые ответы на все вопросы README, объяснение основных функций и порядок демонстрации — DEFENSE.md. Использование ИИ раскрыто выше; автору необходимо самостоятельно понимать код и уметь изменить его на защите.