26 KiB
Лабораторная №3 — Балансировка и отказ API-реплики
Автор: Дугина Александра, БПИ2301. Целевая оценка: 4.
Запуск из чистого clone
Нужны Docker Desktop с Compose v2, Python 3.11+ и make. На использованном Mac Python хоста — 3.13, контейнера — 3.11.16. Все команды выполняются из mtusi2026lab3.
python3 -m venv .venv
.venv/bin/pip install -r requirements-dev.txt
scripts/up.sh
export BASE_URL="http://localhost:$(sed -n 's/^PUBLIC_PORT=//p' .env)"
curl -i "$BASE_URL/health/ready"
make check
make validate PYTHON=.venv/bin/python
make test
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
scripts/restore.sh
python3 scripts/wait-ready.py
scripts/up.sh вызывает bootstrap, docker compose --env-file .env config --quiet, сборку и запуск, ожидает две реплики через LB.
bootstrap.py создаёт случайный пароль PostgreSQL, DSN в secrets/ и .env, выбирает свободный порт 8080–8099 только при отсутствии .env. Существующие настройки не заменяет. В текущем запуске выбран 127.0.0.1:8080. При уже созданном .env и занятом порте меняют только PUBLIC_PORT своей lab3. Чужие контейнеры не останавливаются.
secrets/, .env игнорируются Git; локальные файлы создаются с umask 077. Compose secrets монтирует их только в нужные контейнеры. Redis доступен исключительно во внутренней сети и не содержит токены в открытом виде.
scripts/compose.sh фиксирует каталог проекта и .env, на macOS добавляет Docker credential helper в PATH.
Swagger UI: http://localhost:8080/docs; /openapi.json отдаёт обязательный контракт без изменения исходного файла.
Безопасная остановка: scripts/compose.sh stop. Повторный запуск: scripts/up.sh.
restart.sh перезапускает API, PostgreSQL, Redis и LB, не удаляет контейнеры/volumes и не меняет секреты.
Данные живут в mtusi2026lab3_postgres_data и mtusi2026lab3_redis_data; сеть — mtusi2026lab3_default.
Удаление учебных данных — отдельная намеренная административная операция, при выполнении работы не применялась. Обычные start/restart/down без удаления volumes данные не очищают.
Архитектура и версии
клиент → 127.0.0.1:8080 → HAProxy → api × 2 (Uvicorn/FastAPI)
├── PostgreSQL: данные, сессии, идемпотентность
└── Redis: общий кэш профилей сессий
| Компонент | Версия | CPU | RAM |
|---|---|---|---|
| API, каждая реплика | Python 3.11.16 slim-bookworm, FastAPI 0.115.12, Uvicorn 0.34.2 | 0,75 | 384 MiB |
| Мигратор | тот же образ приложения, отдельный one-shot процесс | 0,5 | 256 MiB |
| PostgreSQL | 16.8-bookworm | 1 | 512 MiB |
| Redis | 7.4.2-alpine | 0,25 | 128 MiB |
| HAProxy | 3.0.9-alpine | 0,5 | 128 MiB |
Остальные зависимости закреплены в requirements.txt: psycopg 3.2.6, psycopg-pool 3.2.6, redis-py 5.2.1, Argon2-cffi 23.1.0, Pydantic 2.11.4. Образы поддерживают ARM64. Docker Engine 28.0.1, Compose 2.33.1-desktop.1.
Хост: MacBookPro18,3, Apple M1 Pro ARM64, 8 CPU, 16 GiB RAM; Docker VM имеет 8 CPU и 8 218 316 800 байт RAM. Полные условия — evidence/environment.txt.
Перенесены собственные src/, SQL начальной схемы, зависимости, Dockerfile и тест авторизации из lab2 (bd34c1050a61d92faa30468eace4e4dadea306c3, та же рабочая ветка). Lab2 читалась, её файлы и данные не изменялись. Контракты, публичные тесты и исходный README lab3 сохранены. Добавлены балансировка, заголовок процесса, отдельный мигратор, общая идемпотентность, эксплуатационные скрипты, эксперименты. API — один Compose-service с deploy.replicas: 2, без container_name, без опубликованных портов. Публичен только LB на loopback.
HAProxy выбран за активные HTTP readiness-проверки и штатный Docker DNS resolver/server-template; это позволяет масштабировать один сервис без перечня двух фиксированных имён. Round robin распределяет HTTP-запросы без cookie/sticky session. В конфигурации десять слотов backend (поддерживаемый предел данного учебного конфига). Незаполненные слоты переходят в DNS maintenance. Логи ошибок, переходы UP/DOWN и HTTP-статусы пишутся в stdout контейнера.
Состояние, контракт и идемпотентность
PostgreSQL — источник истины для пользователей, membership, чатов, сообщений и сессий. Пароли — Argon2id: time_cost=3, memory_cost=65536 KiB, parallelism=4. Basic используется только для выдачи случайного токена с 256 битами энтропии. В БД хранится SHA-256 токена и expiry; TTL по умолчанию 3600 секунд, рестарт его не продлевает. На каждом защищённом запросе БД проверяет expiry/revoked_at. Redis кэширует профиль пользователя по хешу токена, но не заменяет проверку сессии: отказ Redis допускает чтение профиля из PostgreSQL. Сессионное состояние не локально. Logout отзывает сессию в PostgreSQL и удаляет кэш. Redis использует AOF с appendfsync always и отдельный volume.
Доступ к чату проверяется перед операцией; посторонний получает 404. Ошибки соответствуют контракту, request_id в JSON совпадает с X-Request-Id. Каждый созданный API ответ, включая ошибки/health/204, получает X-Instance-Id (случайный UUID при импорте приложения) и X-Request-Id. ID стабилен в жизни одного Uvicorn-процесса, после рестарта меняется. LB-ошибки соединения могут не иметь этих заголовков.
Пагинация keyset по (created_at, id), limit 1–100; cursor содержит область user/chat и ID последней записи, проверяется принадлежность. История читается непосредственно из PostgreSQL без устаревающего кэша. При конкурентных вставках между страницами нет snapshot: поздний COMMIT с более ранним created_at может оказаться позади уже выданного cursor. Для неизменной истории обход без повторов; это соответствует контракту. Вложения не добавлены: CreateMessage lab3 принимает только text.
Idempotency-Key обязателен, ASCII [A-Za-z0-9._:-]{1,128}. Таблица message_requests имеет PK (chat_id, sender_id, key); HTTP-метод и тип пути фиксированы единственным POST сообщений. Записи не удаляются: защита дольше 24 часов (плата — рост таблицы).
В одной транзакции выполняются:
- INSERT запроса с ON CONFLICT DO NOTHING.
- Победитель создаёт сообщение и связывает результат с ключом.
- Конкурирующий INSERT ожидает завершения транзакции победителя. Следующий SELECT в READ COMMITTED видит готовое сообщение. Одинаковый text возвращает тот же объект и 201; отличный — 409.
COMMIT атомарен для сообщения и результата. При исключении обе записи откатываются; транзиентные ошибки не закрепляются. Другие пользователи/чаты имеют независимые ключи. Аутентификация и доступ проверяются заново до повтора. Участники неизменяемы в обязательном API. Синхронная транзакция отправки вынесена в thread pool, поэтому HTTP-запросы могут реально конкурировать и внутри одного процесса. Локального словаря ключей нет.
Готовность, отказ и остановка
/health/live проверяет жизнь процесса. /health/ready выполняет SELECT 1 в обязательной PostgreSQL; Redis не критичен благодаря fallback. Если PostgreSQL недоступен — 503 в общем формате. В evidence/readiness.json зафиксирован реальный эксперимент: после stop PostgreSQL у обеих API live=200 и ready=503; после stop Redis ready=200 и профиль читается через fallback. Оба хранилища затем восстановлены. Пул: 1–10 соединений на API, ожидание до 5 с, connect_timeout 5 с, statement_timeout 5 с.
HAProxy проверяет каждую реплику раз в 1 с, при изменении состояния fastinter 500 мс, fall=2, rise=2, timeout check/connect=1 с. Для отказа соединения практический бюджет обнаружения порядка 2–4 с при свободном Docker-host; это расчёт по настройкам, не гарантия при остановке всей VM. Read timeout сервера 8 с, клиента 10 с. Docker-health API — каждые 2 с, timeout 3 с, retries 3, start_period 5 с; сам Docker-health не маршрутизирует запросы. Решение о маршрутизации принимает HAProxy.
Docker DNS 127.0.0.11:53, hold valid/obsolete/NX=1 с, resolver retry/timeout=1 с обновляет server-template. Отдельный тест реально изменил IP работающей API-реплики и подтвердил её повторную доступность через LB (dns-change.json). Для занятия старого IP кратковременно запускалась третья настоящая API-реплика; после теста она удалена без удаления данных. Проверка включает Docker CLI и ожидание, поэтому её 9,420 с — не чистый DNS latency.
PID 1 — Uvicorn, STOPSIGNAL SIGTERM. При сигнале сервер закрывает listener, ждёт активные запросы до 4 с; shutdown hook закрывает пул. Compose даёт 6 с до SIGKILL. После закрытия listener HAProxy исключает backend активными проверками. Полного drain перед остановкой нет: краткие ошибки допустимы и измерены. LB не делает автоматический replay POST (retries 0): неопределённую запись повторяет клиент с тем же ключом. stop-one.sh опрашивает прямой health внутри только API-контейнеров, точно сопоставляет TARGET_INSTANCE_ID и останавливает найденный контейнер; остальные компоненты не трогает. Восстановление — scripts/restore.sh, затем ожидание двух ID.
Миграции и rolling update
Миграции не запускаются из API/startup и не подключены к docker-entrypoint PostgreSQL. Сервис migrate ждёт healthy PostgreSQL; API ждут service_completed_successfully. SQL-файлы применяются в одной транзакции под pg_advisory_xact_lock(310026) и записываются в schema_migrations. Это также сериализует случайный повторный запуск runner. Времена применения двух миграций зафиксированы; явный повтор runner вывел Already applied, таблица до/после совпала. Восстановление API не запускает зависимости. Мигратор может вызываться повторно при полном up, но каждая версия схемы применяется ровно один раз, а не каждым API.
002 — добавление таблицы без изменения старых колонок, совместимо с работающей API lab2. При демонстрационном обновлении схема не менялась; версии образов старого/нового API записаны в JSON. Для будущих несовместимых миграций этот скрипт не гарантирует rolling: нужен expand/contract, обратная совместимость либо согласованное окно обслуживания. Автоматического rollback схемы нет.
scripts/compose.sh build api
# При НОВЫХ совместимых миграциях отдельно, до замены API:
scripts/compose.sh run --rm --no-deps migrate
scripts/rolling-update.sh
# Или эксперимент сразу с 4 writers и проверкой подтверждений:
python3 student-tests/scenarios.py rolling --output evidence/rolling-update-new.json
Алгоритм: сохранить два исходных контейнера; проверить survivor; остановить/удалить только первый API; up --no-deps --no-recreate --scale api=2 api создаёт недостающий контейнер новым образом, не пересоздаёт survivor; дождаться readiness нового и наблюдения обоих ID через LB; затем заменить второй исходный. При ошибке готовности дальнейшая замена прекращается. Номера Compose-контейнеров могут увеличиваться; скрипты не зависят от суффиксов 1/2. Это поочерёдная замена Compose на одном host, не встроенный rolling deploy оркестратора, не автоматический rollback и не нулевые ошибки.
Команды и результаты испытаний
python3 student-tests/check_auth.py
python3 student-tests/scenarios.py idempotency --output evidence/idempotency.json
python3 student-tests/scenarios.py failover --target-index 0 --duration 15 --output evidence/failover-replica-1.json
python3 student-tests/scenarios.py failover --target-index 1 --duration 15 --output evidence/failover-replica-2.json
python3 student-tests/baseline.py
python3 student-tests/scenarios.py rolling --output evidence/rolling-update.json
python3 student-tests/scenarios.py rolling --output evidence/rolling-continuity.json
python3 student-tests/dns.py
python3 student-tests/readiness.py
# Полный повтор (заменяет соответствующие evidence новыми результатами):
scripts/verify.sh
Публичные make check, validate, test, test-persistence и test-failover прошли. У persistence сняты sanitized StartedAt/ID всех контейнеров до/после, включая оба хранилища; токен сохранился. Собственный тест: 24 параллельных одинаковых POST обслужены обеими репликами, один Message и одна копия в истории; повтор с другим body — 409, чужой чат — 404, отозванный токен — 401, независимые user/chat scope, отсутствующий/неверный ключ — 400. Старение тестовых ключей до 25 часов не отменило повтор. Общая сессия и чтение подтверждённого сообщения наблюдались на обеих репликах.
| Эксперимент (4 writers) | Duration, с | Успешные / ошибки | Ошибки, % | Successful RPS | p50/p95/p99, мс | Восстановление, с | Потеря подтверждённых |
|---|---|---|---|---|---|---|---|
| Baseline, public load.py, 30 с | 30,077 | 11112 / 0 | 0 | 369,451 | 9,070 / 15,647 / 63,266 | — | не оценивается этим генератором |
| Отказ первой | 16,683 | 4803 / 366 | 7,0807 | 287,901 | 9,761 / 25,936 / 69,031 | 3,277 | 0 из 4804 |
| Отказ второй после восстановления первой | 16,741 | 4282 / 322 | 6,9939 | 255,782 | 11,185 / 28,477 / 69,385 | 2,879 | 0 из 4283 |
| Rolling новым образом | 19,218 | 4768 / 453 | 8,6765 | 248,103 | 9,335 / 51,021 / 80,478 | см. ниже | 0 из 4769 |
| Дополнительный rolling, тот же образ | 20,325 | 5064 / 270 | 5,0619 | 249,150 | 11,866 / 36,704 / 71,268 | см. ниже | 0 из 5065 |
В первом эксперименте остановлен container 7d2957677a35…, alias d2f38075-ad18-4b40-b025-0b6b75b5deec; во втором — другой исходный контейнер cdc714ebeb09…, alias 0fa5e6d8-e471-4f44-992c-42c530dceb1f. JSON хранит полные IDs и факт Running=false после hook. Первый восстановлен до второго эксперимента; после обоих снова наблюдались две реплики. Чтение полной истории выполнялось при остановленной реплике прежней сессией; подтверждены запись и доступность всех подтверждений.
Время восстановления измерено от начала action до завершения первого успешного POST, начатого после возврата action. Это консервативная оценка с затратами Docker CLI, обе менее 10 с. Длительность собственных сценариев включает завершение worker/сборщика ресурсов, поэтому больше запрошенного 15-секундного интервала. Успешные RPS посчитаны по этому полному интервалу. Между экспериментами данные не очищались.
Rolling новым образом: обе замены заняли 3,447 и 6,235 с; весь action (с подготовкой) 12,639 с. Поле first_success_after_action=12,666 с означает первый POST после завершения двух замен, а не 12-секундный простой! Дополнительный эксперимент специально измерил непрерывность: 3424 успешных запроса начаты во время action, максимальный промежуток между успешными завершениями 1,000 с; прежняя сессия и все 5065 подтверждений сохранены. Версии образов первого rolling действительно отличаются, повторный rolling проверяет замену контейнеров тем же образом.
Методика: synthetic POST text, closed loop, уникальные ключи, 4 потока, без прозрачного retry в измерении throughput. Для отказов 2 с до воздействия, далее нагрузка до ~15 с. Все тестовые объекты синтетические. На baseline уже были данные предшествующих проверок, размер БД в конце — dataset.txt. CPU/RAM сняты параллельно, интервалы нерегулярны (docker stats и Docker CLI добавляют задержку); peaks — максимум из выборок, не абсолютный пик. Baseline дал 9 выборок; API суммарно до 120,70% CPU / 118,69 MiB, PostgreSQL 41,47% / 53,01 MiB, HAProxy 17,39% / 13,63 MiB, Redis 4,16% / 9,33 MiB. CPU 100% означает одно ядро; API в таблице суммируются. Детали остальных экспериментов — resources-summary.json, raw samples — в JSON экспериментов.
Это единичные небольшие генераторы на одном ноутбуке: coordinated omission, overhead Python/клиента, latency только успешных ответов, нет определения saturation point. Предельная производительность и SLA production не заявляются. Baseline выполнялся до финального изменения Swagger; путь сообщений и транзакций тот же. Краткие 503/обрывы при остановке не скрыты; нужны retry клиента с тем же ключом и более аккуратный drain для уменьшения ошибок.
Соответствие всем критериям уровней 3 и 4
| Уровень / требование | Проверка / реализация | Фактическое доказательство |
|---|---|---|
| 3: воспроизводимый Compose, 2+ настоящих API | up.sh, capture-state.py, CPU/port metadata | containers.json, containers.txt |
| 3: одна публичная точка, общие БД/сессии | compose.yaml, public smoke и persistence | smoke.txt, persistence.txt |
| 3: одна сессия на разных репликах | scenarios.py idempotency, me и история на двух ID | idempotency.json |
| 3: X-Instance-Id реального процесса | опрос внутри контейнера, сопоставление hook | failover-replica-1.json, failover-replica-2.json |
| 3: новые чтения/записи ≤10 с после отказа любой одной | последовательный отказ каждой, полная история до restore | оба failover-replica JSON: 3,277 / 2,879 с |
| 3: подтверждённые сообщения не потеряны | сравнение всех объектов в полной истории | оба failover-replica JSON, lost_confirmed=0 |
| 3: общая идемпотентность, включая concurrent/replay | PostgreSQL транзакция, PK; 24 запроса на обе реплики | idempotency.json |
| 3: make test | публичный контрактный сценарий | smoke.txt |
| 3: persistence и failover tests | make test-persistence, make test-failover | persistence.txt, failover-public.txt |
| 4: health/readiness, timeout, SIGTERM, исключение backend | Dockerfile, HAProxy checks, настоящие stop | оба failover JSON; lb-events.txt |
| 4: восстановление / DNS backend | restore.sh; реальная смена IP | dns-change.json, instances_after_restore в failover JSON |
| 4: отказ каждой реплики, RPS/errors/recovery | scenarios.py failover с индексами 0/1 | оба failover-replica JSON и TXT |
| 4: CPU/RAM limits, нет обхода LB и container_name | Compose + sanitized inspect | containers.json, resources-summary.json |
| 4: корректное общее состояние/секреты | PostgreSQL authority, Redis AOF, secrets mounts | persistence.txt, idempotency.json, compose.yaml |
| 4: rolling под нагрузкой, рабочий survivor | rolling-update.py, 4 writers, проверка данных | rolling-update.json, rolling-continuity.json |
| 4: согласованные однократные миграции / совместимость | one-shot migrate, advisory lock, version table | migrations-initial.txt, migrations-rerun.txt, migrations-before.txt, migrations-after.txt |
| Подготовка: структура/полная схема OpenAPI | make check / make validate | check.txt, validate.txt |
Все пути доказательств в таблице относительны evidence/. HTTP-тесты не заменяют анализа конфигурации миграций/лимитов: оба вида доказательств приведены вместе.