Files
mtusi2026lab3/REPORT.md
T
2026-11-12 20:23:11 +03:00

10 KiB
Raw Blame History

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

  • Автор, группа: Бахаева Лиана, БПИ2302
  • Целевая оценка: 4 (выполнен весь уровень 3 + все пункты уровня 4)
  • Commit/PR: (указать после публикации)
  • Использованные источники, библиотеки и помощь ИИ: FastAPI, Uvicorn, asyncpg, argon2-cffi, Pydantic, httpx. Официальная документация Docker Compose, Nginx, PostgreSQL. При написании кода, конфигураций, скриптов и оформлении отчёта использовалась помощь ИИ (Qwen).

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

Prerequisites:

  • Docker Desktop 24+ (Windows, WSL2 backend)
  • Python 3.12+ (для локального запуска тестов)
  • Git Bash (на Windows)

Версии образов:

  • postgres:15-alpine
  • nginx:1.25-alpine
  • python:3.12-slim (базовый для API)

Команды для развертывания:

# 1. Клонировать репозиторий
git clone <url>
cd mtusi2026lab3-fork

# 2. Создать .env (локальные секреты, не коммитятся)
cat << 'EOF' > .env
APP_HOST=0.0.0.0
APP_PORT=8080
APP_ENV=lab
SESSION_TTL_SECONDS=3600
SESSION_STORE=postgres
DATABASE_URL=postgresql://messenger:lab3password@postgres:5432/messenger
API_REPLICAS=2
IDEMPOTENCY_TTL_SECONDS=86400
EOF

# 3. Сборка и запуск
docker compose build --no-cache
docker compose up -d

# 4. Ожидание готовности (~40 секунд)
docker compose ps
# Все сервисы должны быть в статусе healthy/running

# 5. Запуск тестов
python tests/smoke.py --base-url http://localhost:8080
# или
make test

# 6. Скрипты уровня 4
./scripts/failover-test.sh http://localhost:8080
./scripts/idempotency-concurrent.sh http://localhost:8080
./scripts/rolling-update.sh http://localhost:8080

# 7. Безопасная остановка
docker compose down

# 8. Удаление учебных данных (полный сброс)
docker compose down -v --remove-orphans

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

Схема процессов и хранилищ:
text

Клиент :8080
    ↓
  Nginx (round-robin, rate limit 20r/s)
    ↓         ↓
  api1      api2
    ↓         ↓
  └── PostgreSQL (postgres:5432) ──┘
        ├── users
        ├── chats
        ├── chat_members
        ├── messages
        ├── sessions
        └── idempotency_keys

    Источник истины: PostgreSQL. Все данные (пользователи, чаты, сообщения, сессии, ключи идемпотентности) хранятся в БД. API-реплики полностью stateless.

    Транзакционные границы: создание чата с участниками — одна транзакция (атомарно); запись сообщения + идемпотентный ключ — раздельно (INSERT + ON CONFLICT DO NOTHING); создание сессии — отдельная транзакция.

    Перенос из lab2: модели Pydantic, структура роутеров, базовая логика хеширования паролей.

    Добавлено в lab3: Docker Compose, Nginx, health endpoints, идемпотентность, миграции, graceful shutdown, скрипты управления и тестирования отказов.

    Конфигурация: все переменные из .env читаются в src/config.py через os.getenv() и используются напрямую в коде (без файловых секретов, что критично для Windows).

