Files
mtusi2026lab3/REPORT.md
T

20 KiB
Raw Blame History

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

  • Автор, группа: Журавский, БВТ2301
  • Целевая оценка; выбранный трек 5, если нужен: 4 (уровень 3 + уровень 4); трек 5 не заявлен
  • Commit/PR: TODO после публикации (ветка solution/БВТ2301-Журавский)
  • Использованные источники, библиотеки и помощь ИИ: FastAPI 0.115.6, Pydantic 2.10.6, Uvicorn 0.34.0, psycopg 3.2.3 + psycopg-pool 3.2.4, argon2-cffi 23.1.0, redis-py 5.2.1 (клиент Valkey), nginx 1.27.4, PostgreSQL 16.6, Valkey 8.0.2, Docker Compose v2.27.1. Документация nginx (upstream, resolve, proxy_next_upstream), PostgreSQL (pg_advisory_xact_lock, EXPLAIN), RFC 7617. Помощь ИИ: генерация каркаса и текста отчёта, проверено запуском тестов.

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

Версии и prerequisites

Компонент Версия / образ
Runtime Python 3.11.9
API-образ python:3.11.9-slim-bookworm, свой Dockerfile, тег messenger-api:lab3
Балансировщик nginx:1.27.4-alpine (встроенный Docker DNS resolve)
PostgreSQL postgres:16.6-bookworm
Valkey valkey/valkey:8.0.2-alpine
Docker / Compose 26.1.4 / v2.27.1
Python-зависимости requirements.txt (пины: fastapi, pydantic, uvicorn, psycopg[binary], psycopg-pool, argon2-cffi, redis)
Стенд Windows 10 Pro 10.0.19045, Ryzen 5 3600 (6C/12T), 15.9 GiB RAM; публичные хуки restart.sh/stop-one.sh выполняются в WSL Ubuntu (Python 3.12)

Prerequisites: Docker с Linux-контейнерами и плагином Compose. Публичный smoke и make check работают везде; на «родном» Windows для make check нужен PYTHONUTF8=1 (иначе Python читает UTF-8 JSON в кодировке cp1251). Хуки persistence/failover — POSIX-скрипты, их нужно запускать в WSL/Git Bash либо Linux-раннере.

Создание локальных secrets (не коммитятся)

sh scripts/gen-secrets.sh
# создаёт ./secrets/database_password, ./secrets/database_url, ./secrets/cache_url

Запуск, миграции, проверка, остановка

docker compose --env-file .env config --quiet      # 1. валидация конфигурации
docker compose --env-file .env up -d --build       # 2. сборка и запуск lb + api x2 + postgres + valkey
docker compose ps                                  # 3. все healthy, api портов наружу не публикует

# Миграции выполняет одноразовый сервис `migrate` до старта реплик (advisory-lock, идемпотентно):
docker compose exec -T api python -m src.migrate   # -> "migrations up to date"

python tests/smoke.py --base-url http://localhost:8080          # 4. публичный smoke
.venv\Scripts\python -m pytest student-tests -v                 #    свои тесты (36 passed)

make test-persistence ACTION_SCRIPT=scripts/restart.sh          # выполнять в WSL/Linux
make test-failover    ACTION_SCRIPT=scripts/stop-one.sh         # одна реплика остаётся остановленной
sh scripts/restore-api.sh                                       # вернуть остановленную реплику
sh scripts/rolling-update.sh                                    # поочерёдная замена под нагрузкой
python scripts/check-revocation.py                              # отзыв сессии при недоступном Valkey

# Безопасная остановка (данные сохраняются):
docker compose stop
# Намеренное удаление учебных данных (тома):
docker compose down -v

Оператору нужно: сгенерировать secrets, выполнить шаги 1–4. Обычная остановка/down (без -v) сохраняет данные PostgreSQL и Valkey; down -v удаляет их.

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

