Files
mtusi2026lab3/REPORT.md
T
2026-11-03 20:49:07 +03:00

25 KiB
Raw Blame History

Отчёт по лабораторной работе №3

Тема: горизонтальное масштабирование, балансировка и отказоустойчивость API

Автор: Антипин Егор Иванович, БПИ2301

Целевая оценка: 5

Выбранный трек уровня 5: трек 2 — «Отказ узла»

Commit/PR: работа проверена в локальной копии; ссылку следует указать после публикации репозитория.

1. Цель работы

Цель — запустить несколько взаимозаменяемых экземпляров API за одной публичной точкой входа и сохранить корректность приложения при остановке отдельной реплики. Сессии, сообщения и результаты идемпотентных операций не должны зависеть от памяти или локального диска API.

Для уровня 5 дополнительно проверяется потеря целого Docker-узла. Реализованы два стенда:

  1. основной Compose-стенд с Nginx и двумя API-репликами;
  2. отдельный трёхузловой Swarm-стенд для переноса API после потери worker-узла.

2. Использованные технологии

  • Java 23, Spring Boot 4.1.1;
  • PostgreSQL 16.4 — источник истины;
  • Redis 7.4 — общий необязательный cache-aside кэш;
  • Nginx 1.27.4 — единственная публичная точка входа и балансировщик;
  • Docker Compose v2 — основной стенд;
  • Docker Swarm и Docker-in-Docker — эксперимент с отказом узла;
  • Flyway — версионирование схемы;
  • Python 3.9+ — black-box и нагрузочные сценарии.

Приложение собирается из исходного кода текущего репозитория. Готовый образ серверной части преподавателя не используется.

3. Архитектура основного стенда

клиент -> localhost:8080 -> Nginx -> API replica 1/2 -> PostgreSQL
                                      |
                                      +-----------> Redis (необязательный кэш)

Nginx — единственный сервис, публикующий порт на host. API, PostgreSQL и Redis доступны только во внутренней Docker-сети backend. У сервиса api нет container_name, поэтому один Compose-service масштабируется параметром --scale api=2.

3.1. Роли компонентов

Роль Service / образ Health/readiness Хранилище Порт и сеть Credentials
Публичный LB nginx, nginx:1.27.4-bookworm nginx -t, каждые 2 s нет 127.0.0.1:8080 -> 80, backend не требуются
API api, локальный hla-lab3-api:local GET /health/ready, каждые 2 s нет только 8080/backend параметры БД из .env через environment
Миграции migrate, тот же образ API one-shot, код завершения нет backend те же параметры БД
Источник истины postgres, postgres:16.4-bookworm pg_isready, каждые 2 s postgres-data только 5432/backend DATABASE_PASSWORD из .env
Общий кэш redis, redis:7.4-bookworm redis-cli ping, каждые 2 s redis-data, AOF everysec только 6379/backend наружу порт не открыт

PostgreSQL хранит пользователей, Bearer-сессии, чаты, членство, сообщения и message_idempotency. Поэтому следующий запрос одного пользователя может попасть на другую API-реплику без повторного входа. Redis не является источником корректности: при cache miss или недоступности Redis приложение читает данные из PostgreSQL.

Постоянные volumes подключены только к PostgreSQL и Redis. API и Nginx stateless и могут быть удалены и созданы заново.

4. Воспроизводимый запуск Compose + Nginx

Требуются Docker Engine с Compose v2, make и Python 3.9+.

cp .env.example .env
# заменить DATABASE_PASSWORD в .env локальным случайным значением
docker compose --env-file .env config --quiet
docker compose --env-file .env build api
docker compose --env-file .env up -d postgres redis
docker compose --env-file .env run --rm migrate
docker compose --env-file .env up -d --scale api=2 api nginx
curl --fail http://localhost:8080/health/ready

Это единая последовательность запуска. Миграции выполняются отдельным one-shot сервисом до API. Во всех обычных API-репликах установлено FLYWAY_ENABLED=false, поэтому реплики не соревнуются за схему. Повторный запуск migrate безопасен: Flyway сверяет таблицу истории и не повторяет уже применённые версии.

Обычная остановка сохраняет данные:

docker compose --env-file .env stop

Удаление учебных данных выполняется только осознанно:

docker compose --env-file .env down --volumes

.env не должен попадать в Git. Для production вместо него требуется secret manager или Docker secrets.

5. Балансировка Nginx

