18 KiB
Отчёт — лабораторная 4
- Автор, группа: [ФИО], [группа]
- Целевая оценка; выбранный трек 5, если нужен: 5, трек 2 «Согласованность двух хранилищ»
- Commit/PR: локальный коммит ветки
solution/lab4; PR — после публикации - Использованные источники, библиотеки и помощь ИИ: Python 3.12, uvicorn, asyncpg, aiobotocore (S3), Pillow (проверка изображений), argon2-cffi; SeaweedFS 4.48 (S3); HAProxy; PostgreSQL; Valkey. Код lab3 перенесён. Использование ИИ: [заполняется автором]
Запуск из чистого 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
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-сервера. Образы MinIO в Docker Hub (minio/minio, minio/mc) недоступны для скачивания на момент выполнения (репозиторий не найден, проверено docker pull), поэтому воспроизводимый стенд построен на SeaweedFS (разрешён README): образ закреплён тегом и 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). Объект, у которого есть строка в БД, не удаляется никогда; перед удалением выполняется повторная проверка строки. Повторный запуск идемпотентен.
Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|---|---|---|---|
| Smoke lab4 (загрузка, checksum, чужой пользователь) | tests/smoke.py |
PASS | evidence/checks.txt |
| Байты в приватном bucket, метаданные в PostgreSQL | описание; test_bucket_is_private_outside_the_api |
анонимный GET объекта из сети стенда → 403; в БД нет bytea | evidence/checks.txt |
| PNG/JPEG ≤10 MiB, ≤40 млн px, MIME по содержимому, опасный filename | student-tests/test_attachments.py |
11 тестов OK (413, 415 ×9 вариантов, 400 ×8 вариантов filename) | evidence/checks.txt |
| Upload → остановка реплики → download через другую; restart с сохранением volumes | tests/resilience.py failover ×2 и persistence |
PASS; StartedAt seaweedfs/postgres/valkey/api изменился |
evidence/checks.txt |
| Отдельные тесты (слишком большой, повреждённый, подмена MIME, чужое attachment_id, вложение другого чата) | test_attachments.py |
OK; ни один случай не приводит к 500 | evidence/checks.txt |
| Прерывание загрузки / отказ между S3 и БД: компенсация и сверка | test_s3_failures.py |
4 теста OK: компенсация, orphan при неудачной компенсации (dry-run/apply/grace), missing object, отказ S3 | evidence/checks.txt |
| ≥10 одновременных загрузок, пик памяти | research/upload_memory.py |
12 клиентов × 8.7 MiB: пик RSS 99 / 116 / 123 MiB при UPLOAD_CONCURRENCY 1 / 4 / 12 (старт процесса 94 MiB, лимит контейнера 256 MiB); все 12 файлов приняты и скачиваются побайтно; OOMKilled=false |
evidence/upload_memory.json |
| Bootstrap идемпотентен, отдельные ключи API с ограниченными правами, консоль не открыта, bucket private | s3-init; docker compose logs s3-init |
повторный запуск: «bucket уже существует», анонимный доступ 403, ключ API не может создать bucket (AccessDenied) |
логи s3-init |
| Лимиты и потоковая обработка | описание; upload_memory.json |
размер/пиксели проверяются до распаковки; тело не буферизуется целиком | src/app/attachments.py, images.py |
| Трек 2 | research/reconcile_bench.py |
см. ниже | evidence/track2_reconcile.json |
Эксперименты и отказы (трек 2)
Гипотеза. Reconciler обнаруживает ровно внедрённые расхождения в обе стороны, в режиме dry-run ничего не меняет, при apply исправляет только безопасное (осиротевшие объекты старше grace; повреждённые/потерянные вложения помечает failed), не затрагивает свежие и используемые вложения, повторяется идемпотентно, а стоимость обхода линейна по числу объектов.
Методика (research/reconcile_bench.py): ≈15 000 вложений (мелкие PNG, загружены через API); внедрено на обеих сторонах: 20 осиротевших объектов в S3, у 20 вложений удалён объект в S3, у 5 вложений объект подменён по размеру; после паузы > grace (5 с) — dry-run дважды, затем --apply --grace 5 параллельно с загрузкой 200 новых вложений, затем повторный apply. Проверки: количество найденного, неизменность при dry-run, целостность 200 используемых и 200 свежих вложений (скачивание, sha256).
| Показатель | Результат |
|---|---|
| dry-run нашёл | 20 orphan, 20 missing, 5 size_mismatch — ровно внедрённое; два dry-run дают одинаковый отчёт, fixed = 0/0 |
| apply (grace 5 с) | удалено 20 осиротевших объектов; 25 вложений помечены failed (object_missing=20, size_mismatch=5) |
| Свежие загрузки во время apply | 200 из 200 принято и скачивается побайтно |
| Используемые вложения | 200 из 200 целы (sha256 совпадает) |
| Повторный apply | изменений 0 (идемпотентно) |
| Стоимость обхода (dry-run) | 13 271 объект → 2.17 с; 14 271 → 2.34 с; 15 271 → 2.50 с (из них листинг S3 ≈ 96 %, запрос к БД 13 мс) — ≈0.16 мс на объект, линейно; на меньшем наборе (1–3 тыс. объектов, предварительный прогон) 0.28–0.59 с |
Границы. Reconciler сверяет только наличие и размер, не содержимое (содержимое подтверждает sha256 из БД при скачивании на стороне клиента); обход листингом S3 — O(число объектов), для очень больших бакетов нужен инкрементальный обход по префиксам/времени. Если объект удалён, восстановить байты нельзя — вложение остаётся в БД как failed. Grace period выбирается больше максимального времени загрузки + таймаутов (здесь 900 с против лимита чтения 15 с). Ограничение: измерения на одном ноутбуке, S3 — один узел SeaweedFS без репликации.
Отказы
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|---|---|---|---|
| Остановка S3 | загрузка/скачивание 503 + Retry-After, текст работает, ready=200 |
OK (test_s3_down…) |
после старта S3 — сразу; метаданные не накапливают «битых» строк |
| Остановка одной реплики после upload | файл скачивается другой репликой | failover PASS ×2 (восстановление записи 2.3 с) | потерь нет |
| Рестарт всего стенда | метаданные и оригинал на месте | persistence PASS | < 90 с |
| Сбой БД после записи в S3 | объект не остаётся | удаляется компенсацией; при сбое компенсации — reconciler | потерь подтверждённых данных нет |
Ограничения и следующие шаги
- Один узел S3 и один PostgreSQL (SPOF); репликации нет. Загрузка проксируется через API (прямые подписанные URL не реализованы — трек 1 не выбран).
- Проверка содержимого JPEG — декодирование в режиме draft (1/8), PNG — потоковая проверка; полная валидация пикселей не выполняется (это не нужно для отдачи оригинала).
- Подтверждено экспериментом: обнаружение/исправление расхождений, защита свежих и используемых вложений, линейная стоимость обхода, ограничение памяти при 12 одновременных загрузках. Гипотеза без доказательства: поведение reconciler на бакетах > 100 тыс. объектов.