# Отчёт — лабораторная 3 - Автор, группа: **Пинаев Олег Константинович, БПИ2302**. - Целевая оценка: **5, трек 1 — цена масштабирования**. - Версия: API — коммит `24f32c3`, инфраструктура — `676b38c`, проверки — `5c8bcf0`; основа — skeleton `0ab3a34`. Хеши и образы измеренной версии сохранены в [measurements.json](evidence/measurements.json), актуальной проверенной версии — в [checks.json](evidence/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`. ```sh 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](evidence/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](evidence/scaling.csv), [агрегаты и диагностика](evidence/measurements.json), рисунки ниже | Все 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](evidence/scaling.png) ### Ограничение 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/improvements.png) ### Исходные данные и повторение В `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 и дубли рисунков удалены. Ненужные предварительные и отменённые серии в отчёт не включены. Повтор основной матрицы в отдельный временный каталог: ```sh 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 и два рисунка из сохранённых данных без новой нагрузки: ```sh 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 сам по себе выигрыша не гарантирует. Следующий шаг для уточнения границы — независимый генератор или больший запас хоста и чередование вариантов с достаточной фактической подачей.