Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
29 KiB
Отчёт — лабораторная 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.
Запуск из чистого 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/, монтируются composesecrets:; Spring читает их черезconfigtree(имя файла = имя свойства). В compose.yaml паролей нет. - Код: Attachments.java (upload/download), ImageCheck.java (проверка формата), Storage.java (S3), Reconciler.java (сверка), миграция V3__attachments.sql.
Загрузка и транзакционные границы (Attachments.upload):
- Сессия → членство в чате (404) →
filename(400) →Content-Type(415) →Content-Length > 10 MiB(413, до чтения тела). - Тело читается во временный файл с жёстким лимитом 10 MiB, SHA-256 считается по ходу. Файл удаляется в
finally: это буфер проверки, а не хранилище — оригинала на API после запроса нет. ImageCheck: формат по сигнатуре; размеры из заголовка (> 40 Мпикс → 413) до распаковки; PNG — CRC всех chunk иinflateIDAT «в никуда» со счётчиком (ровно ожидаемое число байтов); JPEG — структура сегментов, SOF, сканы, EOI. Затем полное декодирование ImageIO с прореживанием: декодер читает все строки PNG и все сканы JPEG, но растр ограничен ~0.25 Мпикс; ошибка или предупреждение декодера → 415. Только структурной проверки мало: PNG с верными CRC и фильтром строки 5 или JPEG из 27 байт SOI/SOF/SOS/EOI без таблиц и данных скана её проходят, но не декодируются. Память — буферы по 64 KiB и прореженный растр. ЗаявленныйContent-Typeдолжен совпасть с содержимым (415).- INSERT строки
state='uploading'(намерение до S3) → S3 PUT по серверному ключуoriginals/<uuid>→ UPDATEstate='ready'→201. - Компенсация: 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 1×1 с фильтром строки 5, JPEG 27 байт без таблиц и данных скана) → 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 |
не тронута |
Строка uploading старше grace (2 ч), объект только что записан |
stale_upload_fresh_object_kept |
не тронуты: удаляем, только когда старше grace и строка, и объект (LastModified) |
| Объект используемого вложения удалён | 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без репликации томов; потеря volumes3data= потеря файлов. - Временный файл загрузки лежит на диске контейнера API до конца запроса; для асинхронной обработки в lab5 нужен устойчивый staging (S3-префикс).
- Ключи идемпотентности хранятся бессрочно (контракт требует минимум 24 ч).
- Вариантов изображений в lab4 нет:
variant=thumbnail→ 404.