24 KiB
Отчёт — лабораторная 4
- Автор, группа: Кушнаренко Николай Вячеславович, БПИ2302
- Целевая оценка; выбранный трек 5, если нужен: 5, трек 2 «Согласованность двух хранилищ»
- Commit/PR: ветка
solution/bpi2302-kushnarenkoв форке kolya; ссылка на PR добавляется после открытия - Использованные источники, библиотеки и помощь ИИ: Python 3.12, uvicorn, asyncpg, aiobotocore (S3), Pillow (проверка изображений), argon2-cffi; SeaweedFS 4.48 (S3); HAProxy; PostgreSQL; Valkey. Код lab3 перенесён. ИИ-ассистенты использовались для помощи с кодом, тестами и отчётом; Codex проверил подготовку к сдаче, усилил проверки исследования и выполнил реальные запуски 11.11.2026
Запуск из чистого clone
Prerequisites: Docker Compose v2, bash (Git Bash на Windows), Python ≥ 3.9; на Windows PYTHONUTF8=1 для tests/*.py.
Версии: python:3.12.12-slim-bookworm@sha256:593bd06e…, postgres:17.11-alpine@sha256:b0f9560a…, valkey/valkey:8.1.10-alpine@sha256:081c2f5c…, haproxy:3.0-alpine@sha256:56b887da…, chrislusf/seaweedfs:4.48@sha256:4e61d15f…, зависимости — requirements.txt (закреплены, включая aiobotocore==3.9.2, pillow==12.3.0).
sh scripts/init-secrets.sh # secrets/*: пароль БД, ключи S3 (admin и отдельные ключи API), seaweed_s3.json
cp .env.example .env
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build # postgres, valkey, seaweedfs -> migrate + s3-init (один раз) -> api x2 -> lb
curl http://127.0.0.1:8080/health/ready
python3 tests/smoke.py --base-url http://127.0.0.1:8080
python3 tests/resilience.py --mode persistence --action-script scripts/restart.sh --base-url http://127.0.0.1:8080
python3 tests/resilience.py --mode failover --action-script scripts/stop-one.sh --base-url http://127.0.0.1:8080
sh scripts/restore-replicas.sh
# собственные тесты (стенд должен быть запущен)
python3 -m unittest discover -s student-tests -p "test_api.py" -v
python3 -m unittest discover -s student-tests -p "test_attachments.py" -v
python3 student-tests/test_idempotency.py
python3 student-tests/test_topology.py
python3 student-tests/test_s3_failures.py
python3 student-tests/test_expiry.py
python3 student-tests/test_dependencies.py
Windows: scripts/restart.cmd и scripts/stop-one.cmd вместо .sh. Остановка с сохранением данных — docker compose --env-file .env stop; намеренное удаление учебных данных — docker compose --env-file .env down -v (volumes pgdata, valkeydata, seaweeddata).
Выбор S3-сервера. Используется SeaweedFS, разрешённый заданием. Образ закреплён тегом и digest. SeaweedFS запускается одним процессом (weed server -filer -s3), права задаются файлом identities (secrets/seaweed_s3.json).
Архитектура и решения
Клиент ─▶ HAProxy ─▶ API ×2 ─▶ PostgreSQL (метаданные вложений, сообщения, сессии, ключи идемпотентности)
├─▶ SeaweedFS S3 (приватный bucket, байты вложений) [volume seaweeddata]
└─▶ Valkey (кэш сессий)
| Роль | Сервис | Health | Volume | Сеть | Credentials |
|---|---|---|---|---|---|
| S3 | seaweedfs (master+volume+filer+S3) |
wget …:9333/cluster/status и nc -z :8333 |
seaweeddata |
только backend, порты не опубликованы, консоли/админки наружу нет |
seaweed_s3.json (secret) |
| bootstrap | s3-init (one-shot) |
код выхода 0 | — | backend |
admin-ключи (только он), ключи API для проверки |
| остальные роли | как в lab3 |
- Данные. Метаданные — таблицы
attachments(id, chat_id, owner_id, display filename, content_type, size, sha256, status, error_code, s3_key, …) иmessage_attachments (message_id, attachment_id, position); байты — в S3 под ключомatt/<uuid>/original, который назначает сервер;filenameиспользуется только как отображаемое имя и нигде не входит в путь/ключ. Байты не хранятся ни в БД, ни в локальном каталоге API (временный буфер загрузки —SpooledTemporaryFile, удаляется после запроса). - Загрузка (
POST /chats/{id}/attachments?filename=…, сырые bytes): авторизация → членство (чужой чат 404) →filename(1–255 code points;/,\, NUL, управляющие символы → 400) →Content-TypePNG/JPEG (иначе 415) → размер ≤ 10 MiB проверяется поContent-Lengthдо чтения и по счётчику при потоковом приёме (413, соединение закрывается) → тело принимается порциями (до 1 MiB в RAM, далее временный файл) с подсчётом SHA-256 → проверка изображения до полной распаковки: сигнатура PNG/JPEG должна совпасть с заявленным типом (подмена MIME → 415), формат и размеры по заголовку Pillow, >40 млн пикселей → 413 (decompression bomb отклоняется по заголовку), целостность: PNG — CRC всех чанков (verify) + потоковая распаковка IDAT с проверкой конца потока и ожидаемого размера данных, JPEG — декодирование в режиме draft (≈1/64 памяти) → запись в S3 → строка в PostgreSQL (status=ready,201). Ограничение одновременных загрузок на реплику (UPLOAD_CONCURRENCY=4, очередь 16, далее429). - Скачивание (
GET /attachments/{id}/content,?variant=original|thumbnail|crop|optimized): авторизация → доступ по членству в чате вложения (постороннему/несуществующему — 404 без различий) → потоковая отдача из S3 порциями по 64 КиБ с истиннымContent-Type,Content-Length,X-Content-Type-Options: nosniff, без redirect; недоступный S3 →503; несуществующий вариант → 404; невалидныйvariant→ 400. - Сообщения:
attachment_ids(0–10 уникальных UUID, по умолчанию[]; пустой текст допустим только с вложением). Вложение другого чата/неизвестное/чужое → 404; дубликаты, >10 → 400; идемпотентный повтор учитываетattachment_ids(нормализованное тело: порядок ключей JSON и отсутствие поля ==[]). Проверка вложений и вставка — внутри той же серверной функцииsend_message(миграция 0004), то есть атомарно. - Readiness API = PostgreSQL. S3 в readiness не включён осознанно: при падении S3 текстовые сообщения продолжают работать (проверено тестом), вложения отвечают
503 + Retry-After.
Согласованность S3 и PostgreSQL (механизм компенсации и сверки — уровень 4)
Порядок записи: сначала объект в S3, затем строка в PostgreSQL. Окна отказа:
| Сбой | Результат | Исправление |
|---|---|---|
| Клиент оборвал загрузку | ни объекта, ни строки (проверено тестом) | — |
| S3 недоступен | 503, строка не создаётся | — |
| Сбой БД после записи в S3 | клиент получает ошибку; объект удаляется компенсацией сразу (проверено внедрением сбоя FAULT_INJECTION=db_after_put) |
компенсация |
| Сбой БД и неудача удаления (или крах процесса между S3 и COMMIT) | «осиротевший» объект без строки | reconciler python -m app.reconcile |
Reconciler (src/app/reconcile.py): по умолчанию dry-run; сравнивает attachments.s3_key и листинг bucket. Находит: orphan_object (объект без строки; удаляется только если старше grace — по умолчанию 900 с, поэтому свежая, ещё не зафиксированная загрузка не затрагивается), missing_object (строка ready без объекта → failed/object_missing, строка не удаляется, сообщения сохраняются, скачивание даёт 409), size_mismatch (размер объекта ≠ size_bytes → failed/size_mismatch). Объект, у которого есть строка в БД, не удаляется никогда; перед удалением выполняется повторная проверка строки. Повторный запуск идемпотентен.
Исправление отказа общей БД при подготовке к сдаче
В первом повторе 11.11.2026 тест остановки PostgreSQL обнаружил ответ вне JSON-контракта: после отрицательного readiness всех реплик HAProxy отдавал собственную ошибку вместо ответа приложения. Добавлен резервный backend по liveness, используемый только при отсутствии ready-реплик. Теперь живое приложение возвращает 503 с Retry-After и X-Request-Id, сохраняет 401 для запроса без токена и 200 для /health/live. Основная маршрутизация по readiness сохранена. Тест ждёт 5 с после остановки БД, чтобы гарантированно покрыть состояние после healthcheck балансировщика.
Также автоматические повторы HAProxy ограничены ошибкой установления соединения: ответ/таймаут уже отправленного upload POST не повторяется, поскольку контракт не делает загрузку идемпотентной. Описание директив: HAProxy 3.0 Configuration Manual. Первичный сбой сохранён в evidence/checks_before_fix_2026-11-11.txt; полный итоговый прогон — в evidence/checks_2026-11-11.txt.
Доказательства критериев — повторная проверка 11.11.2026
Проверены текущая ветка решения и исходный skeleton ec540a1. README задания, COURSE, CONTRIBUTING, публичные tests/ и contracts/ сохранены без изменений. Команды и фактический вывод: evidence/checks_2026-11-11.txt. В Windows выполнены Python-команды, соответствующие make check, make validate и make test; GNU Make для проверки не требуется.
| Критерий | Проверка | Результат |
|---|---|---|
| Контракт и публичный сценарий | check_contract, validate_openapi, smoke | PASS |
| API, авторизация и идемпотентность между репликами | test_api + test_idempotency | 12 + 9 тестов OK |
| Изображения, лимиты, MIME, filename, ACL, чужой чат, прерывание upload, private bucket | test_attachments | 11 тестов OK; пользовательские ошибки не дают 500; анонимный S3 GET → 403 |
| Реплики, порты, лимиты, непривилегированный пользователь | test_topology | 6 тестов OK |
| Компенсация, dry-run/apply, свежие orphan, используемые вложения, отказ S3 | test_s3_failures | 4 теста OK; защищённый файл связан с сообщением, ссылка сохранена |
| Истечение сессии, недоступность PostgreSQL и Valkey | test_expiry + test_dependencies | 2 + 2 теста OK |
| Сохранность при restart и остановке обслужившей реплики | tests/resilience.py | persistence/failover PASS; восстановление записи 2.329 с, 105 успешных записей, 0 неуспешных попыток |
| Идемпотентный bootstrap, отдельные ограниченные ключи API | два повторных запуска s3-init | существующий bucket сохранён; anonymous → 403; create_bucket ключом API → AccessDenied |
| ≥10 параллельных загрузок и пик памяти | research/upload_memory.py | 12 клиентов; все файлы приняты и SHA-256 совпали; OOM нет |
| Трек 2: обнаружение и исправление расхождений, стоимость обхода | research/reconcile_bench.py | 20 orphan / 20 missing / 5 size mismatch; безопасное исправление и повтор без изменений |
Всего 46 собственных тестов. После экспериментов дополнительно повторены persistence и smoke. В lifecycle.json зафиксировано изменение StartedAt всех сервисов (включая обе API-реплики и S3), сохранение имён volumes и healthy после restart.
Эксперименты и отказы (трек 2)
Гипотеза. Reconciler находит внедрённые расхождения в обе стороны; dry-run ничего не меняет; apply удаляет только старые объекты без строки в БД, помечает потерянные/повреждённые вложения failed и сохраняет свежие объекты и файлы сообщений. Повтор apply не вносит изменений. Стоимость полного обхода увеличивается с числом объектов.
Методика и окружение. Windows, Docker Desktop с Linux-контейнерами, Python клиента 3.11.9, aiohttp 3.14.3, Pillow 12.3.0; приложение — Python 3.12.12. Образы и лимиты закреплены в compose.yaml. Во время исследования на машине оставался другой Docker-проект; абсолютные времена зависят от фоновой нагрузки. Один измерительный прогон на точку, статистическая значимость различий не оценивалась. Команды воспроизведения — student-tests/README.md.
В клиенте исследования сверки отключено повторное использование HTTP-соединений: блокирующий вызов Docker мог длиться дольше keep-alive сервера, и первая попытка остановилась с ServerDisconnectedError до внедрения расхождений. После исправления выполнен полный повтор сверки; исходный вывод сохранён в evidence/recheck_2026-11-11/commands_before_client_fix.txt. Замеры памяти не повторялись: они завершились успешно и не зависели от этого клиента. SHA-256 проверенных исходников записаны в source_metadata.json рядом с результатами.
Память при одновременных загрузках
12 клиентов загружают по 8.73 MiB PNG (шум 1700×1700). Для каждой точки создаётся одна новая API-реплика, 1 CPU / 256 MiB; меняется только UPLOAD_CONCURRENCY. Пик — VmHWM процесса API, это не суммарная память всех контейнеров. После измерения каждый принятый файл скачивается и проверяется SHA-256. В конце восстановлены две реплики с UPLOAD_CONCURRENCY=4.
| UPLOAD_CONCURRENCY | Пик RSS, MiB | Загрузка всех файлов, с | Принято и цело | OOMKilled |
|---|---|---|---|---|
| 1 | 99.2 | 1.31 | 12/12 | false |
| 4 | 119.0 | 1.18 | 12/12 | false |
| 12 | 121.2 | 1.14 | 12/12 | false |
Сверка двух хранилищ
К существующим синтетическим данным добавлены 3000 вложений тремя порциями по 1000. После каждой порции измерен dry-run. Затем созданы 20 orphan в S3, удалены объекты 20 существующих вложений и изменён размер ещё 5. 200 других вложений прикреплены к 20 сообщениям (по 10); перед исправлением сохранены идентификаторы сообщений и их attachment_ids.
После паузы больше 5 с выполняются два dry-run, затем apply с grace=5 параллельно с задачей загрузки 200 новых файлов, затем повторный apply. Рабочее значение grace — 900 с; короткий grace используется только в эксперименте. Отдельный тест детерминированно оставляет свежий orphan и подтверждает, что --apply --grace 900 его не удаляет.
| Проверка | Фактический результат |
|---|---|
| dry-run ×2 | ровно 20 orphan, 20 missing, 5 size mismatch; fixed=0/0; повторяемо |
| apply | удалено 20 старых orphan, 25 строк помечены failed (20 object_missing, 5 size_mismatch) |
| Новые загрузки | 200/200 приняты и скачаны с совпадающей SHA-256 |
| Вложения сообщений | 200/200 целы; все 20 сообщений и attachment_ids неизменны |
| Повтор apply | 0 удалений, 0 изменений статусов, новых расхождений нет |
| Строк БД | Объектов S3 | Запрос БД, мс | Листинг S3, мс | Весь обход, мс |
|---|---|---|---|---|
| 19554 | 19530 | 20.2 | 3540.6 | 3649.4 |
| 20554 | 20530 | 19.0 | 3697.2 | 3806.4 |
| 21554 | 21530 | 21.2 | 3939.1 | 4055.0 |
На проверенном наборе основную стоимость даёт листинг S3; результаты трёх точек не доказывают линейное время на произвольном объёме. Алгоритм хранит снимки метаданных и листинга в памяти: время и дополнительная память — O(N). Сырой результат: upload_memory.json, track2_reconcile.json; вывод команд — commands.txt.
Границы. Сверяются наличие и размер, но не содержимое S3-объектов: подмена байтов без изменения размера этим reconciler не обнаруживается. Целостность контрольных файлов подтверждает скачивание с SHA-256. Потерянные байты не восстанавливаются, строка остаётся failed. Grace должен превышать время загрузки и таймаутов; для рабочих запусков принят 900 с. S3 и PostgreSQL — по одному узлу. Старые октябрьские результаты сохранены в evidence/checks.txt, evidence/upload_memory.json и evidence/track2_reconcile.json; текущие выводы опираются на повтор 11.11.2026.
Отказы
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|---|---|---|---|
| Остановка S3 | загрузка/скачивание 503 + Retry-After, текст работает, ready=200 |
OK (test_s3_down…) |
после старта S3 — сразу; метаданные не накапливают «битых» строк |
| Остановка одной реплики после upload | файл скачивается другой репликой | failover PASS (восстановление записи 2.329 с) | потерь нет |
| Рестарт всего стенда | метаданные и оригинал на месте | persistence PASS | < 90 с |
| Сбой БД после записи в S3 | объект не остаётся | удаляется компенсацией; при сбое компенсации — reconciler | потерь подтверждённых данных нет |
Ограничения и следующие шаги
- Один узел S3 и один PostgreSQL (SPOF); репликации нет. Загрузка проксируется через API (прямые подписанные URL не реализованы — трек 1 не выбран).
- Проверка содержимого JPEG — декодирование в режиме draft (1/8), PNG — потоковая проверка; полная валидация пикселей не выполняется (это не нужно для отдачи оригинала).
- Подтверждено экспериментом: обнаружение/исправление расхождений, защита свежих и используемых вложений, стоимость обхода на трёх размерах набора, ограничение памяти при 12 одновременных загрузках. Гипотеза без доказательства: поведение reconciler на бакетах > 100 тыс. объектов.