Files
mtusi2026lab4/REPORT.md
T

28 KiB
Raw Blame History

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

  • Автор, группа: Гавриков В.Д БПИ2303
  • Целевая оценка: 5, трек 5 — трек 2 «Согласованность двух хранилищ»
  • Commit/PR: после публикации
  • Источники и помощь ИИ: Spring Boot 3.3.5, AWS SDK for Java v2 2.29.52, Flyway 10, SeaweedFS 3.99, nginx 1.28.0. Реализация, тесты и отчёт подготовлены с помощью ИИ-ассистента (Claude Code); всё ниже проверено запуском на стенде.

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

Нужно: Docker Engine + Compose v2.24+, Python 3.9+. Проверено: macOS 14 (Apple M3 Pro, 11 CPU, 18 GiB), OrbStack, Docker 29.8.2, Compose 5.5.0.

# 1. Синтетические секреты в secrets/ (в Git их нет; повторный запуск файлы не меняет).
python3 scripts/init_secrets.py          # Windows: py -3 scripts\init_secrets.py

# 2. Сборка и запуск; --wait ждёт healthy всех сервисов (≈30–40 с на первом запуске после сборки).
docker compose up -d --build --wait

# 3. Проверки.
make test
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
docker compose start api-1 api-2         # вернуть остановленную тестом реплику
make test-persistence ACTION_SCRIPT=scripts/restart.sh
python3 tests/attachments_negative.py --with-docker
scripts/check-private-bucket.sh

Остановка без потери данных: docker compose down. Намеренное удаление учебных данных: docker compose down -v (секреты в secrets/ остаются; чтобы сменить их, удалите secrets/ вместе с volumes — пароль PostgreSQL задаётся при первой инициализации тома).

Порядок старта задан depends_on: postgres, redis, s3 → s3-init (bucket) и migration (Flyway) → api-1, api-2 → nginx. Действий оператора не требуется.

Архитектура и решения

клиент ──► nginx :8080 ──► api-1 ─┬─► PostgreSQL  (пользователи, чаты, сообщения, метаданные вложений)
                     └──► api-2 ─┼─► Redis       (Bearer-сессии)
                                 └─► SeaweedFS S3 (байты вложений, приватный bucket)
однократно: s3-init (bucket), migration (Flyway); по требованию: reconciler, s3-probe (profile tools)
Роль Service Образ Health/readiness Volume Сеть/порт Credentials
LB nginx nginx:1.28.0-alpine пассивная (max_fails=3, fail_timeout=10s) — единственный опубликованный порт 8080 —
API ×2 api-1, api-2 messenger-api:lab4 (из Dockerfile) /health/ready каждые 5 с нет (stateless) 8080 только во внутренней сети /run/secrets: пароль БД, Redis, ключи S3 api
Миграции migration тот же образ, режим migrate завершение с кодом 0 — внутренняя только пароль БД
БД postgres postgres:16.4 pg_isready pgdata 5432 внутренняя POSTGRES_PASSWORD_FILE
Сессии redis redis:7.4.1 redis-cli ping с паролем redisdata (AOF) 6379 внутренняя requirepass в redis.conf из secrets
S3 s3 chrislusf/seaweedfs:3.99 GET /healthz s3data только :8333 в сеть стенда; master/volume/filer слушают 127.0.0.1 identities из s3_config.json
Bootstrap S3 s3-init curlimages/curl:8.11.1 завершение с кодом 0 — внутренняя только ключи S3 admin
Сверка reconciler тот же образ, режим reconcile запуск по требованию — внутренняя пароль БД, ключи S3 api

Почему SeaweedFS, а не MinIO: образы minio/minio и quay.io/minio/minio с этой машины не скачиваются (registry отвечает access denied). SeaweedFS 3.99 проверен: S3 API, identities с правами на конкретный bucket, anonymous → 403.

Что перенесено из lab3: весь API, nginx-балансировка, идемпотентность, failover/restart hooks, скрипты замеров. В lab3 по ходу курса исправлены (и перенесены сюда): гонка идемпотентности (503 при параллельных повторах выключал обе реплики в nginx), DNS реплик в nginx (resolve), прозрачный повтор любых POST (non_idempotent теперь только для сообщений), 500 на неизвестный путь/метод/Content-Type, created_at чата, тайминги shutdown, скрипты замеров.

