31 KiB
Отчёт - лабораторная 4
- Автор, группа: Голиков Антон, БВТ2303
- Целевая оценка: на 4 (уровни 3+4, без трека 5)
- Commit/PR: ветка
solution/BVT2303-Golikov, PR будет открыт после публикации - Использованные источники, библиотеки и помощь ИИ:
- Скелет лабы 4 и материалы курса: COURSE.md, contracts/openapi.json, contracts/README.md, contracts/infrastructure.json
- Документация MinIO (mc admin user/policy, bucket policy), S3 API (PutObject/GetObject/ListObjects), pgx v5, goose, gin
- Собственная реализация лабы 3: Go 1.26, gin, pgx, goose, Redis, nginx, две API-реплики, X-Instance-Id, Idempotency-Key
- ИИ (ChatGPT) использован для структуры отчёта, вычитки формулировок и подсказок по рутинным местам (политика MinIO, healthcheck). Весь код, конфигурация, эксперименты и финальные тексты проверены и объясняются автором на защите.
Запуск из чистого clone
Prerequisites:
- Docker Desktop 4.30+ (WSL2 backend) или Docker Engine с Compose v2.20+
- Go 1.26+ (для локальной сборки без Docker; в Docker-варианте не нужен)
- Python 3.9+ (для публичных тестов из scaffold)
- git, make
Шаги запуска:
-
Клонировать fork и перейти на ветку solution:
git clone https://gitea.privcloud.tech/Maximillan_Mercer/mtusi2026lab4-fork.git cd mtusi2026lab4 git checkout solution/BVT2303-Golikov -
Создать локальные secrets. Значения генерируются оператором, в Git не попадают. Добавились четыре секрета для S3 (в дополнение к трём из lab2-3):
mkdir -p secrets # PostgreSQL (как в lab2-3) PW="$(openssl rand -hex 16)" printf "%s" "$PW" > secrets/postgres_password printf "%s" "postgres://messenger:$PW@postgres:5432/messenger?sslmode=disable" \ > secrets/database_url printf "%s" "redis://redis:6379/0" > secrets/cache_url # MinIO root (только для mc-init, API их не видит) printf "%s" "messenger-minio-root" > secrets/minio_root_user openssl rand -base64 32 | tr -d '\r\n' > secrets/minio_root_password # S3 API-креды (для сервиса api) printf "%s" "messenger-api" > secrets/s3_access_key_id openssl rand -hex 32 > secrets/s3_secret_access_key chmod 600 secrets/* -
Создать .env из .env.example:
cp .env.example .envПеременные и дефолты, которые изменились относительно lab3:
- S3_ENDPOINT=http://minio:9000
- S3_BUCKET=messenger-attachments
- S3_REGION=us-east-1
- S3_USE_SSL=false
- S3_ACCESS_KEY_ID_FILE=/run/secrets/s3_access_key_id
- S3_SECRET_ACCESS_KEY_FILE=/run/secrets/s3_secret_access_key
- MAX_UPLOAD_BYTES=10485760 (10 MiB)
- MAX_IMAGE_PIXELS=40000000 (40 млн)
- RECONCILER_ENABLED=true
- RECONCILER_INTERVAL_SECONDS=300
- RECONCILER_GRACE_SECONDS=3600 (1 час)
- MINIO_ROOT_USER=messenger-minio-root
- MINIO_CPUS=0.5, MINIO_MEMORY=512M
Остальные переменные (SESSION_STORE=redis, SESSION_TTL_SECONDS, IDEMPOTENCY_TTL_SECONDS, SHUTDOWN_DRAIN_SECONDS, лимиты CPU/RAM, API_REPLICAS=2, LB_PORT=8080) без изменений от lab3.
-
Собрать образ API и запустить стек:
docker compose build api docker compose up -d -
Дождаться, пока mc-init создаст bucket и API-пользователя, и применились миграции 0001–0004:
docker compose logs migrate # ожидать: goose: successfully migrated database to version: 4 # при первом запуске: OK 0001..0004 docker compose logs mc-init # ожидать: minio bootstrap ok: bucket=messenger-attachments user=messenger-api curl -sS http://localhost:8080/health/ready # ожидать: {"status":"ok"}Сервис mc-init идемпотентен: повторный
docker compose run --rm mc-initне падает и не дублирует bucket или policy. API использует отдельные S3-креды (messenger-api, policy только на messenger-attachments/*); root-креды MinIO видят только minio и mc-init. -
Прогнать публичный smoke и проверки от scaffold:
PYTHONUTF8=1 make check PYTHONUTF8=1 make test -
Проверки сохранности и отказа (требуют scripts/restart.sh и scripts/stop-one.sh из lab3, они перенесены):
PYTHONUTF8=1 make test-persistence ACTION_SCRIPT=scripts/restart.sh PYTHONUTF8=1 make test-failover ACTION_SCRIPT=scripts/stop-one.sh
Версии образов (закреплены в compose.yaml):
- pgsty/silo:RELEASE.2026-09-16T00-00-00Z — drop-in MinIO fork. Оригинальный minio/minio заархивирован в 2025-м, официальные community-образы сняты с Docker Hub; pgsty/silo сохраняет S3 API, mc и healthcheck без изменений.
- postgres:16.4-alpine
- redis:7.4-alpine
- nginx:1.27.4-alpine
- mtusi-messenger-api:lab3 — собственный образ, собирается из Dockerfile
Безопасная остановка:
docker compose stop # остановить контейнеры, volumes сохранить
docker compose down # удалить контейнеры и сеть, volumes сохранить
Остановка с удалением учебных данных (необратимо, удалит все volumes):
docker compose down -v
Отдельно про .env и secrets: оба пути в .gitignore, в репозиторий не попадают. Значения паролей синтетические, для локального стенда.
Архитектура и решения
Схема:
client (curl / python / smoke)
|
v
nginx LB (:8080) единственная публичная точка
|
+-> api-1 :8080 реплика 1
+-> api-2 :8080 реплика 2
|
+-> postgres :5432 users, chats, chat_members, messages,
| sessions, idempotency_keys, attachments,
| message_attachments
+-> redis :6379 сессии (SESSION_STORE=redis)
+-> minio :9000 S3, приватный bucket messenger-attachments
(порты наружу не публикуются)
|
+-- mc-init (одноразовый) bootstrap: bucket + policy + API-user
+-- migrate (одноразовый) goose up
Источник истины - PostgreSQL для метаданных и S3 для бинарных байтов. Разделение намеренное: байты не хранятся в БД (не BLOB, не локальный каталог api), только в приватном bucket; в Postgres - object_key, sha256, content_type, size_bytes, status, привязка к chat_id и к message_attachments. Через S3 любая API-реплика читает любую вложенность одинаково; локальный volume API не годится, потому что файл лежит только на одной реплике и теряется при её остановке - это критерий README уровня 3 "Upload → остановка обслужившей API → download через другую возвращает тот же файл".
Сессии - в Redis (без изменений от lab2-3). Без sticky session на LB любая реплика видит любую сессию.
Транзакционные границы:
-
Создание чата - одна транзакция в Postgres (chats + chat_members).
-
Идемпотентная отправка сообщения - одна транзакция: слот в idempotency_keys, проверка и линковка attachments, INSERT в messages, INSERT в message_attachments. Либо всё, либо ничего.
-
Загрузка вложения - две точки сохранения без общей транзакции (S3 и Postgres - разные системы). Последовательность:
INSERT attachments (status='pending', object_key, sha256) → COMMIT PutObject в S3 → OK/FAIL UPDATE attachments status='ready' → COMMITЭто ключевая граница lab4. Ниже - как каждый отказ на этой границе компенсируется.
-
Регистрация - один INSERT с UNIQUE-индексом на username (23505 → 409 через mapError).
Компенсация и сверка (уровень 4):
-
Отказ между INSERT и PutObject. Строка pending осталась, объекта в S3 нет. Handler ловит ошибку PutObject и сразу вызывает MarkFailed(id, "upload_failed") - компенсация в том же запросе, без ожидания reconciler.
-
Отказ между PutObject и UPDATE status='ready'. Объект в S3 есть, строка pending. Это и есть "вечный неучтённый объект", если ничего не делать. Закрывает reconciler: ListStalePending(now - grace) → Delete(object_key) → DeletePending(id). Grace 1 час: свежие pending (реальные upload'ы) не трогаются, только застрявшие.
-
Обратный случай: PutObject прошёл, INSERT в Postgres упал. Объект в S3 есть, строки в БД нет - orphan. Закрывает reconciler: List(S3) → отфильтровать LastModified < now - grace → ExistingKeys(DB) → Delete тех, которых нет в БД. Grace 1 час защищает свежий Put, чей INSERT ещё не закоммичен.
-
Reconciler запускается во всех репликах, но использует pg_try_advisory_lock: одна реплика на tick берёт session-level advisory lock, остальные пропускают tick. Postgres автоматически освобождает лок, если процесс упал.
Отдельные S3-креды и приватность bucket:
- Root-креды MinIO (minio_root_user/minio_root_password) видят только minio и mc-init. API-контейнер их не получает.
- API использует messenger-api с policy только на messenger-attachments (GetObject, PutObject, DeleteObject на bucket/*, ListBucket на bucket). Создание/удаление bucket, policy, пользователей недоступны.
- Bucket приватный: без подписи GET возвращает 403. Проверяется в evidence/s3-private.txt.
- MINIO_BROWSER=off: административная консоль не слушается. Порты 9000/9001 не публикуются на хост (только внутри internal-сети).
Что перенесено из lab3 без изменений:
- Схема БД: users, chats, chat_members, messages, sessions
- idempotency_keys с TTL 24 часа, Idempotency-Key обязателен
- X-Instance-Id в каждом ответе API (os.Hostname())
- Миграции goose, отдельный процесс /server migrate
- Graceful drain на SIGTERM, atomic ready-флаг, SHUTDOWN_DRAIN_SECONDS
- CPU/RAM лимиты на api, postgres, redis через deploy.resources
- nginx LB перед двумя репликами, upstream keepalive
- Горизонтальное масштабирование: две реплики, общие сессии в Redis
Что добавлено/изменено в lab4:
- Отдельный сервис minio (pgsty/silo), persistent volume minio_data.
- Одноразовый сервис mc-init: создаёт bucket, policy, API-user. Идемпотентен.
- Миграция 0003: таблицы attachments и message_attachments, индексы, ограничения (status, size, sha256, content_type, filename).
- Миграция 0004: ослаблен CHECK messages_text_not_blank - пустой текст разрешён при наличии вложений (lab4 anyOf), но whitespace-only по-прежнему запрещён.
- Три endpoint: POST /chats/{chat_id}/attachments (raw bytes PNG/JPEG, max 10 MiB, max 40M пикселей), GET /attachments/{id} и GET /attachments/{id}/content (без redirect, только участникам чата).
- POST /messages принимает attachment_ids (0-10), все вложения должны принадлежать этому чату и быть ready; anyOf text или attachments.
- RequestHash расширен: sha256(text) без attachments (обратная совместимость с lab3), sha256(text + 0x00 + ids) с attachments.
- Reconciler в API, pg advisory lock, две задачи (stale pending, orphan objects), grace 1 час.
- Healthcheck /health/ready пингует S3 (BucketExists).
- nginx client_max_body_size=12m (10 MiB upload + запас на 11 MiB negative-тест, чтобы 413 шёл от API с X-Request-Id, а не от nginx).
Соответствие переменных .env.example реальной конфигурации (новое в lab4):
- S3_ENDPOINT, S3_BUCKET, S3_REGION, S3_USE_SSL - читаются в config.Load, идут в s3.Config. Для внутреннего MinIO http://minio:9000, SSL=false.
- S3_ACCESS_KEY_ID_FILE, S3_SECRET_ACCESS_KEY_FILE - secrets в /run/secrets, читаются через readSecretOptional.
- MAX_UPLOAD_BYTES - идёт в AttachmentService (io.LimitReader body = maxBytes+1, 413 при превышении).
- MAX_IMAGE_PIXELS - идёт в AttachmentService (image.DecodeConfig, 413 при W*H > maxPixels).
- RECONCILER_ENABLED, RECONCILER_INTERVAL_SECONDS, RECONCILER_GRACE_SECONDS - читаются в config.Load, идут в service.Reconciler.
- MINIO_ROOT_USER - только для minio и mc-init, не попадает в api.
Доказательства критериев
Все evidence-файлы лежат в evidence/, содержат только обезличенные
результаты и не включают токены, пароли, signed URL или приватные
ключи.
Уровень 3:
| Критерий | Команда | Наблюдаемый результат | Файл |
|---|---|---|---|
| Публичный smoke | PYTHONUTF8=1 make test |
PASS: lab4 public API scenario | evidence/smoke.txt |
| >= 2 API-реплики за LB | docker compose ps |
api-1 и api-2 Up (healthy), LB публикует :8080 | evidence/container-state.txt |
| Остановка одной реплики <= 10 с | make test-failover |
first_recovery_seconds 5.48 | evidence/failover-1.txt |
| Поочерёдная остановка каждой (автотест) | make test-failover дважды |
recovery 5.48 и 5.34, дублей нет | evidence/failover-1.txt, failover-2.txt |
| Поочерёдная остановка каждой (ручной) | docker stop api-1, потом api-2 |
после остановки каждой отвечает ровно один X-Instance-Id | evidence/failover-manual.txt |
| Идемпотентность POST | smoke + failover (replay с тем же ключом) | тот же ответ, дублей нет | evidence/smoke.txt, failover-*.txt |
| Persistence после restart | make test-persistence |
PASS, StartedAt всех контейнеров обновился | evidence/persistence.txt |
| S3-сервер в общем стенде, приватный bucket | docker compose ps, mc ls local |
minio Up (healthy), bucket messenger-attachments (0 B) | evidence/container-state.txt |
| Метаданные в Postgres, байты в S3 | psql \d attachments, mc ls |
таблица attachments; object_key в S3 | evidence/s3-private.txt, container-state.txt |
| POST вложения возвращает 201 ready | smoke, test_attachments | 201 ready, sha256/size совпадают | evidence/attachments-negative.txt |
| Download побайтно, sha256 совпадает | smoke | download.bytes == original | evidence/smoke.txt |
| Чужой участник получает 404 на метаданные и байты | test_attachments | 404 без 403 | evidence/attachments-negative.txt |
| Прямой GET S3 без подписи -> 403 | wget http://minio:9000/messenger-attachments/<key> |
HTTP/1.1 403 Forbidden | evidence/s3-private.txt |
| Upload -> остановка обслужившей API -> download через другую | failover (файл приложен до отказа) | download через другую реплику == оригинал | evidence/failover-1.txt, failover-2.txt |
| Restart с сохранением volumes сохраняет оригинал | persistence | PASS, download == исходный файл | evidence/persistence.txt |
| S3 недоступен -> 503 без утечек | docker compose stop minio |
/health/ready 503 unavailable; LB снимает реплики | evidence/s3-down.txt |
| Не более 10 MiB, не более 40M пикселей | test_attachments | 11 MiB -> 413 payload_too_large | evidence/attachments-negative.txt |
| MIME по содержимому | test_attachments | PNG-байты с Content-Type image/jpeg -> 201, content_type image/png | evidence/attachments-negative.txt |
| Опасные filename отклоняются | test_attachments | /, \, NUL -> 400 invalid_request | evidence/attachments-negative.txt |
Уровень 4:
| Критерий | Команда | Наблюдаемый результат | Файл |
|---|---|---|---|
| Тест слишком большого файла | test_attachments (11 MiB) | 413 payload_too_large, не 500 | evidence/attachments-negative.txt |
| Тест повреждённого изображения | test_attachments (signature без IHDR) | 415 unsupported_media_type | evidence/attachments-negative.txt |
| Тест подмены MIME | test_attachments (PNG как image/jpeg) | 201, content_type определён по magic bytes | evidence/attachments-negative.txt |
| Тест чужого attachment_id | test_attachments (eve -> metadata и bytes) | 404 без утечки существования | evidence/attachments-negative.txt |
| Тест attachment_id из другого чата | test_attachments (message с чужим id) | 404 not_found | evidence/attachments-negative.txt |
| Failed-вложение в message | test_attachments | 409 conflict (см. Contract) | evidence/attachments-negative.txt |
| Пользовательская ошибка не превращается в 500 | test_attachments | все отказы 4xx; ни одна не 500 | evidence/attachments-negative.txt |
| Отказ S3/БД не оставляет вечных неучтённых объектов | reconciler с ускоренными интервалами | stale pending и orphan-объект удалены; pending_left=0 | evidence/reconciler.txt |
| Документированный grace period | README/REPORT, плюс evidence | ListStalePending(now - 1h), orphan только старше 1h | этот отчёт, evidence/reconciler.txt |
| Лимиты до неограниченного чтения | код + memory test | io.LimitReader(maxBytes+1), image.DecodeConfig до декодирования | student-tests/test_memory.py |
| >=10 одновременных загрузок с измерением пика RAM | test_memory.py + cgroups v2 | пик 141 MiB на каждой реплике <= 256 MiB лимита | evidence/memory-10x10mb.txt |
| Bucket bootstrap идемпотентен | docker compose run --rm mc-init дважды |
exit 0, "no such bucket / user exists" не срабатывает | этот отчёт |
| API использует отдельные S3-креды с ограниченными правами | mc admin user list, policy |
только messenger-api, GetObject/PutObject/DeleteObject на bucket/* | evidence/s3-private.txt |
| Административная консоль не открыта в общей сети | docker compose port minio 9001, printenv MINIO_BROWSER |
порт не проброшен, браузер off | evidence/s3-private.txt |
| Проверка private bucket вне API | wget http://minio:9000/messenger-attachments/<key> |
403 Forbidden без подписи | evidence/s3-private.txt |
Эксперименты и отказы
Общая среда: Windows 10, Docker Desktop (WSL2 backend), одна физическая машина, на которой работают и весь стенд, и клиенты тестов. Все пользователи и изображения синтетические. Версии: PostgreSQL 16.4, Redis 7.4, nginx 1.27.4, pgsty/silo RELEASE.2026-09-16T00-00-00Z (MinIO fork), Go 1.26.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления, потеря данных |
|---|---|---|---|
| Остановка одной API-реплики | writes продолжаются через LB, без дублей | recovery 5.48 / 5.34 с, повтор с тем же ключом даёт то же сообщение | 5–6 с, потерь нет |
| Поочерёдная остановка api-1 и api-2 вручную | каждый раз обслуживает оставшаяся | после stop api-1 отвечает один X-Instance-Id, после stop api-2 другой | <20 с суммарно, потерь нет |
Перезапуск всего стека (scripts/restart.sh) |
данные, сессии и файлы сохранены | StartedAt всех контейнеров обновился, PASS, прежний токен работает | в пределах бюджета теста, потерь нет |
| Остановка minio | /health/ready 503, LB снимает реплики; после start всё возвращается | ровно так; после start оба X-Instance-Id вернулись | ~15–20 с, потерь нет |
| Stale pending (2 минуты) при grace 30 с (для теста) | reconciler удаляет строку и объект | "reconciler: sweep done pending=1 orphans=0", pending_left=0 | на следующем tick (≤10 с в тестовом прогоне) |
| Orphan-объект в S3 старше grace | reconciler удаляет объект | лог orphans=N, объект удалён | аналогично |
| 10 параллельных upload по 10 MiB | RAM каждой реплики в пределах 256 MiB | 10 upload за 1.79 с, peak 138 / 141.5 MiB | пик не превышен, OOM нет |
Пояснения:
- Ошибки в окне переключения nginx при остановке API-реплики - нормальны и разрешены README уровня 3 ("краткие ошибки во время обнаружения отказа измеряются и допустимы"). После 5 секунд writes продолжаются.
- Reconciler в тесте запускался с
RECONCILER_INTERVAL_SECONDS=10иRECONCILER_GRACE_SECONDS=30, чтобы уложиться в минуту. В дефолтной конфигурации интервал 5 минут, grace 1 час - для реальной работы это безопаснее, потому что не трогает свежие upload'ы и только что загруженные объекты, чей INSERT ещё в полёте. - Пик RAM 141 MiB на реплике - не от upload'ов, а от Argon2id при
регистрации пользователей (6 операций × 64 MiB malloc при bootstrap).
Upload'ы добавили только +1..4 MiB к peak, потому что Go heap уже
раздут GC и
io.LimitReaderограничивает каждый upload 10 MiB. Худший сценарий 141 + 100 = 240 MiB < 256 MiB - укладывается с запасом.
Ограничения и следующие шаги
Что выдерживает:
- Отказ одной API-реплики при живом S3 и Postgres.
- Перезапуск API и всех хранилищ (Postgres, Redis, MinIO) с сохранением volumes - данные, сессии и файлы.
- Отказ S3: /health/ready 503 без утечек, LB снимает реплики, после восстановления всё возвращается.
- Отказ между INSERT и PutObject: компенсация MarkFailed в том же запросе, без ожидания reconciler.
- Отказ между PutObject и UPDATE ready: reconciler через grace period (1 час) удаляет застрявшие pending и объект.
- Orphan-объекты (Put прошёл, INSERT упал): reconciler через grace period удаляет объекты в S3, которых нет в БД.
- 10 параллельных upload по 10 MiB - peak RAM каждой реплики укладывается в лимит 256 MiB.
Что не выдерживает:
- Отказ узла. Всё работает на одном хосте, потеря хоста = потеря системы. PostgreSQL и MinIO без репликации, nginx LB без резерва.
- Отказ MinIO на длительное время (например, потеря volume): файлы не восстановятся, потому что второй копии нет. Метаданные в Postgres остаются, скачивание отдаёт 404/503.
- Grace period reconciler (1 час) защищает от случайного удаления живых загрузок, но не является транзакционной гарантией. В редком случае ровно на границе grace и очень медленной загрузки возможен false-positive, теоретически удаление свежего объекта. Вероятность пренебрежимо мала для учебного стенда, но в реальной работе grace стоит увеличивать до нескольких часов и добавлять heartbeat-обновление updated_at у активных загрузок.
- Медленная сеть к S3: reconciler обходит ListObjects и Delete по одному, что на больших бакетах станет дорого. На учебном бакете это не проявляется.
Не реализовано в этой работе:
- Трек 5 (presigned upload или повторяемый reconciler с dry-run и инъекцией ошибок) - целевая оценка 4, трек 5 не заявлен.
- Background worker и thumbnail (это уже lab5).
- Argon2id вместо текущего KDF в lab7, TLS/mTLS, OpenBao.
- HTTPS. По контракту до lab7 достаточно HTTP для локального стенда.
- Rate limiting: схема допускает
429, реализация не требуется.
Учебные упрощения:
- MinIO fork pgsty/silo:
minio/minioзаархивирован, официальных community-образов с 2025 нет. pgsty/silo - drop-in замена с тем же S3 API и mc; версия образа закреплена. - Роль reconciler в одной реплике через pg advisory lock. Не является распределённой HA-сверкой; при потере хоста обе реплики и reconciler исчезают.
- БД и S3 в одном экземпляре, оба на том же хосте, что и API. Для уровня 3-4 достаточно, для продакшена нужны репликация БД, версионирование S3, отдельный хост под reconciler/worker.
Подтверждённые улучшения (сводка по lab4):
- Метаданные и бинарные данные разнесены: Postgres - источник истины для структуры, S3 - источник истины для байтов. Файл в локальном volume API не равен объектному хранилищу, потому что при остановке реплики файл недоступен через другую; S3 решает это.
- Grace period reconciler (1 час) не трогает живые загрузки и свежие Put-объекты: stale pending и orphans обрабатываются только после истечения срока.
- Отдельные S3-креды с ограниченной policy плюс приватный bucket плюс MINIO_BROWSER=off: административный доступ к S3 полностью изолирован от API. Проверяется в evidence/s3-private.txt.
- nginx client_max_body_size=12m: иначе nginx режет на 1 MiB по умолчанию, 413 летит без X-Request-Id (это ответ LB, а не API), и публичный тест падает "missing X-Request-Id".
- Миграция 0004 ослабляет CHECK messages_text_not_blank до
text !~ '^[[:space:]]+$':text=""с attachments валиден по lab4 anyOf, а whitespace-only по-прежнему запрещён на уровне БД.
Следующий шаг для полной картины: увеличить grace period reconciler до нескольких часов и добавить heartbeat от активных загрузок (обновление updated_at), чтобы устранить теоретический false-positive на границе grace. Для production-варианта - вынести reconciler в отдельный процесс/реплику и добавить репликацию БД и S3.