Files
mtusi2026lab3/REPORT.md
T

14 KiB
Raw Blame History

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

  • Автор, группа: Герейханов Ильяс, БВТ2301
  • Целевая оценка: 4
  • Commit/PR: ветка solution/bvt2301-Gereykhanov. PR: ЛР 3 — БВТ2301 — Герейханов — на 4
  • Использованные источники, библиотеки и помощь ИИ: Python 3.12, FastAPI, Uvicorn, PostgreSQL 16, Redis 7, Nginx 1.27, asyncpg, argon2-cffi, Pydantic, Pytest, Docker Compose; документация Nginx, RFC 7231, OpenAPI 3.1.0. ИИ использовался для подготовки скриптов, отладки конфигурации nginx и расширения тестов pytest.

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

  1. Версии runtime и базовых образов:

    • Локальный runtime: Linux, Docker 29.9.1, Docker Compose v5.6.0
    • Load Balancer: nginx:1.27-alpine
    • API контейнеры: python:3.12-slim
    • PostgreSQL: postgres:16-alpine
    • Redis: redis:7-alpine
  2. Подготовка окружения и запуск стека:

    git checkout solution/bvt2301-Gereykhanov
    cp .env.example .env
    
    # Сборка и запуск всех сервисов
    make up
    
  3. Ожидание готовности и запуск тестов:

    # Проверка структуры и синтаксиса
    make check
    
    # Проверка smoke теста
    make test
    
    # Проверка сценария сохранности данных и сессий при рестарте
    make test-persistence ACTION_SCRIPT=scripts/restart.sh
    
    # Проверка отказоустойчивости при отключении одной API-реплики
    make test-failover ACTION_SCRIPT=scripts/stop-one.sh
    
    # Восстановление остановленной реплики после теста
    docker compose up -d
    
    # Запуск собственных тестов
    .venv/bin/pytest tests_student
    
    # Запуск нагрузочного теста
    python3 tests/load.py --duration 10 --concurrency 4 --output evidence/load.json
    
  4. Остановка и очистка:

    # Остановка с сохранением данных volumes
    docker compose down
    
    # Остановка с удалением volumes
    docker compose down -v
    

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

  • Топология процессов и распределение ролей:
    • Клиент отправляет все HTTP-запросы в единую точку входа Nginx Load Balancer на порт 8080.
    • Nginx осуществляет Round-Robin балансировку между двумя независимыми репликами API.
    • Реплики API без портирования наружу хоста, не обходят балансировщик.
    • Каждая реплика API обращается к общему PostgreSQL (пользователи, чаты, сообщения, ключи идемпотентности) и общему Redis (хранилище сессий).
    • Есть отдельный одноразовый контейнер migration, применяющий init.sql перед стартом API-реплик.
  • Идентификация реплик (X-Instance-Id):
    • Каждая реплика API конфигурируется переменной окружения INSTANCE_ID (api-1 и api-2).
    • Middleware и глобальный обработчик ошибок возвращают заголовок X-Instance-Id в каждом HTTP ответе.
    • При последовательных запросах идет чередование инстансов api-1 и api-2.
  • Общие сессии без Sticky Sessions:
    • Токены Bearer-сессий хранятся в Redis с TTL (SESSION_TTL_SECONDS=3600) и сохраняются на redis_data через --appendonly yes.
    • Вход пользователя через одну реплику дает выполнять запросы через любую другую реплику без повторной аутентификации.
  • Идемпотентность отправки сообщений:
    • Заголовок Idempotency-Key обязателен для POST /api/v1/chats/{chat_id}/messages.
    • Область уникальности: (user_id, chat_id, idempotency_key).
    • В PostgreSQL создана таблица idempotency_keys с ограничением PRIMARY KEY (user_id, chat_id, idempotency_key).
    • В транзакции создания сообщения сохраняется хэш тела запроса (SHA-256 от нормализованного JSON).
    • При одновременных запросах с одним ключом в разные реплики ограничение PRIMARY KEY предотвращает вставку дубликата; проигравшая транзакция перехватывает UniqueViolationError и возвращает результат победителя.
  • Динамический DNS и быстрый Failover в Nginx:
    • Nginx настроен с внутренним Docker DNS-резолвером resolver 127.0.0.11 valid=2s ipv6=off; и зоной разделяемой памяти zone api_backend 64k;:
      upstream api_backend {
          zone api_backend 64k;
          server api-1:8080 resolve max_fails=1 fail_timeout=2s;
          server api-2:8080 resolve max_fails=1 fail_timeout=2s;
      }
      
      Параметр resolve динамически переопределяет IP-адреса реплик в runtime при пересоздании контейнеров без перезагрузки Nginx.
  • Ограничения ресурсов и масштабируемость:
    • Все сервисы с лимитамт CPU и RAM.
    • Для API-реплик не задаётся параметр container_name, чтобы не мешать масштабированию.

