Files
mtusi2026lab3-fork/REPORT1.md
T
2026-10-27 14:00:48 +03:00

18 KiB
Raw Blame History

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

  • Автор, группа: Миронов Алексей, бвт2302
  • Целевая оценка: 4; трек 5 не заявлен
  • Commit/PR: 1b476ee, mtusi2026/mtusi2026lab3#56
  • Использованные источники, библиотеки и помощь ИИ: исходный репозиторий лабораторной 3 и его COURSE.md, README.md, contracts/README.md, contracts/openapi.json, tests/; перенесённая собственная реализация лабораторной 2; FastAPI, Pydantic, psycopg/psycopg-pool, PostgreSQL, Redis, Argon2, HAProxy, Docker Compose; использовалась помощь ИИ.

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

Требуются Docker Engine с Compose v2 и GNU Make. Команды выполняются из корня репозитория. Стенд предназначен только для локальных синтетических данных.

  1. Создать .env и задать уникальный локальный пароль PostgreSQL:
    cp .env.example .env
    
  2. Проверить структуру и конфигурацию:
    make check
    pip install -r requirements-dev.txt
    make validate
    docker compose --env-file .env config --quiet
    
  3. Собрать образы и запустить две API-реплики за HAProxy:
    docker compose --env-file .env up -d --build --scale api=2
    
    migrate запускается однократно после готовности PostgreSQL и до API. Проверить docker compose --env-file .env ps и curl -i http://localhost:8080/health/ready.
  4. Проверить контракт и общую идемпотентность:
    make test
    python tests/grade4_checks.py
    
  5. Проверить сохранность состояния и отказ реплик (только на тестовом стенде):
    make test-persistence ACTION_SCRIPT=scripts/restart.sh
    make test-failover ACTION_SCRIPT=scripts/stop-one.sh
    
    Failover-тест оставляет одну реплику остановленной. Восстановить желаемые две реплики: docker compose --env-file .env up -d --scale api=2 api. Проверить отказ для каждой реплики отдельно, каждый раз восстанавливая предыдущую.
  6. Нагрузка и поочерёдная замена:
    make load
    # В отдельном терминале можно запустить `bash scripts/rolling-restart.sh`
    (проверка того, что апи-реплики могут перезапускаться по отдельности без изменения, не останавливая всё приложение. Это проверка отказоустойчивости, балансировщик должен перенаправлять запросы на доступную реплику, пока другая перезапускается)
    
    Сохранить фактические параметры и JSON-нагрузку в evidence/. Команды ожидания готовности и остановки: docker compose --env-file .env down (volumes сохраняются); для намеренного удаления учебных данных использовать docker compose --env-file .env down -v только после явного решения удалить БД и Redis.

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

Клиент → HAProxy → две и более взаимозаменяемые FastAPI-реплики → общая PostgreSQL и общий Redis. В Compose наружу опубликован только HAProxy на 127.0.0.1:8080; API-реплики доступны лишь во внутренней сети. HAProxy опрашивает /health/ready, исключает backend после неуспешных проверок и повторно включает после восстановления. Период проверки — 1 с; исключение после двух ошибок ожидается примерно за 2 с плюс timeout/расписание проверок, фактическое время необходимо измерить.

  • Перенос из lab2: src/main.py, базовая SQL-схема пользователей/чатов/участников/сообщений, Redis-сессии, Argon2, пагинация и формат ошибок перенесены. Также перенесены зависимости, examples/requests.http, .gitignore и scripts/restart.sh. В REPORT1.md явно фиксируется этот перенос.
  • Изменения lab3: добавлен X-Instance-Id (hostname контейнера, стабильный в пределах его жизни), обязательный Idempotency-Key при POST сообщения и таблица idempotency_records. Тело запроса нормализуется перед SHA-256; транзакционная advisory lock сериализует одинаковый ключ на всех репликах; запись сообщения и сохранённого ответа выполняется в одной транзакции PostgreSQL. Идентичный повтор в течение 24 часов возвращает исходный 201 и то же сообщение; другой body при том же ключе получает 409.
  • Миграции: scripts/migrate.py — отдельный одноразовый Compose-сервис, применяющий миграции в порядке имени и записывающий версии в schema_migrations. API-реплики не пытаются одновременно менять схему при старте.
  • Сессии: остаются в Redis, который использует AOF и именованный volume; PostgreSQL — источник истины для бизнес-данных и идемпотентности.
  • Health/shutdown: /health/live проверяет процесс, /health/ready проверяет PostgreSQL и Redis. Uvicorn получает SIGTERM, graceful timeout — 10 с, Compose stop_grace_period — 15 с.
  • Ресурсы: Compose задаёт CPU/RAM limits для API, PostgreSQL, Redis и HAProxy. Это ограничения на одном Docker-host, не гарантия доступности при потере хоста.
  • Секреты: .env игнорируется Git и не копируется в образ.

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

