20 KiB
Отчёт — лабораторная 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 -X utf8 tests/smoke.py --base-url http://localhost:8080
Проверка собственными тестами:
python -X utf8 -m pytest student-tests/test_validation.py -v
python -X utf8 -m pytest student-tests/test_race.py -v
python -X utf8 -m pytest student-tests/test_cache.py -v
Проверка сохранности:
python -X utf8 tests/resilience.py --mode persistence --action-script scripts/restart.cmd --base-url http://localhost:8080
Проверка отказа одной реплики:
python -X utf8 tests/resilience.py --mode failover --action-script scripts/stop-one.cmd --base-url http://localhost:8080
Проверка идемпотентности:
python -X utf8 scripts/test-idempotency.py
Проверка времени обнаружения отказа:
python -X utf8 scripts/measure-detection.py
Проверка rolling update:
python -X utf8 scripts/rolling-update.py
Бенчмарк масштабирования:
python -X utf8 scripts/fair-scaling-benchmark.py
Безопасная остановка:
docker compose down— остановка без потери данных.docker compose down -v— удаление volumes, все данные пропадут.
Архитектура и решения
Схема:
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— конфигурация из переменных окружения.app/db.py— асинхронный пул соединений asyncpg.app/migrate.py— отдельный модуль для применения миграций.app/migrations.py— раннер миграций.app/models.py— Pydantic-модели с валидацией.app/security.py— Argon2id, токены, Basic и Bearer.app/storage.py— работа с PostgreSQL, транзакции,idempotency_keys, версионирование кэша.app/session_store.py— backend для сессий.app/cache.py— кэш истории и single-flight.migrations/*.sql— 9 миграций.scripts/stop-one.py,stop-one.cmd— остановка реплики.scripts/measure-detection.py,rolling-update.py,test-idempotency.py,fair-scaling-benchmark.py— эксперименты.compose-scale.yaml— override для смены лимитов и числа реплик.
Источник истины: PostgreSQL для пользователей, чатов, участников, сообщений, idempotency_keys. Сессии — в Valkey с TTL 3600 секунд. Кэш истории — в Valkey с TTL 30 секунд. При перезапуске Valkey сессии и кэш восстанавливаются из AOF (--appendonly yes).
Транзакционные границы: операции с пользователями и сообщениями — один SQL-запрос. Создание чата с участниками — одна транзакция. Запись в idempotency_keys и вставка сообщения — одна транзакция. Уникальность username и Idempotency-Key гарантируется констрейнтами БД.
Идемпотентность. Обязательный Idempotency-Key (ASCII [A-Za-z0-9._:-]{1,128}). Область уникальности: user_id + method + path + key. При повторе того же тела — сохранённый 201. При другом теле — 409. Конкурентные повторы через разные реплики создают одно сообщение.
X-Instance-Id. Генерируется в Dockerfile через secrets.token_hex(6), логируется при старте. Middleware добавляет заголовок во все ответы.
Балансировка. Nginx с round-robin (после улучшения), max_fails=1 fail_timeout=10s, proxy_next_upstream error timeout http_502 http_503 http_504. API-реплики не публикуют порты наружу.
Healthcheck. У api: interval=5s, timeout=3s, retries=3, start_period=10s. Readiness проверяет PostgreSQL и Valkey через asyncio.wait_for с таймаутом 2 секунды.
Миграции. Отдельный сервис migrate запускается однократно и завершается с Exited (0). API стартует после service_completed_successfully.
Версионирование кэша. В chats добавлена колонка version BIGINT NOT NULL DEFAULT 0. При POST version увеличивается. При записи в кэш сохраняется версия. При чтении проверяется совпадение с текущей версией в БД. Если версия изменилась — кэш удаляется, результат не публикуется. Это защищает от race condition: старый GET не сможет опубликовать устаревший снимок после инвалидации.
Валидация входных моделей. Pydantic extra="forbid" — лишние поля → 400. field_validator проверяет наличие непробельных символов в display_name, title, text.
Валидация member_ids. В create_chat до обращения к БД проверяются дубликаты и формат UUID. Невалидный UUID или дубликат → 400.
Обработка ошибок: единый формат {"error": {"code", "message", "request_id"}}. При недоступности PostgreSQL или Valkey /health/ready → 503 unavailable. HTTPException, PostgresConnectionError, redis.exceptions.ConnectionError обрабатываются в main.py.
Пагинация: keyset-cursor по (created_at, id). Cursor привязан к чату: <chat_id>|<created_at>|<id>, при несовпадении — 400.
Кэш истории. Ключ messages:<chat_id>:<limit>:<cursor>, TTL 30 секунд. При вставке add_message инвалидирует все ключи messages:<chat_id>:*. Защита от cache stampede — single-flight через try_lock (SET NX EX). Проверка членства выполняется до возврата из кэша.
Доказательства критериев «3»
| Критерий | Команда | Результат |
|---|---|---|
| Публичный smoke | python -X utf8 tests/smoke.py --base-url http://localhost:8080 |
PASS: lab3 public API scenario |
| ≥2 API-реплики через LB | python -X utf8 scripts/check-balance.py |
Counter({'f7c6d1104aab': 200, '1a6b2e1b3b45': 200}) |
| Разные реплики для одного токена | python -X utf8 -c "...10 GET /users/me..." |
два id, по 5 |
| Failover одной реплики | python -X utf8 tests/resilience.py --mode failover --action-script scripts/stop-one.cmd |
PASS, 7 успешных, 0 ошибок, recovery 5.1 с |
| Persistence | python -X utf8 tests/resilience.py --mode persistence --action-script scripts/restart.cmd |
PASS |
| Идемпотентность | python -X utf8 scripts/test-idempotency.py |
10×201, 1 сообщение |
| Свои тесты | python -X utf8 -m pytest student-tests/test_validation.py student-tests/test_race.py student-tests/test_cache.py -v |
14 passed |
Доказательства критериев «4»
| Критерий | Команда | Результат |
|---|---|---|
| Healthcheck API | docker compose ps |
Up (healthy) |
| Healthcheck Nginx | nginx.conf |
max_fails=1, fail_timeout=10s, proxy_next_upstream |
| CPU/RAM-лимиты | compose.yaml |
deploy.resources.limits для всех сервисов |
Нет container_name |
compose.yaml |
не используется |
| Миграции однократно | docker compose logs migrate |
migrations applied, Exited (0) |
| Период проверок и время обнаружения | python -X utf8 scripts/measure-detection.py |
max 0.046 сек, среднее 0.033 сек |
| Rolling update под нагрузкой | python -X utf8 scripts/rolling-update.py |
1294 успешных, 6710 ошибок, avg 39.7 мс |
| Идемпотентность через разные реплики | python -X utf8 scripts/test-idempotency.py |
2 реплики, 1 сообщение |
Трек 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/fair_scaling.json.
Результаты (медианы 3 прогонов):
| Реплики | least_conn RPS | round_robin RPS | least_conn p95 | round_robin p95 | least_conn p99 | round_robin p99 |
|---|---|---|---|---|---|---|
| 1 | 116.39 | 103.64 | 125 | 125 | 5235 | 5250 |
| 2 | 125.65 | 120.15 | 156 | 109 | 5125 | 4375 |
| 4 | 76.10 | 89.52 | 610 | 438 | 2938 | 2297 |
Ошибок нет ни в одном прогоне.
Анализ:
- На 1 реплике разница между стратегиями — шум. Балансировки нет, стратегия не работает.
- На 2 репликах
least_conn= 125.65,round_robin= 120.15 — разница в пределах шума (−4%). - На 4 репликах
least_conn= 76.10,round_robin= 89.52 — +18% в пользуround_robin. При 4 репликахleast_connчаще залипает на одной из-за коротких запросов. - Saturation point = 2 реплики для обеих стратегий. При 4 репликах RPS падает — CPU starvation: 0.5 CPU на реплику не хватает на 20 клиентов.
- p99 = ~5 секунд во всех случаях — tail latency, вероятно из-за GC или переключения процессов ОС. При 2 репликах p99
round_robin= 4375 мс, уleast_conn= 5125 мс.
Улучшение: замена стратегии балансировки Nginx с least_conn на round_robin. Добавлен proxy_next_upstream для перехода на живую реплику при ошибках.
Что подтверждено:
- Saturation point при фиксированных суммарных ресурсах — 2 реплики. Дальше рост реплик вредит из-за CPU starvation.
round_robinдаёт +18% RPS на 4 репликах по сравнению сleast_conn. На 2 репликах разница незначима.- Ошибок нет ни в одном прогоне.
Ограничения измерения:
- Разброс между прогонами до 20% — на 2 репликах разница
least_connvsround_robin(−4%). - p99 ~5 секунд — tail latency, не связано со стратегией.
- Один Docker-хост, closed-loop нагрузка.
- Не тестировали 8+ реплик и больший объём истории.
Исправления по замечаниям преподавателя
1. Устаревший кэш после POST
Проблема: старый GET мог прочитать пустую историю, задержаться, а после POST (с инвалидацией) записать устаревший снимок в кэш. Следующий GET получал пустой список.
Исправление: добавлена колонка version в chats (миграция 009_chat_version.sql). При POST version увеличивается. При записи в кэш сохраняется версия. При чтении проверяется совпадение с текущей версией в БД. Если версия изменилась — кэш удаляется, результат не публикуется.
2. Пробельные строки и лишние поля
Проблема: строка " " проходила валидацию Pydantic. Лишние поля (например, sender_id) молча игнорировались.
Исправление: в CreateUser, CreateChat, CreateMessage добавлено model_config = ConfigDict(extra="forbid") — лишние поля → 400. Добавлен field_validator("...") с функцией _not_blank — только пробелы → 400.
3. Дубликаты участников и невалидные UUID в create_chat
Проблема: дубликат member_ids молча убирался. Невалидный UUID попадал в SQL и давал 500.
Исправление: в app/api/chats.py добавлена валидация до обращения к БД: проверка дубликатов и формата UUID → 400. В app/storage.py убран dict.fromkeys.
4. Nginx не обновлял список адресов реплик
Проблема: upstream резолвит api один раз при старте. При добавлении реплики через --scale api=3 Nginx её не видел.
Исправление: upstream api_backend с max_fails=1 fail_timeout=10s. После масштабирования выполняется docker compose restart lb — Nginx резолвит новый список IP. fail_timeout=10s возвращает восстановившуюся реплику в обслуживание. Проверено: при 3 репликах после restart lb — три значения X-Instance-Id; после docker restart api-1 — три значения; при возврате к 2 — два значения.
5. Неверные цифры и нечестное сравнение
Проблема: между измерениями менялись число реплик, число клиентов и размер истории. Медианы были посчитаны неверно.
Исправление: проведён корректный эксперимент scripts/fair-scaling-benchmark.py с фиксированными параметрами. Меняется только стратегия балансировки. 3 прогона, медианы.
Новые медианы:
| Реплики | least_conn RPS | round_robin RPS |
|---|---|---|
| 1 | 116.39 | 103.64 |
| 2 | 125.65 | 120.15 |
| 4 | 76.10 | 89.52 |
Разница на 1–2 репликах в пределах шума, на 4 — значимая (+18% в пользу round_robin).
Ограничения и следующие шаги
Что выдерживается:
- Перезапуск API и БД с сохранением volumes: данные и сессии не теряются.
- Перезапуск Valkey: сессии и кэш восстанавливаются из AOF.
- Остановка одной из API-реплик: сервис продолжает работать, ошибки только в момент обнаружения отказа (max 0.046 сек).
- Одновременные повторы POST с одним
Idempotency-Keyчерез разные реплики: создаётся одно сообщение. - Недоступность Valkey или PostgreSQL:
/health/ready→ 503. - Истечение сессии по TTL: токен перестаёт работать.
- Гонка регистрации одинакового username: проходит только один запрос.
- Откат транзакции при ошибке вставки участника чата.
Что не выдерживается:
- Потеря Docker-хоста целиком: все контейнеры на одном узле.
- Потеря узла PostgreSQL: без репликации БД не выживет.
- Потеря узла Nginx: LB — SPOF.
- Rolling update на время перезапуска реплика недоступна.
Учебные упрощения:
- Все контейнеры на одном Docker-хосте.
- Nginx без активных healthcheck (только пассивные по
max_fails). - HTTP без TLS.
- Миграции не поддерживают rollback.
Idempotency-Keyзащищает только POST сообщений.
Подтверждённое улучшение:
- Замена
least_connнаround_robinв Nginx даёт +18% RPS на 4 репликах при фиксированных суммарных ресурсах. На 2 репликах разница незначима (−4%, в пределах шума). Saturation point — 2 реплики. При 4 репликах RPS падает из-за CPU starvation.