29 KiB
Отчёт — лабораторная 4
- Автор, группа: Кораблев Петр, БВТ2304
- Целевая оценка: 5 (уровень 3 + уровень 4 + трек 2 «Согласованность двух хранилищ»)
- Commit/PR: ветка
solution/BVT2304-korablev - Использованные источники, библиотеки и помощь ИИ: Go 1.23.4, net/http, pgx/v5 5.7.2, go-redis/v9 9.7.0, golang.org/x/crypto (Argon2id), golang.org/x/sync 0.10.0 (semaphore), google/uuid 1.6.0, minio-go/v7 7.0.82 (S3-клиент, работает с любым S3-совместимым сервером), стандартные
image/pngиimage/jpeg. Образы: PostgreSQL 17.2-alpine3.21, Valkey 8.0.2-alpine3.21, HAProxy 3.0.5-alpine, SeaweedFS 3.80 (chrislusf/seaweedfs:3.80), golang:1.23.4-alpine3.21 → alpine:3.21.2; для проверок вне API — python:3.12.8-alpine3.21. Документация: AWS S3 (uploads, SigV4, ListObjectsV2), SeaweedFS wiki (S3 API,s3.configidentities), Goimage.DecodeConfig. Помощь ИИ использовалась при написании отчёта.
Запуск из чистого clone
Prerequisites: Docker 29.x + Compose v2 (Docker Desktop/WSL2), Python 3.9+, Git. Go и make локально не нужны (сборка в Docker; без make команды ниже запускаются через python). На Windows тесты запускать с PYTHONUTF8=1 (контракт в UTF-8).
python3 scripts/init_secrets.py # = make secrets: secrets/* + .env из .env.example
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --wait # = make up
make check && make test # smoke через LB http://localhost:8080
make test-student # собственные тесты (18 кейсов)
make test-persistence ACTION_SCRIPT=scripts/restart.sh # Windows: scripts/restart.cmd
make test-failover ACTION_SCRIPT=scripts/stop-one.sh # Windows: scripts/stop-one.cmd
docker compose up -d --no-recreate --wait api # вернуть остановленную реплику
make ops-checks memory track2-faults track2-cost # уровень 4 и трек 2 (нужен Docker)
init_secrets.pyгенерирует случайные пароли PostgreSQL/Valkey и две S3-идентичности:bootstrap-admin(только дляs3-init) иmessenger-api(праваRead/Write/Listтолько на bucketmessenger-attachments), а такжеsecrets/s3_identities.json— конфиг SeaweedFS. Всё вsecrets/(в.gitignoreи.dockerignore), контейнерам передаётся как Compose secrets/run/secrets/*.- Порядок старта задан
depends_on: postgres/valkey/s3 healthy →migrate(миграции под advisory lock) →s3-init(идемпотентное создание bucket) →api×2 →lb;reconcilerстартует послеs3-init. Готовность —--wait//health/ready. - Безопасная остановка:
docker compose stop(make down), данные в volumespgdata,s3dataсохраняются. Намеренное удаление учебных данных:docker compose down -v(удаляет volumes — необратимо).
Архитектура и решения
client → HAProxy (lb, 127.0.0.1:8080) → api ×2 (Go, read-only rootfs)
├─ PostgreSQL: users, chats, messages, sessions, idempotency,
│ attachments (метаданные), message_attachments
├─ Valkey: кэш сессий (из lab3)
└─ SeaweedFS S3 (bucket messenger-attachments, приватный): байты
reconciler (тот же образ, `reconcile --apply --every 10m`) — сверка БД ↔ S3
Перенесено из lab3 без изменения поведения: пользователи, Basic → Bearer-сессии (Argon2id, Valkey-кэш), чаты, keyset-пагинация, обязательный Idempotency-Key, X-Instance-Id, HAProxy с health-check, хуки restart/stop-one. Изменено: убран экспериментальный путь MESSAGE_WRITE_PATH=tx трека 1 lab3 (остался один путь — one-shot CTE), лимит памяти API 256M → 512M, таймауты HAProxy client/server 30s/10s → 75s (загрузка до 10 MiB).
Выбор S3-сервера. Планировался MinIO, но на 2026-10 образы minio/minio и minio/mc недоступны ни в Docker Hub, ни в quay.io (pull access denied / 401). Выбран SeaweedFS 3.80: одна команда weed server -s3 (master+volume+filer+S3), идентичности с правами на конкретный bucket через -s3.config, без анонимной идентичности — значит bucket приватный. S3-порт 8333 не публикуется, консоли master (9333) и filer (8888) тоже: сервис только в сети data.
Модель данных (src/internal/db/migrations/0003_attachments.sql):
attachments:id,chat_id,owner_id,filename(только для отображения),content_type,size_bytes,sha256,width,height,object_key(UNIQUE, генерирует сервер:attachments/<chat_id>/<attachment_id>),status ∈ {pending, ready},missing_at,created_at,updated_at. FK(chat_id, owner_id) → chat_members, CHECK-и на размер ≤ 10 MiB, пиксели ≤ 40M, формат sha256.message_attachments(message_id, chat_id, attachment_id, position)с составным FK(chat_id, attachment_id) → attachments(chat_id, id): сама БД не даёт привязать к сообщению файл другого чата.messages.textтеперь может быть пустым (CHECK 0..4000); правило «пустой текст только при ≥1 вложении» проверяет API.
Загрузка POST /api/v1/chats/{id}/attachments?filename=… (src/internal/api/attachments.go):
- Аутентификация → членство в чате (посторонний получает 404 до чтения тела) →
filename(1..255 code points, без/,\, NUL, управляющих и bidi-override символов, не./..) →Content-Type∈ {image/png, image/jpeg} иначе 415 →Content-Length > 10 MiB→ 413 сразу. - Слот загрузки (семафор
UPLOAD_CONCURRENCY=8на реплику), тело читается черезhttp.MaxBytesReader(10 MiB)→ 413 при превышении. Тело буферизуется в памяти (≤ 10 MiB на слот), значит память одной реплики под загрузки ограничена 8 × 10 MiB. - Формат определяется по magic bytes и сравнивается с заявленным (подмена → 415);
image.DecodeConfigчитает только заголовок: >40M пикселей → 413 до декодирования; затем полное декодирование под общим бюджетом памяти (DECODE_BUDGET_BYTES=128 MiB, взвешенный семафор по оценкепиксели × байт/пиксель) — повреждённые данные → 415. - Транзакционная граница: (a)
INSERT attachments status='pending'→ (b) S3PUT(Content-MD5) → (c)UPDATE … SET status='ready' WHERE status='pending'→201 ready. 201 возвращается только когда и байты, и метаданные зафиксированы. - Ошибка на (b) или (c) → 503 и фоновая компенсация, которая начинается со строки:
DELETE … WHERE status='pending', и только если строка удалена — удаление объекта. ЕслиUPDATE → readyна самом деле закоммитился, а ответ БД потерялся, строка уже ready, и объект не трогаем (иначе получилось бы ready-вложение без байтов). Если недоступна БД, остаётся stale pending; если недоступен S3, может остаться объект без строки. Оба случая убирает reconciler после grace.
Скачивание GET /attachments/{id}/content: только участники чата (иначе 404), только status='ready'; Stat до первого байта ответа (отсутствие объекта → 404, недоступность S3 → 503), затем поток из S3 в ответ, без redirect; заголовки Content-Type (истинный), Content-Length, X-Content-Type-Options: nosniff, Cache-Control: private, no-store, ETag: "<sha256>". variant=thumbnail|crop|optimized → 404 (вариантов в lab4 нет), неизвестный → 400.
Сообщение с attachment_ids: 0..10 уникальных UUID (иначе 400). Проверка «все ready и в этом чате», запись idempotency, сообщения и связей — одним SQL-оператором (CTE), как в lab3. Чужое, неизвестное или из другого чата → 404, ничего не сохраняется. Отпечаток идемпотентности считается по {text, attachment_ids} с нормализацией «нет поля» = [].
Готовность и отказы. /health/ready зависит только от PostgreSQL. Недоступность S3 ломает только эндпоинты вложений (503), а текстовый мессенджер продолжает работать: если бы ready зависел от S3, LB снял бы обе реплики и упал бы весь API. SDK S3 настроен на быстрый отказ: MaxRetry=1, dial-таймаут 2 с, ResponseHeaderTimeout 10 с, операции под S3_TIMEOUT=15s.
Соответствие .env.example — все переменные реально используются в compose.yaml: S3_ENDPOINT=http://s3:8333, S3_REGION, S3_BUCKET, S3_*_FILE (secrets), MAX_UPLOAD_BYTES (не больше 10 MiB, иначе старт с ошибкой), MAX_IMAGE_PIXELS, плюс UPLOAD_CONCURRENCY, DECODE_BUDGET_BYTES, UPLOAD_TIMEOUT, S3_TIMEOUT, API_MEMORY, API_GOMEMLIMIT, RECONCILE_GRACE, RECONCILE_EVERY.
| Роль | Service | Образ | Health | Volume | Сеть / порт | Credentials |
|---|---|---|---|---|---|---|
| LB | lb | haproxy:3.0.5-alpine | :8404/healthz |
— | app; 127.0.0.1:8080 | — |
| API ×2 | api | mtusi-messenger:lab4 (сборка) | /health/ready |
нет (read-only rootfs, tmpfs /tmp 1m) | app, data | secrets: database_url, cache_url, s3_access_key_id, s3_secret_access_key |
| БД | postgres | postgres:17.2-alpine3.21 | pg_isready | pgdata | data | pg_password |
| Сессии | valkey | valkey/valkey:8.0.2-alpine3.21 | ping | — | data | valkey_auth |
| S3 | s3 | chrislusf/seaweedfs:3.80 | :8333/healthz |
s3data | data, не публикуется | s3_identities.json |
| Bootstrap | migrate, s3-init | mtusi-messenger:lab4 | one-shot | — | data | database_url / s3_admin_* |
| Сверка | reconciler | mtusi-messenger:lab4 | — | — | data | database_url, s3 api-ключи |
Доказательства критериев
Окружение всех замеров: Windows 11, Docker Desktop 29.7.2 / Compose 5.5.0, WSL2 kernel 6.18; лимиты: API 1 CPU / 512M ×2, S3 1 CPU / 1G, PostgreSQL 2 CPU / 1G, reconciler 0.5 CPU / 128M. Дата — 2026-10-29.
Уровень 3
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл |
|---|---|---|---|
| Публичный smoke | make check, make test |
PASS: lab4 public API scenario | evidence/check-smoke.txt |
| Возможности lab3 сохранены | make test-student (8 кейсов lab3) |
no-sticky, идемпотентность через 2 реплики, logout на всех репликах — PASS | evidence/student-tests.txt |
| S3 в общем стенде, байты в приватном bucket | lab4ops.py private |
аноним GET/LIST/CreateBucket → 403; api-ключ GET → 200, sha256 совпадает; порт S3 не опубликован | evidence/private.json |
| Метаданные в PostgreSQL, не байты в БД/на диске API | lab4ops.py no-local-file |
у API read-only rootfs (touch → Read-only file system), монтируются только secrets, новых файлов 0 |
evidence/no-local-file.json |
| 201 ready, побайтный download, ACL | smoke + t_upload_formats, t_attachment_acl |
PNG и JPEG: sha256/размер/Content-Type совпадают; посторонний получает 404 на метаданные/content/upload, без токена 401 | evidence/student-tests.txt |
| Реальные PNG/JPEG ≤10 MiB, ≤40M px, MIME по содержимому, опасные filename | t_size_limit, t_bomb, t_corrupt_and_spoof, t_filenames |
PNG 10 420 335 B → 201; 10 MiB+1 → 413; заголовок 20000×20000 → 413 за 32 мс; 9 вариантов подмены/повреждения → 415; 12 опасных имён → 400 | evidence/student-tests.txt |
| Upload → стоп обслужившей реплики → download через другую | lab4ops.py failover-upload |
загрузка через api-2, docker stop api-2, 10/10 скачиваний через api-1 с верным sha256 |
evidence/failover-upload.json |
| Failover (публичный тест) | make test-failover для каждой реплики |
остановлена api-2: PASS, 123 записи, 0 ошибок, восстановление за 4.1 с; остановлена api-1: PASS, 116 записей, 0 ошибок, 4.1 с; файл цел в обоих случаях | evidence/failover.txt |
| Restart всего стенда с volumes | make test-persistence (restart.cmd) |
PASS; postgres/valkey/s3/api перезапущены (uptime до/после в файле), файл и сессия сохранились | evidence/persistence.txt |
Уровень 4
| Критерий | Команда/сценарий | Наблюдаемый результат | Файл |
|---|---|---|---|
| Тесты: большой файл, повреждённое изображение, подмена MIME, чужой attachment_id, файл другого чата; нет 500 | make test-student (10 кейсов lab4) |
18/18 PASS; в логах API за все прогоны нет ни одного 500 | evidence/student-tests.txt |
| Нет вечных неучтённых объектов: компенсация + сверка с grace | pending-intent + компенсация + reconciler (grace 15 мин, каждые 10 мин) |
см. трек 2; реальный случай: после падения S3 reconciler нашёл 19 stale pending из прерванных загрузок и удалил их | evidence/track2/faults.json |
| Отказ S3 | lab4ops.py s3-outage |
upload 503 за 2.0 с, download 503 за 2.0 с, метаданные 200, текстовое сообщение 201, ready 200; после старта S3 загрузки сразу работают, старый файл цел; pending-строк не осталось (компенсация удалила строку) | evidence/s3-outage.json |
| Ограниченная RAM, ≥10 одновременных загрузок | make memory |
см. «Эксперименты»: пик API ≤ 311 MiB при 40 одновременных 10-МБ загрузках, плато уже после 20 | evidence/memory.json |
| Bootstrap идемпотентен | lab4ops.py bootstrap (двойной запуск migrate и s3-init) |
«migrations up to date», created:false |
evidence/bootstrap.json |
| Отдельные ограниченные S3 credentials; консоль закрыта; private bucket проверен вне API | lab4ops.py private |
api-идентичность: CreateBucket → 403, PUT в другой bucket → 403; S3/консоли не опубликованы; аноним → 403 | evidence/private.json |
Трек 5.2 «Согласованность двух хранилищ»
| Критерий | Команда | Результат | Файл |
|---|---|---|---|
| Повторяемый reconciler с dry-run | server reconcile [--apply] [--grace] [--every] |
dry-run по умолчанию; advisory lock — одновременно идёт один проход | src/internal/reconcile/reconcile.go |
| Ошибки на обеих сторонах: обнаружение и исправление | make track2-faults |
5 из 5 внедрённых сбоев найдены, 7 исправлений, повторный apply → 0 | evidence/track2/faults.json |
| Свежие и используемые не удаляются | там же | свежий orphan, свежий pending и используемые U1/U2 остались целы | evidence/track2/faults.json |
| Стоимость обхода | make track2-cost |
линейно, ~70 мкс/объект, 20k за 1.4–1.6 с | evidence/track2/cost.json |
Эксперименты и отказы
Память API при одновременных загрузках (уровень 4)
Гипотеза: пиковая память реплики ограничена ≈ база + UPLOAD_CONCURRENCY × 10 MiB + бюджет декодирования, поэтому она выходит на плато и не растёт с числом клиентов.
Методика: scripts/lab4ops.py memory. Синтетический шумовой PNG 1000×3480, 10 420 335 B (почти лимит). Перед каждым прогоном docker compose restart api, одна прогревочная загрузка, затем N одновременных загрузок (барьер) через LB. Пик читается из cgroup v2 memory.peak каждой реплики. По 2 повтора.
| Одновременно | Успешно | Wall, с | p50 / max, мс | Пик API, MiB (max из 2 реплик) |
|---|---|---|---|---|
| 1 | 1/1, 1/1 | 0.35 | 337–344 | 64.4 / 66.4 |
| 10 | 10/10, 10/10 | 3.1–4.1 | 2844–3830 / 2882–3945 | 148.2 / 151.7 |
| 20 | 20/20, 20/20 | 6.4–7.1 | 5476–6097 / 6062–6830 | 286.0 / 263.7 |
| 40 | 40/40, 40/40 | 11.8–12.6 | 8542–9590 / 11156–12044 | 264.5 / 311.1 |
Вывод: память выходит на плато ~250–310 MiB между 20 и 40 клиентами (слоты по 8 на реплику). Лишние клиенты ждут слота, это видно по росту latency, а не памяти. Это ниже лимита 512M и GOMEMLIMIT 400MiB. Ограничения: буфер одного тела ≤10 MiB в RAM — сознательное упрощение вместо потокового парсера PNG. 40M-пиксельный RGBA PNG при декодировании занимает ~160 MB и упирается в бюджет 128 MiB (декодируется один, остальные ждут). Запуск на одном ноутбуке, клиент и стенд делят CPU.
Найденный отказ: первый прогон шёл с лимитом S3 512M, и на 20 параллельных PUT процесс SeaweedFS перезапустился (RestartCount 1, логов завершения нет — kill по памяти). 18 из 20 загрузок получили корректный 503, их pending-строки остались (тогдашняя версия компенсации сначала удаляла объект и при недоступном S3 сохраняла строку) и затем были найдены reconciler как 19 stale pending, вместе с одной от теста отказа S3. Лимит S3 поднят до 1G: в повторе 0 рестартов при memory.peak ≈ 1 GiB. Этот пик включает page cache записываемых файлов, который ядро может вытеснить.
Трек 2: внедрение ошибок (grace = 1 мин для эксперимента, 15 мин в стенде)
Методика scripts/track2/run_track2.py faults. Периодический reconciler на время теста останавливается. Сбои вносятся напрямую: в S3 через scripts/track2/s3tool.py (SigV4 на stdlib, запускается в одноразовом контейнере в сети data), в БД через psql.
| Сбой (сторона) | Ожидание | dry-run | apply |
|---|---|---|---|
| F1 объект без строки (S3) | удалить после grace | orphan_object | удалён |
| F2 потеряна строка неиспользуемого U3 (БД) | объект стал сиротой → удалить | orphan_object | удалён |
| F3 потерян объект используемого U2 (S3) | метаданные не трогать, пометить | missing_object | missing_at выставлен; GET метаданных 200, content 404, сообщение по-прежнему ссылается на U2 |
| F4 падение между PUT и ready (pending + объект, 1 ч) | удалить строку, затем объект | stale_pending | удалены оба |
| F5 падение до PUT (pending без объекта, 1 ч) | удалить строку | stale_pending | удалена |
| F7 загрузка «в процессе» (свежие pending + объект) | не трогать | не найдена (row известен) | цела |
| F8 свежий объект без строки | не трогать | skip: younger than grace |
цел |
| U1 используемый, исправный | не трогать | — | скачивается, sha256 верный |
- Dry-run ничего не меняет: счётчики S3-объектов, строк, pending и missing до и после совпадают (
dry_run_changed_nothing: true). - Первый apply: 7 исправлений, 0 ошибок.
- Повторный apply: 0 исправлений, только
skipсвежего F8 — проход идемпотентен. - Восстановление: после возврата объекта U2 «из бэкапа» (те же байты) apply выдаёт
recovered=1, снимаетmissing_at, и скачивание отдаёт исходный sha256. - Сторонние находки: dry-run отдельно учитывает находки вне чата эксперимента (
other_findings_outside_experiment) — это остатки предыдущих прогонов.
Почему это безопасно. Порядок «сначала LIST S3, потом скан БД» плюс «pending-строка пишется до PUT» означают, что у любого объекта из листинга строка уже есть. Перед каждым разрушающим действием есть повторная проверка: сирота — ObjectKeyKnown в БД, missing — StatObject, pending — DELETE … WHERE status='pending'. Удаляются только объекты без строк и pending-строки; ни одна из них не может быть в message_attachments, потому что привязать можно только ready. Используемые метаданные никогда не удаляются. Grace 15 мин намного больше бюджета загрузки (60 с). Если UPDATE → ready проигрывает гонку с reconciler, загрузка отвечает 503, а не 201.
Трек 2: стоимость обхода
scripts/track2/run_track2.py cost: в БД добавляются N ready-строк (SQL generate_series), в S3 — N объектов по 100 B. Каждый размер замеряется трижды в dry-run, после замеров bench-данные удаляются.
| Объектов | list S3, мс | скан БД, мс | всего, мс | мкс/объект | пик памяти reconciler, MiB | находок |
|---|---|---|---|---|---|---|
| 1 229 | 52 | 6–9 | 59–61 | 48–50 | 10.1–10.9 | 0 |
| 5 229 | 258–345 | 62–70 | 326–408 | 62–78 | 15.8–17.2 | 0 |
| 20 229 | 1321–1537 | 41–95 | 1404–1618 | 69–80 | 30.8–31.2 | 0 |
Вывод: стоимость линейна, примерно 70 мкс и 1 КБ RAM на объект. Больше 90% времени занимает постраничный LIST в S3 (по 1000 ключей). На 20k объектов ложных срабатываний 0. При частоте раз в 10 минут нагрузка ничтожна. Ограничение: все ключи держатся в памяти, на 10M объектов это ~1 ГБ. Дальше нужен обход по префиксам attachments/<chat_id>/ или потоковое слияние двух отсортированных списков: ключи S3 и ORDER BY object_key в БД.
Сводка отказов
| Воздействие | Что ожидаем | Что наблюдали | Восстановление / потеря данных |
|---|---|---|---|
docker stop обслужившей API-реплики |
LB уводит трафик | первая успешная запись через ~4 с, 0 дублей; файл скачивается через другую | без потерь |
| Restart postgres+valkey+s3+api | данные, сессия и файл живы | PASS, тот же токен работает | без потерь |
| Остановка S3 | 503 только на вложениях | upload/download 503 за 2 с, текст и ready работают | после старта S3 сразу; pending-строк не осталось |
| SeaweedFS убит по памяти (лимит 512M) | 503, без 201 на несохранённое | 18× 503, 2× 201 | 19 pending-строк убраны reconciler; лимит поднят до 1G |
| Внедрённые orphan/missing/pending | найти, исправить безопасно | 5/5 найдены, повторный apply = no-op | missing-байты невосстановимы без бэкапа: метаданные помечены и сохранены |
Ограничения и следующие шаги
- Один Docker-host, по одному PostgreSQL, S3-узлу и LB: выдерживается отказ одной API-реплики и рестарт стенда, но не потеря хоста или диска S3. В SeaweedFS нет репликации томов.
- Тело загрузки буферизуется в RAM до 10 MiB на слот. Это ограничено и измерено, но не полностью потоковый режим.
- Полное декодирование нужно для отсева повреждённых файлов и стоит CPU: 40 одновременных загрузок 10 МБ занимают ~12 с на 2×1 CPU.
- Объект, у которого обнаружен
missing, невосстановим без бэкапа. Reconciler только помечает его, и API отдаёт 404 на content. - Reconciler хранит все ключи в памяти (ограничение указано выше).
size_mismatchтолько сообщается, автоматически не исправляется. - Цель failover-теста выбирается по
X-Instance-Idобслужившего ответа, а HAProxy раздаёт запросы по кругу, поэтому без вмешательства тест детерминированно останавливал api-2. Для проверки api-1 перед запуском был сделан один лишний запрос через LB (curl http://localhost:8080/health/live), сдвигающий очередь; так получен прогон с остановкой api-1. - CI-job со сборкой стенда и
make testне добавлен: workflow skeleton проверяет только контракт.