Files
mtusi2026lab3/REPORT.md
T
Artu-RitoandClaude Sonnet 5 2f1cf3afac Лаба 3: Nginx LB, 2 реплики API и общая идемпотентность (оценка 4)
Переиспользован стек lab2 (Postgres/Redis/Argon2id). Добавлены: Nginx
балансировщик перед api1/api2, общая идемпотентность POST-сообщений
(idempotency_keys + advisory-lock сериализация в Postgres), explicit
stop-one/restart hooks. make test/test-persistence/test-failover/validate
зелёные для обеих реплик; найдены и исправлены гонка миграций и гонка
рестарта Nginx/DNS — см. REPORT.md.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-10-30 00:35:53 +03:00

13 KiB
Raw Blame History

Отчёт — лабораторная 3

  • Автор, группа: Сарибекян, БПИ2303
  • Целевая оценка: 4
  • Commit/PR: см. ветку solution/БПИ2303-Сарибекян
  • Использованные источники, библиотеки и помощь ИИ: та же база, что в лабе 2 (FastAPI/asyncpg/redis-py/argon2-cffi) плюс Nginx как балансировщик. Реализация подготовлена с помощью AI-ассистента (Claude Code); проверено локальным запуском make check/test/test-persistence/test-failover/validate.

Запуск из чистого clone

Версии: Python 3.12.7, PostgreSQL 16.4, Redis 7.4.1, Nginx 1.27.2. Docker Engine + Compose v2.

