146 lines
18 KiB
Markdown
146 lines
18 KiB
Markdown
# ЛР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) связывает учтённые ошибки с замечаниями преподавателя.
|