# Отчёт — лабораторная работа №3 ## «Балансировка и отказ API-реплики» - **Автор:** Перевалова Виктория - **Группа:** БПИ2302 - **Целевая оценка:** 5 - **Выбранный исследовательский трек:** Track 1 — цена масштабирования --- ## 1. Цель работы Цель лабораторной работы — реализовать систему с несколькими взаимозаменяемыми экземплярами API, работающими за единой точкой входа, обеспечить балансировку запросов и сохранение корректности при отказе одной API-реплики. Дополнительные задачи: - вынести общее состояние за пределы API-контейнеров; - реализовать общую идемпотентность операций отправки сообщений; - обеспечить автоматическое исключение недоступных реплик из балансировки; - проверить восстановление при отказе экземпляров API; - исследовать влияние количества реплик и доступных ресурсов на производительность системы. ## 2. Архитектура и принятые решения ### 2.1. Общая архитектура Система построена на Docker Compose и включает следующие компоненты: - **Traefik 3.6** — единая точка входа и балансировщик нагрузки; - **API × N** — несколько экземпляров приложения на FastAPI; - **PostgreSQL 16.6** — основное долговременное хранилище; - **Redis 7.4.2** — общее хранилище сессий и вспомогательных данных; - **Migrate** — отдельный одноразовый процесс выполнения миграций Alembic. Схема взаимодействия: ```text Клиент | v Traefik 3.6 / \ v v API replica 1 API replica 2 | | +------+------+ | +--------+--------+ | | v v PostgreSQL Redis (данные) (сессии) ``` Все API-реплики используют общие PostgreSQL и Redis. Поэтому состояние пользователя не зависит от конкретного экземпляра приложения. API-контейнеры не публикуют порты непосредственно на хост. Внешний доступ осуществляется через Traefik. ### 2.2. Балансировка Traefik распределяет запросы между доступными API-репликами с использованием стратегии Weighted Round Robin. Для обнаружения недоступных экземпляров настроена проверка: - endpoint: `/health/ready`; - интервал: 3 секунды; - timeout: 2 секунды. При недоступности реплики балансировщик перестаёт направлять на неё запросы. Для наблюдения за экземпляром, обработавшим запрос, API возвращает заголовок `X-Instance-Id`. Sticky sessions не используются. ### 2.3. Хранение данных и миграции PostgreSQL является основным источником долговременных данных. Redis используется как общее хранилище сессий и вспомогательное хранилище. Миграции выполняются отдельно от API посредством Alembic: ```bash alembic upgrade head ``` В Docker Compose предусмотрен отдельный одноразовый сервис миграций. API запускается после успешного завершения миграций и проверки готовности PostgreSQL и Redis. ### 2.4. Идемпотентность Для отправки сообщения используется обязательный заголовок `Idempotency-Key`. Реализованы следующие сценарии: 1. Повтор запроса с тем же ключом и тем же содержимым возвращает результат первоначальной операции. 2. Повторное создание сообщения не происходит. 3. Использование того же ключа с другим содержимым приводит к ответу `409 Conflict`. 4. Конкурентные запросы с одинаковым ключом не создают дубликаты. 5. Идемпотентность сохраняется при обработке запросов разными API-репликами. ## 3. Запуск проекта ### 3.1. Требования Для запуска необходимы: - Docker Desktop; - Docker Compose v2; - Git. ### 3.2. Получение проекта ```bash git clone https://gitea.privcloud.tech/perevalova/mtusi2026lab3.git cd mtusi2026lab3 git checkout solution/lab3-implementation ``` ### 3.3. Подготовка конфигурации ```bash cp .env.example .env ``` ### 3.4. Проверка и запуск ```bash docker compose config --quiet docker compose up -d --build docker compose ps ``` Для просмотра состояния сервисов: ```bash docker compose ps ``` Для просмотра журналов: ```bash docker compose logs -f ``` Единая точка входа приложения: ```text http://localhost:8080 ``` ### 3.5. Остановка Без удаления сохранённых данных: ```bash docker compose down ``` Для намеренного удаления учебных данных вместе с volumes: ```bash docker compose down -v ``` Последняя команда удаляет данные PostgreSQL и Redis и должна применяться только при необходимости полного сброса стенда. ## 4. Проверка функциональных требований ### 4.1. Работа нескольких реплик Проверено обращение к API через Traefik с использованием заголовка `X-Instance-Id`. Запросы одного пользователя обрабатывались разными экземплярами API без повторной аутентификации. Результат: общая сессия доступна независимо от выбранной реплики. Sticky sessions не требуются. ### 4.2. Проверка идемпотентности Проверены: - повторная отправка с тем же ключом; - повтор с изменённым содержимым; - 10 конкурентных запросов с одним ключом; - получение истории сообщений после конкурентных запросов. Результат: запросы с одинаковым ключом и содержимым возвращают один и тот же результат. Дубликаты сообщений не создаются. ### 4.3. Проверка отказа API-реплики Для проверки использовался сценарий: ```bash BASH_EXE="$(cygpath -w "$(command -v bash)")" \ python tests/resilience.py --mode failover --action-script scripts/stop-one.sh ``` Сценарий последовательно проверял отказ каждой реплики. | Проверяемая реплика | Успешные записи | Неуспешные попытки | Восстановление | |---|---:|---:|---:| | Replica 1 | 83 | 3 | 4,195 с | | Replica 2 | 87 | 3 | 4,051 с | В обоих случаях проверка завершилась успешно. Результаты сохранены: - `evidence/failover/replica-1.txt`; - `evidence/failover/replica-2.txt`. Время восстановления в обоих сценариях не превысило 10 секунд. ### 4.4. Проверка rolling update Для последовательной замены API-реплик реализован скрипт: ```bash bash scripts/rolling-update.sh ``` Скрипт выполняет следующие действия: 1. Создаёт новую реплику. 2. Ожидает её готовности. 3. Переводит старую реплику в состояние drain. 4. Ожидает прекращения направления новых запросов. 5. Останавливает старую реплику. 6. Повторяет процесс для следующего экземпляра. Для проверки использовалась нагрузка с восемью параллельными клиентами в течение примерно 90 секунд. Последний диагностический запуск: | Метрика | Результат | |---|---:| | Длительность | 91,245 с | | Параллельные клиенты | 8 | | Успешные запросы | 6050 | | Неуспешные запросы | 20 | | Доля ошибок | 0,3295% | | Успешный RPS | 66,305 | | p50 | 87,748 мс | | p95 | 280,709 мс | | p99 | 427,002 мс | Все зарегистрированные ошибки в последнем запуске — HTTP 502. Тайм-аутов в этом запуске не зафиксировано. По сравнению с предыдущим диагностическим запуском число ошибок уменьшилось с 22 до 20, а тайм-ауты исчезли. Однако полностью устранить кратковременные HTTP 502 пока не удалось. Поэтому rolling update считается реализованным и проверенным под нагрузкой, но не безошибочным. ## 5. Исследовательский трек 1. Цена масштабирования ### 5.1. Цель эксперимента Исследовать влияние количества API-реплик на производительность системы при фиксированном суммарном объёме ресурсов. Гипотеза: увеличение количества реплик повышает пропускную способность, но эффект масштабирования постепенно уменьшается из-за общих инфраструктурных компонентов. После сравнения количества реплик проводится дополнительная серия с увеличением доступных CPU и RAM. ### 5.2. Методика В первой серии сравнивались 1, 2 и 4 API-реплики при одинаковом суммарном бюджете: - CPU: 2; - RAM: 2048 MB. Во второй серии использовались 4 API-реплики, а доступные ресурсы увеличивались. Результаты экспериментов сохранены в каталоге `evidence/scaling/`, включая исходные JSON, сводную таблицу и графики. ### 5.3. Сравнение количества реплик | Конфигурация | RPS | p95, мс | Ошибки | |---|---:|---:|---:| | 1 реплика | 37,541 | 302,388 | 0 | | 2 реплики | 59,211 | 294,656 | 0 | | 4 реплики | 65,877 | 390,895 | 0 | При переходе от одной реплики к двум пропускная способность выросла примерно на 57,7%. При переходе от двух реплик к четырём прирост составил около 11,3%. Это демонстрирует снижение эффективности дальнейшего горизонтального масштабирования при неизменном суммарном бюджете ресурсов. ### 5.4. Серия с увеличением ресурсов | API-реплики | CPU | RAM, MB | RPS | p95, мс | |---|---:|---:|---:|---:| | 4 | 2 | 2048 | 68,467 | 374,351 | | 4 | 3 | 3072 | 95,214 | 238,599 | | 4 | 4 | 4096 | 119,589 | 137,459 | При увеличении ресурсов с 2 CPU / 2048 MB до 4 CPU / 4096 MB пропускная способность выросла примерно на 74,7%. Значение p95 latency уменьшилось примерно на 63,3%. ### 5.5. Выводы по эксперименту Эксперимент показал, что горизонтальное масштабирование при фиксированном суммарном объёме ресурсов имеет убывающую отдачу. Увеличение количества реплик с одной до двух существенно повышает пропускную способность. Переход от двух к четырём репликам даёт значительно меньший прирост и сопровождается увеличением p95 latency. Дополнительное увеличение CPU и RAM при четырёх репликах улучшило пропускную способность и задержки. При этом точка насыщения PostgreSQL, Traefik или пула соединений не была однозначно локализована: для такого вывода необходимы отдельные измерения загрузки БД, ожидания соединений, CPU балансировщика и состояния пула. Следовательно, эксперимент подтверждает влияние количества реплик и доступных ресурсов на производительность, но не позволяет достоверно приписать снижение эффективности конкретному компоненту. ## 6. Итоговая проверка критериев | Требование | Результат | Доказательство | |---|---|---| | Не менее двух API-реплик | Выполнено | `docker compose ps` | | Единая точка входа | Выполнено | Traefik, порт 8080 | | Общая PostgreSQL и Redis | Выполнено | `compose.yaml` | | Разные `X-Instance-Id` | Проверено | Результаты функциональных проверок | | Отсутствие sticky sessions | Выполнено | Общая сессия между репликами | | Обязательный `Idempotency-Key` | Проверено | Конкурентные тесты | | Readiness и healthcheck | Выполнено | `/health/ready`, Docker healthcheck | | Отказ каждой API-реплики | PASS | `evidence/failover/` | | Восстановление не более 10 секунд | PASS | 4,195 и 4,051 секунды | | CPU/RAM limits | Выполнено | `compose.yaml` | | API-порты не опубликованы | Выполнено | `docker compose ps` | | Однократные миграции | Выполнено | Сервис `migrate` | | Rolling update под нагрузкой | Выполнено с ограничением | `evidence/rolling-update-final.json` | | Сравнение 1/2/4 реплик | Выполнено | `evidence/scaling/summary.csv` | | Серия увеличения ресурсов | Выполнено | `evidence/scaling/` | | Локализация saturation point | Не подтверждена | Требуется дополнительная телеметрия | ## 7. Ограничения реализации 1. Rolling update пока сопровождается небольшим количеством кратковременных HTTP 502. Поэтому нельзя утверждать, что замена реплик полностью бесшовна. 2. Точка насыщения БД, балансировщика или пула соединений экспериментально не локализована. 3. Стенд работает на одном Docker host. Отказ всего хоста не покрывается данной архитектурой. 4. PostgreSQL и Traefik остаются отдельными потенциальными точками отказа. 5. Результаты производительности относятся к конкретному окружению и не являются универсальными характеристиками приложения. Для дальнейшего улучшения необходимо исследовать метрики PostgreSQL и пула соединений, дополнительно настроить drain и проверку состояния backend перед остановкой старого экземпляра, а также рассмотреть отказоустойчивость самой БД и балансировщика. ## 8. Заключение В лабораторной работе реализована система с несколькими API-репликами, общей базой данных, общим хранилищем сессий и балансировщиком Traefik. Проверены распределение запросов между репликами, сохранение сессии, общая идемпотентность, конкурентные запросы и восстановление после остановки каждой API-реплики. Время восстановления в двух сценариях отказа составило около четырёх секунд, что укладывается в установленный предел 10 секунд. В рамках исследовательского трека выполнено сравнение одной, двух и четырёх API-реплик при фиксированном бюджете ресурсов, а также серия экспериментов с увеличением CPU и RAM. Полученные результаты показали убывающую отдачу от горизонтального масштабирования и положительное влияние увеличения ресурсов на пропускную способность. Таким образом, основные механизмы балансировки, отказоустойчивости и масштабирования реализованы и проверены. При этом ограничения rolling update и отсутствие однозначно установленной точки насыщения инфраструктурных компонентов явно зафиксированы, а не скрыты в итоговых выводах.