Конфигурация находится в infra/nginx.conf. Upstream задаётся DNS-именем api:8080. Встроенный Docker DNS 127.0.0.11 возвращает адреса актуальных Compose-реплик. resolve и resolver ... valid=2s обновляют список адресов без reload с TTL 2 секунды.

Алгоритм least_conn выбирает живую реплику с наименьшим числом активных соединений. Реплика с длинными запросами временно получает меньше новой работы.

Sticky session не используется. Она закрепляла бы клиента за одной репликой и скрывала ошибочное локальное состояние. Здесь запросы одного Bearer-пользователя могут проходить через разные реплики. X-Instance-Id, равный hostname процесса, позволяет это наблюдать.

Параметры upstream:

  • max_fails=1: одной сетевой ошибки достаточно для временного исключения;
  • fail_timeout=2s: ошибочный peer исключается на 2 секунды;
  • proxy_connect_timeout=500ms;
  • proxy_read_timeout=4s и proxy_send_timeout=4s;
  • максимум две upstream-попытки.

Для зависшего backend максимальное время первичного обнаружения — 4 секунды. Две последовательные timeout-попытки завершают запрос примерно за 8,5 секунды. Ошибка соединения определяется быстрее — в пределах 500 ms на попытку. Это укладывается в требование возобновить новые операции не позднее 10 секунд.

Nginx OSS использует пассивную runtime-проверку upstream: Docker readiness не допускает ранний операторский запуск публичного маршрута, а отказ уже работающего backend обнаруживается запросом и указанными таймерами.

6. Readiness и graceful shutdown

GET /health/live подтверждает, что процесс работает. GET /health/ready проверяет:

  1. Spring ReadinessState.ACCEPTING_TRAFFIC;
  2. доступ к PostgreSQL;
  3. наличие таблицы message_idempotency, то есть применение V3.

Ping Redis прогревает соединение, но ошибка Redis не делает API неготовым, поскольку Redis — необязательный кэш.

Docker вызывает readiness каждые 2 s, timeout — 2 s, start period — 45 s. Перед завершением Spring переводит приложение из ACCEPTING_TRAFFIC, прекращает приём новой работы и завершает принятую. В application.yml установлены server.shutdown=graceful и timeout-per-shutdown-phase=10s; Compose даёт API 12 s через stop_grace_period. У Nginx worker_shutdown_timeout=10s и такой же stop_grace_period.

7. Общая идемпотентность сообщений

Для POST /api/v1/chats/{chatId}/messages обязателен Idempotency-Key. Область ключа:

(user_id, HTTP method, canonical request path, Idempotency-Key)

В общей PostgreSQL-транзакции API вычисляет SHA-256 семантического тела и получает transaction-scoped advisory lock:

SELECT pg_advisory_xact_lock(hashtextextended(scope, 0));

Advisory-блокировка — именованная блокировка PostgreSQL, которой управляет приложение. pg_advisory_xact_lock действует до конца транзакции. Одинаковый ключ с разных API-реплик сериализуется общей БД. Затем сервис:

  1. ищет запись в message_idempotency;
  2. при совпадающем SHA-256 возвращает ранее созданное сообщение;
  3. при другом теле отвечает 409 Conflict;
  4. при новом ключе создаёт messages и message_idempotency в одной транзакции.

Сообщение и запись идемпотентности фиксируются атомарно. Если клиент не получил ответ, он безопасно повторяет запрос с тем же ключом через любую реплику. Записи живут не менее 24 часов. Коллизия 64-битного хеша advisory lock только лишний раз сериализует разные ключи: полная область проверяется primary key.

Nginx разрешает non_idempotent retry только для endpoint сообщения. Тело буферизуется, а общая идемпотентность делает повтор безопасным. Остальные POST после начала отправки автоматически не повторяются.

Результат student_tests/idempotency_concurrent.py: 32 одновременных запроса с одним ключом прошли через два X-Instance-Id и создали ровно одно сообщение.

8. Проверка отказа API-реплик

scripts/stop-one.sh (Windows: stop-one.cmd) получает наблюдаемый X-Instance-Id, сопоставляет его hostname контейнера и останавливает выбранную API-реплику. Нагрузка идёт только через Nginx.

chmod +x scripts/stop-one.sh scripts/restore-api.sh
make test-failover-each \
  ACTION_SCRIPT=scripts/stop-one.sh \
  RESTORE_SCRIPT=scripts/restore-api.sh

Предыдущая реплика восстанавливается и снова наблюдается через LB до остановки следующей. В Windows используются одноимённые .cmd-скрипты.