Что нового в lab4:

  • POST /api/v1/chats/{id}/attachments?filename=… — сырые байты PNG/JPEG, 201 ready; GET /api/v1/attachments/{id} и /content — только участникам чата, байты потоком из S3, без redirect.
  • attachment_ids в сообщениях: 0–10 уникальных id, только готовые вложения этого чата (иначе 404), text="" допустим с вложением, порядок сохраняется (message_attachments.position). Идемпотентность учитывает вложения: отсутствие поля и [] дают один хеш.
  • Миграции — Flyway (V1–V3) в одноразовом контейнере; реплики миграции не запускают (spring.flyway.enabled=false).
  • Секреты — файлы из secrets/, монтируются compose secrets:; Spring читает их через configtree (имя файла = имя свойства). В compose.yaml паролей нет.
  • Код: Attachments.java (upload/download), ImageCheck.java (проверка формата), Storage.java (S3), Reconciler.java (сверка), миграция V3__attachments.sql.

Загрузка и транзакционные границы (Attachments.upload):

  1. Сессия → членство в чате (404) → filename (400) → Content-Type (415) → Content-Length > 10 MiB (413, до чтения тела).
  2. Тело читается во временный файл с жёстким лимитом 10 MiB, SHA-256 считается по ходу. Файл удаляется в finally: это буфер проверки, а не хранилище — оригинала на API после запроса нет.
  3. ImageCheck: формат по сигнатуре; размеры из заголовка (> 40 Мпикс → 413) до распаковки; PNG — CRC всех chunk и inflate IDAT «в никуда» со счётчиком (ровно ожидаемое число байтов); JPEG — структура сегментов, SOF, сканы, EOI. Память — буферы по 64 KiB. Заявленный Content-Type должен совпасть с содержимым (415).
  4. INSERT строки state='uploading' (намерение до S3) → S3 PUT по серверному ключу originals/<uuid> → UPDATE state='ready' → 201.
  5. Компенсация: PUT не удался → строка удаляется, ответ 503; UPDATE не удался → объект удаляется. Если не удалась и компенсация (процесс упал), остаётся uploading-строка — её найдёт сверка после grace period.

/health/ready проверяет PostgreSQL и Redis, но не S3: текстовые сообщения — обязательный синхронный путь, и они продолжают работать при недоступном S3 (вложения отвечают 503). Проверено ниже.

Соответствие .env.example: S3_ENDPOINT/S3_REGION/S3_BUCKET — env в compose; S3_ACCESS_KEY_ID_FILE, S3_SECRET_ACCESS_KEY_FILE, DATABASE_URL_FILE → файлы /run/secrets/s3.access-key, s3.secret-key, spring.datasource.password; MAX_UPLOAD_BYTES=10485760 и MAX_IMAGE_PIXELS=40000000 — константы контракта в коде; SESSION_STORE = Redis; API_REPLICAS=2 — сервисы api-1/api-2.

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

Уровень 3

Критерий README Команда/сценарий Наблюдаемый результат
Публичный smoke make test PASS: lab4 public API scenario
Возможности lab3 сохранены make test (сценарий накопительный), make test-failover PASS; failover: 2 реплики, 98 записей, 0 ошибок, восстановление записи 2.18 с
S3 в стенде, метаданные в PostgreSQL, байты в приватном bucket docker compose ps; scripts/check-private-bucket.sh сервис s3 с volume s3data; таблица attachments без байтов; anonymous GET/HEAD/LIST/PUT → 403
201 ready, оригинал побайтно, checksum, посторонний 404 make test, tests/attachments_negative.py PASS: SHA-256 и размер совпадают, eve получает 404 на метаданные и bytes
PNG/JPEG ≤10 MiB и ≤40 Мпикс, MIME по содержимому, опасные filename, лимиты до чтения/декодирования tests/attachments_negative.py PASS (см. уровень 4)
Upload → остановка обслужившей реплики → download через другую tests/attachments_negative.py --with-docker PASS upload replica … stopped: other replica serves identical bytes
Restart с volumes сохраняет метаданные и оригинал make test-persistence ACTION_SCRIPT=scripts/restart.sh PASS: persistence preserved confirmed data and existing session (тест в lab4 перечитывает файл)

