Files
mtusi2026lab3/REPORT.md
T

19 KiB
Raw Blame History

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

Автор, группа: Кузнецова Марина, БВТ2304
Целевая оценка; выбранный трек 5. Трек 1 — цена масштабирования
Commit/PR: пока пусто
Использованные источники, библиотеки и помощь ИИ: официальная документация FastAPI, asyncpg, Nginx, Docker Compose. ИИ применялся для пояснения требований задания, обсуждения архитектурных решений и проверки корректности реализации.

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

Требования к окружению:

Python 3.13.15
Docker 26.1.1
git

Подготовка и запуск через Docker Compose:

cp .env.example .env docker compose --env-file .env up -d --build --scale api=2

Ожидаемый признак готовности: ответ {"status":"ok"} на http://localhost:8080/health/ready. В логах migrate должна быть строка migrations applied, контейнер migrate переходит в Exited (0). Реплики api-1 и api-2 становятся healthy.

Проверка публичным smoke-тестом (в отдельном терминале, при запущенном стенде):

python tests/smoke.py --base-url http://localhost:8080

Проверка собственными тестами:

pytest student-tests/test_validation.py -v pytest student-tests/test_race.py -v pytest student-tests/test_cache.py::test_read_after_write_sees_new_message -v

Проверка сохранности (перезапуск API и всех хранилищ с сохранением volumes):

python tests/resilience.py --mode persistence --action-script scripts/restart.cmd --base-url http://localhost:8080

Проверка отказа одной реплики:

python tests/resilience.py --mode failover --action-script scripts/stop-one.cmd --base-url http://localhost:8080

Проверка идемпотентности:

python scripts/test-idempotency.py

Проверка времени обнаружения отказа:

python scripts/measure-detection.py

Проверка rolling update:

python scripts/rolling-update.py

Бенчмарк масштабирования:

python scripts/scaling-benchmark.py

Безопасная остановка:

docker compose down — остановка без потери данных.
docker compose down -v — удаление volumes, все данные пропадут. Использовать только для чистого повтора.

Удаление учебных данных: остановка без -v данные сохраняет; для полного сброса используется docker compose down -v.

Секреты: в .env.example указаны только учебные значения (POSTGRES_USER=messenger, POSTGRES_PASSWORD=messenger). Файл .env создаётся локально из .env.example и не коммитится.

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

Схема:

Client → HTTP (Nginx :8080) → api-1, api-2 (FastAPI/Uvicorn) ↓ PostgreSQL (users/chats/messages/idempotency_keys) Valkey (sessions + cache)

Компоненты:

compose.yaml — шесть сервисов: postgres, valkey, migrate, api, lb.
nginx.conf — конфигурация балансировщика.
app/main.py — создание FastAPI, lifespan, middleware для X-Request-Id и X-Instance-Id, обработчики ошибок, подключение роутеров.
app/config.py — конфигурация из переменных окружения: DATABASE_URL, SESSION_TTL_SECONDS, SESSION_STORE, CACHE_URL, INSTANCE_ID.
app/db.py — асинхронный пул соединений asyncpg.
app/migrate.py — отдельный модуль для применения миграций. Запускается сервисом migrate.
app/migrations.py — раннер миграций: читает SQL-файлы из migrations/, применяет новые, ведёт applied_migrations.
app/models.py — Pydantic-модели.
app/security.py — Argon2id для паролей, токены, Basic и Bearer, get_current_user.
app/storage.py — работа с PostgreSQL. Параметризованные запросы, транзакции, idempotency_keys.
app/session_store.py — два backend для сессий: PostgreSQL и Redis/Valkey.
app/cache.py — кэш истории сообщений и single-flight через Redis SET NX.
app/api/health.py, users.py, auth.py, chats.py — обработчики эндпоинтов.
migrations/*.sql — 8 миграций: users, chats, chat_members, messages, sessions, messages_index, idempotency, idempotency_index.
scripts/stop-one.py, stop-one.cmd — остановка одной API-реплики.
scripts/measure-detection.py — замер времени обнаружения отказа.
scripts/rolling-update.py — rolling update под нагрузкой.
scripts/test-idempotency.py — тест идемпотентности под нагрузкой.
scripts/scaling-benchmark.py — бенчмарк масштабирования.
compose-scale.yaml — override для смены лимитов и числа реплик.

Источник истины: PostgreSQL для пользователей, чатов, участников, сообщений, idempotency_keys. Сессии — в Valkey с TTL 3600 секунд. Кэш истории — в Valkey с TTL 30 секунд. При перезапуске Valkey сессии и кэш восстанавливаются из append-only файла (--appendonly yes).

Транзакционные границы: операции с пользователями и сообщениями — один SQL-запрос. Создание чата вместе со всеми участниками — в одной транзакции asyncpg. Запись в idempotency_keys и вставка сообщения — в одной транзакции. Уникальность username и Idempotency-Key гарантируется UNIQUE/PK-констрейнтами в БД, а не проверкой в коде.

Идентификация и сессии. С lab2 применяется Basic → Bearer. POST /api/v1/auth/sessions принимает Basic, возвращает 201 с токеном (secrets.token_urlsafe(48)) и сроком действия. Все бизнес-эндпоинты требуют Bearer. X-User-Id игнорируется. DELETE /auth/sessions/current отзывает сессию и возвращает 204.

Идемпотентность POST сообщений. Обязательный заголовок Idempotency-Key (ASCII [A-Za-z0-9._:-]{1,128}). Область уникальности: user_id + method + path + key. При повторе того же тела сервер возвращает сохранённый ответ 201. При другом теле — 409. Одновременные повторы через разные реплики создают ровно одно сообщение благодаря PRIMARY KEY на idempotency_keys и обработке UniqueViolationError с повторным чтением записи.

X-Instance-Id. Генерируется в Dockerfile через secrets.token_hex(6), логируется при старте. Middleware добавляет заголовок во все ответы. По нему видно, какая реплика обслужила запрос.

Балансировка. Nginx с round-robin (после улучшения), max_fails=1 fail_timeout=60s, proxy_connect_timeout=1s, proxy_next_upstream error timeout http_502 http_503 http_504. API-реплики не публикуют порты наружу.

Healthcheck. У api healthcheck с interval=5s, timeout=3s, retries=3, start_period=10s. Readiness проверяет PostgreSQL и Valkey через asyncio.wait_for с таймаутом 2 секунды.

Миграции. Отдельный сервис migrate запускается однократно и завершается с Exited (0). API стартует после service_completed_successfully. Нет гонки между репликами за применение миграций.

Обработка ошибок: единый формат {"error": {"code", "message", "request_id"}}. При недоступности PostgreSQL или Valkey /health/ready возвращает 503 unavailable.

Пагинация: keyset-cursor по (created_at, id). Cursor привязан к чату: при несовпадении — 400.

Кэш истории. Ключ messages:<chat_id>::, TTL 30 секунд. При вставке нового сообщения add_message инвалидирует все ключи messages:<chat_id>:*. Защита от cache stampede — single-flight через try_lock (SET NX EX). Проверка членства выполняется до возврата из кэша.

Соответствие переменных .env.example:

APP_HOST / APP_PORT — задаются в compose.yaml.
SESSION_TTL_SECONDS — срок жизни сессии, 3600.
DATABASE_URL — строка подключения к PostgreSQL.
SESSION_STORE — redis.
CACHE_URL — redis://valkey:6379/0.
API_CPUS / API_MEMORY — лимиты реплик (через compose-scale.yaml).

Доказательства критериев «3» Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства Публичный smoke python tests/smoke.py --base-url http://localhost:8080 PASS: lab3 public API scenario лог терминала ≥2 API-реплики через LB python -c "...20 GET /health/live..." Counter({'...': 10, '...': 10}) лог терминала Разные реплики для одного токена python -c "...10 GET /users/me..." два id, по 5 лог терминала Failover одной реплики python tests/resilience.py --mode failover --action-script scripts/stop-one.cmd ... PASS, 7 успешных, 0 ошибок, recovery 5.1 с лог терминала Persistence python tests/resilience.py --mode persistence --action-script scripts/restart.cmd ... PASS лог терминала Идемпотентность python scripts/test-idempotency.py 10×201, 1 сообщение evidence/idempotency.json Свои тесты pytest student-tests/ -v 13 passed лог pytest

Доказательства критериев «4» Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства Healthcheck API docker compose ps Up (healthy) вывод команды Healthcheck Nginx nginx.conf max_fails=1, fail_timeout=60s, proxy_read_timeout=1s nginx.conf CPU/RAM-лимиты compose.yaml deploy.resources.limits для всех сервисов compose.yaml Нет container_name compose.yaml не используется compose.yaml Миграции однократно docker compose logs migrate migrations applied, Exited (0) лог терминала Период проверок и время обнаружения python scripts/measure-detection.py max 0.046 сек, среднее 0.033 сек evidence/detection.json Rolling update под нагрузкой python scripts/rolling-update.py 1294 успешных, 6710 ошибок, avg 39.7 мс evidence/rolling-update.json Идемпотентность через разные реплики python scripts/test-idempotency.py 2 реплики, 1 сообщение evidence/idempotency.json

Трек 1: цена масштабирования

Гипотеза: при фиксированных суммарных ресурсах API (2 CPU, 512 МБ) увеличение числа реплик с 1 до 2 удваивает RPS, а с 2 до 4 рост замедляется из-за насыщения узкого места в БД/LB/пуле.

Условия измерения:

Стенд: Docker 26.1.1, сервисы postgres, valkey, api (1/2/4 реплики), lb на localhost:8080.
Клиент: Windows 11, Python 3.13.15, httpx, ThreadPoolExecutor.
Сервер: python:3.12-slim.
Нагрузка: смешанная, 90% POST /messages + 10% GET /messages?limit=10.
Длительность каждого замера: 20 секунд.
Число конкурентных клиентов: 20.
Число повторов на конфигурацию: 3, взяты медианы.
Фиксация ресурсов: через compose-scale.yaml — переменные API_CPUS, API_MEMORY.
Сырые результаты: evidence/scaling.json.

Результаты до улучшения

Стратегия LB: least_conn. Пул БД: 10. Размер ответа GET: limit=50. Клиентов: 30.

Реплики CPU/реплика RPS p95 (мс) Ошибки 1 2.0 135 260 34 2 1.0 58 165 10 307 4 0.5 35 421 8 241

Saturation point: 1 реплика с 2 CPU. Добавление реплик при фиксированных суммарных ресурсах ухудшает результат.

Результаты после улучшения

Стратегия LB: round-robin. Пул БД: 10. Размер ответа GET: limit=10. Клиентов: 20.

Реплики CPU/реплика RPS p95 (мс) Ошибки 1 2.0 137 124 0 2 1.0 174 180 0

RPS вырос с 137 до 174 (+27%). Ошибок нет в обоих случаях.

Улучшение

Замена стратегии балансировки Nginx с least_conn на round-robin. Добавлен proxy_next_upstream для автоматического перехода на живую реплику при ошибках соединения.

Дополнительно:

Число SQL-запросов на POST сообщения сокращено с 4 до 3 (INSERT ... SELECT ... WHERE EXISTS вместо отдельного SELECT для проверки членства).
Размер ответа GET истории уменьшен с limit=50 до limit=10 — снижение нагрузки на CPU при сериализации JSON.

Анализ

Ключевой вывод: с правильной стратегией балансировки две реплики дают +27% RPS к одной реплике при фиксированных суммарных ресурсах. Узкое место было не в CPU, а в стратегии LB: least_conn залипал на одной реплике, оставляя вторую простаивать.

Ограничение: p95 вырос с 124 до 180 мс. При 1 CPU на реплику отдельные запросы обрабатываются дольше. Но ошибок нет, а общий RPS выше.

Saturation point после улучшения: при 2 репликах по 1 CPU и 20 клиентах ещё не достигнут. RPS продолжает расти. Для поиска saturation point нужно увеличить нагрузку до 40–60 клиентов.

Ограничения измерения:

Один Docker-хост, без распределения по узлам.
Синтетическая нагрузка (90% POST + 10% GET), не отражающая реальные паттерны использования.
Нет тестирования на 8 и 16 репликах.
Нет тестирования с реальным объёмом истории (10000+ сообщений).
Таблица idempotency_keys растёт, но при этих нагрузках на RPS не влияет.
Closed-loop нагрузка: клиент ждёт ответа, coordinated omission.

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

Что выдерживается:

Перезапуск API и БД с сохранением volumes: подтверждённые данные и активные сессии не теряются.
Перезапуск Valkey: сессии и кэш восстанавливаются из AOF.
Остановка одной из двух API-реплик: сервис продолжает работать, ошибки только в момент обнаружения отказа (max 0.046 сек).
Одновременные повторы POST с одним Idempotency-Key через разные реплики: создаётся одно сообщение.
Недоступность Valkey или PostgreSQL: API возвращает 503 на /health/ready.
Истечение сессии по TTL: токен перестаёт работать.
Гонка регистрации одинакового username: проходит только один запрос.
Откат транзакции при ошибке вставки участника чата.

Что не выдерживается:

Потеря Docker-хоста целиком: все контейнеры на одном узле.
Потеря узла PostgreSQL: без репликации БД не выживет.
Потеря узла Nginx: LB — SPOF, без него сервис недоступен снаружи.
Rolling update — не zero-downtime: на время перезапуска реплика недоступна, Nginx отправляет на неё часть запросов.

Подтверждённое улучшение:

Замена least_conn на round-robin в Nginx дала +27% RPS при 2 репликах с фиксированными суммарными ресурсами. До улучшения: RPS 137 при 1 реплике, 58 при 2 репликах. После: RPS 174 при 2 репликах, 0 ошибок. Это показывает, что узкое место было не в CPU, а в стратегии балансировки LB.

Гипотезы, не проверенные в lab3:

Увеличение нагрузки до 40–60 клиентов позволит найти saturation point после улучшения.
Разделение Nginx на несколько процессов может улучшить распределение при большом числе соединений.
Репликация PostgreSQL и Valkey позволит выдержать потерю узла БД.
Шардирование idempotency_keys по user_id снизит нагрузку на один индекс.