19 KiB
ЛР 3 — балансировка и отказ API-реплики
Автор: Маслов, БВТ2301. Цель: 5, трек 1 — цена масштабирования.
Площадка сдачи: Gitea, личная ветка solution/bvt2301-maslov.
Запуск
Нужны 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, улучшение | изолированная матрица | результат добавляется после выполнения |
Матрица масштабирования и чистый 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 в трёх чередующихся повторах. Пока измерений нет, выигрыш не заявляется.
Вопросы защиты
Чем отказ процесса отличается от отказа узла? Остановка одной 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 прошёл.