Критерий Команда/сценарий Фактический результат Источник
Структура проекта и синтаксис make check PASS: проверка офлайн-структуры, локальных ссылок и синтаксиса Python. В выводе отдельно указано, что приложение этим тестом не проверялось. evidence.txt
OpenAPI и JSON Schema make validate PASS: полная валидация OpenAPI 3.1 и JSON Schema. В выводе отдельно указано, что приложение этим тестом не проверялось. evidence.txt
Конфигурация Docker Compose docker compose --env-file .env config --quiet Команда завершилась без диагностического вывода. Отдельный код завершения в предоставленном фрагменте не зафиксирован. evidence.txt
Сквозной публичный API make test PASS: lab3 public API scenario. evidence.txt
Две разные API-реплики и конкурентная идемпотентность python3 tests/grade4_checks.py PASS: наблюдались две разные реплики (21d7ab63f9dc, 3c995d3af7ef); 12 параллельных запросов дали один уникальный ID сообщения; изменённое тело с тем же ключом вернуло HTTP 409; отсутствующий и некорректный ключи вернули HTTP 400. evidence.txt
Сохранность данных и сессии после перезапуска make test-persistence ACTION_SCRIPT=./scripts/restart.sh PASS: подтверждённые данные и существующая сессия сохранены. Вывод содержит предупреждение: Hook scope needs operator evidence; область действия hook требует отдельного подтверждения оператором. evidence.txt
Failover одной API-реплики make test-failover ACTION_SCRIPT=./scripts/stop-one.sh PASS: до отказа наблюдались 2 экземпляра; зафиксировано 73 успешные записи, 1 неудачная попытка и 3,223 секунды до первой успешной записи после восстановления. Подтверждена сохранность данных и сессии. В предоставленном результате не указано, что проверка отдельно повторялась для каждой реплики. evidence.txt
Нагрузка без перезапуска make load PASS: 30,088 с; concurrency=4; 1528 успешных запросов, 0 неудачных; error ratio 0; 50,785 успешного запроса/с; p50=64,545 мс, p95=192,316 мс, p99=258,186 мс. Процентили рассчитаны только по успешным запросам. evidence.txt
Rolling restart bash scripts/rolling-restart.sh PASS: скрипт завершился сообщением rolling restart completed with 2 healthy API replicas. evidence.txt
Нагрузка во время rolling restart make load, выполнявшийся параллельно с rolling restart Выполнено, но не без ошибок: 30,128 с; concurrency=4; 1839 успешных запросов и 9 неудачных; error ratio=0,00487 (около 0,487%); 61,039 успешного запроса/с; p50=33,306 мс, p95=97,359 мс, p99=163,583 мс. Типы этих 9 ошибок в приведённом JSON не указаны. evidence.txt

|

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

В качестве доказательств используются только результаты из evidence.txt. Метрики нагрузки получены закрытым циклом POST-запросов к сообщениям, с concurrency=4, длительностью около 30 секунд и без автоматических повторов. В выводе теста отдельно отмечено, что процентили задержки учитывают только успешные запросы, а closed-loop профиль подвержен coordinated omission и накладным расходам клиента. Поэтому значения характеризуют именно этот тестовый профиль и не являются универсальной оценкой пропускной способности сервиса.