Схема: клиент → nginx (LB, единственный публичный порт 127.0.0.1:8080) → api × 2 (FastAPI/Uvicorn) → PostgreSQL (источник истины) + Valkey (кэш сессий).

  • Единая точка входа. Публикуется только lb (127.0.0.1:8080). Реплики api используют expose: 8080 без ports, поэтому обойти балансировщик нельзя. Балансировка — nginx round-robin.
  • Динамический backend-list. upstream api_backend { zone …; server api:8080 resolve max_fails=1 fail_timeout=5s; } + resolver 127.0.0.11 valid=5s. nginx перечитывает A-записи Docker DNS: добавление/остановка реплики подхватывается без reload; proxy_next_upstream error timeout http_502/503/504 повторяет запрос на живой реплике. Максимальное время обнаружения отказа: пассивный fail_timeout 5 s + valid 5 s, замеренная первая успешная запись после старта хука — < 1 с.
  • X-Instance-Id. src/instance.py: INSTANCE_ID = $INSTANCE_ID или hostname контейнера (= короткий container id). Ставится middleware на каждый ответ, включая ошибки и health; стабилен на время жизни процесса. Проверка в evidence/lab3-instances.txt: 12 запросов дают ровно два чередующихся id.
  • Общая идемпотентность. Таблица idempotency_keys (PK user_id, scope, key, scope = "POST /api/v1/chats/{id}/messages"), request_hash, status_code, response_body jsonb, expires_at. POST …/messages требует Idempotency-Key [A-Za-z0-9._:-]{1,128} (нет/неверный — 400). Вставка сообщения и запись журнала — одна транзакция; pg_advisory_xact_lock(hashtext(user|scope), hashtext(key)) сериализует одинаковые ключи между всеми репликами. Повтор возвращает тот же 201 и тот же Message; другой body — 409. TTL — IDEMPOTENCY_TTL_SECONDS (default 86400).
  • Сессии общие, отзыв корректен при сбое кэша. Источник истины — PostgreSQL (sessions): валидность и отзыв определяет строка с expires_at > now(). Valkey — кэш сессий session:{sha256(token)} -> {user_id, expires_at} с TTL min(remaining, SESSION_CACHE_TTL_SECONDS) (по умолчанию 60 c) — это верхняя граница устаревания. Logout в одной транзакции удаляет строку сессии и кладёт токен в cache_invalidations; фоновый дренажёр (src/invalidation.py, период 0.5 c) удаляет ключ Valkey и строку очереди. Поэтому logout, выполненный при лежащем Valkey, применяется сразу после восстановления кэша, а не «воскресает» до истечения TTL. При недоступности Valkey запросы обходят кэш и идут в PostgreSQL. Sticky-сессии не используются.
  • Одноразовые миграции. Отдельный сервис migrate (python -m src.migrate) под pg_advisory_xact_lock; реплики стартуют только после service_completed_successfully, гонки за схему нет.
  • Graceful shutdown. src/main.py переопределяет Server.handle_exit: по SIGTERM/SIGINT выставляет флаг (src/state.py), /health/ready отвечает 503 (LB выводит реплику из ротации), затем Uvicorn доигрывает запросы (timeout_graceful_shutdown=10).
  • Ресурсы и секреты. У всех сервисов заданы CPU/RAM-лимиты (deploy.resources.limits); секреты — файловые compose secrets/*_FILE, в образ и Git не попадают. container_name не задаётся, масштабирование одной Compose-service работает.
  • Надёжность БД. Ограниченный пул (DB_POOL_MAX), DB_POOL_TIMEOUT, statement_timeout; все SQL параметризованы; индекс messages(chat_id, created_at, id) под keyset-пагинацию.

Соответствие .env.example

Переменная Роль в решении
APP_HOST, APP_PORT адрес/порт Uvicorn; в compose 0.0.0.0:8080
APP_ENV, LOG_LEVEL метки логирования запуска
SESSION_TTL_SECONDS срок жизни сессии (sessions.expires_at) и TTL кэша
SESSION_STORE valkey/redis — включить кэш; postgres — без кэша
SESSION_CACHE_TTL_SECONDS верхняя граница жизни записи кэша сессий (граница устаревания)
CACHE_INVALIDATION_INTERVAL_SECONDS период фонового дренажёра очереди инвалидаций
IDEMPOTENCY_TTL_SECONDS срок хранения журнала идемпотентности (24 ч)
DATABASE_URL_FILE, CACHE_URL_FILE файлы с DSN PostgreSQL и URL Valkey (compose secrets)
API_REPLICAS число реплик api (deploy.replicas)
PUBLISH_PORT публикуемый порт LB (по умолчанию 8080)
DB_POOL_*, DB_STATEMENT_TIMEOUT_MS ограничения пула и таймауты

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

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Публичный smoke python tests/smoke.py --base-url http://localhost:8080 PASS: lab3 public API scenario evidence/lab3-smoke.txt
Стенд: ≥2 реплики, LB, общая БД/сессии docker compose up -d --build, docker compose ps 2× api healthy, lb 127.0.0.1:8080, postgres, valkey; у api порты не публикуются evidence/lab3-compose-ps.txt
Разные запросы одной сессии обслуживают разные реплики 12× GET /users/me через LB чередование двух разных X-Instance-Id (2 реплики), один токен evidence/lab3-instances.txt
Уровень 3: остановка одной реплики, запись/чтение продолжаются ≤10 с make test-failover ACTION_SCRIPT=scripts/stop-one.sh 138 успешных записей, 0 ошибок, восстановление 0.67 с; api-8 Exited при живом api-7 evidence/lab3-failover.txt
Общая идемпотентность, в т.ч. конкурентная и через разные реплики test_idempotency.py повтор = тот же Message; другой body → 409; 8 параллельных запросов с одним ключом → ровно одно сообщение evidence/lab3-student-tests.txt
Отзыв сессии не обходится при сбое Valkey python scripts/check-revocation.py (pause Valkey → logout 204 → unpause → 6 c) старый токен даёт 401 через 2 реплики и не может отправить сообщение evidence/lab3-revocation-fix.txt
Кэш сессий реален, очередь инвалидаций дренируется warm-up → pause/logout/unpause → valkey-cli --scan 'session:*' + cache_invalidations ключ session:* с TTL 60 → после восстановления 0 ключей и 0 строк очереди; старый токен 401 evidence/lab3-cache-invalidation.txt
Деградация кэша без остановки API pause Valkey, валидный /users/me 5×200, /health/ready = 200 (кэш обойдён) evidence/lab3-valkey-degradation.txt
Persistence: данные и сессия переживают рестарт API и хранилищ make test-persistence ACTION_SCRIPT=scripts/restart.sh PASS: persistence preserved confirmed data and existing session evidence/lab3-persistence.txt
Миграции применяются однократно и повторно идемпотентно docker compose exec -T api python -m src.migrate migrations up to date; в schema_migrations 3 строки evidence/lab3-migrations.txt
Уровень 4: health/readiness, SIGTERM, LB исключает backend scripts/stop-one.sh + /health/ready остановленная реплика исчезает из ответов; readiness→503 при SIGTERM; пассивные проверки nginx evidence/lab3-failover.txt
Уровень 4: CPU/RAM-лимиты, порты API только через LB docker compose config, docker stats лимиты 0.75 CPU / 256M у api; 8080/tcp без проброса evidence/lab3-stats.txt, evidence/lab3-compose-ps.txt
Уровень 4: rolling update под нагрузкой scripts/rolling-update.sh при непрерывном опросе LB 400/400 запросов 200, реплики заменены по одной evidence/lab3-rolling.txt
Уровень 4: индекс под keyset-пагинацию (≥10 000 сообщений) EXPLAIN (ANALYZE, BUFFERS) Bitmap Index Scan on messages_chat_created_id_idx, 0.907 мс evidence/lab3-explain.txt
Уровень 4: нагрузочные метрики tests/load.py 113.6 RPS, 0 ошибок, p50/p95/p99 = 47/172/281 мс evidence/lab3-load.txt
Секреты вне Git .gitignore, secrets.example/, gen-secrets.sh git status без .env/secrets/ описание в PR

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

Гипотеза: LB с динамическим backend-list маскирует отказ одной реплики, общая идемпотентность в PostgreSQL не даёт дублей при переключении реплик, а общий статус позволяет любой реплике обслуживать сессию. Методика: реальный compose-стенд, синтетические данные, хуки в WSL.

Нагрузочный профиль: closed-loop POST сообщений, 8 параллельных клиентов, 20 с, прогрева нет; конфигурация — один Docker-host (WSL2), api 0.75 CPU/256 MB ×2, postgres 1 CPU/512 MB.

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
Остановка одной API-реплики (stop-one.sh, TARGET = обслужившая реплика) записи/чтения продолжаются, без дублей, токен жив 138 записей за 15 с, 0 ошибок, цель не в последних ответах; api-8 Exited 0.67 с; потерь нет
То же для второй реплики (после восстановления первой) то же ≈120–140 записей, 0 ошибок ≈1 с; потерь нет
docker compose restart api lb postgres valkey данные и сессия сохранены PASS: persistence preserved…… рестарт ≈ секунды; потерь нет
Rolling update (rolling-update.sh) под непрерывным опросом замена реплик без недоступности 400/400 200 при поочерёдной замене простоя нет
Valkey недоступен во время logout (check-revocation.py) отзыв сессии не обходится, старый токен → 401 pause → logout 204 → unpause → ключ кэша удалён дренажёром ≤1.5 c, очередь cache_invalidations=0; через 6 c 401 через обе реплики, POST отклонён потерь нет; сессия отозвана в PostgreSQL
Нагрузка ~114 RPS на 2 реплики стабильная пропускная способность 0 ошибок, p99 281 мс n/a

Ограничения измерения: closed-loop генератор страдает coordinated omission и ограничен клиентом; числа — throughput HTTP-подтверждений, не точный счётчик COMMIT; единичный Docker-host не проверяет отказ узла. docker stats показывает ~150 MB RSS на реплику при лимите 256 MB.

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

  • Выдерживается: отказ процесса одной API-реплики, рестарт API и хранилищ с volumes, потеря Valkey (кэш), конкурентные повторы с общим ключом, rolling-замена реплик под нагрузкой, некорректный ввод.
  • Не выдерживается и не заявлено: отказ Docker-host, отказ единственного PostgreSQL и единственного LB, отказ узла БД. Multi-node/HA БД — это трек 5, он не выбран.
  • Учебные упрощения: HTTP без TLS (локальный стенд lab1–6); scripts/rolling-update.sh — поочерёдная замена через docker+compose, эквивалент rolling update оркестратора, а не сам оркестратор; нет rate limiting.
  • Граница устаревания сессионного кэша — SESSION_CACHE_TTL_SECONDS (60 c). При полностью недоступном Valkey отзыв применяется не мгновенно, а когда дренажёр сможет удалить ключ после восстановления кэша (замерено ≤1.5 c); TTL — страховка на случай, если дренажёр не успеет. Это осознанный компромисс: logout должен возвращать 204 и при недоступном кэше, поэтому «нулевая» задержка инвалидации в этот момент невозможна без отказа от кэша.
  • Подтверждено измерениями: смена обслуживающей реплики при отказе, конкуренто-безопасная идемпотентность, сохранность после рестарта, использование индекса (EXPLAIN), отсутствие публикации портов API.
  • Возможное улучшение (гипотеза): при большем числе реплик и proxy_next_upstream_tries можно снизить долю ошибок при «жёстком» (без ожидания healthy) rolling-обновлении; в этой работе замена ожидает healthy, поэтому ошибок нет.