Фактические результаты 03.11.2026:

Реплика Чтения Записи Ошибки Successful RPS Первая успешная операция после stop
170796a1dad0 81 82 0 10,839 1,306 s
feb12e05fd43 75 76 0 10,014 2,672 s

Обе реплики до опытов были видны по X-Instance-Id. Во время отказа продолжались чтения и идемпотентные записи, подтверждённые сообщения остались доступны. Raw-результат: evidence/failover-each-2026-11-03.json.

9. Persistence и сохранение сессии

make test-persistence ACTION_SCRIPT=scripts/restart.sh

restart.sh перезапускает зависимости без удаления volumes, выполняет однократную миграцию и поднимает две API-реплики. Тест использует созданный до рестарта Bearer token и проверяет прежние данные. Корректность обеспечивает PostgreSQL, а не память API и не Redis.

10. Ресурсы и изоляция

  • каждая Compose API-реплика: 0,75 CPU и 768 MiB;
  • Nginx: 0,25 CPU и 128 MiB;
  • API не публикует host port;
  • volumes есть только у PostgreSQL и Redis;
  • container_name отсутствует;
  • API/Nginx не имеют состояния, необходимого для корректности.

В Swarm PostgreSQL ограничен 1 CPU/768 MiB, Redis — 0,25 CPU/256 MiB.

11. Rolling update под нагрузкой

scripts/rolling-update.sh по очереди заменяет каждую исходную API-реплику и ждёт readiness новой. Одновременно student_tests/rolling_update.py держит четыре закрытых потока записи:

make test-rolling ACTION_SCRIPT=scripts/rolling-update.sh

Фактический опыт 03.11.2026:

  • нагрузка — 180,118 s, замена — 115,800 s;
  • наблюдались четыре X-Instance-Id: две старые и две новые реплики;
  • 12 147 успешных записей и 177 ошибок;
  • successful RPS — 67,439; error ratio — 1,4362%;
  • latency успешных запросов: p50 37,729 ms, p95 189,374 ms, p99 215,986 ms.

Ошибки не скрыты клиентским retry. Это closed-loop измерение на одном host; percentiles не включают ошибки и подвержены coordinated omission. Raw: evidence/rolling-update-2026-11-03.json.

V3 обратно совместима: она только добавляет таблицу и индекс. Старая версия работает после применения V3, новая не становится ready до появления V3. Автоматический downgrade не реализован; rollback приложения оставит неиспользуемую V3-таблицу.

12. Уровень 5: отказ целого узла

12.1. Гипотеза

Если две stateless API-задачи распределены по разным Swarm-узлам, есть свободный узел, а общий PostgreSQL работает, потеря worker с API приведёт к созданию новой задачи на живом узле. Через Nginx продолжатся чтение и запись, а подтверждённые данные сохранятся.

Гипотеза не утверждает выживание узла PostgreSQL: БД не реплицирована.

12.2. Топология и образы

Одноразовый стенд содержит три независимых Docker daemon в privileged DinD: hla-swarm-manager, hla-swarm-worker1, hla-swarm-worker2.

API имеет две задачи, endpoint_mode: dnsrr и max_replicas_per_node: 1. Третий узел оставляет место для переноса. Nginx обращается к tasks.hla-app_api:8080 через overlay DNS.

scripts/swarm-lab-up.ps1 собирает API и Nginx из текущего репозитория, публикует hla-swarm-registry:5000/hla-lab3-*:swarm в одноразовый registry и разворачивает образы на узлах по digest. Затем создаётся overlay network, разворачивается state stack, отдельно выполняется migration job и запускается app stack.

make swarm-up
make test-node-failover PYTHON=python
make swarm-down

Swarm Nginx доступен на http://localhost:18080, отдельно от Compose на 8080.

12.3. Методика

student_tests/node_failover.py:

  1. проверяет не менее двух API tasks и instance ID;
  2. создаёт контрольное сообщение;
  3. находит worker, реально выполняющий API task;
  4. жёстко останавливает весь внешний DinD-контейнер worker;
  5. 30 s выполняет через Nginx чтения и идемпотентные записи;
  6. проверяет новую task ID на другом узле и новый X-Instance-Id;
  7. читает контрольное и все подтверждённые сообщения;
  8. возвращает worker и ждёт Ready.

12.4. Результат

03.11.2026 полностью остановлен hla-swarm-worker2.

