forked from mtusi2026/mtusi2026lab3
Переиспользован стек 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>
13 KiB
13 KiB
Отчёт — лабораторная 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, оба стоит знать на защите:
- Гонка миграций: обе реплики при одновременном первом старте пытались создать одинаковые таблицы и падали с
UniqueViolationError. Исправленоpg_advisory_lockвapp/db.pyперед прогоном миграций. - "Залипание" балансировки на одной реплике: при
worker_processes autoу Nginx каждый worker-процесс ведёт свой независимый round-robin счётчик, и на малом числе запросов казалось, что трафик идёт только наapi1. Исправленоworker_processes 1(демонстративно для лабы — на реальной нагрузке это стало бы ограничением пропускной способности самого LB, что подходящий компромисс не для production, а именно здесь задокументирован явно). - Рестарт целого стека падал:
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 с активными пробами.