Files
mtusi2026lab3/REPORT.md
T
2026-10-02 14:39:37 +03:00

24 KiB
Raw Blame History

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

  • Автор, группа: Пластинин Денис, БВТ2303
  • Целевая оценка: 5
  • Выбранный трек: 1 — цена масштабирования
  • Ветка/PR: solution/bvt2303-plastinin, PR #1
  • Среда эксперимента: Docker, linux/arm64, Go 1.26.5

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

Требуются Git, Docker Engine с Docker Compose v2 и свободные локальные порты 8080, 8081, 9090 и 3000. Все внешние образы закреплены по версиям. Локальные пароли из примера предназначены только для изолированного стенда. Compose передаёт каждому контейнеру только нужные ему переменные: API получает строки подключения PostgreSQL/Valkey без отдельных исходных паролей и пароля Grafana, а migrate — только настройки PostgreSQL и миграций.

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

Compose сначала ожидает PostgreSQL, затем однократно запускает контейнер migrate. API-реплики стартуют только после успешного завершения миграций. Единственная публичная точка API — Nginx на http://localhost:8080; порты отдельных API-контейнеров на хост не публикуются.

Доступные интерфейсы:

  • Swagger UI: http://localhost:8081;
  • Prometheus: http://localhost:9090;
  • Grafana: http://localhost:3000, логин admin, локальный пароль берётся из .env;
  • Nginx API: http://localhost:8080.

Проверки запущенного стенда:

make check
make test
docker compose --profile tests run --rm --build tests
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh

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

docker compose stop

Повторный запуск выполняется командой docker compose up -d --scale api=2 --wait. Намеренное удаление всех учебных данных:

docker compose down -v

Архитектура и решения

flowchart LR
    C[Клиент] -->|HTTP :8080| N[Nginx]
    N --> A1[API replica 1]
    N --> A2[API replica 2]
    N -. scale .-> AN[API replica N]
    A1 --> P[(PostgreSQL)]
    A2 --> P
    AN --> P
    A1 --> V[(Valkey)]
    A2 --> V
    AN --> V
    M[Однократный migrate] --> P
    PR[Prometheus] --> A1
    PR --> A2
    PR --> NE[Nginx exporter]
    PR --> PE[PostgreSQL exporter]
    PR --> VE[Valkey exporter]
    G[Grafana] --> PR

PostgreSQL является источником истины для пользователей, чатов, сообщений и записей идемпотентности. Valkey хранит общие сессии, поэтому запросы с одним bearer token могут обслуживаться разными API-репликами. В Valkey ключ имеет вид session:<sha256(token)>, а значением служит JSON с user_id и сроком действия. Исходный случайный 256-битный токен возвращается клиенту один раз и не записывается в хранилище.

API остаётся stateless относительно пользовательских данных. Локально в процессе находятся только конфигурация, подключения, метрики конкретной реплики и флаг readiness. Каждый HTTP-ответ содержит X-Instance-Id, равный hostname контейнера.

Балансировка и отказ реплики

Nginx OSS 1.30.5 использует round-robin, Docker DNS 127.0.0.11, повторное разрешение имени api каждые 2 секунды и общий upstream zone. Keep-alive соединения ограничены 32. Таймаут подключения равен 1 секунде, таймауты отправки и чтения — 10 секунд. Ошибка соединения или ответ 502/503/504 временно исключают backend на 3 секунды; небезопасные POST автоматически не повторяются.

Docker проверяет /health/ready каждой API-реплики раз в 2 секунды с таймаутом 1 секунду. Readiness обращается к PostgreSQL и Valkey. При SIGTERM приложение сначала снимает readiness, затем вызывает http.Server.Shutdown с лимитом 5 секунд; Compose даёт контейнеру 8 секунд до принудительной остановки.

Nginx OSS в этом стенде использует пассивное исключение backend. Docker healthcheck не передаёт своё состояние напрямую в Nginx. Поэтому верхняя практическая граница обнаружения отказа складывается из connect timeout и fail timeout; в проверках восстановление произошло примерно за 1.4 секунды, что ниже требуемых 10 секунд.