Уровень 4

Критерий README Команда/сценарий Наблюдаемый результат
Тесты: большой файл, повреждённое изображение, подмена MIME, чужое attachment_id, файл другого чата; нет 500 python3 tests/attachments_negative.py --with-docker PASS: 12 attachment checks — 10 MiB+1 → 413 (API), 12 MiB → 413 JSON (nginx); битые/обрезанные PNG/JPEG → 415; PNG как image/jpeg, GIF/SVG как image/png → 415; >40 Мпикс → 413, «бомба» с ложным заголовком → 415, честные 36 Мпикс приняты; ../, /, \, NUL, управляющие → 400; вложение другого чата/неизвестное → 404; каждый 4xx проверен на отсутствие internal_error
Недоступность S3 там же, --with-docker S3 остановлен: upload/download → 503 unavailable, метаданные 200, текстовое сообщение 201, /health/ready 200, uploading-строк 0 (компенсация); после старта S3 скачивание снова работает
Прерывание загрузки и отказ между S3/БД не оставляют вечных объектов порядок «намерение → PUT → ready», компенсация, Reconciler (автоматически раз в 15 мин в API-репликах, grace 1 ч, pg advisory lock — одна реплика за раз) после всех негативных тестов и отключения S3 сверка: 82 объекта = 82 строки, находок 0; эксперимент трека 2 ниже
Лимиты/таймауты, RAM не растёт от загрузки; ≥10 одновременных загрузок с пиком памяти python3 tests/upload_memory.py --runs 1,10,20 10 и 20 одновременных загрузок по 9.8 MiB: все 201; память процессов API (anon) +4…7 MiB к фону (см. эксперимент)
Bucket bootstrap идемпотентен docker compose up повторно / docker compose run --rm s3-init bucket messenger-attachments already exists, anonymous list -> 403, bucket is private
Отдельные S3 credentials с ограниченными правами s3_config.json (identity api: Read/Write/List только на свой bucket); scripts/check-private-bucket.sh контроль: ключ API читает свой объект (200); создать другой bucket → 403 AccessDenied (не ошибка подписи); удалить свой bucket → 403. Admin-ключи есть только у s3-init и самого s3
Административная консоль не открыта в общей сети scripts/check-private-bucket.sh master UI :9333, filer UI :8888, volume :8080 из сети стенда недоступны (слушают 127.0.0.1); с хоста порты публикует только nginx
Проверка private bucket вне API scripts/check-private-bucket.sh (запросы из отдельного контейнера s3-probe) PASS anonymous GET/HEAD/LIST/PUT -> 403

Лимиты и таймауты: nginx client_max_body_size 11m, client_body_timeout 15s, тело буферизуется в nginx (медленный клиент не держит поток API); Tomcat connection-timeout 10s; не больше 8 одновременных загрузок на реплику (MAX_CONCURRENT_UPLOADS, ожидание слота 10 с, иначе 503); S3-клиент: connect 2 с, socket 30 с, весь вызов ≤ 60 с.

Уровень 5 — трек 2

Критерий трека Команда/сценарий Наблюдаемый результат
Повторяемый reconciler orphan/missing docker compose run --rm reconciler [--apply] [--grace-seconds=N] [--verify-checksums] JSON-отчёт: находки, действия, стоимость
Ошибки на обеих сторонах, обнаружение, безопасное исправление, dry-run и повтор python3 tests/reconcile_experiment.py --cost 1000,10000 PASS: dry-run — 12 находок в 9 категориях, состояние до и после совпадает (11 строк, 12 объектов); apply — objects_deleted 5, rows_deleted 2, marked_lost 3; повторный apply — 0 действий; --verify-checksums — подмена байтов того же размера → lost, ложный lost с верной SHA-256 → restored; повтор — 0 действий
Свежие и используемые вложения не удаляются там же свежий orphan и строка uploading моложе grace — *_kept, не тронуты; используемое и только что загруженное вложение скачиваются, байты совпадают; сообщение с вложением не изменилось; строка используемого вложения без объекта не удалена, а помечена lost (download → 404 not_found, не 500)
Стоимость обхода там же, --cost 1 000 строк: 1.0 с, 1 LIST, 2 запроса БД; с --verify-checksums 18.9 с (996 GET). 10 000 строк: 5.3 с, 10 LIST, 11 запросов БД; с проверкой сумм 87.6 с (9 996 GET)

