Files
mtusi2026lab3/REPORT.md
T

146 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# ЛР3: балансировка и отказ API-реплики
**Васильев Никита · БВТ2301 · цель:5 · трек1 «Цена масштабирования».**
Реализация продолжает собственную ЛР2, адаптированную к исходному skeleton ЛР3. Контракты, публичные tests, README, COURSE и CONTRIBUTING не изменялись. Код и анализ подготовлены с помощью AI-ассистента; доказательства получены настоящими локальными запусками, а не из чужих PR. Публикация не выполнялась.
## Воспроизводимый запуск
Нужны Docker с Compose и Python3.9+ для публичных скриптов. Для собственных тестов — uv и Python3.12.
```sh
make up
make check
make test
uv sync --locked --python 3.12
make validate PYTHON=.venv/bin/python
make lint
make student-test
```
`make up` создаёт локальные secrets/.env только при отсутствии, собирает образ, запускает PostgreSQL/Valkey, отдельную миграцию, две API и HAProxy. Единственная публикация — `127.0.0.1:8083`. API внутри слушают0.0.0.0:8080 и наружу порт не публикуют. `.env.example` описывает фактические параметры Compose.
Ручная сборка: `VCS_REF=$(git rev-parse HEAD) docker compose build`. Запуск: `docker compose up -d --wait`. Остановка с сохранением данных: `make down`. Не применяйте `down --volumes` для обычной остановки.
## Архитектура и ресурсы
```text
Клиент → HAProxy → API ×2 → PostgreSQL
↘ Valkey: карточки пользователей TTL60s
```
Все API используют одну БД и сессии PostgreSQL. Sticky sessions нет. `X-Instance-Id` — случайный UUID, постоянный на время жизни процесса. `X-Request-Id` добавляется ко всем созданным API ответам, включая ошибки.
Штатные ограничения:
|Сервис|CPU|RAM|
|---|---:|---:|
|Каждая API,2шт.|0.5|256MiB|
|PostgreSQL|1|768MiB|
|Valkey|0.5|128MiB|
|HAProxy|0.5|128MiB|
|migrate,однократный|0.5|256MiB|
Нет container_name; один Compose-service API масштабируется. LB находится в frontend-сети, PostgreSQL/Valkey в backend, API в обеих. Хранилище PostgreSQL — именованный volume. API без root, read-only, cap_dropALL, no-new-privileges, tmpfs16MiB, pids96. Секреты передаются файлами, не входят в Git и Docker context.
Python3.12, зависимости закреплены uv.lock; базовый Python-образ и HAProxy закреплены digest. PostgreSQL17.10 и Valkey8.1.3 закреплены версиями. Базовый образ и runtime-пакеты унаследованы из проверенной собственной ЛР2. Дополнительные aiohttp и matplotlib нужны только исследовательским инструментам, в runtime image не устанавливаются.
## Идемпотентность
Для отправки сообщения обязателен ASCII Idempotency-Key длиной1..128. Область — пользователь, POST, чат и ключ. Под одной транзакцией выполняются ACL, advisory lock, поиск результата, вставка сообщения и сохранение исходного201-ответа. TTL24h. Разный валидный body с тем же ключом —409. Отсутствующий attachment_ids и[] эквивалентны. Неуспешные5xx не фиксируются как результат.
Повтор заново проверяет сессию и доступ. Одновременные запросы через разные API возвращают одно сообщение. Сбой до COMMIT откатывает сообщение вместе с ключом; после COMMIT клиент повторяет тот же ключ. LB не повторяет POST автоматически, включая создание чатов и пользователей.
Подробности структуры, bytea для losslessUnicode U+0000 и транзакционных границ — [SCHEMA.md](SCHEMA.md).
## Readiness, DNS и остановка
HAProxy server-template разрешает до8 API через DockerDNS127.0.0.11, обновляет адреса без фиксированных IP. Roundrobin, активная проверка `/health/ready`, inter1s, timeoutcheck1s, fall2, rise2. Оценка обнаружения устойчивого отказа — примерно до3s без учёта аномалий планировщика; фактические переходы измерены отдельно. Fallback без readiness нет.
Readiness выполняет дешёвую проверку обязательных таблиц и полей БД, а не только проверки процесса. Liveness отвечает независимо от БД. Если одна API теряет backend-сеть, она остаётся живой, но readiness503 исключает её из LB.
ConnecttimeoutLB1s, server8s, client10s, queuetimeout2s, transparent retries0. Uvicorn grace5s, Compose stop8s. ПулБД до8 соединений/API, очередь32, ожидание2s, подключение2s, SQL2.5s, lock1.5s. Дополнительный client-side I/Odeadline3s закрывает зависшее соединение, даже если PostgreSQL paused и серверный statement_timeout не исполняется. Эти бюджеты не складываются в обещание единогоHTTP SLA.
## Проверки уровней3–4
- [Публичный контракт и схема](evidence/contract-validation.txt):PASS.
- [Собственные тесты](evidence/tests-final.txt):98PASS, включая11unit-регрессий форматаcursor,10HTTP-регрессийcursorнаобоихмаршрутах,20конкурентных повторов через≥2API, bodyconflict, scopes, NUL, Unicode, malformedUTF8, Basicbody, cursor и заголовки.
- [Независимые HTTP-регрессии](evidence/independent-http.json):61PASS.
- [Независимые отказы](evidence/independent-faults.json):4PASS — ACLдоreplay, исчезновение обязательной таблицы, pausedPG с503примерно3.08s и восстановлением, logout под блокировкой с последующим отзывом.
- [LB без готовых API](evidence/lb-no-ready-api.json):503JSON, новыйX-Request-Idсовпадаетсerror.request_id, фиктивногоX-Instance-Idнет; прежняя сессия работает после восстановления.
- [КороткийTTL](evidence/independent-expiry.json):проверен отдельной API, рабочая конфигурация TTL3600не менялась.
- [Публичный persistence](evidence/persistence.txt):прежний токен и подтверждённые данные сохранились.
- [Публичный failover](evidence/failover-first.txt):123успешных записи,3неуспешных попытки, первое восстановление1.429s.
- [Отказ каждой реальной реплики](evidence/replica-failures.json):два отдельных прогона1419и1472успешных записей;83и62переходные ошибки соответственно. **Все подтверждённые записи каждого прогона найдены**, потерь нет. Target сопоставлен с настоящим containerID и оставлен остановленным; перед следующей проверкой предыдущий восстановлен.
- [Изоляция неготовой API](evidence/readiness-isolation.json):после потери backend-сети directready503;30/30последующих запросов черезLBуспешны и обслужены только другой API. После reconnect снова видны две.
- [Поочерёдная замена](evidence/rolling-update.json):3558успешных записей,257переходных ошибок, все подтверждённые сообщения сохранены. Обе API последовательно заменены, containerIDs и imageIDs изменились.
Команды проверки:
```sh
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
# Восстановить остановленную реплику перед следующими проверками:
docker compose up -d --no-recreate --wait
uv run --locked python scripts/verify_replicas.py
uv run --locked python scripts/verify_readiness.py
uv run --locked python scripts/verify_rolling.py
uv run --locked python scripts/verify_lb_unavailable.py
# Дополнительные независимые проверки, адаптированные для запуска из репозитория:
uv run --locked python scripts/verify_teacher_http.py --lab 3 --repo . --base-url http://127.0.0.1:8083 --output evidence/teacher-http-repeat.json
uv run --locked python scripts/verify_teacher_faults.py --output evidence/teacher-faults-repeat.json
```
Проверки отказов запускаются последовательно, не одновременно с нагрузочным исследованием. restart-hook сохраняет безопасные snapshots StartedAt/ID до и после, чтобы доказать перезапуск API,LB,PGиValkey. Все shellhooks executable100755. Cursorпринимает только собственный каноническийформатYYYY-MM-DDTHH:MM:SS(.1..6digits)?Z, с календарной проверкой и целойверсией1; PythonISO-расширения не доходят доSQL.
Rolling-target отличается revision-label, функциональный код и схема одинаковы. Этот опыт доказывает поочерёдную замену образа и процессов под трафиком, но не совместимость произвольного нового кода/схемы. Первоначальная миграция003с textнаbytea требует maintenancewindow со старой ЛР2; ограничения не скрываются.
## Исследование на5
Методика, параметры и ограничения — [research/README.md](research/README.md). Основной файл [scaling-final.json](evidence/scaling-final.json), итоговая [таблица](evidence/scaling-final-summary.md), [график](evidence/scaling-final.svg).
**Гипотеза:** рост API перестанет помогать при насыщении общей БД. Если активно ограничивает CPUquotaPostgreSQL, её увеличение при остальных неизменных ресурсах повысит успешный throughput.
Сравниваются фиксированный суммарный бюджет API1CPU/1024MiB для1/2/4реплик и растущий бюджет по0.5CPU/256MiB на реплику. PostgreSQL специально ограничена0.25CPU/768MiB в основной матрице. Контрольное улучшение:4APIпо0.5CPU/256MiB, только CPUБДувеличен0.25→0.5. Штатный стенд имеет другую квотуБД1CPU.
Предлагаемая нагрузка100/400/900уникальных POST/s,3повтора×6s,7конфигураций —63прогона. Генератор open-loop aiohttp, in-flightcap128; отдельно учитываются scheduled, attempts, successful201, errors и dropped. Процентили только успешных запросов; RPSпо реальному времени вместе с завершением начатых запросов. Actual CPU/RAM проверяются dockerinspect, samplesdockerstats сохраняются; CPUиRAM API сначала суммируются на каждомtimestamp.
Основная матрица: **114780 успешных HTTP-ответов,0 HTTP-ошибок,61620 неотправленных слотов** из176400запланированных. Все dropped связаны с in-flightcap128; scheduler-drops0. Максимальная загрузка процесса генератора —31.54% одногоhostCPU. Успешность отправленных запросов не означает выполнение всех предложенных слотов.
Медианы при900offeredPOST/s, по3повтора:
|Серия|API1|API2|API4|
|---|---:|---:|---:|
|Fixed-total1CPU/1024MiB, successfulRPS|391.81|363.47|378.74|
|Growth0.5CPU/256MiBнаAPI, successfulRPS|163.01|384.98|442.33|
При фиксированной сумме ресурсов увеличение числа процессов не дало выигрыша throughput. На900offered peak summed memoryAPIвfixedсерии составила96.91/159.57/304.92MiB для1/2/4процессов: у реплик есть собственные расходы.
В growthсерии переход2→4APIдал только≈14.9% throughput при удвоении APIресурсов. Дляgrowth4на900offered медианаCPUБД25.05%приquota25%,API107.08%приобщемbudget200%,LBоколо5%CPU: общая ограниченная PostgreSQL стала активным узким местом.
Контроль изменил **только CPUPostgreSQL0.25→0.5**, RAMБД768MiB и4APIпо0.5CPU/256MiB сохранены и проверены inspect:
|Метрика,900offered/s|PG0.25CPU|PG0.5CPU|
|---|---:|---:|
|МедианаsuccessfulRPS|442.33|881.06|
|Медианаp95успешных,ms|621.58|223.69|
|Droppedслотов,3повтора|8147|298|
|МедианаDBCPU%|25.05|42.86|
|МедианаAPI CPU%,сумма|107.08|179.65|
Подтверждённое улучшение:≈99.2%успешногоthroughput и≈64.0%сниженияp95вэтомопыте. После него [обратный контроль](evidence/scaling-reversal.json) вернулPG0.25CPU:411.104/471.464/465.411RPS,медиана465.411. Возврат производительности к исходному диапазону поддерживает причинное объяснение через квотуБД, хотя короткая серия и прогрев/checkpointоставляют шум.
881RPSне объявляется новым пределом: это близко к предложенным900/s, а CPUAPIподошёл к своему бюджету. Для установления следующего ограничения понадобился бы отдельный более высокий профиль. Мы доказали границу специально ограниченной0.25CPUБД, а не общий максимум PostgreSQL.
[Ресурсные графики](evidence/scaling-final-resources.svg) показывают CPUБД, CPUгенератора и droppedslots. Калибровочныеpilotфайлы сохранены отдельно и в63основных прогона не входят; обратный контроль —ещё3отдельныхпрогона.
Runtimeисследования соответствует commit029bf9b, sourceSHA256записаны в JSON. Форматирование runnerбез изменения поведения отражено в [manifest](evidence/research-runner-manifest.json). После измерений добавлены JSON503для случая отсутствия готовых backend и строгая валидация некорректногоcursor (ISOweek/basic/не-T,True/1.0вместоцелойверсии). Измеренный профиль отправки сообщений cursorне использует; прежняя конфигурация сохранена в [haproxy-benchmark.cfg](evidence/haproxy-benchmark.cfg). Это изменение пути отказа не является измеренным улучшениемthroughput.
После опыта штатные2API и PostgreSQL1CPUвосстановлены. Копии результатов не содержат токенов и секретов.
## Ограничения и подготовка к защите
Один DockerDesktophost, один LB, одна PostgreSQL и её volume остаются точками отказа. Переживание отказа узла или потери диска не заявляется. Короткие синтетические прогоны не равны промышленному SLA; после неопределённой сетевой ошибки POST повторяется с исходным ключом. Retention старых idempotency-записей не выполняется фоновым GC: срок учитывается при replay, просроченный ключ удаляется при его повторном использовании; неиспользуемые просроченные строки потребуют эксплуатационной очистки.
Сначала на защите показать≥2разныхX-Instance-Id с одним токеном, затем конкурентный replay, остановку конкретного контейнера, сохранность прежних сообщений и таблицу/график исследования. [REVIEW_NOTES.md](REVIEW_NOTES.md) связывает учтённые ошибки с замечаниями преподавателя.