155 lines
27 KiB
Markdown
155 lines
27 KiB
Markdown
# ЛР 3 — балансировка и отказ API-реплики
|
||
|
||
Автор: **Маслов, БВТ2301**. Цель: **5, трек 1 — цена масштабирования**.
|
||
Площадка сдачи: Gitea, личная ветка `solution/bvt2301-maslov`.
|
||
|
||
Открыт [PR153](https://gitea.privcloud.tech/mtusi2026/mtusi2026lab3/pulls/153) из публичного [собственного fork](https://gitea.privcloud.tech/wh1tet3a/mtusi2026lab3). Удалённый commit status: pending,0checks; это отсутствие результатов CI, локальный PASS отдельно.
|
||
|
||
## Запуск
|
||
|
||
Нужны Docker с Compose v2+ и Python 3.14 с uv; публичные преподавательские проверки работают также на Python 3.9+. Все команды выполняются в корне этого репозитория; соседние лабораторные не нужны.
|
||
|
||
```sh
|
||
uv sync --locked
|
||
make bootstrap
|
||
VCS_REF=$(git rev-parse HEAD) docker compose up -d --build --wait
|
||
make check validate PYTHON=.venv/bin/python
|
||
NO_PROXY=localhost,127.0.0.1 make test BASE_URL=http://127.0.0.1:8083
|
||
make test-student BASE_URL=http://127.0.0.1:8083
|
||
make verify
|
||
```
|
||
|
||
Bootstrap создаёт независимые случайные credentials в `secrets/` и `.env`, существующие файлы сохраняет. Каталог secrets имеет права 0700; файлы читаются непривилегированным UID10001 через read-only mounts. Секреты не находятся в Git или образе. Начальная база создаётся образом PostgreSQL; отдельный одноразовый `migrate` применяет SQL под advisory lock. API стартуют после успешной миграции. Изменённая применённая миграция отклоняется по SHA-256.
|
||
|
||
Основной адрес — `http://127.0.0.1:8083`. Порт можно изменить через `PUBLIC_PORT`; API и хранилища host ports не публикуют. В `.env.example` `API_REPLICAS` задаёт Compose scale, `API_CPUS` и `API_MEMORY` — квоты каждой API, `DB_POOL_SIZE` — максимум соединений каждого процесса. `SESSION_STORE=postgres` описывает выбранную архитектуру; переключателя на локальные сессии нет. Срок идемпотентности фиксирован контрактом в 86400 секунд, его уменьшение конфигурацией не поддерживается. `APP_ENV` — поясняющее поле skeleton, код его не использует.
|
||
|
||
```sh
|
||
# Одна выбранная реплика остаётся остановленной:
|
||
NO_PROXY=localhost,127.0.0.1 make test-failover ACTION_SCRIPT=scripts/stop-one.sh BASE_URL=http://127.0.0.1:8083
|
||
# Явно вернуть требуемое число реплик:
|
||
docker compose up -d --no-build --wait
|
||
# Перезапуск API, PostgreSQL, Valkey и LB с сохранением volumes:
|
||
NO_PROXY=localhost,127.0.0.1 make test-persistence ACTION_SCRIPT=scripts/restart.sh BASE_URL=http://127.0.0.1:8083
|
||
# Поочерёдно заменить все API, добавляя готовую реплику перед остановкой старой:
|
||
make rolling-update
|
||
# Безопасная остановка с сохранением данных:
|
||
docker compose stop
|
||
# Удалить контейнеры и сеть, сохранив данные:
|
||
make down
|
||
# Только намеренный сброс учебных данных ЭТОГО проекта:
|
||
docker compose down --volumes
|
||
```
|
||
|
||
Тесты создают синтетических пользователей и сообщения. Нагрузочные и аварийные сценарии запускаются явно. Для нового измерения выбирать новое имя output, сохраняя предыдущие результаты.
|
||
|
||
## Архитектура
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
C[Клиент] --> LB[HAProxy]
|
||
LB --> A[API процесс 1]
|
||
LB --> B[API процесс 2]
|
||
A --> PG[(PostgreSQL)]
|
||
B --> PG
|
||
A --> V[(Valkey: disposable User cache)]
|
||
B --> V
|
||
```
|
||
|
||
Перенесена собственная реализация ЛР2: строгая валидация UTF-8 JSON и типов, ACL, keyset pagination `(created_at,id)`, Argon2id, случайные Bearer-сессии с абсолютным expiry, PostgreSQL и ограниченный по времени Valkey-кэш карточек User. Преподавательские README, COURSE, contracts и tests сохранены. Пароль не сохраняется открытым; для сессии хранится SHA-256 случайного 256-битного токена. Каждый защищённый запрос сначала проверяет действительность сессии в PostgreSQL. Кэш не может восстановить отозванную сессию или разрешить доступ при отказе БД.
|
||
|
||
Новые части: `X-Instance-Id` — UUID alias, генерируемый один раз внутри процесса API; HAProxy его не подменяет. Round robin применяется без sticky sessions. Одна сессия обслуживается любым процессом. Порты API доступны только внутри сети Compose; `container_name` не используется. Один uvicorn worker на контейнер, масштабирование — числом контейнеров.
|
||
|
||
HAProxy 3.2.1 закреплён digest, использует Docker DNS 127.0.0.11 и server-template до 8 адресов. DNS hold valid/obsolete/nx — 1 с. HTTP readiness проверяет PostgreSQL каждые 1 с, fall2/rise1, fastinter250ms. Номинальный бюджет исключения отказавшего адреса — около 2 с плюс длительность зависшей readiness; connect timeout1с, HTTP server timeout8с. PostgreSQL-клиент имеет checkout deadline4с, pool wait1с, connect2с, statement2.5с и lock1с. Поэтому в реальном отказе возможны короткие ошибки; время подтверждается экспериментом. HAProxy не повторяет POST автоматически (`retries 0`).
|
||
|
||
`/health/live` проверяет процесс; `/health/ready` — доступность обязательного синхронного PG-пути. Valkey необязателен для корректности и при runtime-отказе обходится с circuit backoff. Uvicorn завершает принятые запросы с бюджетом5с; контейнеру выделено10с. До импорта uvicorn действует ранний обработчик SIGTERM. Поочерёдная замена сначала добавляет готовую реплику, ждёт проверки и DNS, затем отправляет SIGTERM одной старой. Это проверка замены процессов одной версии; совместимость разных версий приложения отдельно не заявляется. Миграция002 — только расширение схемы, старый код ЛР2 не теряет свои таблицы.
|
||
|
||
Ресурсы обычного стенда: API2×0.5CPU/384MiB, PostgreSQL1CPU/512MiB, Valkey0.25CPU/128MiB, LB0.5CPU/128MiB. API работают под UID10001, root filesystem read-only, tmpfs16MiB, capabilities удалены. Python3.14.7 и uv0.13.7 закреплены digest; зависимости — `uv.lock`.
|
||
|
||
## Атомарность повторной отправки
|
||
|
||
1. API проверяет Bearer и членство в чате, затем валидирует body и ASCII ключ `[A-Za-z0-9._:-]{1,128}`.
|
||
2. Область — пользователь, POST, нормализованный UUID чата и ключ. Другие чаты и пользователи независимы. В ЛР3 body содержит только text; схема вложений появляется в ЛР4.
|
||
3. В одной PG-транзакции берётся `pg_advisory_xact_lock` по первым64битам SHA-256 области. Коллизия lock лишь дополнительно сериализует независимые запросы: окончательное сравнение выполняется по полному составному PK.
|
||
4. Если результат моложе24ч, сравнивается SHA-256 канонического JSON. Другой text даёт409; тот же —201 с прежним Message, включая id и created_at. Порядок JSON-полей не влияет на hash.
|
||
5. Для нового/истёкшего ключа в той же транзакции вставляется Message и результат идемпотентности с expiry по clock_timestamp PostgreSQL. COMMIT подтверждает оба изменения; исключение откатывает оба.
|
||
|
||
При неизвестном исходе POST клиент сохраняет исходные key/body и повторяет их. Повтор заново проверяет сессию/ACL. Ошибки5xx не сохраняются как успешный replay result. Записи истёкших ключей могут оставаться в таблице до обслуживания; expiry проверяется независимо от физического удаления. Контракт не обещает дедупликацию после24ч. Создание чата, регистрации и входа этим механизмом не защищены.
|
||
|
||
## Проверки и исследование
|
||
|
||
Проверки выполняются последовательно относительно изменений одного стенда. Первый собственный прогон был испорчен ошибочной пересборкой всех API/LB во время тестов: 503 и connection refused; этот прогон не засчитан. Повтор на готовом стенде: **87passed, 279.66с**; детали в `evidence/http-tests.json`.
|
||
|
||
В `evidence/cluster-first.json` сохранены30 параллельных одинаковых POST через обе реальные реплики: один Message. Инъекция исключения в INSERT idempotency вернула500 и оставила0 сообщений; повтор того же key после удаления fault завершился201. Искусственное истечение записи разрешило новый результат.
|
||
|
||
Остановка API1:221 подтверждённых записей/215 чтений,7 ошибок, первый успех после завершения action4.191с от его старта. API2:211/203,9 ошибок,3.643с. Это15-секундные серии с паузой40ms между циклами чтение/запись. Все подтверждённые Message и уникальность text проверены по полной истории. Public failover отдельно:115 успешных записей,3 ошибки, восстановление3.142с; наблюдались2 alias до отказа. Операторские before/after содержат CID/PID/StartedAt и реальные квоты/ports.
|
||
|
||
Поочерёдная замена:655 подтверждённых записей,36 ошибок запросов за45-секундное окно. Старые контейнеры заменены новыми API3/4; replay прежнего ключа вернул исходный Message. Стенд не обещает безошибочную замену: в этой реализации обнаружение изменения адресов и закрытие keep-alive могут давать краткие503/обрывы. Подтверждённые данные не потеряны; клиент может повторить неопределённый POST тем же ключом. Полный restart API/PG/cache/LB прошёл public persistence; StartedAt всех state services и LB изменились. Ни volumes, ни токены не заменялись.
|
||
|
||
| Критерий README | Реализация и проверка | Evidence |
|
||
|---|---|---|
|
||
| 3: две API, один LB, общий PG/сессии | Compose scale2, HTTP через LB, реальные разные CID/PID | `evidence/cluster-first.json` |
|
||
| 3: единая действующая сессия через реплики | 30 concurrent POST, два alias, один результат | тот же файл |
|
||
| 3: остановка любой API, запись≤10с, сохранность | обе API остановлены по очереди, проверена вся история | тот же файл |
|
||
| 3: одинаковый ключ без дублей, конфликт body | PostgreSQL transaction, HTTP concurrent/conflict, 5xx rollback | `evidence/http-tests.json`, `evidence/cluster-first.json` |
|
||
| 3: smoke/persistence/failover | исходные публичные TCP-сценарии | `evidence/cluster-first.json`; smoke повторяется в clean clone |
|
||
| 4: readiness, deadlines, SIGTERM и исключение backend | HAProxy check1с/fall2 и конечные бюджеты | `infra/haproxy.cfg`, `evidence/cluster-first.json` |
|
||
| 4: остановить каждую API с RPS/errors/recovery | собственные15-секундные серии | `evidence/cluster-first.json` |
|
||
| 4: квоты, закрытые API ports, нет container_name | compose и inspect обеих API | тот же файл |
|
||
| 4: последовательная замена под нагрузкой, миграции отдельно | surge одна готовая API, SIGTERM старой;002 expand | тот же файл, `migrations/002_idempotency.sql` |
|
||
| 5: fixed/growing1/2/4, saturation, улучшение | изолированная матрица и отдельный before/after | `evidence/scaling-first/`; `evidence/acl-comparison-first/` |
|
||
|
||
Основная матрица завершена:42/42 прогона,40825 успешных HTTP,0 ошибок. Исходные данные и график: [scaling-first](evidence/scaling-first/analysis.md), [CSV](evidence/scaling-first/summary.csv), [PNG](evidence/scaling-first/scaling.png). Эти измерения относятся к исходному runtime `df4eee9`, source harness `fa3a69d`; последующее улучшение пути чтения измеряется отдельно.
|
||
|
||
При C8 фиксированный1CPU:1/2/4 API дали205.2/185.1/155.2RPS; при растущем CPU:110.4/185.3/257.9RPS. При C32 fixed1/2/4 p95 вырос425.05/462.64/883.62ms, RPS снизился177.9/162.1/128.5. Счётчики cgroup показывают частые throttled periods: например, fixedN2C32/r2 —45/68 и64/68 периодов у разных API. Само увеличение concurrency выше8 на этом профиле уже не повышает HTTP throughput. Последовательный C1 почти не выигрывает от числа процессов, поскольку клиент не создаёт параллельной работы.
|
||
|
||
Дополнительная настройка пула: при N2/C32 пул1 дал медиану200.4RPS, пул10 —175.8RPS (три чередующихся повтора). Маленький пул снизил конкуренцию внутри ограниченного CPU-процесса, но отдельный повтор1 оказался хуже10; это локальный результат с заметным разбросом, основание для проверки настройки под свою нагрузку. Стандартный пул10 сохранён, универсальная рекомендация уменьшать его не делается.
|
||
|
||
В улучшенном runtime повторный SELECTget_chat в service.history заменён передачей уже авторизованного immutableChat из HTTP-слоя с повторной локальной проверкой actor∈members. Членство в обязательном API неизменяемо; ACL по-прежнему выполняется до parsing limit/cursor, это проверяет отдельный негативный HTTP-тест. Транзакции отправки и дедупликация не менялись. Сравнение до/после выполнено отдельно: [12 прогонов](evidence/acl-comparison-first/analysis.md), [raw/CSV](evidence/acl-comparison-first/summary.csv), [график](evidence/acl-comparison-first/comparison.png). Четыре API по1CPU/384MiB, pool10, C16,2с прогрева/12с измерения, три чередующихся повтора на каждую версию и PG quota. Before образ revision `df4eee9`, after `cabd0ca`.
|
||
|
||
При PostgreSQL1CPU медиана RPS **211.3→247.4 (+17.1%)**, p95 **220.94→200.82ms**; RPS улучшился в каждой из трёх пар. При PG0.1CPU:29.4→32.8RPS, p951290.65→1298.07ms; здесь выигрыш по медиане мал и один after хуже before, улучшение latency не подтверждено. PG расходует квоту в97.2–100% CPU-периодов при0.1CPU против0–6.2% при1CPU. Это контролируемый пример насыщения общей БД: четыре API не заменяют ресурс PostgreSQL. Всего18849 успешных HTTP,0 ошибок. Один из повторов заметно отличается: короткие окна не дают уверенной оценки дальних хвостов.
|
||
|
||
Таким образом, выбранный трек завершён с фиксированными и растущими ресурсами, контролем общей БД и подтверждённым улучшением SQL-пути при стандартном PG1CPU. Последующая правка src/api.py меняет только форматирование этой же операции. Итоговый код дополнительно проверен из чистого clone. Для уровня5 предусмотрены фиксированная суммарная квота API1CPU/1024MiB и серия с ростом ресурсов0.5CPU/256MiB на реплику; 1/2/4 процесса, C1/8/32, два повтора,2с прогрева и6с измерения. Смешанный closed-loop профиль:80% чтений истории limit20 и20% отправок с уникальными ключами. Перед каждой ячейкой в отдельном исследовательском проекте очищается только его новая БД и создаётся100 сообщений. Отдельно сравнивается пул1/10 при N2/C32 в трёх чередующихся повторах. Исходные короткие окна, два повтора основной серии и три настройки пула не позволяют оценить стабильность production-tail; необработанные данные сохранены.
|
||
|
||
## Вопросы защиты
|
||
|
||
**Чем отказ процесса отличается от отказа узла?** Остановка одной API оставляет другие процессы, LB и общую БД живыми. Потеря этого Docker-host одновременно лишает нас всех контейнеров и локальных volumes. Этот стенд проверяет отказ процесса, многосерверной HA здесь нет.
|
||
|
||
**Почему depends_on/healthcheck не являются балансировщиком?** depends_on определяет порядок запуска и начальную готовность. Healthcheck помечает состояние контейнера. Маршрутизацию клиентских запросов, исключение backend и DNS выполняет отдельный HAProxy. Его конфигурация нужна и после старта.
|
||
|
||
**Какие POST повторять после timeout и что защищает ключ?** POST сообщения можно повторить с теми же key/body в пределах24ч: запись Message и результата общая и атомарная. Ключ не повторяет данные на клиенте и не защищает другой endpoint; registration/chat/login при неизвестном результате требуют отдельного решения. Timeout не означает гарантированный rollback.
|
||
|
||
**Что сломается при локальных сессиях?** После round robin другая API не узнает токен, появятся случайные401; остановка владельца лишит сессии доступа. Sticky session скрыла бы часть ошибок до первого отказа. Общая PG-сессия сохраняет identity и абсолютный expiry через любую API и restart.
|
||
|
||
## Границы и источники
|
||
|
||
Один LB, PostgreSQL, Valkey и Docker-host; потеря БД/host не маскируется ростом API. TLS, репликация PostgreSQL, backup/PITR и промышленное наблюдение здесь не добавлены. HTTP доступен только на loopback, данные синтетические. Closed-loop имеет coordinated omission; короткий локальный прогон не задаёт production SLA. Пул — на процесс: рост реплик увеличивает возможное суммарное число PG-соединений.
|
||
|
||
Источники: [HAProxy3.2 configuration](https://docs.haproxy.org/3.2/configuration.html), [PG18 explicit locks](https://www.postgresql.org/docs/18/explicit-locking.html), [Compose services](https://docs.docker.com/reference/compose-file/services/). Библиотеки перечислены в `pyproject.toml`, точные версии — `uv.lock`. Помощь ИИ использована при разборе требований, подготовке реализации и проверок; результаты подтверждаются сохранёнными запусками.
|
||
|
||
Собственный `.github/workflows/application.yml` описывает сборку и интеграцию на runner с Docker; наличие файла не означает, что удалённый runner запущен или CI прошёл.
|
||
|
||
История сортируется по серверному `(created_at,id)`. На одном host процессы используют общие системные часы; при их скачке назад либо при скосу времени на разных узлах новые записи могут оказаться до уже выданного cursor. Snapshot между HTTP-страницами не обещается.
|
||
|
||
|
||
Повтор исследования (отдельные временные проекты, основной стенд предварительно остановить):
|
||
|
||
```sh
|
||
make image
|
||
make research RESEARCH_OUTPUT=evidence/scaling-new
|
||
uv run --locked python -m research.analyze evidence/scaling-new
|
||
# Для сравнения нужны собственные образы двух зафиксированных версий:
|
||
uv run --locked python -m research.compare --before IMAGE_BEFORE --after IMAGE_AFTER --output evidence/comparison-new
|
||
uv run --locked python -m research.analyze_compare evidence/comparison-new
|
||
# Полная проверка отдельного clone с новыми credentials/volumes:
|
||
uv run --locked python scripts/verify_clean.py --output evidence/clean-clone-new.json
|
||
```
|
||
|
||
Исследования автоматически удаляют только volumes своих уникальных временных проектов; основной messenger не очищается. CPU/RAM собираются по docker stats в измерительном окне, cgroup cpu.stat подтверждает throttling. memory.peak — lifetime peak контейнера, его нельзя объявлять пиком одного измерительного окна. Модель closed-loop, генератор на том же Mac/Docker VM, фоновые задачи host не изолированы, snapshots страниц не фиксированы. Hardware: Apple M1/8 CPU/8GiB host, Docker VM8CPU/6209978368bytes. Точные версии и hardware сохранены в run.json.
|
||
|
||
|
||
## Итоговая проверка из чистого clone
|
||
|
||
[evidence/clean-clone-first.json](evidence/clean-clone-first.json): source commit `ac5c30c`, новый `.env`, случайные секреты, пустые volumes, отдельный loopback-порт и отдельное имя образа. `uv sync --locked`, lint/check/validate, build, public smoke и **88 HTTP-тестов за273.11с** прошли. Полная cluster-проверка повторена: обе API остановлены по очереди, повторен rolling, сохранены сообщения/прежние сессии после полного restart. Хеши каждого Python-модуля src в ОБЕИХ новых API совпали с clone; OCI revision обеих — `ac5c30c`; прямые API ports отсутствуют. `git fsck --full` завершён успешно. Временный проект и только его volumes удалены; основной проект сохранён остановленным.
|
||
|
||
Измерения основной матрицы и сравнения версий привязаны к собственным source/image revisions выше. Чистый clone проверяет итоговое поведение;54 нагрузочных прогона повторно в нём не запускались. После source `ac5c30c` меняются только отчёт, evidence и оформление сдачи.
|