30 KiB
Отчёт — лабораторная 4
- Автор, группа: Вейнмайер Андрей Андреевич, БВТ2303
- Целевая оценка: 5 (уровни 3, 4 и трек 2 «Согласованность двух хранилищ»)
- Commit/PR: ветка
solution/bvt2303-weinmaierв https://gitea.privcloud.tech/WeinmaierAndrew/mtusi2026lab4, PR в mtusi2026/mtusi2026lab4 - Основа: собственная lab3 (PR mtusi2026/mtusi2026lab3#43) — балансировка, идемпотентность, отказ реплики
- Использованные источники:
- Контракт: contracts/openapi.json, contracts/README.md (разделы «Вложения»)
- Библиотеки: github.com/minio/minio-go/v7, github.com/jackc/pgx/v5, github.com/redis/go-redis/v9, golang.org/x/crypto/argon2
- Спецификации: PNG (ISO/IEC 15948: chunks, CRC, Adam7), JPEG (ITU T.81: маркеры, SOF, SOS, EOI)
- Документация: MinIO (
mc admin policy,mc anonymous), AWS S3 ListObjectsV2, Docker Compose - Помощь ИИ: ИИ-ассистент использовался при реализации и отладке; все результаты ниже — реальные прогоны, ссылки на них приведены.
Запуск из чистого clone
Версии
| Компонент | Образ |
|---|---|
| API, reconciler | golang:1.26-alpine → alpine:3.20, оба закреплены по digest в Dockerfile; один образ, два бинарника (/app/api, /app/reconcile) |
| S3 | bitnamilegacy/minio:2025.4.22@sha256:50cec18a… — MinIO RELEASE.2025-04-22T22-12-26Z |
| Bootstrap S3 | bitnamilegacy/minio-client:2025.4.16@sha256:8a86e441… — mc RELEASE.2025-04-16 |
| LB / БД / сессии | haproxy:3.0.5-alpine, postgres:16.4-alpine, redis:7.4.1-alpine (digest в evidence/images.txt) |
| Миграции | migrate/migrate:v4.17.0 |
Почему Bitnami. Официальные образы minio/minio и minio/mc в ходе работы оказались недоступны и на Docker Hub (repository does not exist), и на quay.io (unauthorized) — проверено отдельным прогоном на GitHub runner. Использована сборка Bitnami того же релиза MinIO, закреплённая по digest. Запасной вариант из задания, если и она пропадёт, — SeaweedFS (chrislusf/seaweedfs:3.97, доступен).
Prerequisites: Docker с Compose v2, Python 3.9+, POSIX shell (Linux/macOS/WSL или Git Bash).
Команды
sh scripts/init-secrets.sh # .env и secrets/ (пароли и ключи S3 генерируются, не печатаются)
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --wait # postgres, redis, s3 → migrate, s3-init → api×2, reconciler → lb
make test # публичный smoke lab4
make test-failover ACTION_SCRIPT=scripts/stop-one.sh && sh scripts/restore.sh
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-files # негативный набор вложений
make test-reconcile # трек 2: внедрение расхождений
make reconcile-dry # отчёт reconciler без изменений
sh scripts/collect-evidence.sh all # все доказательства в evidence/
Остановка без потери данных: docker compose --env-file .env stop. Намеренное удаление учебных данных: docker compose --env-file .env down -v (удаляет pg_data, redis_data, s3_data).
Архитектура и решения
клиент ──► lb (HAProxy, единственный опубликованный порт 127.0.0.1:8080)
▼
api × N ──► postgres: users, chats, messages, attachments (метаданные), message_attachments
│ ──► redis: сессии, кэш истории
└───────► s3 (MinIO, сеть back, порты не опубликованы, консоль off): bucket messenger-attachments (private)
reconciler (тот же образ, --apply --interval 10m --grace 1h) ──► postgres + s3
s3-init (one-shot): bucket, anonymous none, политика и пользователь API
Перенесено из lab3: всё — X-Instance-Id, идемпотентность, HAProxy с readiness, drain по SIGTERM, сессии в Redis, версия кэша истории в PostgreSQL, однократные миграции, скрипты отказа.
Новое в lab4:
- Модель данных (0004_attachments.up.sql):
attachments(id, chat_id, owner_id, filename, object_key UNIQUE, status uploading|ready|missing, content_type, size_bytes, sha256, …)иmessage_attachments(message_id, attachment_id, position). Object keya/{chat_id}/{attachment_id}назначает сервер; filename только отображается. - Загрузка (attachment.go):
- членство в чате (иначе 404) → filename (иначе 400) → Content-Type png/jpeg (иначе 415) →
Content-Length > 10 MiB→ 413 без чтения тела; без Content-Length тело читается максимум до лимита + 1 байт; - формат по первым байтам (подмена MIME → 415); ранний отказ по пикселям, если заголовок в первых 64 KiB;
- намерение
status=uploadingв PostgreSQL — до записи в S3, поэтому у любого объекта, который может появиться в bucket, есть учётная запись; - один потоковый PUT в S3; через pipe параллельно идёт SHA-256 и структурная проверка изображения (imagecheck.go): PNG — CRC каждого chunk, IHDR, длина распакованного IDAT (zlib → io.Discard, с учётом Adam7); JPEG — сегменты, SOF, сканы, EOI. Пиксели не декодируются, лимит 40 млн пикселей проверяется по IHDR/SOF до распаковки, «бомба» 100000×100000 отклоняется по 66 байтам;
status=ready+ content_type/size/sha256 → 201 только после того, как объект и метаданные сохранены.
- членство в чате (иначе 404) → filename (иначе 400) → Content-Type png/jpeg (иначе 415) →
- Компенсация. Ошибка до
MarkReady(битое изображение, отказ S3, обрыв клиента) — сразу удаляются объект и намерение. ОшибкаMarkReady— исход неизвестен: объект не удаляется, намерение удаляется, только если оно всё ещёuploading(см. «Исправления, найденные тестами»). Остатки любых сбоев убирает reconciler. - Скачивание — только через API, без redirect: проверка членства в чате вложения,
Content-Typeоригинала,Content-Length, сверка размера с метаданными,Cache-Control: private, no-store.variant=original/по умолчанию — байты;thumbnail|crop|optimized— 404 (у ready-объекта lab4 вариантов нет); прочее — 400. - Сообщения:
attachment_ids(0–10 уникальных UUID, по умолчанию[]),text=""допустим только с вложениями. Вложения проверяются и блокируютсяFOR SHAREв транзакции сообщения: того же чата,ready; чужое/неизвестное/незавершённое — 404, в карантине — 409. Порядок сохраняется; отпечаток идемпотентности включаетattachment_ids(отсутствие =[], другой порядок = другое тело → 409). - S3 и права (infra/s3/init.sh): идемпотентный bootstrap —
mb --ignore-existing,anonymous set none, политикаmessenger-api(Get/Put/Delete объектов и List только этого bucket), отдельный пользователь API. Root-ключ есть только уs3иs3-init; у API и reconciler — ключ с политикой. Консоль MinIO выключена (MINIO_BROWSER=off), порты S3 не публикуются. - Readiness не включает S3 — сознательно: без S3 работают регистрация, сессии, чаты и текстовые сообщения, а эндпоинты вложений отвечают 503. Если бы S3 входил в readiness, LB снял бы все реплики и уронил весь мессенджер из-за одной функции.
- Таймауты: обычный API 5 s, загрузка/скачивание 30 s (
ReadTimeout30 s), HAProxytimeout server 15s; minio-go — 2 повтора вместо 10, чтобы отказ S3 давал быстрый 503, а не таймаут LB.
Соответствие .env.example: S3_ENDPOINT/S3_REGION/S3_BUCKET/S3_*_FILE/MAX_UPLOAD_BYTES/MAX_IMAGE_PIXELS — как в контракте; SESSION_STORE=redis; добавлены RECONCILE_INTERVAL, RECONCILE_GRACE, DRAIN_DELAY, SHUTDOWN_TIMEOUT.
Где запускался стенд
На машине разработки нет аппаратной виртуализации для Docker Desktop, поэтому Docker-проверки выполнены на GitHub-hosted runner workflow .github/workflows/lab4-stand.yml: три независимых стенда параллельно (base, files, track2), тот же compose.yaml и те же скрипты. Runner: 2 vCPU, 8 GB, Docker 28.0.4, Compose v2.38.2.
Итоговый прогон: https://github.com/CharaWein/2026_lab3/actions/runs/41881945345 (commit 5119d0b, stand=success). Все файлы в evidence/ — из него. Предыдущие прогоны той же ветки нашли ошибки, исправленные ниже.
До Docker-прогона логика проверялась нативно (PostgreSQL 17, S3-эмулятор moto, 2 процесса API): smoke, негативный набор, reconciler.
Исправления, найденные тестами
| Что показал тест | Причина | Исправление |
|---|---|---|
db-gap: после паузы PostgreSQL во время MarkReady строка стала ready, а объекта в S3 нет |
клиент отвалился по таймауту LB → контекст отменён → код посчитал UPDATE неудавшимся и удалил объект; но UPDATE уже ушёл в БД и закоммитился после разморозки | MarkReady выполняется в собственном контексте (байты уже сохранены, учёт доводится до конца); ошибка MarkReady считается неопределённым исходом — объект не удаляется. Повторный прогон: ready + объект, согласовано |
s3-outage: при остановленном S3 загрузка давала 415 вместо 503 |
PUT упал → pipe закрыт с ошибкой → валидатор принял обрыв потока за «битое изображение» | валидатор различает собственную ошибку и обрыв потока снаружи (trackingReader); unit-тест attachment_test.go на все четыре причины |
| официальные образы MinIO недоступны | убраны из Docker Hub и quay.io | Bitnami той же версии, по digest |
| файлы секретов 600 читались контейнерами (uid 1001) только потому, что uid runner совпал | права | файлы 644, каталог secrets/ 700 |
Доказательства критериев
Уровень 3
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл |
|---|---|---|---|
| Возможности lab3 сохранены | регрессии lab3, идемпотентность, failover ×2, persistence, серия отказов, rolling update | все PASS; 0 дублей, 0 ошибок при остановке реплик, rolling update — 0 ошибок из 34 743 запросов | evidence/regressions.txt, idempotency_concurrent.json, failover_.txt, failover_series.json, rolling_update.* |
| S3 в общем стенде; метаданные в PostgreSQL, байты в приватном bucket | compose.yaml, docker compose ps |
s3, s3-init, reconciler в стенде; у API нет volume, оригиналы только в s3_data |
evidence/docker_ps.txt |
| POST вложения → 201 ready; оригинал побайтно; Message с attachment_ids; посторонний — 404 | make test |
PASS: lab4 public API scenario (SHA-256 оригинала, 404 у постороннего) |
evidence/smoke.txt |
| Реальные PNG/JPEG ≤10 MiB, ≤40 Мпикс; MIME по содержимому; опасные filename; лимиты до чтения/декодирования | make test-files |
28 случаев, 0 ответов 5xx (таблица ниже) | evidence/files/attachments_negative.txt |
| Upload → остановка обслужившей реплики → download через другую | attachments_ops.py failover |
загрузил 5c22e6c38769, контейнер остановлен, скачивал cd9621e01c62, SHA-256 совпал |
evidence/files/files_failover.json |
| Restart с volumes сохраняет метаданные и оригинал | make test-persistence (lab4 проверяет и файл) |
PASS; перезапущены postgres, redis, s3, api, lb, reconciler | evidence/persistence.txt |
| Failover lab4 (с проверкой оригинала) | make test-failover ×2 |
PASS ×2, по 144 записи, 0 ошибок, восстановление записи 3.49 s / 3.35 s | evidence/failover_1.txt, failover_2.txt |
Уровень 4
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл |
|---|---|---|---|
| Тесты: большой файл, повреждённое изображение, подмена MIME, чужое attachment_id, вложение другого чата; без 500 | attachments_negative.py |
413 по Content-Length (тело не читается) и по chunked 11 MiB; 413 на «бомбе» и 40 000 001 пикселе; 415 на обрезанных/повреждённых PNG и JPEG, подмене MIME в обе стороны, тексте, GIF, пустом теле; 404 на вложение другого чата и неизвестный id; 400 на дубли, >10 id, невалидный UUID | evidence/files/attachments_negative.txt |
| Прерывание загрузки не оставляет неучтённых объектов | attachments_ops.py interrupt: отправлен 1 MiB из 4, соединение оборвано |
строк 0, объектов 0 (компенсация сразу) | evidence/files/files_interrupt.json |
| Отказ между S3 и БД | attachments_ops.py db-gap: PUT прошёл, PostgreSQL на паузе 45 s |
клиент получил 504, 201 не было; после разморозки — ready + 1 объект (согласовано); reconciler ничего исправлять не пришлось |
evidence/files/files_db-gap.json, compensation_log.txt |
| Механизм сверки/очистки с безопасным grace | reconciler (сервис и make reconcile-*) |
grace 1h по умолчанию; <5m только с --unsafe-short-grace; трек 2 ниже |
cmd/reconcile, evidence/track2/ |
| Недоступность S3 | attachments_ops.py s3-outage |
загрузка 503 за 0.38 s, скачивание 503, метаданные 200, текстовое сообщение 201, readiness 200, брошенных намерений 0; после старта S3 загрузка снова ready, старый файл цел | evidence/files/files_s3-outage.json |
| ≥10 одновременных загрузок, пик памяти | attachments_ops.py memory: 10 и 20 загрузок по 10.2 MB, memory.peak cgroup реплик |
см. таблицу ниже: +17.7 MiB при 97 MiB трафика, +39.7 MiB при 194 MiB | evidence/files/files_memory.json |
| Bootstrap идемпотентен; отдельные ограниченные credentials; консоль закрыта; private bucket вне API | attachments_ops.py security |
анонимный GET и LIST изнутри сети — 403; ключ API: свой bucket — да, создать bucket — нет, admin API — нет, видит только messenger-attachments; s3-init два раза подряд — exit 0, объектов 10→10; порты S3 не опубликованы |
evidence/files/files_security.json |
Пик памяти при одновременных загрузках (файл 10 187 085 байт, лимит контейнера 256 MiB):
| Параллельно | Успешно | Трафик, MiB | Пик реплики до → после, MiB | Рост, MiB | ≈ на загрузку |
|---|---|---|---|---|---|
| 10 | 10/10 | 97.2 | 7.3 → 25.0 | 17.7 | 1.8 MiB |
| 20 | 20/20 | 194.3 | 8.1 → 47.8 | 39.7 | 2.0 MiB |
Рост пропорционален числу одновременных загрузок, а не размеру файла: на загрузку уходят буферы чтения (64 KiB peek, 32 KiB валидатор, чанки подписи minio-go) и служебная память HTTP/GC. Буферизация файла целиком дала бы ≥10 MiB на загрузку (≥200 MiB при 20). Ограничение памяти по числу одновременных загрузок сверху — maxconn HAProxy и лимит контейнера; отдельного семафора на загрузки нет.
Трек 5.2: согласованность двух хранилищ
Гипотеза
- Повторяемый reconciler, обходящий PostgreSQL и S3 одним merge-проходом в общем порядке ключей, находит все виды расхождений (сироты, потерянные объекты, брошенные загрузки, подменённый размер) и исправляет их безопасно: dry-run ничего не меняет, повторный прогон ничего не находит, свежие (моложе grace) и используемые сообщениями вложения не удаляются никогда.
- Память обхода постоянна (O(1) от числа вложений), время линейно и определяется S3 LIST, а не базой.
Разбивка времени по источникам (wait_ms) добавлена после первого замера, когда рост времени на пару оказался нелинейным на малых N.
Методика
Reconciler (reconcile.go, cmd/reconcile): строки attachments (ORDER BY object_key COLLATE "C") и ListObjectsV2 (лексикографический порядок) читаются потоками и сливаются как отсортированные списки. Время «сейчас» берётся из PostgreSQL. Одновременно работает один экземпляр (pg_try_advisory_lock).
| Расхождение | Условие | Действие (--apply) |
Защита |
|---|---|---|---|
| stale_intent | строка uploading старше grace |
удалить объект (если есть), затем строку | моложе grace — загрузка может идти |
| orphan_object | объект без строки, старше grace | удалить объект | перед удалением повторная проверка строки по ключу |
| missing_object | строка ready без объекта |
карантин status=missing (API → 503) |
перед карантином повторный Stat объекта |
| size_mismatch | размер объекта ≠ метаданным | карантин | — |
| restored | missing, объект снова есть и размер совпал |
status=ready |
— |
| purge_missing | missing старше grace и ни одно сообщение не ссылается |
удалить строку | FOR UPDATE против FOR SHARE при прикреплении; используемые остаются навсегда |
Порядок «сначала объект, потом строка» выбран так, чтобы сбой между шагами оставлял учтённое намерение, а не неучтённый объект.
Внедрение ошибок (reconcile_faults.py): через API — чат и 6 вложений, 3 из них прикреплены к сообщениям. Затем: S3 — старая сирота, свежая сирота, удалены 3 объекта (2 используемых, 1 нет), подменён размер одного; БД — 2 брошенных намерения (с объектом и без), 1 «идущая» загрузка. Grace в тесте 8 s (--unsafe-short-grace), «старые» строки сдвинуты на 30 минут, чтобы фоновый reconciler стенда (grace 1h) их не трогал.
Стоимость обхода (reconcile_cost.py): досеиваем согласованные пары до N = 1 000 / 10 000 / 30 000 (строки — SQL, объекты по 1 KiB — mc mirror), три dry-run на каждый N, медиана; затем 1% расхождений (150 удалённых объектов + 150 сирот).
Результаты
Обнаружение и исправление (evidence/track2/faults.json):
| Проход | Найдено | Исправлено | Пропущено (защита) |
|---|---|---|---|
| dry-run | stale_intent 2, orphan 1, missing 3, size_mismatch 1 | — (снимки БД и S3 до/после совпали) | fresh_intent 1, fresh_object 1 |
| apply | те же 7 | все 7 | fresh_intent 1, fresh_object 1 |
| повторный apply | 0 | 0 | + fresh_missing (карантин моложе grace) |
| объект «восстановлен из бэкапа» | restored 1 | 1 (скачивание снова отдаёт исходные байты) | — |
| после grace | purge_missing 2, orphan 1 (бывшая свежая), stale_intent 1 (бывшая «идущая») | все | referenced_missing_kept 1 |
После apply через API: здоровые вложения скачиваются байт-в-байт; потерянные отвечают 503 на метаданные и байты; сообщение сохраняет attachment_ids; прикрепить вложение из карантина — 409.
Стоимость обхода (evidence/track2/cost.json, медиана 3 dry-run; runner 2 vCPU):
| Пар (строка+объект) | Время, ms | мкс на пару | LIST-страниц | Ожидание S3 LIST, ms | Ожидание БД, ms | Heap, MB |
|---|---|---|---|---|---|---|
| 1 004 | 96 | 96 | 2 | 59–96 | 0–74 | 2.4 |
| 10 004 | 2 647 | 265 | 11 | 2 410–2 863 | 58–235 | 3.4 |
| 30 004 | 8 374 | 279 | 31 | 7 502–11 235 | 127–292 | 2.2 |
| 30 004 + 1% расхождений | 10 344 | — | 31 | — | — | — + 150 Stat |
- Память постоянна: heap 2–3.4 MB при росте N в 30 раз — merge-проход не держит множества в памяти. Гипотеза подтверждена.
- Время определяется S3 LIST: 96–98% времени reconciler ждёт листинга MinIO, менее 3% — PostgreSQL. Гипотеза подтверждена.
- Линейность — с оговоркой: от 10k к 30k время на пару почти постоянно (265 → 279 мкс, +5%), а 1k дешевле в 2.8 раза. Объяснение (не измерено отдельно): небольшой листинг MinIO отдаёт из кэша метаданных, большие требуют обхода диска. На 2 vCPU это ≈ 0.28 ms на объект, то есть ~4.6 минуты на миллион вложений — при интервале 10 минут приемлемо, дальше нужен обход по префиксам чатов или инкрементальная сверка по событиям S3.
- 1% расхождений добавляет ~2 s: 150 точечных
Statдля перепроверки перед карантином (в dry-run сироты моложе grace только учтены какfresh_object).
Ограничения трека
- Один узел MinIO на 2 vCPU; абсолютные цифры зависят от диска и CPU, вывод о доминировании LIST — нет.
- Объекты по 1 KiB: размер на обход не влияет (LIST не читает тела), но на время
mc mirrorпри подготовке влияет. - Сверка размера — по LIST, без пересчёта SHA-256 (это потребовало бы скачать все объекты); подмена содержимого с тем же размером не обнаруживается.
- Grace зависит от часов: время строк — из PostgreSQL, LastModified — из MinIO; на одном хосте расхождение пренебрежимо, на разных узлах grace должен покрывать skew.
- Ready-вложение, загруженное, но так и не прикреплённое к сообщению, reconciler не удаляет (контракт не задаёт срок жизни таких вложений).
Эксперименты и отказы
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|---|---|---|---|
| Остановка реплики, загрузившей файл | скачивание через другую | тот же SHA-256 через другую реплику | 0 |
| Остановка S3 | 503 на вложениях, остальное работает | 503 за 0.38 s; текст, сессии, readiness — OK | после старта S3 — сразу; данные целы |
| Обрыв клиента посреди тела | ни строки, ни объекта | 0/0 | — |
| PostgreSQL замер между PUT и MarkReady | не 201; нет ready без объекта |
504 клиенту; ready + объект после разморозки |
0 потерь; дубль загрузки при повторе клиента возможен (см. ограничения) |
| Restart всего стенда | данные и файлы целы | PASS с прежним токеном | ≈14 s до healthy |
| Остановка каждой реплики под нагрузкой | 0 ошибок | 0 из 18 996 | возврат в LB за 6.4 s |
| Rolling update под нагрузкой | 0 ошибок | 0 из 34 743 | замена 29 s |
Ограничения и следующие шаги
- SPOF: один узел MinIO (без erasure coding), PostgreSQL, Redis, LB, хост. Выдерживается отказ API-реплики и временная недоступность S3 (вложения недоступны, мессенджер работает).
- Загрузка не идемпотентна (контракт не требует ключа): если клиент не получил ответ (504 в
db-gap) и повторит загрузку, появится второе вложение; первое останется неприкреплённым. - Ограничение памяти на одновременные загрузки обеспечено косвенно (буферы O(1) на загрузку +
maxconnLB + лимит контейнера); явного семафора нет. - JPEG проверяется структурно (маркеры, SOF, EOI), без энтропийного декодирования: формально корректный JPEG с испорченными данными скана будет принят.
- Bitnami legacy-образы больше не обновляются; при смене образа достаточно поменять
imageв compose.yaml (MinIO API тот же) или перейти на SeaweedFS.