16 KiB
Отчёт — лабораторная 4
- Автор, группа: Казанцева Виктория / БПИ2301
- Целевая оценка; выбранный трек 5: 5, трек 2 — согласованность PostgreSQL и S3
- Commit/PR: mtusi2026/mtusi2026lab4#88
- Источники и библиотеки: контракт репозитория, документация S3 и MinIO; FastAPI, uvicorn, asyncpg, argon2-cffi (Argon2id), boto3, Pillow.
Запуск из чистого clone
Машина проверки: Windows, Docker Desktop 29.2.1, CPU Intel i7-12650H, 16 ГБ RAM. Лимит каждой API-реплики — 768 МиБ. Публичные тесты на Windows нужно запускать с PYTHONUTF8=1: tests/client.py читает OpenAPI через Path.read_text() без кодировки.
Образы, все с фиксированной версией или digest:
| Роль | Образ | Digest |
|---|---|---|
| API | python:3.12-alpine@sha256:d09d15e60962ca365d1cd544a48773bac9d33f2fb1b00f2aa0deec78ade7dc31 |
Python 3.12.14 внутри контейнера |
| PostgreSQL | postgres:16.8-bookworm |
sha256:301bcb60b8a3ee4ab7e147932723e3abd1cef53516ce5210b39fd9fe5e3602ae |
| S3 | minio/minio:RELEASE.2025-09-07T16-13-09Z |
sha256:14cea493d9a34af32f524e538b8346cf79f3321eff8e708c1e2960462bd8936e |
| Клиент bootstrap | mc RELEASE.2025-08-13T08-35-41Z, скопирован из образа MinIO |
тот же digest MinIO |
| Балансировщик | haproxy:2.8.14-alpine |
sha256:72030a2e37d5c5790e13387da24f890bf860b8dfef10fab1b1fd0fd2e974ff75 |
Порты MinIO, включая консоль :9001, наружу не публикуются. Снаружи только 127.0.0.1:8080 балансировщика.
python scripts/init_env.py
docker compose --env-file .env up -d --build
scripts/init_env.py создаёт локальный .env и не перезаписывает существующий. Секреты в отчёт и git не входят. Схема создаётся при старте API из infra/migrate.sql под advisory lock. Bucket и пользователь API создаёт одноразовый s3-init (infra/bootstrap-s3.sh); повторный запуск идемпотентен.
Дождаться GET /health/ready → 200 {"status":"ok"}. Затем:
python tests/smoke.py --base-url http://127.0.0.1:8080
python tests/resilience.py --mode persistence --action-script scripts/restart.sh --base-url http://127.0.0.1:8080
python tests/resilience.py --mode failover --action-script scripts/stop-one.sh --base-url http://127.0.0.1:8080
На Windows тот же сценарий выполняет scripts/restart.exe и scripts/stop-one.exe (исходник scripts/labhook.cs): команды совпадают с .sh, потому что subprocess не запускает shell-скрипт. После failover остановленную реплику возвращают отдельно: docker compose --env-file .env start api-1 api-2.
Остановка без удаления данных: docker compose --env-file .env down. Учебные volume удаляет только явная команда docker compose --env-file .env down -v.
Архитектура и решения
Клиент → HAProxy (lb, round-robin, проверка /health/live) → api-1 и api-2 → PostgreSQL и приватный bucket MinIO.
Из lab3 сохранены регистрация, Argon2id-сессии в PostgreSQL, чаты, keyset-история, Idempotency-Key с advisory lock на пользователя+метод+путь+ключ и заголовок X-Instance-Id (api-1 / api-2). Сессии и сообщения переживают рестарт, TTL сессии рестарт не продлевает.
Вложение: байты лежат в S3 по ключу o/<uuid>, который назначает сервер. filename только отображаемое имя. Метаданные, связь с чатом и ссылки из сообщений — в PostgreSQL. У API нет volume. 201 возвращается после успешного PUT и COMMIT строки attachments вместе с переводом ledger в committed. Если PUT прошёл, а commit нет, процесс удаляет объект и помечает ledger aborted. Если удаление тоже не удалось, объект остаётся staging: reconciler заберёт его только после grace period 120 секунд. Свежий staging не трогается, потому что загрузка может ещё идти.
Переменные .env.example отображаются так: DATABASE_URL собирается в Compose из POSTGRES_*; S3_ENDPOINT=http://minio:9000 только во внутренней сети; ключ API — S3_ACCESS_KEY_ID / S3_SECRET_ACCESS_KEY. Root MinIO есть у minio и s3-init, у процесса API его нет. Политика пользователя API: GetObject, PutObject, DeleteObject на объекты bucket и ListBucket/GetBucketLocation на сам bucket.
Пароль: Argon2id, time_cost 2, memory 19 МиБ, parallelism 1. Для отсутствующего пользователя выполняется verify фиктивного хеша.
Курсор истории — непрозрачная строка с chat_id. Чужой чат даёт 400. Порядок (created_at, id). Снимок между запросами не обещается: created_at берётся из clock_timestamp() в момент вставки.
Чтение изображения ограничено 10 МиБ до разбора. Число пикселей читается из заголовка PNG/JPEG и сравнивается с 40 млн до Pillow. Полный load() делается только до 1 млн пикселей, чтобы одна загрузка не разворачивала 40-мегапиксельный буфер. Файл на время проверки пишется во временный файл контейнера и удаляется; каноническая копия — объект S3.
/health/live не смотрит зависимости. /health/ready требует SELECT 1 и доступность bucket. Балансировщик проверяет live, поэтому остановленный процесс выпадает из пула, а живой процесс при недоступном S3 продолжает отвечать 503 на ready.
Доказательства критериев
| Критерий | Команда | Результат | Файл |
|---|---|---|---|
| Публичный smoke | python tests/smoke.py --base-url http://127.0.0.1:8080 |
PASS: lab4 public API scenario на финальной сборке |
вывод команды |
| Контракт skeleton | python scripts/check_contract.py |
PASS: offline skeleton structure |
вывод команды |
| JPEG, checksum, участник чата | python tests_student/negative.py |
201, SHA-256 совпал, скачивание вторым участником побайтово |
вывод PASS: negative... |
| Слишком большой файл | тот же прогон | 413 payload_too_large |
там же |
| Повреждённый PNG и подмена MIME | тот же прогон | 415 unsupported_media_type, не 500 |
там же |
| Опасные filename | тот же прогон | 400 invalid_request |
там же |
| Чужой attachment и файл другого чата | тот же прогон | 404 not_found для метаданных, байтов и attachment_ids |
там же |
| Пиксельная бомба 20000×20000 | тот же прогон | 413 до декодирования |
там же |
| Параллельный idempotency | python tests_student/idempotency_race.py |
8 повторов, один id в истории | PASS: eight parallel... |
| Приватный bucket | python tests_student/private_bucket.py |
анонимные GET и List → 403; порты MinIO не опубликованы; у API нет mounts и нет MINIO_ROOT_USER |
вывод команды |
| 10 одновременных загрузок | python scripts/memory_experiment.py |
10/10 для 12420 байт и для 3241218 байт | evidence/memory.json |
| Reconciler, трек 2 | python scripts/reconcile_experiment.py |
dry-run 2 действия, повторный dry-run 0; свежий orphan и in-use metadata сохранены | evidence/reconcile.json |
| Недоступность S3 | python scripts/s3_outage.py |
live 200, ready 503, после start тот же SHA-256 |
evidence/s3_outage.json |
| Рестарт с volume | tests/resilience.py --mode persistence --action-script scripts/restart.exe |
PASS: persistence preserved confirmed data and existing session |
вывод команды |
| Отказ одной реплики | tests/resilience.py --mode failover --action-script scripts/stop-one.exe |
до отказа 2 реплики; 106 успешных записей, 1 ошибка; первое восстановление 2.390 с; PASS |
вывод команды |
Память. Гипотеза: десять загрузок не занимают неограниченную RAM, потому что тело режется лимитом 10 МиБ, пишется во временный файл чанками и не декодируется в bitmap, если пикселей больше 1 млн. Волна 12 КиБ заняла около 0.37 с, пик docker stats 56.2 и 57.2 МиБ, VmHWM около 73 МиБ и за волну не вырос. Волна 3.24 МиБ × 10 заняла 0.74 с. Пик docker stats 65.2 МиБ на api-1 и 53.6 МиБ на api-2. VmHWM вырос с 74892 до 77184 КиБ и с 74776 до 76492 КиБ, то есть примерно на 2 МиБ на процесс, а не на 10 × 3.24 МиБ. Ограничение измерения: волна короче секунды, docker stats снимался каждые 0.25 с и включает page cache; VmHWM — честный максимум RSS процесса после рестарта перед волной.
Трек 2. Гипотеза: полный обход с grace 120 с удаляет только просроченный orphan и метаданные без объекта, на которые не ссылается сообщение; повторный запуск ничего не удаляет. Методика: через API сохранены свежее вложение в сообщении и свежее вложение без сообщения; app.admin inject добавил свежий staging-объект, staging возрастом 2 часа, строку без объекта возрастом 2 часа и такую же строку, на которую ссылается сообщение. Dry-run увидел 27 объектов за 1 страницу ListObjects, 129.4 мс, из них 127.2 мс — список S3 и 2.0 мс — запросы к PostgreSQL. Действия: удалить old-orphan и fault-stale-missing. Пропущены fresh_orphan и in_use_missing. Apply повторил те же два действия за 154.3 мс. Второй dry-run: action_count=0, объектов 26. Скачивание свежего вложения из сообщения совпало с fixture. Ограничения: это полный обход одного bucket, не инкрементальный; возраст orphan считается по ledger, потому что LastModified MinIO из лаборатории не переписывается; пропавшие байты используемого вложения не восстанавливаются, строка остаётся, content отвечает 404; reconciler запускается оператором, а не постоянным циклом.
Эксперименты и отказы
| Воздействие | Что ожидаем | Что наблюдали | Восстановление |
|---|---|---|---|
| Рестарт API, PostgreSQL, MinIO и LB с сохранением volume | прежний токен, сообщение и байты вложения | PASS публичного persistence-теста | стек снова ready, данные на месте |
stop реплики, обслужившей пробный POST |
запись продолжается через вторую реплику, подтверждённые сообщения без дублей | 2 реплики до отказа, 106 успехов, 1 ошибка, восстановление 2.390 с, остановленная реплика не в последних ответах | реплика остаётся остановленной, пока её явно не запустить |
| Остановка MinIO | live 200, ready 503, после старта те же байты | именно так | оригиналы в volume MinIO |
Один Docker-host не переживает потерю этой машины. Один PostgreSQL и один MinIO не являются отказоустойчивой парой. Эксперимент показывает потерю одной API-реплики и краткую недоступность S3, не потерю диска.
Ограничения и следующие шаги
Пользовательские ошибки загрузки остаются 400/404/413/415. Полный decode сознательно ограничен 1 млн пикселей: файл до 40 млн пикселей принимается после заголовка и verify(), но редкое повреждение большого файла может быть не поймано так же строго, как у маленького. Grace 120 с защищает незавершённую загрузку и одновременно откладывает уборку мусора на этот срок. Секреты живут в локальном .env, не в образе.
Ответы, которые пригодятся на защите
Файл в volume одной API-реплики не равен объектному хранилищу: у второй реплики этого диска нет, рестарт контейнера без общего volume его теряет, а bucket с собственным volume читают обе реплики.
201 честно отдаётся только когда объект уже записан в S3 и строка метаданных закоммичена. До commit клиент получает ошибку и может повторить загрузку отдельным запросом: у загрузки нет Idempotency-Key.
Если S3 PUT прошёл, а COMMIT нет, ответ не 201. Компенсация удаляет объект. Если удалить не удалось, reconciler после 120 с видит staging без строки attachments и удаляет объект. Повторный dry-run после apply пустой.
Случайный ключ и закрытый bucket не заменяют ACL: любой авторизованный пользователь, не состоящий в чате, должен получать 404 и на метаданные, и на байты. Проверка членства делается в API. Анонимный GET в MinIO и так отвечает 403, это отдельная граница.