git clone <ваш форк>
cd mtusi2026lab3
mkdir -p secrets
openssl rand -hex 20 > secrets/postgres_password.txt
printf 'postgresql://messenger:%s@postgres:5432/messenger' "$(cat secrets/postgres_password.txt)" > secrets/database_url.txt
printf 'redis://redis:6379/0' > secrets/cache_url.txt
chmod 600 secrets/*.txt
printf 'SESSION_TTL_SECONDS=3600\n' > .env

docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
curl -s localhost:8080/health/ready

make test
chmod +x scripts/restart.sh scripts/stop-one.sh
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
# после отказа одной реплики: docker compose start api1 (или api2), повторить make test-failover для второй.

Остановка: docker compose stop. Намеренное удаление учебных данных: docker compose down -v.

Архитектура и решения

Клиент → lb (Nginx, :8080) → api1 / api2 (FastAPI) → PostgreSQL (общий) + Redis (общие сессии)
  • Балансировщик: Nginx, upstream с двумя явными backend (api1:8080, api2:8080), max_fails=1 fail_timeout=3s — пассивная проверка здоровья: один неудачный запрос выводит backend из ротации на 3 секунды, что укладывается в бюджет обнаружения отказа <10с. worker_processes 1 — намеренное решение: с несколькими worker-процессами у каждого свой независимый round-robin счётчик, и балансировка на малом числе реплик визуально "залипала" на одном backend (воспроизведено и исправлено, см. ограничения).
  • Почему две явные службы api1/api2, а не --scale api=2: с явными именами легко детерминированно остановить ровно одну реплику по алиасу (TARGET_INSTANCE_ID), и INSTANCE_ID передаётся как переменная окружения напрямую, без догадок по hostname контейнера.
  • Общие хранилища: Postgres и Redis — те же роли, что в lab2, без изменений схемы (см. migrations/0001_init.sql), плюс новая таблица idempotency_keys (migrations/0002_idempotency.sql).
  • Локальных сессий в API не осталось: обе реплики читают/пишут один и тот же Redis по CACHE_URL_FILE; ни один стейт не держится в памяти процесса API (кроме пула соединений).
  • Идемпотентность (app/idempotency.py): таблица idempotency_keys с PK (user_id, method, path, idem_key). На POST: INSERT ... ON CONFLICT DO NOTHING внутри той же транзакции, что и создание сообщения; если конфликт — читаем существующую запись: совпадает хеш запроса → при необходимости дождаться status='done' (конкурентная уже выполняющаяся транзакция блокирует INSERT до своего COMMIT/ROLLBACK на уровне PostgreSQL — поэтому конкурентные повторы с одним ключом естественно сериализуются самой БД, без ручных блокировок в приложении) и вернуть тот же результат; не совпадает — 409. При ошибке внутри perform() строка идемпотентности откатывается вместе со всей транзакцией — повтор не блокируется навечно.
  • Транзиентные ошибки не коммитятся как факт: побочный эффект (вставка сообщения) и фиксация результата идемпотентности — одна транзакция asyncpg; при любой ошибке всё откатывается целиком.
  • Миграции без гонки реплик: app/db.py берёт pg_advisory_lock перед применением миграций — без этого обе реплики, стартующие одновременно, пытались создать одну и ту же таблицу и падали с UniqueViolationError (воспроизведено и исправлено, см. ограничения).
  • Ресурсы: deploy.resources.limits на каждый сервис (compose.yaml) — Compose v2 применяет их и без Swarm.
  • Graceful shutdown: uvicorn --timeout-graceful-shutdown 5 — после SIGTERM процесс донашивает текущие запросы до 5 секунд, не принимая новые.

Доказательства критериев

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
≥2 реплики, одна точка входа, общая БД/сессии docker compose ps; 8 последовательных GET /health/live через LB чередование X-Instance-Id: api1/api2 ручной прогон, см. ниже
Публичный smoke make test PASS: lab3 public API scenario... вывод команды
Персистентность make test-persistence ACTION_SCRIPT=scripts/restart.sh PASS: persistence preserved confirmed data and existing session. вывод команды
Failover (≥2 наблюдаемых реплики, запись не прерывается >10с) make test-failover ACTION_SCRIPT=scripts/stop-one.sh, для обеих реплик по очереди observed_instances_before: 2; 1-й прогон: successful_writes: 97, failed_attempts: 0, first_recovery_seconds: 0.899; 2-й прогон (другая реплика): successful_writes: 101, failed_attempts: 0, first_recovery_seconds: 0.885 вывод команды, evidence/failover_both_replicas.txt
Идемпотентность при конкурентном повторе через разные реплики 5 параллельных curl POST с одним Idempotency-Key все 5 ответов — один и тот же id сообщения; в БД SELECT count(*) = 1 evidence/idempotency_concurrent.txt
Разный body под тем же ключом → 409 повтор с тем же ключом, другим text 409 conflict evidence/idempotency_concurrent.txt
Health/readiness, graceful shutdown uvicorn --timeout-graceful-shutdown 5; Nginx max_fails=1 fail_timeout=3s код/конфиг; поведение подтверждено failover-тестом (восстановление <1с) Dockerfile, infra/nginx/nginx.conf
Нет публикации портов API в обход LB compose.yaml: api1/api2 без секции ports только lb публикует 8080:8080 compose.yaml
Ресурсные лимиты deploy.resources.limits на каждый сервис код ревью compose.yaml

Эксперименты и отказы

Последовательная остановка каждой реплики (уровень 4). scripts/stop-one.sh получает TARGET_INSTANCE_ID от теста и останавливает именно её контейнер (docker compose stop api1|api2). Прогнано дважды — по разу на каждую реплику, с восстановлением (docker compose start) между прогонами.

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
Остановка api1 (пока работает api2) Запись продолжается <10с, нет дублей successful_writes=97, failed_attempts=0, first_recovery_seconds=0.899 восстановление записи 0.9с, потерь нет
Остановка api2 (пока работает api1) То же successful_writes=101, failed_attempts=0, first_recovery_seconds=0.885 восстановление записи 0.89с, потерь нет
docker compose restart postgres redis api1 api2 lb (последовательно) Сообщения и активная сессия сохраняются PASS в make test-persistence, тот же Bearer-токен работает восстановление <90с (бюджет теста), без потери данных
5 параллельных POST, один Idempotency-Key Ровно одно сообщение 1 строка в messages, все 5 ответов идентичны без дублей

Ограничение: нагрузочный тест (tests/load.py) и исследовательский трек уровня 5 не выполнялись — цель лабы — оценка 4.

Ограничения и следующие шаги

  • При разработке найдены и исправлены два реальных бага concurrency, оба стоит знать на защите:
    1. Гонка миграций: обе реплики при одновременном первом старте пытались создать одинаковые таблицы и падали с UniqueViolationError. Исправлено pg_advisory_lock в app/db.py перед прогоном миграций.
    2. "Залипание" балансировки на одной реплике: при worker_processes auto у Nginx каждый worker-процесс ведёт свой независимый round-robin счётчик, и на малом числе запросов казалось, что трафик идёт только на api1. Исправлено worker_processes 1 (демонстративно для лабы — на реальной нагрузке это стало бы ограничением пропускной способности самого LB, что подходящий компромисс не для production, а именно здесь задокументирован явно).
    3. Рестарт целого стека падал: docker compose restart перезапускает контейнеры параллельно, и Nginx (резолвит upstream-хосты только при своём старте) иногда стартовал раньше, чем Docker DNS успевал зарегистрировать api1/api2 после их параллельного перезапуска, и падал насмерть (host not found in upstream). Исправлено явной последовательностью в scripts/restart.sh: сначала БД/Redis, затем api1/api2, и только потом lb.
  • Трек исследования уровня 5 (цена масштабирования / отказ узла) не реализован.
  • Rolling update под нагрузкой не прогонялся отдельным сценарием (ограничение времени); качественно это покрывается failover-тестом, который и есть частный случай замены одной реплики.
  • Nginx open-source не делает активных health-check проб — только пассивные (по факту неудачного реального запроса); для прод-уровня здесь нужен Nginx Plus/HAProxy/Traefik с активными пробами.