14 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.
Результаты аварийных сценариев, матрицы масштабирования и чистого 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. Помощь ИИ использована при разборе требований, подготовке реализации и проверок; результаты подтверждаются сохранёнными запусками.