OS: Майкрософт Windows 11 Pro 10.0.22631 (build 22631) CPU: Intel(R) Core(TM) i5-8350U CPU @ 1.70GHz, cores=4, threads=8 RAM: 15.9 GB Docker Compose version v2.32.4-desktop.1 docker version Client: Version: 27.5.1 API version: 1.47 Go version: go1.22.11 Git commit: 9f9e405 Built: Wed Jan 22 13:41:44 2025 OS/Arch: windows/amd64 Context: desktop-linux Server: Docker Desktop 4.38.0 (181591) Engine: Version: 27.5.1 API version: 1.47 (minimum version 1.24) Go version: go1.22.11 Git commit: 4c9b3b0 Built: Wed Jan 22 13:41:17 2025 OS/Arch: linux/amd64 Experimental: false containerd: Version: 1.7.25 GitCommit: bcc810d6b9066471b0b6fa75f557a15a1cbf31bb runc: Version: 1.1.12 GitCommit: v1.1.12-0-g51d5e946 docker-init: Version: 0.19.0 GitCommit: de40ad0

Сводка нагрузочных прогонов

Сценарий Длительность Успешные Ошибки Error ratio Успешных запросов/с p50 p95 p99
Обычная нагрузка 30,088 с 1528 0 0% 50,785 64,545 мс 192,316 мс 258,186 мс
Нагрузка во время rolling restart 30,128 с 1839 9 0,487% 61,039 33,306 мс 97,359 мс 163,583 мс

Успешные RPS и задержки различаются между двумя прогонами; на основании только этих двух запусков нельзя заключать, что rolling restart сам по себе повышает производительность. Во время параллельного прогона было 9 ошибок, поэтому результат не подтверждает полностью безошибочную доступность при замене реплик. Предоставленный JSON не содержит классификации ошибок, поэтому их HTTP-коды и причины здесь не приписываются.

Проверки идемпотентности и отказоустойчивости

Воздействие Наблюдение из evidence.txt Вывод и ограничение
12 параллельных запросов с одинаковым ключом Обнаружены две разные реплики; все параллельные повторы дали один уникальный ID сообщения. Подтверждена конкурентная идемпотентность между наблюдавшимися репликами в этом сценарии.
Тот же ключ с изменённым телом HTTP 409. Конфликт при повторном использовании ключа с другим телом подтверждён.
Отсутствующий или некорректный ключ HTTP 400 в обоих случаях. Валидация ключа подтверждена для этих случаев.
Перезапуск с проверкой сохранности Подтверждённые данные и существующая сессия сохранились. Тест завершился PASS; при этом вывод просит дополнительное операторское подтверждение области действия hook.
Остановка одной API-реплики 73 успешные записи, 1 неудачная попытка, первая успешная запись после восстановления через 3,223 с; данные и сессия сохранены. Failover-сценарий завершился PASS, но переход не был полностью безошибочным. Предоставленный результат не доказывает отдельную проверку каждой реплики.
Rolling restart без параллельной нагрузки Скрипт завершился с двумя здоровыми API-репликами. Завершение скрипта и конечное состояние подтверждены; это само по себе не означает нулевых ошибок во время замены.
Rolling restart под нагрузкой 1839 успешных запросов, 9 ошибок за 30,128 с. Нагрузка продолжалась, но были ошибки. Их тип и временное распределение в предоставленном JSON не указаны.

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

  • Реализована репликация процесса API на одном Docker-host. Потеря хоста, единственного HAProxy, PostgreSQL или Redis не переживается; автоматическая HA для этих компонентов отсутствует.
  • HAProxy health checks и Docker health checks имеют ограниченную периодичность; краткие ошибки во время обнаружения отказа возможны и должны измеряться.
  • Идемпотентность ограничена текущим API POST сообщений, scope — пользователь + чат/путь + ключ, срок — 24 часа. Ключи старше 24 часов могут быть использованы повторно.
  • Redis AOF appendfsync everysec не равен синхронной репликации/резервному копированию.
  • scripts/rolling-restart.sh выполняет поочерёдную замену контейнеров в Compose как упражнение rolling restart; он не является автоматическим blue/green deployment с гарантированным обновлением версии приложения. Проверить поведение в целевой версии Compose и сохранить журнал.