Files
mtusi2026lab3-fork/REPORT.md
qrtx c3c4c54ec4 docs(report): document lab 3 results and compact benchmark evidence
Describe scaling limits, pool tuning and verified readiness draining. Retain 54 aggregated runs, validation results and two graphs without raw logs or evidence READMEs.
2026-10-29 11:50:49 +03:00

29 KiB
Raw Permalink Blame History

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

  • Автор, группа: Пинаев Олег Константинович, БПИ2302.
  • Целевая оценка: 5, трек 1 — цена масштабирования.
  • Версия: API — коммит 24f32c3, инфраструктура — 676b38c, проверки — 5c8bcf0; основа — skeleton 0ab3a34. Хеши и образы измеренной версии сохранены в measurements.json, актуальной проверенной версии — в checks.json.
  • Источники: README.md, COURSE.md, contracts/, документация PostgreSQL, Redis, Node.js и Docker. ИИ использовался при разработке, подготовке проверок, замеров и отчёта.

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

Нужны Docker с Compose, Python 3.9+, Node.js 24.20.0, pnpm 10.14.0. Образы: node:24.20.0-bookworm-slim, postgres:17.6-bookworm, redis:7.4.5-alpine, nginx:1.30.6-alpine. Для графиков используется закреплённый в команде диапазон Matplotlib, для нагрузки — grafana/k6:1.3.0.

cp .env.example .env
pnpm install --frozen-lockfile
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
chmod +x scripts/restart.sh scripts/stop-one.sh
python -X utf8 scripts/collect-report-checks.py --base-url http://127.0.0.1:8080

Учебный пароль PostgreSQL заменить в локальном .env, сам файл не публиковать. APP_PORT задаёт только публичный порт Nginx; в контейнерах API слушает 8080. POSTGRES_* — настройки общей БД, DB_POOL_MAX — максимум соединений одной API, SESSION_TTL_SECONDS — срок сессии, IDEMPOTENCY_TTL_SECONDS — срок идемпотентности не менее 86400 с, CACHE_PREFIX — пространство ключей Redis. Адреса БД и Redis внутри Compose устанавливаются именами сервисов. API не публикуют порты наружу.

Миграции выполняет отдельный сервис migrate; API запускаются после успешного завершения миграции и готовности хранилищ, Nginx — после готовности API. Перед HTTP-проверками должны быть healthy обе API и доступен /health/ready через Nginx. /swagger и /docs доступны через тот же LB. На Windows используется .cmd-обёртка с Git Bash; при нестандартной установке Git задаётся GIT_BASH. В выполненных проверках локальный .env задавал порт 18080, поэтому их команды используют этот порт. Запуск из полностью чистого clone отдельно не проверялся.

Безопасная остановка — docker compose down: named volumes остаются. Намеренное удаление учебных данных — docker compose down --volumes; для обычного перезапуска эту команду не использовать.

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

Клиент → Nginx → NestJS/Fastify × 2 → PostgreSQL, Redis используется как общий кэш. Из lab2 сохранены пользователи, чаты, членство, Argon2id, Bearer-сессии, cursor-пагинация и согласованность кэша через эпохи. PostgreSQL остаётся источником истины; сессии хранятся в общей таблице, в БД записывается SHA-256 токена. Переключение API не требует повторного входа. Потеря Redis приводит к чтению из PostgreSQL, недоступность БД — к 503.

Новые элементы lab3 — заголовок X-Instance-Id, несколько реплик одного Compose-service, общая идемпотентность POST сообщения, балансировка и проверки отказа. INSTANCE_ID получает hostname контейнера. container_name и sticky sessions не используются.

Идемпотентность хранится в PostgreSQL с уникальным ключом (user_id, chat_id, key). В одной транзакции API резервирует ключ через INSERT ... ON CONFLICT, создаёт сообщение, изменяет эпоху истории и связывает ключ с сообщением. Конкурирующий повтор получает то же сообщение; другое содержимое с тем же ключом возвращает 409. После истечения TTL запись удаляется при следующем обращении с этим ключом; фонового удаления всех истёкших записей нет. Счётчик истории разделён на 16 строк; запись и увеличение одного счётчика выполняются одним CTE.