Общая идемпотентность

Для POST /api/v1/chats/{chat_id}/messages обязателен один заголовок Idempotency-Key длиной до 128 символов. Область ключа — (user_id, chat_id, key), поэтому одинаковая строка независима для другого пользователя или чата. Минимальный TTL равен 24 часам.

Запись сообщения и запись идемпотентности создаются в одной транзакции PostgreSQL:

  1. Проверяется участие пользователя в чате.
  2. Из текста считается SHA-256 для выявления повторного использования ключа с другим запросом.
  3. Строка идемпотентности блокируется через SELECT ... FOR UPDATE; конкурентные вставки разрешаются первичным ключом и ON CONFLICT DO NOTHING.
  4. Победившая транзакция резервирует UUID сообщения и вставляет сообщение. Отложенный внешний ключ проверяется при commit.
  5. Повтор с тем же телом читает исходное сообщение и возвращает тот же объект. Повтор с другим телом получает 409 Conflict.

Это позволяет безопасно повторить POST после timeout: подтверждённая ранее запись не дублируется, даже если повтор попал на другую реплику. Истёкшая запись заменяется при следующем использовании ключа. Фоновая очистка не реализована; для длительной эксплуатации нужен периодический job по индексу expires_at.

Миграции, обновление и развёртывание

API не выполняет DDL при старте. Отдельная команда /app/migrate берёт advisory lock и применяет versioned SQL один раз. Миграция идемпотентности только добавляет таблицу и индекс, поэтому совместима с уже работающей предыдущей версией.

scripts/rolling-update.sh собирает образы, запускает миграции, временно увеличивает число API с двух до трёх и поочерёдно заменяет старые контейнеры. Скрипт ждёт health каждого состава и затем возвращает две реплики. Workflow deploy запускается только вручную из main через workflow_dispatch; перед подключением к серверу он повторяет check, formatting, Go tests и build для SHA запуска. На сервере выполняется reset именно на этот SHA, даже если main успел измениться. Для SSH используются environment secrets DEPLOY_HOST, DEPLOY_USER, DEPLOY_SSH_KEY и заранее проверенный DEPLOY_KNOWN_HOSTS; изменяемых actions для SSH нет.

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

HTTP middleware каждой реплики публикует число запросов по route/status class, histogram latency, in-flight gauge, число replay идемпотентности, Go runtime и process metrics. Prometheus использует DNS service discovery имени api с периодом обновления 2 секунды и отдельно опрашивает Nginx, PostgreSQL и Valkey exporters каждые 5 секунд. Данные хранятся в Prometheus TSDB с retention 7 суток в named volume.

Provisioned dashboard Grafana показывает общий RPS, RPS и p95 по репликам, классы HTTP-ответов, число healthy replicas, in-flight, heap, replay rate, активные соединения и запросы Nginx, соединения PostgreSQL и состояние Valkey.

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

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Публичный smoke make test через Nginx PASS: регистрация, сессия, чат, пагинация, доступ и идемпотентность evidence/lab3-verification.txt
Общие сессии и ≥2 реплики make test-failover ACTION_SCRIPT=scripts/stop-one.sh Одна сессия обслужена двумя instance ID evidence/lab3-verification.txt
Конкурентная идемпотентность docker compose --profile tests run --rm --build tests 8 конкурентных запросов через два Store вернули один message ID; в БД одна строка evidence/lab3-verification.txt
Сохранность make test-persistence ACTION_SCRIPT=scripts/restart.sh API, PostgreSQL и Valkey перезапущены; старые данные и token доступны evidence/lab3-verification.txt
Отказ API Два запуска failover с остановкой разных реплик 125–131 успешная запись; 0–1 переходная ошибка; восстановление 1.35–1.44 с; дублей нет evidence/lab3-verification.txt
Rolling update 60 секунд Go-нагрузки и scripts/rolling-update.sh 134894 подтверждения, 2248.16 RPS, 0 ошибок, p95 13.12 ms evidence/lab3-rolling-update.json
CPU/RAM-лимиты docker compose config и scale experiment Лимиты заданы всем сервисам; при 128 MiB API не хватает памяти для Argon2id, поэтому рабочий минимум эксперимента — 256 MiB evidence/lab3-verification.txt
Трек 1 scripts/run-scale-experiment.sh 1/2/4 реплики, два бюджета, concurrency 8/32/64, три повтора evidence/lab3-scale-results.json, evidence/lab3-scale-rps.svg

