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

430 lines
25 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Отчёт по лабораторной работе №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-файлов проекта.