resolve() больше не доверяет кэшу: валидность сессии всегда проверяется в PostgreSQL, поэтому неудавшаяся инвалидация при недоступном Valkey не воскрешает отозванный токен. Valkey остаётся read-through кэшем неизменяемого профиля. Добавлены scripts/check-revocation.py и student-tests/test_session_revocation.py.
18 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()), поэтому отозванный токен даёт401на любой реплике немедленно. Valkey — read-through кэш неизменяемого профиля пользователя (user:{id}, TTL 300 c), он никогда не используется для решения о доступе. Поэтому сбой инвалидации при лежащем Valkey не может «воскресить» отозванную сессию (регрессионная проверка —scripts/check-revocation.py). Sticky session не используются: пользователь свободно попадает на любую реплику без повторного входа. - Одноразовые миграции. Отдельный сервис
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 — без кэша |
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 |
чередование 4141f552b001/5ac0582fa5e1 (2 реплики), один токен |
evidence/lab3-instances.txt |
| Уровень 3: остановка одной реплики, запись/чтение продолжаются ≤10 с | make test-failover ACTION_SCRIPT=scripts/stop-one.sh |
122 успешных записи, 0 ошибок, восстановление 1.083 с; api-6 Exited при живом api-5 |
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 |
| Деградация кэша без остановки 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 2 строки |
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 |
133 RPS, 0 ошибок, p50/p95/p99 = 47/141/203 мс | 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 = обслужившая реплика) |
записи/чтения продолжаются, без дублей, токен жив | 122 записи за 15 с, 0 ошибок, цель не в последних ответах; api-6 Exited |
1.083 с; потерь нет |
| То же для второй реплики (после восстановления первой) | то же | ≈120–140 записей, 0 ошибок; api-2 Exited |
≈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 → 6 c → 401 через обе реплики, POST отклонён | потерь нет; сессия отозвана в PostgreSQL |
| Нагрузка 133 RPS на 2 реплики | стабильная пропускная способность | 0 ошибок, p99 203 мс | n/a |
Ограничения измерения: closed-loop генератор страдает coordinated omission и ограничен клиентом; числа — throughput HTTP-подтверждений, не точный счётчик COMMIT; единичный Docker-host не проверяет отказ узла. docker stats показывает ~74 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. - Подтверждено измерениями: смена обслуживающей реплики при отказе, конкуренто-безопасная идемпотентность, сохранность после рестарта, использование индекса (EXPLAIN), отсутствие публикации портов API.
- Возможное улучшение (гипотеза): при большем числе реплик и
proxy_next_upstream_triesможно снизить долю ошибок при «жёстком» (без ожидания healthy) rolling-обновлении; в этой работе замена ожидает healthy, поэтому ошибок нет.