Nginx применяет least_conn. Каждый обход получает адреса API из Docker DNS и проверяет /health/ready параллельно, ограничивая каждый HTTP-запрос одной секундой; после обхода выдерживается пауза 2 с. Backend добавляется после двух успехов и исключается после двух неудач; исчезнувший из DNS адрес удаляется сразу. Сетевые таймауты реплик не суммируются, но DNS, планирование CPU и reload добавляют задержку: пауза 2 с не означает обнаружение за 2 с. Пассивные проверки используют max_fails=2 fail_timeout=2s, connect timeout — 2 с, read timeout — 30 с.

Readiness выполняет SELECT 1, liveness не обращается к БД. При SIGTERM/SIGINT ранний хук HTTP-адаптера сначала включает draining: /health/ready возвращает 503 без запроса к БД, /health/live продолжает возвращать 200. API ещё 7 с обслуживает обычные запросы, пока Nginx исключает её после двух неудачных проверок. Задержка согласована с двумя параллельными обходами по (1 с таймаута + 2 с паузы) и запасом 1 с на обновление upstream; это расчёт для текущих настроек, не гарантия при произвольной нагрузке хоста.

После окна draining Fastify прекращает приём новых соединений и ждёт завершения активных HTTP-запросов. Их ответы на этапе закрытия получают Connection: close, чтобы keep-alive не задерживал остановку. Только затем NestJS закрывает Prisma/Redis; повторное начало shutdown не запускает второй таймер и повторное закрытие HTTP. Compose, restart-hook и stop-one-hook дают процессу до 30 с до принудительного завершения. Проверка подключения/SQL ограничена 5 с, транзакции — 10 с. Образ разделён на build/migrate/runtime, API работает от UID/GID 10001.

Обычный профиль — две API по 1 CPU / 512 МиБ, PostgreSQL — 1 CPU / 512 МиБ, Nginx — 0,5 CPU / 128 МиБ, Redis — 0,5 CPU / 256 МиБ. Пул по умолчанию 15 на API. В исследовании общий бюджет соединений задавался отдельно: по 32/16/8 для 1/2/4 API, до 32 суммарно.

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

Повторные проверки выполнены 29.10.2026; команды, длительности, метрики и состояния контейнеров собраны в одном checks.json.

Проверка Команда/сценарий Результат
Структура, сборка, линтер python scripts/check_contract.py, pnpm lint, pnpm build PASS
Публичный smoke python -X utf8 tests/smoke.py --base-url http://127.0.0.1:18080 PASS, включая X-Instance-Id и POST с Idempotency-Key
Общая идемпотентность test/idempotency.mjs через docker compose run PASS: два экземпляра приложения, 12 конкурентных запросов с одним ключом, одинаковое сообщение; другой текст — 409, чужой участник — 404
Полный перезапуск Публичный tests/resilience.py --mode persistence с scripts/restart.cmd PASS, 59,507 с; API/Nginx/PG/Redis действительно перезапущены, контейнеры и volumes сохранены, прежние данные и сессия доступны
Публичный отказ tests/resilience.py --mode failover с scripts/stop-one.cmd PASS: до отказа две реплики, 73 успешные записи, 1 неудачная попытка, первая запись после завершения hook за 7,900 с от его запуска
Ресурсы и доступ test/grade4.py --scenario resources PASS: реальные CPU/RAM совпадают с профилем, в снимке контейнеров публичный порт есть только у Nginx, migrate завершён с кодом 0
Отказ каждой API test/grade4.py --scenario failover --concurrency 4 --observe-seconds 10 PASS: поочерёдно остановлены обе реплики; прежняя сессия, подтверждённые записи и отсутствие дублей проверены
Поочерёдная замена test/grade4.py --scenario rolling --concurrency 4 --observe-seconds 10 PASS: ID обеих API заменены по очереди, трафик продолжался, контейнер миграции не менялся
Завершение активного запроса node --test --test-reporter=tap test/draining.mjs PASS, 2 теста: запрос завершён до закрытия БД, liveness доступен при draining, повторный shutdown идемпотентен, readiness не возвращает запоздалый 200
Пороги readiness Nginx test/nginx-readiness.sh, test/nginx-readiness-parallel.sh в изолированных контейнерах PASS: пороги двух успехов/неудач сохранены, четыре пробы запускаются параллельно
SIGTERM и draining python -X utf8 test/check_shutdown.py --base-url http://127.0.0.1:18080 PASS: readiness 200 → 503 → закрыто; 114 ответов 503 при liveness=200; LB исключил API через 3,282 с при живом HTTP, остановка 9,963 с, exit code 143 без SIGKILL
Совместимость миграции python -X utf8 test/check_migration_compat.py PASS в отдельной временной БД: миграция 28,386 с, 77 записей старого API без ошибок; общая сессия и взаимное чтение старой/новой версии
Трек 1 Матрица 1/2/4 API, рост CPU, квота PG и размер пула 54 сохранённых прогона, CSV, агрегаты и диагностика, рисунки ниже

