Files
mtusi2026lab4/REPORT.md
T

17 KiB
Raw Blame History

Отчёт — лабораторная работа № 4

  • Автор: Пластинин Денис, БВТ2303.
  • Целевая оценка: 5.
  • Выбранный трек: 2, согласованность PostgreSQL и S3.
  • Ветка: solution/bvt2303-plastinin.
  • Источники и инструменты: документация Go, PostgreSQL и MinIO; Codex использован при реализации.

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

Требуются Docker Engine с Compose V2, Git и свободные локальные порты 8080, 8081, 9090 и 3000. Для запуска Go-проверок вне контейнера нужен Go 1.26. Образы приложения и MinIO собираются из исходников внутри Docker. Версии Go, PostgreSQL, Valkey, Nginx, MinIO и остальных компонентов закреплены в Dockerfile и compose.yaml.

cp lab4.env.example .env
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --scale api=2 --wait --wait-timeout 180

После запуска доступны:

  • API через Nginx: http://localhost:8080;
  • Swagger UI: http://localhost:8081;
  • Prometheus: http://localhost:9090;
  • Grafana: http://localhost:3000, пользователь admin, пароль из GRAFANA_ADMIN_PASSWORD.

Публичные и внутренние проверки:

make check
make test BASE_URL=http://localhost:8080
docker compose --profile tests run --rm --build tests
go test -race ./...
go vet ./...

Сверка PostgreSQL и S3 выполняется внутри запущенной API-реплики. Без --apply команда ничего не удаляет:

docker compose exec -T api /app/messenger reconcile-attachments --grace-period=1h
docker compose exec -T api /app/messenger reconcile-attachments --apply --grace-period=1h

Эксперименты запускаются на чистом стенде:

docker compose exec -T api /app/lab4experiment memory
docker compose exec -T api /app/lab4experiment consistency

Безопасная остановка сохраняет данные в Docker volumes:

docker compose down

Полное удаление учебных данных выполняется только явно:

docker compose down -v

Архитектура

клиент
   |
   v
Nginx :8080
   |
   +---- API replica 1 ----+
   |                       |
   +---- API replica 2 ----+---- PostgreSQL: пользователи, чаты,
                           |                  сообщения, metadata
                           +---- Valkey: сессии
                           +---- MinIO: приватные байты изображений

Prometheus <---- API /metrics, MinIO, Nginx, PostgreSQL, Valkey
    |
    +---- Grafana

Из лабораторной № 3 сохранены две и более API-реплики, Nginx, общие PostgreSQL и Valkey, Bearer-сессии, keyset pagination, идемпотентность сообщений, graceful shutdown, failover, метрики и управляемое развёртывание. В лабораторной № 4 добавлены приватное объектное хранилище, модель вложения, бинарная загрузка и скачивание, привязка вложений к сообщениям и сверка двух хранилищ.

PostgreSQL остаётся источником истины для прав доступа и метаданных. Таблица attachments хранит владельца, чат, отображаемое имя, MIME, размер, SHA-256 и внутренний object key. Таблица message_attachments задаёт упорядоченную связь многие ко многим с сообщениями. Object key генерируется сервером и не зависит от имени файла.

MinIO хранит только байты оригиналов. Bucket закрыт для анонимного доступа. Bootstrap повторяемо создаёт bucket, policy и отдельного пользователя приложения. API получает только действия list/get/put/delete в одном bucket. Root credentials используются bootstrap-контейнером и не передаются API. Web-консоль MinIO отключена и её порт не опубликован.

Загрузка и чтение вложения

Клиент передаёт сырые байты PNG или JPEG. Сервер ограничивает HTTP body до 10 MiB до полного чтения, проверяет заявленный и фактический MIME, декодирует конфигурацию изображения, ограничивает число пикселей 40 миллионами и проверяет полную декодируемость. Filename содержит от 1 до 255 Unicode-символов и не может содержать разделители пути, NUL, управляющие символы или состоять только из пробелов.

При успешной загрузке сервер генерирует UUID для вложения и отдельный случайный object key, считает SHA-256, записывает объект в MinIO и затем metadata в PostgreSQL. Ответ 201 ready возвращается только после обеих операций. Если запись PostgreSQL завершается ошибкой, объект удаляется компенсирующей операцией. Если компенсация также не сработала, старый orphan позднее обнаруживает reconciler.

Метаданные и содержимое читаются только после проверки Bearer-сессии и членства пользователя в чате. Посторонний пользователь и неизвестный идентификатор дают одинаковый 404. API отдаёт байты самостоятельно без redirect и возвращает сохранённый Content-Type и точный Content-Length.

Сообщение принимает до десяти уникальных attachment_ids. В одной транзакции PostgreSQL проверяются членство отправителя и принадлежность каждого вложения нужному чату, создаются сообщение, связи и запись идемпотентности. Отсутствующее поле attachment_ids и пустой массив дают одинаковый семантический hash. Пустой текст допустим только при наличии вложения.

Согласованность PostgreSQL и S3

Операции PostgreSQL и S3 не входят в общую распределённую транзакцию. Возможны два вида расхождений:

  1. object существует в S3, но metadata отсутствует;
  2. metadata существует, но object отсутствует.

Команда reconcile-attachments проходит оба набора в порядке object key постранично, поэтому объём памяти ограничен размером двух страниц. По умолчанию включён dry-run. Grace period защищает свежие объекты и строки, которые могут относиться к ещё выполняющейся операции.

В режиме --apply старый orphan в S3 удаляется. Старая строка с отсутствующим объектом удаляется только при отсутствии ссылки из message_attachments; проверка возраста и отсутствия ссылки повторяется атомарным DELETE. Используемая строка сохраняется и попадает в отчёт для ручного восстановления объекта. Повторный запуск после исправления не выполняет дополнительных удалений.

