Files
mtusi2026lab4/REPORT.md
2026-11-13 11:05:05 +03:00

28 KiB
Raw Permalink Blame History

Отчёт — лабораторная 4: S3 и согласованность двух хранилищ

  • Автор, группа: Поликарпов Даниил Александрович, БПИ2303.
  • Целевая оценка: 5, трек 2 — согласованность PostgreSQL/S3.
  • Измерения: 2026-11-13T07:53:45.321916+00:00; окончание проверки: 2026-11-13T07:58:31.186189+00:00.
  • HEAD репозитория на момент проверки: ec540a1a725862a8619fcb758daec4ad197f0dd5; рабочее дерево содержит незакоммиченную реализацию. Это HEAD основы, а не опубликованный commit решения. Commit/PR ещё не созданы.
  • Идентификатор полного прогона: 79ad73c1e746481385a84cebffdcf65e; итог — acceptance.json.
  • Диагностика, тесты и подготовка отчёта выполнены с помощью OpenAI Codex. Исходники проверок и методики включены в репозиторий.

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

Нужны Docker Engine и Compose v2+, Go 1.27+, Python 3.9+, Bash, OpenSSL и Git. Проверено: macOS-26.5.1-arm64-arm-64bit-Mach-O, Docker 29.7.2, aarch64, 14 vCPU и 7.75 GiB памяти Docker VM. Нужны свободные loopback-порты 18081 и 18082. Соседние репозитории не требуются.

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-dev.txt
make up
make check validate PYTHON=.venv/bin/python
make build vet test test-go test-storage
make test-persistence ACTION_SCRIPT=./scripts/restart.sh
make test-failover ACTION_SCRIPT=./scripts/stop-one.sh
make restore
make reconcile
# Полный изолированный прогон, включая отказы и исследование:
make evidence PYTHON=.venv/bin/python
python3 scripts/write-report.py
# Безопасная остановка основного стенда, данные сохраняются:
make down

make up идемпотентно создаёт .env.lab4, JWT-ключи и отдельные S3 admin/API-ключи в secrets/lab4; существующие пароли и ключи не заменяются. Файлы игнорируются Git и исключены из Docker build context. API монтирует только JWT и собственные S3-ключи, admin-ключи в API не попадают. Единственная публикация основного стенда — 127.0.0.1:18081 через HAProxy.

Для намеренного удаления только учебных данных основного стенда оператор может выполнить ./scripts/compose.sh down -v. При обычном restart/failover эта команда не применяется. Экспериментальный проект — mtusi2026lab4-evidence; его volumes также сохраняются после проверки. Повторная приёмка добавляет синтетические данные к существующим, что отражено в фактических размерах наборов.

Архитектура и конфигурация

Клиент → HAProxy → API × 2 → PostgreSQL + приватный SeaweedFS. Redis хранит кэш неизменного состава чата; серверные сессии остаются в PostgreSQL. Перенесены регистрация/сессии, чаты, keyset-пагинация, общая БД и идемпотентность lab3. Добавлены Attachment, связи с сообщениями, HTTP endpoints, S3, reconciler и операторское восстановление.

Роль Образ / версия Готовность и сохранность Доступ
API × 2 / migrator Сборка исходников: Go 1.27.2-alpine3.23 → Alpine 3.23.6 /health/live; /health/ready проверяет PostgreSQL и S3 API-порты не опубликованы; migrator — отдельный одноразовый процесс
PostgreSQL 17.11-alpine3.23 pg_isready; postgres_data Только сеть Compose
Redis 8.2.11-alpine3.22 AUTH PING; AOF в redis_data Только сеть Compose
HAProxy 3.2-alpine Проверяет readiness каждой API-реплики Только loopback 18081
SeaweedFS 4.52 s3_data содержит master/volume/filer; bootstrap проверяет bucket и PUT/DELETE Только internal-сеть storage, без публикации gateway/master/filer

Все digest закреплены в compose.yaml и Dockerfile. SeaweedFS: sha256:57877e32bb90073b37dc109b438ba66e84fd5ed9ced5f5c04f56444ef243ce59. s3-init использует admin identity и создаёт приватный bucket. В его JSON нет anonymous identity. API identity ограничена Read/Write/List конкретного bucket и не имеет Admin; создание другого bucket отвергается. Образы и точные зависимости Go зафиксированы manifest/lock-файлами проекта.

.env.example описывает параметры Compose: HOST_PORT/API_REPLICAS, пароли PostgreSQL/Redis, лимиты API и пула, SESSION_TTL_SECONDS, S3_BUCKET, MAX_UPLOAD_BYTES/MAX_IMAGE_PIXELS, UPLOAD_TIMEOUT и RECONCILE_GRACE_PERIOD. Их изменения задаются в .env.lab4 или окружении оператора. S3_ENDPOINT, S3_REGION и пути credentials зафиксированы в compose.yaml; одноимённые переменные в .env.lab4 их не переопределяют. В примере они приведены как комментарии для справки.

