forked from mtusi2026/mtusi2026lab3
430 lines
25 KiB
Markdown
430 lines
25 KiB
Markdown
# Отчёт по лабораторной работе №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. Архитектура основного стенда
|
||
|
||
```text
|
||
клиент -> 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+.
|
||
|
||
```sh
|
||
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 сверяет таблицу истории и не повторяет уже
|
||
применённые версии.
|
||
|
||
Обычная остановка сохраняет данные:
|
||
|
||
```sh
|
||
docker compose --env-file .env stop
|
||
```
|
||
|
||
Удаление учебных данных выполняется только осознанно:
|
||
|
||
```sh
|
||
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`.
|
||
Область ключа:
|
||
|
||
```text
|
||
(user_id, HTTP method, canonical request path, Idempotency-Key)
|
||
```
|
||
|
||
В общей PostgreSQL-транзакции API вычисляет SHA-256 семантического тела и
|
||
получает transaction-scoped advisory lock:
|
||
|
||
```sql
|
||
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.
|
||
|
||
```sh
|
||
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 и сохранение сессии
|
||
|
||
```sh
|
||
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` держит
|
||
четыре закрытых потока записи:
|
||
|
||
```sh
|
||
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.
|
||
|
||
```powershell
|
||
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:
|
||
|
||
```powershell
|
||
$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-файлов проекта.
|