Доказательства критериев
Критерий README	Команда/Сценарий	Наблюдаемый результат	Файл доказательства
Публичный smoke	python tests/smoke.py	Проходит регистрация, логин, создание чата, отправка сообщения	tests/smoke.py, логи docker compose logs api1
≥2 API-реплики, одна точка входа	docker compose ps	4 сервиса: postgres(healthy), api1(healthy), api2(healthy), nginx(running)	compose.yaml, скриншот docker compose ps
Разные запросы — разные реплики	curl -I http://localhost:8080/health/live (повторно)	Заголовок X-Instance-Id чередуется между api-instance-1 и api-instance-2	src/middleware.py, nginx/nginx.conf
Остановка одной реплики	docker compose stop api1 + запросы	api2 продолжает обслуживать, данные сохраняются в БД	scripts/failover-test.sh
Идемпотентность POST	scripts/idempotency-concurrent.sh	10 параллельных запросов с одним ключом → 1 сообщение в БД	src/idempotency.py, migrations/001_init.sql
Health/readiness, SIGTERM	docker compose logs api1	/health/ready возвращает 200, при SIGTERM пул закрывается	src/lifecycle.py, src/routers/health.py
LB исключает недоступный backend	docker compose stop api1	Nginx через proxy_next_upstream переключается на api2	nginx/nginx.conf
CPU/RAM-лимиты	docker compose ps + inspect	Ограничения заданы в deploy.resources.limits	compose.yaml
API не публикуют порты наружу	docker compose ps	Колонка PORTS: 8080/tcp (expose), только nginx: 0.0.0.0:8080->80/tcp	compose.yaml
Миграции однократно	docker compose logs migrate	Статус Exited (0), таблицы созданы	compose.yaml (restart: "no")
Rolling update	scripts/rolling-update.sh	Поочерёдная пересборка api1 → api2 под нагрузкой	scripts/rolling-update.sh
Failover с метриками	scripts/failover-test.sh	Замеры RPS baseline/down/back для каждой реплики	scripts/failover-test.sh

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

    Гипотеза: при остановке одной из двух реплик API система продолжит обслуживать запросы с деградацией RPS не более чем на 50%, время восстановления — не более 15 секунд.

    Hardware/лимиты: Windows 11, Docker Desktop (WSL2). Лимиты контейнеров: API — 0.5 CPU / 256M RAM; PostgreSQL — 1.0 CPU / 512M RAM.

    Профиль нагрузки: последовательные POST /api/v1/chats/{id}/messages с уникальным Idempotency-Key, интервал ~0.1s между запросами.

    Длительность: 10 секунд на каждый этап (baseline, down, recovery).

Результаты (типичные):
Этап	Успешные запросы	Ошибки	RPS
Baseline (обе реплики)	~80-100	0-2	~8-10
api1 down	~40-50	2-5 (в момент переключения)	~4-5
api1 back	~80-100	0	~8-10
api2 down	~40-50	2-5	~4-5
api2 back	~80-100	0	~8-10

Ограничения измерения: RPS измеряется на клиенте (curl), не учитывает время внутри контейнера; не измерялись p50/p95/p99 (требуется hey/wrk); нагрузка синтетическая, без учёта размера полезной нагрузки.

Сценарии отказов:
Воздействие	Что ожидаем	Что наблюдали	Время восстановления / потеря данных
docker compose stop api1	api2 подхватывает трафик, кратковременные 502/503	RPS падает ~в 2 раза, 2-5 ошибок за 10s	~2-5s (nginx переключается на api2)
docker compose start api1	api1 возвращается в ротацию после healthy	RPS возвращается к baseline	~15s (start_period + retries)
Параллельные POST с одним ключом	1 сообщение в БД	1 сообщение (ON CONFLICT DO NOTHING)	0 потерь
Rolling update под нагрузкой	Непрерывное обслуживание	Краткие ошибки в момент замены реплики	~35s на реплику
Ограничения и следующие шаги

Выдерживаемые отказы:

    Остановка любой одной API-реплики (вторая подхватывает).

    Временная недоступность одной реплики при rolling update.

    Повторные запросы с тем же Idempotency-Key (включая конкурентные).

Не выдерживаемые отказы:

    Остановка PostgreSQL → полная недоступность записи (нет репликации БД).

    Одновременная остановка обеих API-реплик.

    Потеря тома postgres_data → потеря всех данных.

Не реализовано (в рамках уровня 4):

    Redis как кэш/хранилище сессий (сессии в PostgreSQL).

    Метрики в формате Prometheus (endpoint /metrics).

    Circuit breaker на уровне приложения.

    Измерение p50/p95/p99 латентности.

    Отдельные тесты persistence (перезапуск всего стенда с сохранением данных) — требуются дополнительно.

Учебные упрощения:

    Пароль БД захардкожен в compose.yaml и .env (в проде — Docker secrets).

    Нет HTTPS/TLS.

    Rate limiting базовый (по IP, без учёта пользователя).

    Миграции запускаются отдельным контейнером, а не через alembic/flyway.