Для нестандартного bucket нужно также экспортировать S3_BUCKET перед make up: генератор S3-политики читает окружение процесса, а не .env.lab4. Для сдачи и приёмки используется стандартный messenger-attachments. Основной и экспериментальный проекты используют общие локальные файлы credentials; менять bucket/политику при работающем основном стенде не следует.

По умолчанию: API — 1 CPU/512 MiB каждая, четыре upload slots, один decoder, GOMEMLIMIT=384MiB; PostgreSQL — 2 CPU/1 GiB, Redis — 0.25 CPU/128 MiB, S3 — 1 CPU/512 MiB, LB — 0.5 CPU/128 MiB. Это лимиты контейнеров, а не гарантия высокой доступности единственного Docker-host.

Синхронная загрузка и транзакционные границы

  1. Проверить сессию и членство в чате; неизвестный и чужой ресурс одинаково дают 404. Проверить отображаемое filename, MIME и Content-Length.
  2. Прочитать не более 10 MiB через MaxBytesReader во временный файл, одновременно вычисляя SHA-256. Проверить формат и размеры через DecodeConfig, затем полностью декодировать PNG/JPEG под отдельным semaphore. Лимит 40 млн пикселей проверяется до полной распаковки.
  3. Сервер генерирует уникальный ключ originals/<UUID> и получает advisory session lock этого ключа. Filename не участвует ни в локальном пути, ни в S3 key.
  4. Сохранить оригинал в S3, затем атомарно вставить метаданные в PostgreSQL. Только после подтверждённого сохранения вернуть 201, status=ready, variants=[], error_code=null.
  5. Удалить временный файл. После ответа скачивание зависит от S3 и БД, а не от файловой системы загрузившей реплики. Скачивание проходит через авторизованный API без redirect; Content-Length позволяет клиенту обнаружить обрыв передачи.

Атомарной транзакции PostgreSQL+S3 нет. При неопределённом результате COMMIT API возвращает ошибку, не выполняя слепой S3 DELETE: COMMIT мог пройти. Reconciler позже проверяет наличие метаданных. Обрыв тела до завершения чтения не создаёт готовый Attachment. Повтор самостоятельного upload может создать ещё один объект; прозрачных повторов публичного POST нет.

Сообщение, все связи вложений и результат идемпотентности записываются одной PostgreSQL-транзакцией. Правило «текст или вложение», UTF-8/4000 символов, максимум 10 уникальных ID и доступность вложений проверяет Go-сервис; функции и триггера message_content в миграциях нет. FK сохраняют ссылочную целостность. При проверке вложений используются row locks до COMMIT.

Версия хеша хранится в hash_version: legacy v1 учитывает текст, v2 — канонический текст и упорядоченный список ID. Отсутствующий список и [] равнозначны. Старые текстовые ключи продолжают воспроизводиться; изменение текста или вложений при том же ключе даёт 409. Порядок вложений сохраняется.

Reconciler и восстановление

make reconcile        # По умолчанию dry-run
make reconcile-apply  # Применить безопасные изменения
./scripts/compose.sh run --rm -T operator storage restore \
  --id <attachment-uuid> --source /fixtures/sample.png

Сверка читает S3 страницами по 100 объектов и БД keyset-страницами по 100 метаданных. Обрабатываются только серверные ключи originals/<UUID>. Для каждого ключа используется та же advisory lock, что при upload/restore; под ней проверяются метаданные и актуальный HEAD объекта. Если метаданные существуют, объект защищён, даже если он ещё не прикреплён к сообщению. Отсутствующие метаданные плюс возраст старше grace позволяют удалить orphan.

В обычном стенде upload timeout — 120 секунд, grace — один час; конфигурация требует grace больше удвоенного timeout. Это запас для отменённого запроса/потерянной DB-сессии. Предполагаются синхронизированные часы локального стенда. При неопределённом получении или освобождении lock соединение закрывается, а не возвращается в pool с потенциально удерживаемой блокировкой.

Missing — метаданные без оригинала. Dry-run только сообщает проблему; apply выставляет внутренний integrity_missing, сохраняя metadata, ID и ссылки сообщений. Клиент с доступом получает 503; публичный enum статуса lab4 не меняется. Восстановление требует предоставленного оригинала с совпадающими размером, MIME и SHA-256. После PUT выполняется контрольное чтение; только затем снимается признак повреждения. Неверный оригинал отвергается, повторный restore безопасен.

При ошибке любой зависимости проход завершается ненулевым кодом, сохраняя частичные счётчики. Уже выполненные безопасные действия не откатываются: общего COMMIT между хранилищами нет. Повторный запуск продолжает исправление. Для регулярной очистки оператору нужно запускать make reconcile-apply, например каждые 10 минут через свой планировщик; автоматическое cron-расписание не устанавливается.

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

