27 KiB
ЛР 3 — балансировка и отказ API-реплики
Автор: Маслов, БВТ2301. Цель: 5, трек 1 — цена масштабирования.
Площадка сдачи: Gitea, личная ветка solution/bvt2301-maslov.
Открыт PR153 из публичного собственного fork. Удалённый commit status: pending,0checks; это отсутствие результатов CI, локальный PASS отдельно.
Запуск
Нужны Docker с Compose v2+ и Python 3.14 с uv; публичные преподавательские проверки работают также на Python 3.9+. Все команды выполняются в корне этого репозитория; соседние лабораторные не нужны.
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, код его не использует.
# Одна выбранная реплика остаётся остановленной:
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, сохраняя предыдущие результаты.
Архитектура
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.
Атомарность повторной отправки
- API проверяет Bearer и членство в чате, затем валидирует body и ASCII ключ
[A-Za-z0-9._:-]{1,128}. - Область — пользователь, POST, нормализованный UUID чата и ключ. Другие чаты и пользователи независимы. В ЛР3 body содержит только text; схема вложений появляется в ЛР4.
- В одной PG-транзакции берётся
pg_advisory_xact_lockпо первым64битам SHA-256 области. Коллизия lock лишь дополнительно сериализует независимые запросы: окончательное сравнение выполняется по полному составному PK. - Если результат моложе24ч, сравнивается SHA-256 канонического JSON. Другой text даёт409; тот же —201 с прежним Message, включая id и created_at. Порядок JSON-полей не влияет на hash.
- Для нового/истёкшего ключа в той же транзакции вставляется 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, CSV, 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 прогонов, raw/CSV, график. Четыре 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, PG18 explicit locks, Compose services. Библиотеки перечислены в pyproject.toml, точные версии — uv.lock. Помощь ИИ использована при разборе требований, подготовке реализации и проверок; результаты подтверждаются сохранёнными запусками.
Собственный .github/workflows/application.yml описывает сборку и интеграцию на runner с Docker; наличие файла не означает, что удалённый runner запущен или CI прошёл.
История сортируется по серверному (created_at,id). На одном host процессы используют общие системные часы; при их скачке назад либо при скосу времени на разных узлах новые записи могут оказаться до уже выданного cursor. Snapshot между HTTP-страницами не обещается.
Повтор исследования (отдельные временные проекты, основной стенд предварительно остановить):
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: 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 и оформление сдачи.