Files
dizi 56e4a03bb6
CI / verify (pull_request) Failing after 18s
test: refresh final lab4 evidence
2026-10-09 13:39:32 +03:00

21 KiB
Raw Permalink Blame History

Отчёт — лабораторная работа № 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 не входят в общую распределённую транзакцию. Возможны два вида расхождений:

  1. object существует в S3, но metadata отсутствует;
  2. 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 будет идемпотентным.

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

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