Эксперименты и отказы

Методика исследования масштабирования

Гипотеза: при фиксированном суммарном бюджете дробление ресурсов между большим числом процессов сначала улучшит распределение конкурентных запросов, но затем проиграет из-за меньших CPU-квот и пулов каждой реплики. При добавлении одинаковых ресурсов на реплику RPS должен расти до насыщения PostgreSQL или Nginx.

Используется Go-клиент cmd/lab3experiment. Он создаёт отдельного пользователя, сессию и чат, прогревает стенд 2 секунды, затем 6 секунд выполняет closed-loop POST сообщений через Nginx. Для каждого запроса генерируется уникальный idempotency key. Считаются только HTTP-подтверждения; автоматических retry измеряемого трафика нет. Для каждой точки используются concurrency 8, 32 и 64 и три изолированных повтора с новой базой.

CPU и Nginx RPS считаются по разности монотонных process_cpu_seconds_total и nginx_http_requests_total, прочитанных непосредственно до и после измеряемого интервала. Поэтому bootstrap, warmup и простой между точками в них не входят. Resident memory и число healthy replicas снимаются после нагрузки с /metrics каждой реплики, соединения PostgreSQL — instant query к Prometheus. Короткая контрольная точка дала 2355.97 client RPS и 2359.64 RPS по Nginx-счётчику, расхождение 0.16%.

Фиксированная серия имеет общий бюджет API 2 CPU и 1 GiB RAM: 1×(2 CPU, 1 GiB), 2×(1 CPU, 512 MiB), 4×(0.5 CPU, 256 MiB). Пулы PostgreSQL соответственно равны 16, 8 и 4 соединениям на реплику. В растущей серии каждая реплика получает 1 CPU, 256 MiB и пул 8, поэтому суммарный бюджет растёт вместе с числом процессов.

Предварительный прогон с общим лимитом 512 MiB показал, что вариант 4×128 MiB не выполняет регистрацию: базовое потребление процесса около 71 MiB, а Argon2id временно требует ещё 64 MiB. Cgroup завершает реплику, Nginx наблюдает premature upstream close. Этот результат определил минимальный рабочий лимит 256 MiB и не включён в сравнение throughput.

Медианные результаты фиксированного суммарного бюджета:

Concurrency 1 реплика: RPS / p95 ms 2 реплики: RPS / p95 ms 4 реплики: RPS / p95 ms
8 2412 / 5.86 2484 / 5.59 2242 / 6.35
32 2731 / 18.63 2365 / 24.93 2013 / 34.58
64 2733 / 32.99 2198 / 55.06 2103 / 67.89

При фиксированных 2 CPU и 1 GiB увеличение числа процессов не даёт линейного выигрыша. Две реплики дают небольшой выигрыш только при concurrency 8, одна быстрее при 32 и 64, а четыре проигрывают во всех профилях из-за квоты 0.5 CPU на процесс и расходов четырёх runtime. Для рабочего стенда две реплики остаются осознанным компромиссом ради отказоустойчивости, дальнейшее дробление бюджета не оправдано.

Медианные результаты серии с 1 CPU и 256 MiB на каждую реплику:

Concurrency 1 реплика: RPS / p95 ms 2 реплики: RPS / p95 ms 4 реплики: RPS / p95 ms
8 2712 / 4.95 2554 / 5.28 2185 / 7.05
32 2818 / 15.34 2471 / 21.94 2130 / 24.14
64 2044 / 61.44 2239 / 57.76 1859 / 67.42