Все 16 проверок актуальной версии имеют итоговый PASS. Первый вариант прямого shutdown-теста завершился ошибкой из-за того, что считал клиентские ошибки соединения в парных пробах признаком нездорового HTTP-ответа liveness. В повторе дедлайн проб увеличен с 0,3 до 1 с; HTTP-статусы и транспортные ошибки считаются отдельно. Получены 114 ответов liveness=200 при readiness=503 и ноль транспортных ошибок в этих парах. Неудачная попытка сохранена в previous_attempts, хеши прежнего теста — в source_before_recheck_sha256. Предыдущие 13 проверок версии без draining, включая историю повтора сохранности, оставлены в компактном previous_validation.

Hook полного перезапуска сохраняет число API и volumes, останавливает Nginx/API/PG/Redis, затем поднимает хранилища, API и LB. Hook отказа сопоставляет полученный TARGET_INSTANCE_ID с hostname и оставляет именно эту API остановленной. Сборщик доказательств после проверки восстанавливает две реплики.

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

Отказ и замена API

Четыре параллельных клиента через LB читают профиль и пишут сообщения; неподтверждённая запись повторяется с исходным ключом. Метрики ниже относятся к окну действия и 10 с наблюдения после него.

Воздействие Успешные RPS чтения / записи Ошибки чтения / записи Наблюдаемый результат
Остановка первой API 21,199 / 14,348 0 / 0 После окончания остановки чтение/запись успешны на 8,581 / 8,570 с от начала действия
Остановка второй API 19,580 / 13,140 0 / 0 После окончания остановки чтение/запись успешны на 9,259 / 9,304 с от начала действия
Замена первой API 19,516 / 12,519 0 / 2 Новый контейнер готов через 31,297 с, сохранившаяся реплика отвечала уже через 0,051 с
Замена второй API 18,670 / 12,175 0 / 0 Новый контейнер готов через 24,332 с, сохранившаяся реплика отвечала уже через 0,056 с

В сценарии отказа проверена 1001 подтверждённая запись, в сценарии замены — 1082; потеря подтверждённых сообщений и дубли не обнаружены. Последний ответ останавливаемой API наблюдался через 4,718 и 5,443 с от начала действия: в окне draining она ещё обслуживала запросы до исключения из LB. Это наблюдение конкретных прогонов, а не теоретическая верхняя граница исключения backend. Время создания нового контейнера не равно времени недоступности сервиса: другая API продолжала обслуживать запросы. Нулевые ошибки двух отказов не означают их отсутствие при любых нагрузках: публичный сценарий и первая замена зафиксировали переходные неудачные попытки.

Трек 1: цена масштабирования

Гипотеза: дополнительные API при неизменном суммарном бюджете не дают линейного роста, поскольку делят CPU, создают отдельные пулы и используют одну БД. Увеличение нужного ресурса или ограничение невыгодного параллелизма должно улучшать качество.

Генератор и наблюдатели делят ресурсы с приложением. Набор синтетический: новый чат с 30 сообщениями на прогон, первая страница до 50 сообщений, 80% чтений и 20% отправок. Время регистрации/входа не входит в измеряемое окно. База между прогонами не очищалась.

