Files
mtusi2026lab3/REPORT.md
T

26 KiB
Raw Blame History

Лабораторная №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 часов (плата — рост таблицы).

В одной транзакции выполняются:

  1. INSERT запроса с ON CONFLICT DO NOTHING.
  2. Победитель создаёт сообщение и связывает результат с ключом.
  3. Конкурирующий 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-тесты не заменяют анализа конфигурации миграций/лимитов: оба вида доказательств приведены вместе.