Даже при росте суммарного CPU практический предел не превышает двух реплик. При concurrency 64 переход 1→2 повышает медианный RPS на 9.6%, а 2→4 снижает его на 17.0%. Одновременно число соединений PostgreSQL растёт 9→17→33, суммарная resident memory — примерно 36→65→397 MiB, а p95 у четырёх реплик достигает 67.42 ms. Точная средняя загрузка API составляет примерно 0.43→0.52→0.54 core при доступных 1→2→4 core. API не упирается в CPU-квоту. Вместе с ростом DB connections и tail latency это указывает на насыщение общего пути PostgreSQL/Nginx/network и расходы дополнительных процессов, но данный эксперимент не разделяет вклад этих компонентов.

Во всех 54 основных точках было 0 HTTP-ошибок; каждая конфигурация наблюдала все заявленные реплики. Диапазоны трёх повторов заметно пересекаются и доступны в raw JSON, поэтому небольшие отличия нельзя считать точной оценкой абсолютной производительности.

Для настройки пула конфигурация 4×0.5 CPU, 256 MiB при concurrency 64 дополнительно сравнивалась с 10 и 4 соединениями PostgreSQL на реплику:

Пул на реплику Median RPS p50 / p95 / p99, ms Соединения PostgreSQL Ошибки
10 1918 30.00 / 59.52 / 101.70 41 0
4 2179 23.61 / 66.76 / 80.91 17 0

Уменьшение пула 10→4 сократило число соединений на 58.5%, повысило медианный RPS на 13.6%, уменьшило p50 на 21.3% и p99 на 20.4%. p95 вырос на 12.2%, то есть распределение задержек изменилось неравномерно. Для данного стенда выбран пул 4: он соответствует CPU-квоте 0.5 core и заметно снижает давление на общую БД. При строгом SLO на tail latency значение следует подбирать повторно на более длинном open-loop тесте.

Итоговый график находится в evidence/lab3-scale-rps.svg, обезличенные исходные точки, медианы и диапазоны — в evidence/lab3-scale-results.json.

Отказ и обновление

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
SIGTERM одной API-реплики Nginx исключает backend, другая реплика продолжает работу 0–1 переходная ошибка, старый instance ID исчез из последующих ответов 1.35–1.44 с; подтверждённые сообщения сохранены, дублей нет
Полный restart API, PostgreSQL и Valkey без удаления volumes Данные и сессия сохраняются Старый bearer token и созданные сущности доступны после запуска В пределах 90-секундного окна теста; потерь не обнаружено
Rolling update API 2→3→2 Во время замены остаются healthy backend 134894 успешных POST, 0 ошибок; наблюдались старые и новые instance ID Перерыва по подтверждённым ответам не зафиксировано
Остановка PostgreSQL или Valkey Readiness становится отрицательной Все API теряют готовность, потому что хранилища общие Автоматический failover хранилищ не реализован

Ограничения и следующие шаги

  • Все компоненты работают на одном Docker-хосте. Отказ хоста, Nginx, PostgreSQL или Valkey останавливает сервис; выполнен отказ процесса API, а не отказ узла.
  • Nginx является одной публичной точкой и SPOF. Для эксплуатации потребуются несколько LB с внешним virtual IP или управляемый балансировщик.
  • PostgreSQL и Valkey не реплицированы. AOF Valkey с appendfsync everysec ограничивает возможную потерю примерно последней секундой при аварии хранилища, но этот сценарий в работе не заявляется как защищённый.
  • Нагрузочный клиент closed-loop и подвержен coordinated omission. Результаты сравнивают конфигурации на одной машине и не являются абсолютной производительностью production-системы.
  • Все реплики и клиент делят ресурсы одного хоста; дельта process CPU показывает потребление API, а не полную стоимость Docker/network/storage.
  • Для эксплуатации нужны TLS, внешнее управление secrets, репликация хранилищ, алерты, план очистки истёкших idempotency records и длительный soak test.

Источники и инструменты