В основной матрице k6 одна итерация равна одному запросу, задан постоянный arrival rate, 128 VU на сценарий, таймаут 5 с, POST без автоматических повторов. Измерение 30 с после 10 с смешанного прогрева. 36 прогонов: 1/2/4 API × общий CPU 1/2 × 40/80 RPS × три повтора. Общая RAM API — 1 ГиБ, общий максимум соединений — 32, PG — 1 CPU / 512 МиБ во всех вариантах. Порядок попарный: one-small → one → two-small → two → four-small → four; внутри каждого профиля 40/80 чередуются.

Экспериментальный критерий качества — ошибки ≤1% и p95 всех запросов ≤1000 мс. Достаточная подача — 98–102% планового числа начатых запросов и не более 2% пропусков.

API CPU суммарно CPU / RAM одной API Медиана p95 на 40 RPS, мс Проход / нарушение / недоподача
1 1 1 / 1024 МиБ 1363 0 / 3 / 0
2 1 0,5 / 512 МиБ 1338 0 / 3 / 0
4 1 0,25 / 256 МиБ 808 2 / 0 / 1
1 2 2 / 1024 МиБ 751 2 / 1 / 0
2 2 1 / 512 МиБ 452 3 / 0 / 0
4 2 0,5 / 256 МиБ 1044 1 / 2 / 0

При фиксированных 2 CPU две API прошли все повторы на 40 RPS, четыре — один из трёх. Рост числа процессов не улучшил качество. Четыре API при 1 CPU дали два прохода.

При увеличении CPU двух API с 1 до 2 p95 трёх повторов изменился с 1119 / 1757 / 1338 на 777 / 452 / 404 мс. Все шесть повторов получили достаточную нагрузку, ошибок нет. Медиана p95 снизилась примерно в 2,96 раза, медиана максимальной среди API доли throttled-периодов — 18,83 → 1,30%. Это повторяемое улучшение задержки при прежних RAM, пуле и БД.

На 80 RPS у двух API с общим 1 CPU было 658 / 473 / 499 ошибок, при 2 CPU — 0 / 31 / 0. У четырёх API — 219 / 1 / 101 против 0 / 3 / 0.

Число реплик, фиксированный бюджет и рост CPU

Ограничение PostgreSQL и увеличение его квоты

Раннее сравнение: четыре API с суммарными 2 CPU / 1 ГиБ, пул по 15, то есть до 60 соединений. Linux Node-генератор через Nginx, 60 заданных RPS, по три повтора по 120 с после 20 с прогрева чтениями. PostgreSQL получил 1 CPU вместо 0,5, RAM осталась 512 МиБ. Облегчённый наблюдатель v3 держал одно постоянное psql-соединение.

Метрика PG 0,5 CPU PG 1 CPU
Средняя загрузка PG, CPU 0,32–0,39 0,32–0,39
Загрузка относительно выделенной квоты 64–78% 32–39%
Периоды с CPU throttling PG 33–55% 3–8%
Медиана p95 успешных запросов, мс 826 296
Ошибки за три повтора 121 1
Средние успешные RPS 52,81 53,00
Медиана среднего получения соединения, мс 23,61 1,17

При квоте 0,5 CPU среднее потребление ниже лимита, но во время всплесков квота регулярно исчерпывалась. В проблемной области наблюдались ошибки получения соединений и ожидания блокировок записи; четыре API не добавляли ресурсов общей БД. Увеличение CPU базы снизило p95 примерно в 2,8 раза и ошибки при почти одинаковом числе отправленных запросов. Это подтверждает влияние CPU-квоты PG на задержки и надёжность.

Последующий контроль PG 1 → 2 CPU выполнен отдельно: две API с общими 2 CPU / 1 ГиБ, пул 32, k6, 80 RPS, одинаковые 30 с смешанного прогрева и 30 с измерения. При 1 CPU получены два прохода и одно нарушение задержки: p95 793 / 2026 / 744 мс. При 2 CPU — два недоподанных повтора и один проход: 2122 / 1555 / 713 мс. Throttling PG исчез, но устойчивого выигрыша не получено. Следовательно, усиление БД после снятия жёсткой квоты не гарантирует дальнейшего роста.

Ограничение общего числа соединений