Ограничение памяти

Размер тела ограничен http.MaxBytesReader, поэтому неизвестный Content-Length не позволяет читать бесконечный поток. Исходные байты и декодированное изображение находятся в памяти только во время синхронной загрузки. Перед полной декодировкой weighted semaphore резервирует для запроса сумму размера исходных байтов и восьми байт на пиксель. Общий бюджет одной реплики равен 384 MiB, а лимит её контейнера — 512 MiB. Максимально допустимое изображение требует не более 330 485 760 байт расчётного бюджета. Если свободного бюджета нет, API отвечает 429 с Retry-After: 1.

Go-инструмент cmd/lab4experiment создаёт случайное JPEG-изображение и выполняет четыре волны по 12 одновременных загрузок. Передача каждой копии ограничена по скорости, чтобы нагрузка длилась дольше интервала scrape. Наблюдаемый пик heap и resident memory двух API-процессов читается из Prometheus с интервалом одна секунда. Это измерение локального стенда, а не универсальная оценка производительности S3.

В эксперименте успешно завершились все 48 загрузок файла размером 3 759 914 байт. Четыре волны заняли 12,629 секунды. После трёх секунд стабилизации суммарный heap двух реплик вырос с 181 133 200 до наблюдаемого пика 202 374 848 байт, то есть на 21 241 648 байт. Суммарный RSS вырос с 241 922 048 до 381 063 168 байт, то есть на 139 141 120 байт. Наблюдаемый пик остался ниже общего контейнерного лимита двух реплик 1 GiB.

Наблюдаемость

API экспортирует общие HTTP-метрики и отдельные показатели загрузок:

  • messenger_attachment_uploads_total{result};
  • messenger_attachment_upload_duration_seconds;
  • messenger_attachment_upload_bytes_total.

Prometheus обнаруживает все API-реплики через Docker DNS и отдельно собирает MinIO, Nginx, PostgreSQL и Valkey. Grafana показывает частоту и p95 загрузок, объём принятых байтов, число и ёмкость объектов MinIO, ошибки S3, доступность компонентов, RPS, классы HTTP-ответов и память Go.

/health/live проверяет только процесс. /health/ready требует доступных PostgreSQL, Valkey и приватного bucket S3. Недоступность Grafana или Prometheus не останавливает API.

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

Критерий Команда или сценарий Результат Доказательство
Контракт и OpenAPI make check, make validate offline check PASS; validate входит в CI evidence/lab4-verification.txt
Unit и integration go test ./..., race/tests profile в CI unit PASS evidence/lab4-verification.txt
Upload/download и ACL make test PASS evidence/lab4-verification.txt
Межрепличный failover и restart public resilience hooks проверяются CI точного commit .gitea/workflows/ci.yml
Приватный bucket и повторный bootstrap anonymous HTTP check, два запуска bootstrap PASS evidence/lab4-verification.txt
12 конкурентных загрузок и память lab4experiment memory 48/48 PASS, observed RSS peak 381 063 168 B evidence/lab4-memory.json
Трек 2: dry-run/apply/repeat lab4experiment consistency PASS, повторный apply: 0 удалений evidence/lab4-consistency.json

Эксперимент согласованности

Гипотеза: постраничная сверка с grace period может автоматически удалить старые безопасные расхождения, не удаляя свежие данные и metadata используемого вложения; второй apply будет идемпотентным.

Методика на чистом стенде:

  1. создать согласованное вложение;
  2. удалить S3 object у непривязанного вложения;
  3. привязать другое вложение к сообщению и удалить его S3 object;
  4. создать object без metadata;
  5. выполнить apply с grace period один час и проверить сохранность свежих аномалий;
  6. выполнить dry-run с нулевым grace period;
  7. выполнить apply и проверить удаление orphan и непривязанной строки;
  8. повторить apply и проверить отсутствие новых действий.

Фактическая стоимость обхода записывается как число просмотренных объектов и строк, размер страницы и wall time. Алгоритм выполняет линейный merge двух отсортированных потоков; дополнительные запросы проверки ссылок нужны только для metadata с отсутствующим объектом.

При размере страницы 10 фактический запуск пересёк границу страницы и просмотрел 206 строк metadata и 205 objects. Apply с часовым grace period занял 58 миллисекунд и сохранил один свежий orphan и две свежие строки с отсутствующим object. При нулевом grace period dry-run за 65 миллисекунд обнаружил старый orphan, старую непривязанную строку и одну используемую строку. Apply за 77 миллисекунд удалил только orphan и непривязанную строку. Повторный apply занял 38 миллисекунд, выполнил ноль удалений, а используемая строка осталась в PostgreSQL.

Ограничения

  • Между S3 PUT и PostgreSQL INSERT нет общей транзакции; компенсация и reconciler обеспечивают eventual consistency.
  • Удалённый object используемого вложения автоматически не восстанавливается: строка сохраняется и требует восстановления байтов из резервной копии либо решения оператора.
  • Grace period основан на времени PostgreSQL и S3; для удалённого стенда требуется синхронизация часов.
  • Admission control действует отдельно в каждой API-реплике; при изменении контейнерного лимита его бюджет нужно настраивать вместе с ATTACHMENT_DECODE_MEMORY_BYTES.
  • MinIO собирается из официального закреплённого source tag, поскольку готовые community images больше не публикуются. Это увеличивает время первого CI build.
  • Локальный HTTP допустим только для учебного стенда с синтетическими данными; удалённое развёртывание требует TLS.

Источники