21 KiB
Отчёт — лабораторная работа № 4
- Автор: Пластинин Денис, БВТ2303.
- Целевая оценка: 5.
- Выбранный трек: 2, согласованность PostgreSQL и S3.
- Ветка:
solution/bvt2303-plastinin.
Запуск из чистого 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 добавлены приватное объектное хранилище, модель вложения, бинарная загрузка и скачивание, привязка вложений к сообщениям и сверка двух хранилищ.
Код разделён по ответственности. internal/messenger/httpapi содержит HTTP-маршруты, middleware и преобразование ошибок в ответы. internal/messenger/attachment владеет сценарием загрузки и чтения вложений. internal/postgres, internal/objectstore и internal/session являются адаптерами PostgreSQL, S3 и Valkey. internal/reconcile выполняет сверку хранилищ, а internal/bootstrap собирает зависимости для сервера, миграций и служебной команды. HTTP-слой зависит от узких интерфейсов и общих ошибок модели, поэтому детали PostgreSQL и S3 в handlers не попадают.
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 и создаёт в PostgreSQL строку со статусом pending. Затем он записывает объект в MinIO и переводит строку в ready. Только после этого возвращается 201. При отказе S3 строка pending удаляется. Если результат перевода в ready неоднозначен, сервер повторно читает строку по attachment ID и object key: уже сохранённый ready считается успехом, а подтверждённый pending компенсируется удалением объекта и metadata.
Метаданные и содержимое читаются только после проверки 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 удаляется после повторной проверки object key в PostgreSQL. Старые pending и готовые, но неиспользуемые вложения сначала атомарно переводятся в deleting под блокировкой строки. Под той же блокировкой повторно проверяются ожидаемый статус, возраст и отсутствие ссылки из message_attachments. После удаления объекта строка удаляется только в статусе deleting. Если upload успел изменить pending на ready, устаревший кандидат не захватывается. Используемая строка с отсутствующим объектом сохраняется и попадает в отчёт для ручного восстановления. Повторный запуск продолжает незавершённый deleting и не повторяет уже выполненные удаления.
Ограничение памяти
До чтения body weighted semaphore резервирует полный лимит одной загрузки — 10 MiB. Поэтому отсутствующий или заниженный Content-Length не позволяет одновременно накопить неограниченное число буферов. После чтения дополнительно резервируется восемь байт на пиксель перед полной декодировкой. Бюджеты одной реплики разделены: 64 MiB для исходных body и 384 MiB для декодирования; лимит контейнера равен 512 MiB. Проверки размеров выполняются до умножения, чтобы исключить integer overflow. Если одного из бюджетов недостаточно, API отвечает 429 с Retry-After: 1.
Go-инструмент cmd/lab4experiment создаёт случайное JPEG-изображение и выполняет четыре волны по 12 одновременных загрузок. Передача каждой копии ограничена по скорости, чтобы нагрузка длилась дольше интервала scrape. Наблюдаемый пик heap и resident memory двух API-процессов читается из Prometheus с интервалом одна секунда. Это измерение локального стенда, а не универсальная оценка производительности S3.
В эксперименте успешно завершились все 48 загрузок файла размером 3 759 914 байт. Четыре волны заняли 12,974 секунды. После трёх секунд стабилизации суммарный heap двух реплик вырос с 153 985 824 до 202 505 208 байт, то есть на 48 519 384 байта. Суммарный RSS вырос с 335 298 560 до 345 976 832 байт, то есть на 10 678 272 байта. Наблюдаемый пик остался ниже общего контейнерного лимита двух реплик 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.
CI/CD и blue/green deploy
CI проверяет contract, OpenAPI, форматирование, lint, unit и integration tests, persistence и отказ одной API-реплики. После успешных проверок образы публикуются в Gitea Container Registry. В manifest передаются ссылки вида repository@sha256:digest, поэтому сервер запускает те же байты, которые прошли проверки.
Production workflow запускается вручную и использует защищённое environment production. Перед переключением применяются только обратно совместимые миграции. Скрипт поднимает новый пул API под отдельными DNS-именами и ждёт readiness каждой реплики. Nginx сначала проверяет новую конфигурацию через nginx -t, затем атомарно выполняет reload upstream. Старый пул остаётся запущенным до успешного smoke-check нового и только после этого останавливается. При ошибке до завершения переключения восстанавливается предыдущий upstream, а candidate-контейнеры удаляются.
Сам балансировщик относится к стабильному control plane. Если его verified digest изменился, обычный API deploy завершается до переключения и требует отдельного обслуживания Nginx. Это не подменяет новый образ старым и не создаёт скрытое окно недоступности внутри blue/green обновления API.
Локальная проверка механизма подняла две отдельные candidate-реплики, переключила upstream и выполнила 20 запросов /health/live: все ответы имели статус 200, а X-Instance-Id чередовался только между двумя контейнерами нового пула.
Доказательства критериев
| Критерий | Команда или сценарий | Результат | Доказательство |
|---|---|---|---|
| Контракт и 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 345 976 832 B | evidence/lab4-memory.json |
| Трек 2: dry-run/apply/repeat | lab4experiment consistency |
PASS, повторный apply: 0 удалений | evidence/lab4-consistency.json |
| Blue/green API switch | два candidate-контейнера, nginx -t, reload, 20 health-запросов |
20/20 HTTP 200, только новый пул | evidence/lab4-verification.txt |
Эксперимент согласованности
Гипотеза: постраничная сверка с grace period может автоматически удалить старые безопасные расхождения, не удаляя свежие данные и metadata используемого вложения; второй apply будет идемпотентным.
Методика на чистом стенде:
- создать согласованное вложение;
- удалить S3 object у непривязанного вложения;
- привязать другое вложение к сообщению и удалить его S3 object;
- создать object без metadata;
- создать незавершённое вложение
pending; - выполнить apply с grace period один час и проверить сохранность свежих аномалий;
- состарить
pending, выполнить dry-run с нулевым grace period; - выполнить apply и проверить удаление orphan, непривязанной строки и старого
pending; - повторить apply и проверить отсутствие новых действий.
Фактическая стоимость обхода записывается как число просмотренных объектов и строк, размер страницы и wall time. Алгоритм выполняет линейный merge двух отсортированных потоков; дополнительные запросы проверки ссылок нужны только для metadata с отсутствующим объектом.
При размере страницы 10 фактический запуск пересёк границу страницы. Apply с часовым grace period просмотрел 14 строк metadata и 13 objects за 4 миллисекунды, сохранил свежие orphan, missing metadata и pending. После искусственного старения dry-run за 5 миллисекунд обнаружил один старый orphan, одну непривязанную строку без объекта, одну используемую строку без объекта и один старый pending. Apply за 13 миллисекунд удалил object и metadata старого pending, orphan object и непривязанную missing metadata. Повторный apply занял 1 миллисекунду и выполнил ноль удалений; используемая строка осталась в PostgreSQL.
Ограничения
- Между PostgreSQL и S3 нет общей транзакции; lifecycle
pending/ready/deleting, компенсация и reconciler обеспечивают eventual consistency. - Удалённый object используемого вложения автоматически не восстанавливается: строка сохраняется и требует восстановления байтов из резервной копии либо решения оператора.
- Grace period основан на времени PostgreSQL и S3; для удалённого стенда требуется синхронизация часов.
- Admission control действует отдельно в каждой API-реплике; при изменении контейнерного лимита нужно совместно настраивать
ATTACHMENT_BODY_MEMORY_BYTESиATTACHMENT_DECODE_MEMORY_BYTES. - Автоматический rollback переключает API обратно на предыдущий пул, но не откатывает уже применённые миграции и stateful-хранилища. Поэтому миграции должны оставаться обратно совместимыми как минимум с предыдущей версией приложения.
- MinIO собирается из официального закреплённого source tag, поскольку готовые community images больше не публикуются. Это увеличивает время первого CI build.
- Локальный HTTP допустим только для учебного стенда с синтетическими данными; удалённое развёртывание требует TLS.