Files
mtusi2026lab3/REPORT.md
T
2026-10-15 00:18:02 +03:00

12 KiB
Raw Blame History

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

  • Автор, группа: Станислав Травкин, БВТ2304
  • Целевая оценка: 5, выполнение по этапам 3 → 4 → 5
  • Выбранный трек оценки 5: цена масштабирования
  • Commit/PR: будет указан после публикации
  • Использованные источники: документация Docker Compose, FastAPI, SQLAlchemy, Alembic, PostgreSQL, Redis, Nginx; материалы лабораторной работы
  • Помощь ИИ: ChatGPT использовался для обсуждения архитектуры, разработки, отладки и подготовки документации

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

Для запуска необходимы Docker Engine с поддержкой Docker Compose, Git и Python 3.9 или новее.

Приложение работает в контейнерах. Локальная установка PostgreSQL и Redis не требуется.

Используемые образы:

  • Python 3.13.15-slim
  • PostgreSQL 17.6
  • Redis 8.2.2
  • Nginx 1.29-alpine

Из корневого каталога проекта выполнить:

./scripts/bootstrap.sh
docker compose config --quiet
docker compose up -d --build
docker compose ps -a

Скрипт bootstrap.sh создаёт локальные файлы секретов, если они отсутствуют, и проверяет конфигурацию Compose. Значения существующих секретов не перезаписываются.

Используются файлы:

  • secrets/postgres_password — пароль PostgreSQL
  • secrets/database_url — строка подключения к PostgreSQL
  • secrets/cache_url — строка подключения к Redis

Секреты не должны попадать в Git.

Миграции Alembic выполняются отдельным сервисом migrate перед запуском API. Успешное завершение этого контейнера отображается как Exited (0).

После запуска обе API-реплики должны иметь статус healthy, PostgreSQL и Redis — healthy, Nginx — Up.

Единая точка входа:

http://localhost:8080

Проверки:

make check
make validate
make test
make test-persistence ACTION_SCRIPT=./scripts/restart.sh
make test-failover ACTION_SCRIPT=./scripts/stop-one.sh
python3 tests/test_concurrent_idempotency.py

Для локальных Python-проверок требуется установить зависимости из requirements-dev.txt, если они ещё не установлены.

После failover-теста восстановить реплики:

docker compose start api-1 api-2

Безопасная остановка стенда с сохранением данных:

docker compose down

Повторный запуск:

docker compose up -d --build

Для намеренного удаления учебных данных и постоянных Docker volumes используется:

docker compose down -v

Последняя команда удаляет данные PostgreSQL и Redis и не применяется при обычном перезапуске.

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

Используется Docker Compose со следующими компонентами:

Client
  |
  v
Nginx :8080
  |
  +---- API-1 :8080
  |
  +---- API-2 :8080
           |
           +---- PostgreSQL
           |
           +---- Redis

Nginx является единой публичной точкой входа. API-реплики не публикуют порты на хосте и доступны через внутреннюю сеть Compose.

Обе реплики используют одну PostgreSQL и один Redis.

PostgreSQL хранит постоянные данные приложения и информацию, необходимую для общей идемпотентности отправки сообщений. Redis хранит пользовательские сессии с TTL 3600 секунд.

В API не используются локальные пользовательские сессии, поэтому запросы одного пользователя могут обслуживаться разными репликами без повторной авторизации.

Каждая реплика возвращает заголовок X-Instance-Id, позволяющий определить обработавший запрос экземпляр.

Для отправки сообщений используется обязательный Idempotency-Key. Повторная отправка с тем же ключом не должна создавать второе сообщение. Согласованность между репликами обеспечивается общим PostgreSQL и транзакционным механизмом идемпотентности.

Миграции выполняются отдельным контейнером, что исключает одновременный запуск Alembic несколькими API-репликами.

В Nginx настроены два backend-сервера, таймауты подключения и обработки запросов, а также повторная попытка при отдельных ошибках upstream.

Из лабораторной 2 перенесены основная реализация API, PostgreSQL, миграции, авторизация и работа с сообщениями. В лабораторной 3 добавлены балансировка, две API-реплики, идентификация экземпляров и общая идемпотентность.

