25 KiB
Отчёт по лабораторной работе №3
Тема: горизонтальное масштабирование, балансировка и отказоустойчивость API
Автор: Антипин Егор Иванович, БПИ2301
Целевая оценка: 5
Выбранный трек уровня 5: трек 2 — «Отказ узла»
Commit/PR: работа проверена в локальной копии; ссылку следует указать после публикации репозитория.
1. Цель работы
Цель — запустить несколько взаимозаменяемых экземпляров API за одной публичной точкой входа и сохранить корректность приложения при остановке отдельной реплики. Сессии, сообщения и результаты идемпотентных операций не должны зависеть от памяти или локального диска API.
Для уровня 5 дополнительно проверяется потеря целого Docker-узла. Реализованы два стенда:
- основной Compose-стенд с Nginx и двумя API-репликами;
- отдельный трёхузловой 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
проверяет:
- Spring
ReadinessState.ACCEPTING_TRAFFIC; - доступ к PostgreSQL;
- наличие таблицы
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-реплик сериализуется общей БД. Затем сервис:
- ищет запись в
message_idempotency; - при совпадающем SHA-256 возвращает ранее созданное сообщение;
- при другом теле отвечает
409 Conflict; - при новом ключе создаёт
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:
- проверяет не менее двух API tasks и instance ID;
- создаёт контрольное сообщение;
- находит worker, реально выполняющий API task;
- жёстко останавливает весь внешний DinD-контейнер worker;
- 30 s выполняет через Nginx чтения и идемпотентные записи;
- проверяет новую task ID на другом узле и новый
X-Instance-Id; - читает контрольное и все подтверждённые сообщения;
- возвращает 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-файлов проекта.