Files
mtusi2026lab4/REPORT.md
T

17 KiB
Raw Blame History

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

  • Автор, группа: Герейханов Ильяс, БВТ2301
  • Целевая оценка: 4
  • Commit/PR: ветка solution/bvt2301-Gereykhanov. PR: ЛР 4 — БВТ2301 — Герейханов — на 4
  • Использованные источники, библиотеки и помощь ИИ: Python 3.12, FastAPI, Uvicorn, PostgreSQL 16, Redis 7, Nginx 1.27, MinIO, boto3, Pillow, asyncpg, argon2-cffi, Pydantic, Pytest, Docker Compose; документация AWS S3 API, 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
    • S3-совместимое хранилище: cleanstart/minio:0.20260330.001845
  2. Подготовка окружения и запуск стека:

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

    # Проверка структуры и синтаксиса
    make check
    
    # Валидация схемы OpenAPI
    make validate PYTHON=.venv/bin/python
    
    # Проверка 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
    
    # Запуск собственных тестов
    make test-student
    
    # Запуск нагрузочного теста
    python3 tests/load.py --duration 30 --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-1 и api-2).
    • Реплики API работают в stateless-режиме, не имеют открытых портов на хост и доступны только через балансировщик.
    • Каждая реплика API обращается к общему PostgreSQL, Redis и MinIO S3.
    • Отдельный одноразовый контейнер migration применяет init.sql перед стартом API-реплик.
  • Хранилища данных и источник истины:

    • PostgreSQL: источник истины для реляционных данных пользователей, чатов, сообщений и метаданных вложений в таблице attachments (id, chat_id, owner_id, filename, content_type, size_bytes, sha256, s3_key, status, error_code, created_at, updated_at).
    • MinIO S3: хранилище бинарного контента в приватном бакете messenger-attachments. Ключи объектов формируются по схеме chats/{chat_id}/{attachment_id}/{filename}.
    • Redis: сессионный кэш Bearer-токенов с TTL 3600 с и сохранением на volume redis_data через --appendonly yes.
  • Что перенесено из лабы 3:

    • Балансировщик Nginx с Round-robin 50/50 и proxy_next_upstream для быстрого переключения при сбое.
    • Сквозные заголовки X-Request-Id и X-Instance-Id в ответах API.
    • Единое хранилище сессий в Redis.
    • Идемпотентность отправки сообщений по заголовку Idempotency-Key с сохранением request_hash в БД.
    • Keyset-пагинация сообщений по индексу.
  • Интеграция S3 и изоляция сети:

    • MinIO включен во внутреннюю Docker-сеть с постоянным volume minio_data.
    • Порты MinIO не проброшены на хост наружу, консоль закрыта от общей сети.
    • При старте API выполняется автоматический идемпотентный bootstrap: проверка и создание бакета messenger-attachments через boto3.
  • Загрузка, валидация и защита от атак:

    • Эндпоинт POST /api/v1/chats/{chat_id}/attachments?filename=... принимает сырое бинарное тело (PNG/JPEG) до 10 MiB.
    • Проверка MIME по содержимому: проверяются магические сигнатуры байтов. Невалидные форматы отклоняются с кодом 415.
    • Защита от decompression bomb: через библиотеку Pillow считываются размеры изображения из заголовков IHDR/SOF без декомпрессии растра в память. Превышение лимита 40 млн пикселей возвращает 413 payload_too_large.
    • Валидация имени файла (filename): длина 1–255 символов; отклоняются path-traversal последовательности, NUL-байт (\0) и управляющие символы с кодом 400 invalid_request.
  • Компенсация сиротских объектов и прямой download:

    • Файл сначала сохраняется в S3 через boto3.put_object, после чего выполняется запись метаданных в базу. При ошибке в БД блок except вызывает s3_client.delete_object, удаляя объект из S3.
    • Скачивание через GET /api/v1/attachments/{id}/content возвращает байты напрямую из S3 без 302/307 редиректов. Запрос от постороннего возвращает строго 404 not_found.
  • Связывание с сообщениями и настройки Nginx:

    • В таблицу messages добавлено поле attachment_ids UUID[].
    • Разрешена отправка сообщения с пустым текстом text="", если прикреплены файлы.
    • В infra/nginx.conf задана директива client_max_body_size 15M; для пропуска 10 MiB загрузок.
    • Все параметры согласованы с .env.example: S3_ENDPOINT, S3_BUCKET, MAX_UPLOAD_BYTES, MAX_IMAGE_PIXELS.

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