Файл .env.example является шаблоном задания. Фактическая конфигурация контейнеров задаётся в compose.yaml; подключения к PostgreSQL и Redis передаются через файлы секретов.

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

Критерий Команда или сценарий Наблюдаемый результат Доказательство
Публичный smoke make test PASS evidence/smoke.txt
Структура проекта make check PASS Вывод проверки
OpenAPI make validate PASS Вывод проверки
Две API-реплики docker compose ps -a Обе реплики healthy evidence/compose-status.txt
Общая сессия make test-failover Сессия сохраняется после отказа реплики evidence/failover.txt
Отказ одной реплики make test-failover ACTION_SCRIPT=./scripts/stop-one.sh 55 успешных записей, 4 неудачные попытки, первое восстановление за 1,327 с evidence/failover.txt
Сохранность данных make test-persistence ACTION_SCRIPT=./scripts/restart.sh PASS, подтверждённые данные и сессия сохранились evidence/persistence.txt
Конкурентная идемпотентность python3 tests/test_concurrent_idempotency.py 20 запросов, 1 уникальный ID, 1 сообщение в истории evidence/idempotency.txt
Запросы через разные реплики Конкурентный тест Обнаружены api-1 и api-2 evidence/idempotency.txt
Остановка каждой реплики Ручная последовательная проверка При остановке одной реплики оставшаяся продолжала отвечать HTTP 200 Результаты ручной проверки

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

На этапе оценки 3 выполнены функциональные проверки отказоустойчивости, сохранности данных и идемпотентности.

Отказ API-реплики

Команда:

make test-failover ACTION_SCRIPT=./scripts/stop-one.sh

Полученные результаты:

  • Наблюдаемых реплик до отказа: 2
  • Успешных записей: 55
  • Неудачных попыток: 4
  • Время до первого успешного восстановления: 1,327 с
  • Подтверждённые данные: сохранены
  • Существующая сессия: сохранена

Дополнительно вручную проверена остановка каждой реплики с восстановлением предыдущей. В обоих случаях оставшаяся реплика продолжала обслуживать запросы через Nginx.

Сохранность данных

Команда:

make test-persistence ACTION_SCRIPT=./scripts/restart.sh

Результат: PASS. После перезапуска PostgreSQL, Redis и API подтверждённые данные и существующая сессия остались доступными.

Конкурентная идемпотентность

Команда:

python3 tests/test_concurrent_idempotency.py

Результаты:

  • Параллельных запросов: 20
  • Уникальных идентификаторов сообщений: 1
  • Наблюдаемые реплики: api-1, api-2
  • Совпадающих сообщений в истории: 1
  • Итог: PASS

Таким образом, конкурентные запросы с одинаковым ключом не создали дублирующих сообщений.

Дальнейшие измерения

Для оценки 4 планируется собрать RPS, количество ошибок, время восстановления, задержки и потребление ресурсов при последовательной остановке каждой реплики и поочерёдном обновлении контейнеров.

Для оценки 5 выбран трек исследования цены масштабирования. Планируется сравнить 1, 2 и 4 API-реплики при фиксированном общем бюджете CPU/RAM, затем повторить эксперимент с увеличением ресурсов.

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

Реализована устойчивость к остановке одной API-реплики при сохранении доступности второй.

PostgreSQL, Redis и Nginx представлены одиночными экземплярами и остаются едиными точками отказа. Отказ этих компонентов не покрывается механизмом переключения API-реплик.

Проверка повторного запуска выполнена на существующих Docker volumes. Полностью независимый запуск из чистого клона пока не проверялся.

Время 1,327 с характеризует восстановление, наблюдаемое тестом, а не отдельное измерение времени обнаружения отказа балансировщиком.

В текущем локальном варианте файловые секреты имеют права чтения, допускающие доступ других локальных пользователей. Для следующего этапа необходимо ограничить доступ к ним без нарушения работы непривилегированных контейнеров.

Количественные эксперименты с производительностью, rolling update и масштабированием будут проведены при выполнении критериев оценок 4 и 5.