Параметр Результат
Старая task sesmka0dxn5k на hla-swarm-worker2
Новая task pke5uf5okm69 на hla-swarm-worker1
Instance ID до 1726221ff80d, edb5532a721e
Instance ID после 1726221ff80d, 81c7197f2bfe
Успешные чтения / записи 165 / 166
Ошибки 0
Первая успешная операция 1,796 s
Successful RPS 11,033
Полное время с возвратом узла 73,763 s
Подтверждённые данные сохранены да

API-задача реально перенесена между Docker daemon. Контрольное сообщение и все подтверждённые во время отказа операции сохранились. Результаты: evidence/node-failover-2026-11-03.json и evidence/node-failover-2026-11-03.md.

В JSON записано database_node_failed=false: узел БД не падал, и выживание PostgreSQL не заявляется.

12.5. Оставшиеся SPOF

SPOF Причина Что требуется для production
Nginx одна задача на manager несколько LB за внешним L4/VIP или managed LB
PostgreSQL одна реплика на manager репликация, автоматический failover, проверка RPO/RTO
Redis одна реплика Sentinel/Cluster, если требуется HA кэша
Swarm control plane один manager 3 или 5 manager-узлов для Raft quorum
Storage локальные volumes manager реплицированное/сетевое хранилище и fencing
Underlay/host DinD на одном компьютере разные hosts и резервирование сети

Доказан failover API-worker при живом state/LB-узле. Потеря manager, DB, LB, storage или физического host не переживается и не заявляется.

13. Команды проверок и доказательства

Дополнительные проверки находятся в student_tests; исходные тесты курса — в tests, Spring-тесты — в src/test/java.

Требование Команда / доказательство Результат
Структура и синтаксис make check PASS
Основной API через LB make test PASS
Общая идемпотентность make test-idempotency 32 запроса, 2 реплики, 1 сообщение
Persistence make test-persistence ACTION_SCRIPT=scripts/restart.sh прежние token и данные доступны
Выбранная реплика make test-failover ACTION_SCRIPT=scripts/stop-one.sh чтение/запись продолжаются
Каждая реплика make test-failover-each ... 0 ошибок, recovery 1,306/2,672 s
Rolling update make test-rolling ... 4 instance ID, 12 147 успешных записей
Потеря worker make test-node-failover task перенесена, 0 ошибок, данные сохранены
Compose config docker compose --env-file .env config --quiet exit 0

Сводка уровня 4: evidence/level4-2026-11-03.md. Числа опытов сохранены в машиночитаемых JSON в evidence/.

На Windows Python может использовать cp1251. Для чтения UTF-8 OpenAPI:

$env:PYTHONUTF8='1'
make test PYTHON=python

14. Соответствие критериям

Уровень 3

  • compose.yaml, две API-реплики, одна публичная точка, общие БД и сессии;
  • запросы одного пользователя идут на разные X-Instance-Id без нового login;
  • отказ любой API-реплики проверен при чтении и записи;
  • конкурентный повтор Idempotency-Key не создаёт дубль;
  • smoke, persistence и failover выполняются через LB.

Уровень 4

  • readiness, DNS refresh, timeouts и graceful shutdown согласованы;
  • обе реплики остановлены по очереди с RPS, errors и recovery;
  • заданы CPU/RAM limits, API-порты не опубликованы, container_name нет;
  • rolling replacement проверен под нагрузкой;
  • миграция запускается отдельно и является additive/backward-compatible.

Уровень 5, трек «Отказ узла»

  • создано три Docker-узла;
  • потерян узел, реально выполнявший API task;
  • Swarm создал новую task на другом daemon;
  • чтение/запись продолжались, данные сохранились;
  • разобраны SPOF LB, DB, control plane и storage;
  • отказ DB не проверялся и не заявлен.

15. Ограничения

Измерения выполнены локально на Windows с Docker Desktop. DinD даёт отдельные Docker daemon и реальный Swarm rescheduling, но не моделирует отключение разных физических серверов. Результаты нагрузки зависят от host и не являются production benchmark. Nginx OSS использует пассивное runtime-исключение. TLS и внешний HA ingress в лабораторный стенд не входят.

16. Использование ИИ и внешней помощи

ИИ использовался для обсуждения Compose/Nginx, readiness/graceful shutdown, общей идемпотентности, дополнительных сценариев student_tests, Swarm-опыта и редактирования отчёта. Поведение подтверждено запускаемыми тестами и raw JSON. Заимствованный прикладной код стороннего сервера не использовался; применены стандартные open-source зависимости из build-файлов проекта.