Критерий 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: lab4 public API scenario evidence/smoke_test.log
Чередование реплик for i in {1..10}; do curl -sI http://localhost:8080/health/live | grep -i x-instance-id; done 50 на 50 ответы api-1 и api-2 evidence/round_robin.log
Сохранение данных и сессий при рестарте make test-persistence ACTION_SCRIPT=scripts/restart.sh Стек перезапущен, токен, сообщения и вложения в S3 сохранены evidence/persistence_test.log
Отказ API-реплики под нагрузкой make test-failover ACTION_SCRIPT=scripts/stop-one.sh Восстановление записи за 0.778 с, 105 успешных запросов, 0 сбоев evidence/failover_test.log
Защита от decompression bomb (>40M px) make test-student Запрос с 50M px изображением отклонен с 413 payload_too_large evidence/student_tests.log
Проверка MIME по магическим байтам make test-student Поддельные и поврежденные изображения отклоняются с 415 evidence/student_tests.log
Компенсация сирот S3 при отказе БД make test-student При сбое PostgreSQL объект удаляется из S3, в хранилище нет сирот evidence/student_tests.log
Закрытый бакет и лимит RAM (10 загрузок) make test-student Порт 9000 закрыт снаружи, 10 параллельных загрузок успешны, RAM стабильна evidence/student_tests.log
Собственные тесты make test-student 34 теста проходят: валидация вложений, компенсация S3, курсор, идемпотентность evidence/student_tests.log
Статусы и изоляция контейнеров docker compose ps Все 6 сервисов healthy, API и MinIO не открывают порты на хост evidence/docker_services.log
Нагрузочный тест make load 309.4 RPS, p50 = 7.9 ms, p95 = 40.8 ms, p99 = 63.0 ms, 0 ошибок evidence/load.json

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

  • Профиль нагрузки: скрипт tests/load.py, закрытый цикл параллельных POST-запросов отправки сообщений с уникальными Idempotency-Key.
  • Параметры: длительность 30 секунд, 4 параллельных потока.
  • Результаты нагрузки (evidence/load.json):
    {
      "lab": 4,
      "workload": "closed-loop POST messages; no automatic retries",
      "requested_duration_seconds": 30.0,
      "elapsed_seconds": 30.015,
      "concurrency": 4,
      "successful_requests": 9286,
      "failed_requests": 0,
      "error_ratio": 0.0,
      "successful_rps": 309.375,
      "successful_latency_ms": {
        "p50": 7.928,
        "p95": 40.768,
        "p99": 62.963
      }
    }
    
Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
Остановка одной реплики API (scripts/stop-one.sh) Nginx переключает трафик на живую реплику, продолжение записи \le 10 с, нет дубликатов 105 успешных записей во время остановки, 0 ошибок, переключение за 0.778 с 0.778 сек, потерь данных нет
Рестарт всего стека (scripts/restart.sh) при активной сессии Сохранение подтверждённых данных в Postgres, токенов сессий в Redis и файлов в MinIO Контейнеры перезапущены, токен валиден, история сообщений и файлы сохранены Восстановление около 5 сек, потеря подтверждённых данных: 0
Загрузка декомпрессионной бомбы (изображение 10000x5000) Отклонение запроса с кодом 413 payload_too_large без исчерпания RAM Запрос отклонен мгновенно по метаданным IHDR без распаковки растра Мгновенно (< 2 мс)
Загрузка файла размером более 10 MiB Отклонение запроса с кодом 413 payload_too_large Запрос отклонен до сохранения в S3 Мгновенно
Попытка загрузки файла с поддельным расширением Отклонение с кодом 415 unsupported_media_type Проверка сигнатуры байтов выявляет подмену и возвращает 415 Мгновенно
Попытка доступа к метаданным или контенту посторонним пользователем Защита приватности: возврат строго 404 Not Found без утечки факта существования файла Посторонний получает 404 на GET /attachments/{id} и /content Мгновенно
Попытка передачи опасного имени файла Отклонение запроса с кодом 400 invalid_request Валидатор отклоняет некорректное имя до обращения к хранилищу Мгновенно
Сбой сохранения метаданных в БД после успешного PUT в S3 Автоматическое удаление объекта из S3 В S3 не остается мусорных файлов Мгновенно
Конкурентная загрузка ≥10 файлов с контролем RAM Все файлы сохраняются в S3, память API стабильна 10 параллельных загрузок вернули 201 ready, утечек памяти нет Мгновенно (< 1 с)
Попытка прямого обращения к MinIO на порт 9000 с хоста Соединение отклоняется (Connection Refused), консоль закрыта Порты MinIO не проброшены наружу, прямой доступ невозможен Мгновенно

Ограничения

  • Какие отказы выдерживаются и какие нет:
    1. Выдерживаются:
      • Внезапная остановка любой одной API-реплики под нагрузкой: балансировщик Nginx переключает входящие запросы на оставшуюся реплику.
      • Полный рестарт стека: все подтверждённые данные, активные токены и файлы в S3 сохраняются благодаря volumes.
      • Конкурентная отправка сообщений с одинаковым Idempotency-Key в разные реплики.
      • Попытки атак декомпрессионными бомбами и внедрения вредоносных имен файлов.
      • Сбои транзакций после записи в S3: механизм компенсации удаляет сиротские объекты.
    2. Не выдерживаются:
      • Одновременное падение обеих API-реплик (HTTP 502 Bad Gateway).
      • Падение единственного экземпляра PostgreSQL, Redis или MinIO.
      • Удаление через docker compose down -v.
  • Учебные упрощения:
    1. Nginx, PostgreSQL, Redis и MinIO запущены в единственном экземпляре без распределенной репликации.
    2. Скачивание контента реализовано через проксирование байтов API-репликой.