Критерий Команда / наблюдение Доказательство
Структура и полный OpenAPI make check build vet, make validate — PASS build-checks, validate
Возможности lab3 и идемпотентность Go race suite: история/пагинация, 32 конкурентных повтора через 2 реплики go-tests
Обязательный API lab4 Публичный smoke: файл, attachment-only message, checksum, ACL — PASS smoke
PNG/JPEG, bytes/pixels, filename Exact 10 MiB — 201; превышение bytes, chunked и pixels — 413; MIME/corruption — 415; filename — 400 go-tests
Чужой файл и чат Metadata/content и cross-chat attachment — 404; duplicate/null ID list — 400 go-tests
Только Go-проверка содержимого Пустое сообщение отклоняется; attachment-only сохраняется; триггер отсутствует storage-tests
Атомарность сообщений Ошибка FK/записи ключа откатывает сообщение, связи и результат; legacy replay сохранён storage-tests
Приватность и ограниченные ключи Unsigned GET известного объекта — 403; API CreateBucket запрещён failures
Persistence Прежний token и исходный файл пережили restart; до/после видны реальные процессы всех stores persistence, snapshots
Остановка загрузившей реплики Поочерёдно остановлены обе; файл скачан другой репликой с тем же SHA-256 failures
Публичный failover Запись во время отказа, повторы без дубля, прежняя сессия — PASS failover
Недоступность S3 Liveness 200, readiness/upload 503; reconciler не удаляет/не помечает failures, S3 down
Отказ PostgreSQL Сверка прекращается без изменений; после восстановления метаданные сохранены failures, DB down
Прерывание и PUT → ошибка БД Незавершённый body не создаёт строку; timeout после PUT даёт диагностируемый orphan failures
Missing и восстановление Обнаружен; неверный оригинал отвергнут; верный восстановлен дважды без потери ссылки failures
Память при 10 клиентах Два размера, три повтора; ограничение admission учитывается в ошибках uploads
Безопасная сверка Fresh и использованные объекты сохранены, старые orphan удалены, повтор ничего не удаляет safety, scans
Bootstrap Повтор сохраняет ключи; существующий bucket допускает bootstrap и проверку записи bootstrap-repeat, bucket repeat

Полная команда воспроизведения — make evidence. PASS означает завершение перечисленных локальных сценариев, а не автоматическое выставление оценки. Секреты, tokens и raw HTTP-запросы в evidence не сохраняются.

Эксперименты

Гипотеза: при неизменяемых серверных ключах, общей блокировке и grace можно повторяемо удалить orphan, сохранив свежие и используемые вложения; missing обнаруживаются, а внешний оригинал позволяет восстановить данные без смены ссылок.

Изолированный проект использует те же образы и контейнерные ресурсы, но UPLOAD_TIMEOUT=5s, RECONCILE_GRACE_PERIOD=15s, чтобы ждать grace без часовой паузы. Обычные defaults остаются 120s/1h. Защита свежего объекта отдельно проверяется с grace 1h, независимо от длительности массового заполнения. Наборы содержат также ранее загруженные файлы — фактические размеры указаны ниже.

Upload: bytes и память

Перед каждым из трёх повторов для каждого размера API-контейнеры создаются заново, выполняется одна прогревочная загрузка исходного малого файла, затем barrier запускает 10 клиентов одновременно. Отдельного длительного прогрева нет. Оригинал — RGB PNG 320×200, 111817 байт; вариант 5 MiB содержит валидный ancillary PNG chunk и имеет те же декодированные размеры. Это сравнение стоимости передачи bytes, а не исследование больших изображений.

Bytes Повтор Длительность, s Успехи Успешные RPS Ошибки p50/p95/p99, ms Max peak одной API, MiB CPU samples API
111817 1 0.046 10/10 219.2 0% 25.4/28.5/28.5 13.2 0.25%, 2.55%
111817 2 0.030 9/10 303.6 10% 14.4/16.9/16.9 13.0 0.13%, 0.13%
111817 3 0.028 8/10 282.1 20% 14.5/16.2/16.2 15.2 0.13%, 0.14%
5242880 1 0.548 8/10 14.6 20% 342.3/419.0/419.0 35.2 0.10%, 8.72%
5242880 2 0.550 8/10 14.5 20% 289.6/378.3/378.3 34.4 0.09%, 8.52%
5242880 3 0.534 8/10 15.0 20% 292.3/361.2/361.2 35.5 0.14%, 8.36%

