20 KiB
Отчёт — лабораторная 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_timeout5 s +valid5 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(PKuser_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}с TTLmin(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, поэтому ошибок нет.