Эксперименты и отказы

≥10 одновременных загрузок: пик памяти

Методика: tests/upload_memory.py загружает через nginx N одновременных PNG по 9.79 MiB (случайные пиксели, не сжимаются); память читается из cgroup v2 каждые 0.2 с: anon — память процессов (heap JVM и native), current — плюс page cache временных файлов. Лимиты: API 512M (heap JVM ≤128 MiB), nginx 128M, s3 512M. Сырые данные: evidence/upload_memory.json, до исправления.

N Ответы Время, с (p50 / max) API anon, MiB: фон → пик (api-1 / api-2) API current пик nginx current / anon S3 anon пик
1 201 ×1 1.04 / 1.04 194.6→205.0 / 196.2→196.3 263 / 198 20.6 / 8.1 128
10 201 ×10 4.90 / 4.94 205.1→209.2 / 196.5→212.0 263 / 266 108 / 8.5 239
20 201 ×20 10.42 / 11.30 209.2→214.7 / 212.1→219.3 298 / 301 128 / 8.8 430

Вывод: память процессов API почти не зависит от числа и размера загрузок (+4…15 MiB на 10–20 файлов по 10 MiB) — тело идёт потоком через 64 KiB буфер во временный файл, проверка не декодирует пиксели. Рост current — page cache временных файлов, ядро его вытесняет. nginx: anon ≈ 9 MiB, остальное — page cache буферов тел.

Подтверждённое улучшение. Первый прогон показал, что узкое место — не API, а SeaweedFS: при 10 загрузках его память процесса дошла до 507 MiB из 512M (memory.events max = 5415 срабатываний лимита). Гипотеза: сборщик мусора Go не знает о лимите контейнера. Добавлен GOMEMLIMIT=320MiB; повтор того же профиля:

N S3 anon пик до S3 anon пик после
10 507.0 MiB 239.0 MiB
20 502.2 MiB 430.0 MiB

Ограничение: при 20 одновременных загрузках S3 всё ещё близко к лимиту; дальнейшие рычаги — уменьшить MAX_CONCURRENT_UPLOADS (сейчас до 16 PUT в S3 одновременно) или дать S3 больше памяти. Генератор closed-loop, один прогон на точку.

Отказы

Воздействие Что ожидаем Что наблюдали Восстановление / потеря данных
Остановка обслужившей API-реплики (make test-failover) запись продолжается через другую 98 записей, 0 ошибок первая запись 2.18 с; потерь и дублей нет
Остановка реплики, принявшей загрузку скачивание через другую 5 скачиваний, байты идентичны, другой X-Instance-Id мгновенно; потерь нет
Остановка S3 вложения 503, текст работает upload/download 503, сообщение 201, ready 200 после старта S3 скачивание работает; висящих uploading 0
Restart всего стенда (scripts/restart.sh) данные, сессия и файл сохранены PASS persistence потерь нет

Трек 2: согласованность PostgreSQL и S3

Гипотеза: сверка находит расхождения обеих сторон, dry-run ничего не меняет, apply исправляет только безопасное (старше grace и не используемое сообщением), повторный запуск ничего нового не находит, свежие и используемые вложения остаются доступны.

Методика: tests/reconcile_experiment.py готовит вложения через API, затем ломает состояние мимо API: в S3 — подписанными запросами из контейнера s3-probe (ключи API), в БД — psql в контейнере postgres. Grace сокращён до 90 с: сбои вносятся, выжидается 92 с, затем создаются «свежие» объекты; после этого цепочка dry-run → apply → apply → apply --verify-checksums → apply --verify-checksums. Состояние (строки по состояниям и число объектов по листингу S3) снимается до и после dry-run. Сырые данные: evidence/reconcile_experiment.json.

