18 KiB
Отчёт — лабораторная 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. Команды выполняются из корня репозитория. Стенд предназначен только для локальных синтетических данных.
- Создать
.envи задать уникальный локальный пароль PostgreSQL:cp .env.example .env - Проверить структуру и конфигурацию:
make check pip install -r requirements-dev.txt make validate docker compose --env-file .env config --quiet - Собрать образы и запустить две API-реплики за HAProxy:
docker compose --env-file .env up -d --build --scale api=2migrateзапускается однократно после готовности PostgreSQL и до API. Проверитьdocker compose --env-file .env psиcurl -i http://localhost:8080/health/ready. - Проверить контракт и общую идемпотентность:
make test python tests/grade4_checks.py - Проверить сохранность состояния и отказ реплик (только на тестовом стенде):
Failover-тест оставляет одну реплику остановленной. Восстановить желаемые две реплики:
make test-persistence ACTION_SCRIPT=scripts/restart.sh make test-failover ACTION_SCRIPT=scripts/stop-one.shdocker compose --env-file .env up -d --scale api=2 api. Проверить отказ для каждой реплики отдельно, каждый раз восстанавливая предыдущую. - Нагрузка и поочерёдная замена:
Сохранить фактические параметры и JSON-нагрузку в
make load # В отдельном терминале можно запустить `bash scripts/rolling-restart.sh` (проверка того, что апи-реплики могут перезапускаться по отдельности без изменения, не останавливая всё приложение. Это проверка отказоустойчивости, балансировщик должен перенаправлять запросы на доступную реплику, пока другая перезапускается)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 с, Composestop_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 и сохранить журнал.