Доказательства критериев

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Проверка синтаксиса и контракта make check PASS: offline skeleton structure, local refs and Python syntax evidence/check_contract.log
Полная OpenAPI 3.1 валидация make validate PYTHON=.venv/bin/python PASS: full OpenAPI 3.1 and JSON Schema validation evidence/validate_openapi.log
Публичный smoke-сценарий make test PASS: lab3 public API scenario; infrastructure and grading evidence remain separate. evidence/smoke_test.log
Чередование реплик (LB) for i in {1..10}; do curl -sI http://localhost:8080/health/live | grep -i x-instance-id; done Попеременные ответы api-1 и api-2 (Round-Robin 50/50) evidence/round_robin.log
Сохранение данных и сессий при рестарте make test-persistence ACTION_SCRIPT=scripts/restart.sh Стек перезапущен, токен и сообщения сохранены evidence/persistence_test.log
Отказ API-реплики (Failover) make test-failover ACTION_SCRIPT=scripts/stop-one.sh Восстановление записи за 0.447 с, 0 потерь, дубликатов нет evidence/failover_test.log
Собственные расширенные тесты make test-student 26 тестов проходят: валидация Idempotency-Key, X-Instance-Id, ACL-инъекции, пагинация курсором evidence/student_tests.log
Статусы и лимиты контейнеров docker compose ps Все 5 сервисов запущены и healthy, API не светят порты на хост evidence/docker_services.log
Нагрузочный бенчмарк make load 337.1 RPS, p50 = 6.7 ms, p95 = 53.1 ms, p99 = 79.4 ms, 0 ошибок evidence/load.json

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

  • Профиль нагрузки: скрипт tests/load.py, закрытый цикл параллельных POST-запросов отправки сообщений с уникальными Idempotency-Key.
  • Параметры: длительность 10 секунд, 4 параллельных потока.
  • Результаты нагрузки (evidence/load.json):
    {
      "lab": 3,
      "workload": "closed-loop POST messages; no automatic retries",
      "requested_duration_seconds": 10.0,
      "elapsed_seconds": 10.065,
      "concurrency": 4,
      "successful_requests": 3393,
      "failed_requests": 0,
      "error_ratio": 0.0,
      "successful_rps": 337.112,
      "successful_latency_ms": {
        "p50": 6.724,
        "p95": 53.145,
        "p99": 79.35
      }
    }
    
Воздействие Что ожидаем Что наблюдали Время восстановления
Остановка одной реплики API (scripts/stop-one.sh) под нагрузкой Nginx переключает трафик на живую реплику; продолжение записи \le 10 с; отсутствие дубликатов 122 успешных записи во время остановки, 0 ошибок, переключение за 0.447 с 0.447 сек, потерь данных нет
Рестарт всего стека (scripts/restart.sh) при активной сессии Сохранение подтверждённых данных в Postgres и токенов сессий в Redis; восстановление API \le 90 с Контейнеры перезапущены, токен валиден, история сообщений сохранена Восстановление за 2.1 сек, потеря подтверждённых данных: 0
Повтор отправки сообщения с тем же Idempotency-Key и телом Возврат кода 201 и сохранённого сообщения без создания дубликата в БД 201 Created, ID и текст сообщения идентичны исходным Мгновенно, извлечение из таблицы idempotency_keys
Повтор сообщения с тем же Idempotency-Key, но изменённым текстом Отклонение запроса с конфликтом 409 Conflict Мгновенно, защита целостности данных
Повтор сообщения с тем же ключом после удаления пользователя из чата Проверка прав доступа перед возвратом кэшированного ответа 404 Not Found Проверка ACL выполняется до чтения кэша идемпотентности
Пересоздание контейнера с новым IP (docker compose up -d --force-recreate api-1) Nginx динамически обновляет IP в runtime без ручного reload Nginx переопределяет IP через Docker DNS 127.0.0.11 за 2 с и продолжает балансировку До 2 секунд

Ограничения

  • Какие отказы выдерживаются и какие нет:
    1. Выдерживаются:
      • Внезапная остановка любой одной API-реплики под нагрузкой: балансировщик Nginx переключает входящие запросы на оставшуюся работоспособную реплику за <0.5 секунды без потери данных и дубликатов.
      • Полный рестарт стека: все подтверждённые данные и активные Bearer-токены сохраняются благодаря volumes pg_data и redis_data
      • Конкурентная отправка сообщений с одинаковым Idempotency-Key в разные реплики: ограничение в базе гарантирует, что будет создана ровно одна запись, а проигравшая гонку реплика вернёт созданное сообщение.
      • Пересоздание контейнеров со сменой IP: встроенный Docker DNS-резолвер Nginx автоматически обновляет адреса в shared memory zone за 2 секунды.
    2. Не выдерживаются:
      • Одновременное падение обеих API-реплик (клиент получает HTTP 502 Bad Gateway от Nginx).
      • Падение единственного экземпляра PostgreSQL или Redis.
      • Удаление Docker volumes через docker compose down -v.
  • Учебные упрощения:
    1. Nginx, PostgreSQL и Redis запущены в единственном экземпляре без кластеризации и репликации.
    2. Ключи идемпотентности сохраняются в БД бессрочно.
  • Следующий шаг (Лаба 4):
    • Подключение S3-совместимого хранилища (MinIO) для бинарных вложений к сообщениям чата и разграничение доступа к файлам по presigned URLs.