17 KiB
Отчёт — лабораторная работа № 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 неоднозначен, сервер повторно ищет строку по attachment ID и object key. Найденная строка означает успешный commit и приводит к 201; подтверждённое отсутствие строки разрешает компенсирующее удаление object; ошибка повторной проверки оставляет object для последующей безопасной сверки reconciler.
Метаданные и содержимое читаются только после проверки Bearer-сессии и членства пользователя в чате. Посторонний пользователь и неизвестный идентификатор дают одинаковый 404. API отдаёт байты самостоятельно без redirect и возвращает сохранённый Content-Type и точный Content-Length.
Сообщение принимает до десяти уникальных attachment_ids. В одной транзакции PostgreSQL проверяются членство отправителя и принадлежность каждого вложения нужному чату, создаются сообщение, связи и запись идемпотентности. Отсутствующее поле attachment_ids и пустой массив дают одинаковый семантический hash. Пустой текст допустим только при наличии вложения.
Согласованность PostgreSQL и S3
Операции PostgreSQL и S3 не входят в общую распределённую транзакцию. Возможны два вида расхождений:
- object существует в S3, но metadata отсутствует;
- 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 будет идемпотентным.
Методика на чистом стенде:
- создать согласованное вложение;
- удалить S3 object у непривязанного вложения;
- привязать другое вложение к сообщению и удалить его S3 object;
- создать object без metadata;
- выполнить apply с grace period один час и проверить сохранность свежих аномалий;
- выполнить dry-run с нулевым grace period;
- выполнить apply и проверить удаление orphan и непривязанной строки;
- повторить 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.