forked from mtusi2026/mtusi2026lab4
182 lines
21 KiB
Markdown
182 lines
21 KiB
Markdown
# Отчёт — лабораторная работа № 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`.
|
||
|
||
```sh
|
||
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`.
|
||
|
||
Публичные и внутренние проверки:
|
||
|
||
```sh
|
||
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` команда ничего не удаляет:
|
||
|
||
```sh
|
||
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
|
||
```
|
||
|
||
Эксперименты запускаются на чистом стенде:
|
||
|
||
```sh
|
||
docker compose exec -T api /app/lab4experiment memory
|
||
docker compose exec -T api /app/lab4experiment consistency
|
||
```
|
||
|
||
Безопасная остановка сохраняет данные в Docker volumes:
|
||
|
||
```sh
|
||
docker compose down
|
||
```
|
||
|
||
Полное удаление учебных данных выполняется только явно:
|
||
|
||
```sh
|
||
docker compose down -v
|
||
```
|
||
|
||
## Архитектура
|
||
|
||
```text
|
||
клиент
|
||
|
|
||
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.
|