Максимальный наблюдавшийся пик одной API: 35.5 MiB при лимите 512 MiB. Сняты memory.current и kernel memory.peak cgroup v2: peak относится ко всей жизни заново созданного контейнера, включая startup и прогрев, а не только к интервалу burst. CPU — короткий docker stats --no-stream sample; он не даёт надёжной оценки steady-state CPU для столь короткого burst. В errors отдельно учитываются 429, повторов скрыто нет. Percentiles относятся только к успешным запросам; 10 наблюдений недостаточно для устойчивой оценки хвоста. RPS включает клиентскую подготовку, не доказывает максимальную пропускную способность сервера.

Стоимость сверки

После заполнения выдерживается 16 секунд, выполняются три dry-run, apply и повторный apply. В таблице — медиана времени dry-run; счётчики вызовов приведены для первого прохода.

Добавлено orphan Объекты / metadata Dry-run median, ms Вызовы S3 Проверки/страницы БД Попытки session lock Удалено apply Удалено повторно
100 270 / 167 155 272 271 435 101 0
1000 1169 / 167 555 1180 1170 1334 1000 0

db_checks считает проверки наличия, страницы метаданных и изменения; это не все сетевые round trips PostgreSQL. Каждая успешная session lock добавляет SQL получения и освобождения; отдельно показан lock_attempts. S3-счётчик включает HEAD bucket, List pages, Head objects и Delete. Стоимость растёт с фактическим числом объектов и метаданных; общий snapshot двух хранилищ не создаётся. Вставка UUID позади keyset cursor может попасть в следующий периодический проход.

Безопасность проверена предметными наблюдениями: свежий orphan остался, referenced originals не удалялись, invalid key и объект вне prefix остались, после очистки второй apply удалил ноль объектов и missing не появилось. Во время отдельного прохода выполнялся upload; его подтверждённый оригинал скачан с тем же checksum. Это конкурентный прогон, а детерминированное ожидание и отмена advisory lock отдельно проверены на реальном PostgreSQL в storage suite.

Воздействие Наблюдение Доказательство
Uploader 1 Остановлен именно процесс ffe0b126d1ef-37dbaa20-b33b-435f-9096-d7a918f55274 Скачал ddf8beb720a9-6d79116b-1a2d-435e-80e4-6a59b87714be; SHA-256 совпал
Uploader 2 Остановлен именно процесс ddf8beb720a9-6d79116b-1a2d-435e-80e4-6a59b87714be Скачал ffe0b126d1ef-4c4cd939-b319-45c4-81d8-2d9449a97b87; SHA-256 совпал
Restart PostgreSQL/Redis/S3/API/LB Прежние данные, session и bytes сохранены; процессы перезапущены или заменены persistence + snapshots
S3 остановлен 200 live, 503 ready/upload; после bootstrap путь записи восстановлен failures
PostgreSQL остановлен Reconciler завершился без удаления, после запуска данные сохранены failures
Тело upload оборвано Строка Attachment не появилась failures
PUT успешен, INSERT заблокирован Upload 503, метаданные не появились, orphan найден и очищен после grace failures + reconciliation
Оригинал удалён из S3 Missing отмечен, затем исходник восстановлен с тем же ID/checksum и ссылкой failures

В этих сценариях потери подтверждённых данных после restart/failover не обнаружены. Время восстановления отдельно не измерялось: проверки подтверждают восстановление в пределах своих таймаутов, но не дают оценки RTO.

Ограничения и источники

Один Docker-host, PostgreSQL, Redis, S3 и LB остаются одиночными точками отказа. Сессии хранятся в БД, Redis — необязательный cache; отказ S3 выводит API из readiness. Ошибки, сформированные самим LB при отсутствии здоровых backend, могут не иметь JSON/identity headers приложения. HTTP допустим только для локального стенда с синтетическими данными; TLS — задание lab7.

Reconciler не делает резервное копирование, не восстанавливает bytes из SHA-256 и не проверяет checksum каждого существующего объекта при обычном HEAD-обходе. Если оригинала/backup нет, missing остаётся невосстановимым. Временный локальный файл используется до сохранения, но не является долговременным источником оригинала. GOMEMLIMIT — мягкий бюджет Go, а не жёсткая гарантия RSS; предел процесса задаёт cgroup, полная распаковка всё ещё ограничена количеством пикселей и одним decoder.

Периодическую сверку запускает оператор. Потеря БД сессии/сетевые разделения покрываются блокировками, ограничением времени запроса и grace в рамках заявленного локального стенда; глобальной транзакции или защиты от произвольных внешних writers с admin-ключами нет. Нагрузочные результаты привязаны к этому hardware, размерам изображений и короткому burst-профилю.

Первичные материалы: SeaweedFS 4.52, S3 credentials/configuration, AWS SDK for Go v2 endpoints, S3 upload semantics. Использованы стандартные Go image/png/jpeg, AWS SDK v2, pgx, chi и oapi-codegen; версии — в go.mod/go.sum и generated header. Обязательный контракт и fixture предоставлены материалами курса.