Четыре API, PG 1 CPU / 512 МиБ, остальные ресурсы прежние. Сравниваются пулы по 15 и по 8 на API: общий максимум 60 → 32. Node-генератор, 100 заданных RPS, по три повтора по 60 с после 15 с прогрева чтением.

Метрика 60 соединений 32 соединения
Успешных запросов за 180 с 13 447 14 543
Средние успешные RPS 74,71 80,79
Ошибки 488 4
Ошибки получения соединений 418 0
Медиана успешных RPS повторов 83,93 82,05
Медиана p95 успешных запросов, мс 289 389

Средний полезный поток вырос на 8,15%, ошибок стало меньше. Однако все 488 ошибок исходного варианта пришлись на один нестабильный повтор, а фактически отправленный поток вырос с 77,42 до 80,82 RPS. Это наблюдаемый выигрыш надёжности и среднего полезного потока, а не доказательство ускорения каждого запроса или увеличения предельного RPS. Ограничение пула согласуется с гипотезой защиты общей БД от невыгодного параллелизма; само увеличение числа соединений производительность не гарантирует.

Отдельные сравнения CPU API, квоты PG и пула соединений

Исходные данные и повторение

В evidence/ оставлены пять файлов: checks.json, measurements.json, scaling.csv, scaling.png, improvements.png. JSON содержит 54 прогона из семи исходных серий, их HTTP-агрегаты, p50/p95/p99, CPU/RAM, очереди, SQL-состояния, профили, manifest и хеши исходных результатов. CSV — плоская таблица тех же прогонов. Запросы по отдельности, stdout/stderr, временные ряды, экспериментальные README и дубли рисунков удалены. Ненужные предварительные и отменённые серии в отчёт не включены.

Повтор основной матрицы в отдельный временный каталог:

python -X utf8 scripts/run-saturation.py --profiles one-small one two-small two four-small four --confirm-rates 40 80 --confirm-seconds 30 --no-expand --output .artifacts/scaling/repeat
python -X utf8 scripts/summarize-scaling-diagnostics.py .artifacts/scaling/repeat
python -X utf8 scripts/audit-saturation.py .artifacts/scaling/repeat

После серии runner восстанавливает обычные две API. Варианты исторических сравнений требуют соответствующих квот PG и размеров пулов, записанных в measurements.json; их не следует повторять с текущим пулом 8 и выдавать за старый вариант с пулом 15. Инструкции измерителей — в scripts/diagnostics/.

Пересчитать CSV и два рисунка из сохранённых данных без новой нагрузки:

uv run --no-project --with 'matplotlib>=3.9,<4' python scripts/report-evidence.py --plot

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

Один Docker-host, одна БД, один Redis и один LB. Проверен отказ и замена API, но не выживание при потере узла PostgreSQL, Nginx или всего ноутбука. Резервирование хранилищ и распределённый кластер не реализованы. Rolling-проверка использовала тот же образ; совместимость схемы lab2/lab3 проверена отдельно, но старая API из lab2 не умеет Idempotency-Key, поэтому во время смешанного развёртывания нельзя обещать идемпотентность POST, попавшего на старую версию.

В штатном режиме readiness зависит от ответа PG: краткие задержки базы способны исключить живую API и усилить ошибки. Draining использует 7-секундное окно под текущие параллельные проверки Nginx; при изменении таймаутов, паузы или порогов LB это окно нужно пересогласовать. Активные запросы завершаются в пределах общего 30-секундного бюджета Docker; бесконечно долгие запросы этот бюджет не продлевают. Чистый bootstrap на другой машине и под другим Docker-окружением не проверен. Нагрузочные сравнения не повторялись после добавления draining: их данные относятся к прежнему образу, проверки остановки и отказов — к актуальному.

Итог исследования: две API — устойчивый рабочий вариант при текущем бюджете; увеличение их CPU улучшило задержки, усиление PG с 0,5 до 1 CPU улучшило работу зависимого пути, ограничение соединений сопровождалось снижением ошибок. Дальнейший рост реплик, пула или квоты PG сам по себе выигрыша не гарантирует. Следующий шаг для уточнения границы — независимый генератор или больший запас хоста и чередование вариантов с достаточной фактической подачей.