Внесённый сбой Находка Действие apply
3 объекта без строк + строка удалена из БД (объект остался) orphan_object ×4 объект удалён после повторной проверки БД по ключу
Объект без строки моложе grace orphan_object_fresh_kept не тронут
Строка uploading старше grace, объект есть stale_upload_with_object строка и объект удалены
Строка uploading старше grace, объекта нет stale_upload строка удалена
Строка uploading моложе grace upload_in_progress_kept не тронута
Объект используемого вложения удалён missing_object_used (отсутствие подтверждено HEAD) lost, строка и сообщение сохранены
Объект неиспользуемого вложения удалён missing_object lost
Объект подменён байтами другого размера size_mismatch lost
Объект подменён байтами того же размера только с --verify-checksums: checksum_mismatch lost
Строка ложно помечена lost, объект цел lost_object_back_unverified; с --verify-checksums — lost_object_back ready только после сверки SHA-256

Результат: PASS. Dry-run не изменил ни строк, ни объектов; первый apply — {"objects_deleted": 5, "rows_deleted": 2, "marked_lost": 3}; второй apply — 0 действий (остались только lost_known и свежие *_kept); проверка сумм — {"marked_lost": 1, "restored": 1}; её повтор — 0 действий. После сверки исправные вложения скачиваются побайтно, потерянные отвечают 404, а не 500.

Стоимость обхода (--cost 1000,10000, dry-run, grace 0; маленькие PNG):

Строк Обычный обход --verify-checksums
1 000 996 мс; 1 LIST, 2 запроса БД 18 881 мс; 996 GET, 0.6 MiB прочитано
10 000 5 290 мс; 10 LIST, 11 запросов БД 87 638 мс; 9 996 GET, 1.2 MiB прочитано

Вывод: обычный обход — merge-join двух отсортированных потоков, стоимость линейна (≈ 1 LIST и 1 запрос БД на 1 000 ключей, память O(страница)); подходит для запуска раз в 15 минут. Проверка SHA-256 — один GET на объект, время определяется числом запросов, а не байтами (здесь файлы по ~100 байт; на реальных 10 MiB-файлах это ещё и полный объём хранилища), поэтому она запускается только вручную. Ограничения: один прогон на точку; ключ сбоя «тот же размер, другие байты» без --verify-checksums не обнаруживается — это осознанный компромисс стоимости.

Ответы на вопросы защиты

Почему файл в Docker volume одной API-реплики не равен объектному хранилищу? Volume привязан к контейнеру/узлу: другая реплика его не видит, и после остановки загрузившей реплики файл недоступен (именно это проверяет сценарий upload → stop → download). S3 — отдельный общий сервис с собственным хранением, доступный всем репликам по сети.

Когда можно честно вернуть 201? Только когда оригинал сохранён в S3 и метаданные ready закоммичены в PostgreSQL. У нас UPDATE в ready идёт после успешного PUT; до этого клиент получает только ошибку.

Что произойдёт, если S3 PUT прошёл, а COMMIT в PostgreSQL — нет? Клиент получит ошибку и не узнает id; API пытается удалить объект. Если и это не удалось (процесс упал), остаются объект и строка uploading: сверка после grace period удаляет их. Объект без строки вообще невозможен в нормальной работе — строка пишется до PUT; если он всё же появился (ручное вмешательство, сбой компенсации), сверка удалит его после grace, предварительно перепроверив БД по ключу.

Почему случайный object key и приватный bucket не заменяют ACL приложения? Ключ — не секрет доступа: он может утечь в логах или от бывшего участника, а bucket приватен лишь от анонимов, не от владельца ключей API. Право «участник этого чата» знает только приложение, поэтому каждый GET метаданных и байтов проверяет членство по БД.

Ограничения и следующие шаги

  • Один Docker-host: выдерживается отказ процесса API или S3, но не узла. PostgreSQL, Redis, S3 и nginx — по одному экземпляру (SPOF).
  • SeaweedFS запущен одним процессом weed server без репликации томов; потеря volume s3data = потеря файлов.
  • Временный файл загрузки лежит на диске контейнера API до конца запроса; для асинхронной обработки в lab5 нужен устойчивый staging (S3-префикс).
  • Ключи идемпотентности хранятся бессрочно (контракт требует минимум 24 ч).
  • Вариантов изображений в lab4 нет: variant=thumbnail → 404.