Files
mtusi2026lab3/REPORT.md
T
2026-11-04 16:11:13 +03:00

137 lines
20 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
- Автор, группа: Журавлев Алексей, БПИ2301
- Целевая оценка: 5; трек 1 — цена масштабирования
- Commit/PR:
- Дата проверок: 2026-11-04
- Источники и ИИ: собственные исходники lab2; skeleton и контракт lab3; официальная документация Docker Compose, Nginx, PostgreSQL и Redis. Использовалась помощь ИИ при разработке эксперимента и проверке ошибок; результаты ниже получены командами проекта.
## Запуск из чистого clone
### Среда и локальные файлы
- Windows 11, Docker Desktop с Docker Compose v2; текущая проверенная версия Docker Engine — 29.8.2.
- Docker host сообщает 32 CPU и 7539.719 MiB RAM; эти значения относятся к Docker Desktop, а не к физической памяти/CPU ПК.
- Python 3.9+ для публичных тестов; проверка выполнена Python 3.14.6. В PowerShell используйте `py -3 -X utf8`, чтобы Python на Windows читал UTF-8 JSON/контракт независимо от системной кодировки. Makefile добавляет `-X utf8` автоматически.
- Образы закреплены версиями: `python:3.12.11-slim-bookworm`, `postgres:16.8-alpine`, `redis:7.4.2-alpine`, `nginx:1.27.5-alpine`. API собирается локально из `Dockerfile`.
- GNU Make необязателен. Порты наружу: только `${APP_PORT:-8080}` для Nginx.
В PowerShell из каталога проекта:
```powershell
Set-Location 'C:\VMD3\mtusi2026lab3'
.\scripts\init-local-secrets.ps1
docker compose config --quiet
docker compose up -d --build
Invoke-RestMethod http://localhost:8080/health/ready
make check
make validate
make test
make student-test
```
`init-local-secrets.ps1` копирует `.env.example` в игнорируемый `.env`, если его ещё нет, и создаёт `secrets/postgres_password` и `secrets/database_url` с криптографически случайным паролем. Скрипт не печатает значения. Если оба файла уже есть, он не меняет их; если набор неполный — завершится ошибкой, чтобы случайно не рассинхронизировать пароль и volume. Не публикуйте `.env` или `secrets/`.
Ожидаемая топология после готовности: два `api` контейнера и по одному `nginx`, `postgres`, `redis`. Проверить её и состояние healthchecks:
```powershell
docker compose ps
docker compose logs --tail 100 migrate api nginx
```
`migrate` — однократный job: ждёт PostgreSQL healthcheck, применяет упорядоченные SQL-файлы, завершает работу. Каждый запуск безопасно проверяет уже применённые версии; API-контейнеры не мигрируют схему параллельно при старте.
### Проверки отказа и последовательной замены
Windows-вариант hook-файлов запускается проверкой напрямую:
```powershell
py -3 -X utf8 tests\resilience.py --mode persistence --action-script scripts\restart.bat --base-url http://localhost:8080
py -3 -X utf8 tests\resilience.py --mode failover --action-script scripts\stop-one.bat --base-url http://localhost:8080
docker compose up -d --scale api=2
py -3 -X utf8 tests\resilience.py --mode failover --action-script scripts\stop-one.bat --base-url http://localhost:8080
docker compose up -d --scale api=2
py -3 -X utf8 scripts\rolling_restart.py --base-url http://localhost:8080 --duration 40 --concurrency 16
py -3 -X utf8 scripts\rolling_update.py --base-url http://localhost:8080 --duration 90 --concurrency 16
```
Failover hook оставляет выбранную реплику остановленной; после каждого прогона оператор восстанавливает её командой `docker compose up -d --scale api=2`. POSIX-варианты `scripts/restart.sh` и `scripts/stop-one.sh` предназначены для Linux/macOS; перед запуском задайте им executable bit. Rolling restart последовательно перезапускает каждый работающий API-контейнер во время нагрузки и ждёт его healthcheck. Это подтверждает поведение процесса/балансировщика, но не заменяет отдельный тест деплоя нового бинарного образа.
### Выключение и очистка
```powershell
docker compose down
```
Команда останавливает контейнеры, но оставляет volumes с учебными данными. Только для намеренного полного сброса этого учебного проекта:
```powershell
docker compose down -v
```
Удаление volumes необратимо стирает пользователей, чаты, сообщения, сессии и AOF Redis. Секреты в `secrets/` удаляются отдельно после остановки проекта.
## Архитектура
```text
Клиент
│ единственный опубликованный порт 8080
▼
Nginx 1.27.5 ── DNS discovery / passive fail exclusion
│
├── API × 2+ (stateless; один общий image)
│ ├── PostgreSQL 16.8: пользователи, чаты, членство, сообщения, idempotency results
│ └── Redis 7.4.2: opaque sessions с TTL и AOF
└── общий Compose backend network (наружу не опубликована)
```
| Роль | Service | Версия / readiness | Volume, сеть, порт | Credentials |
| --- | --- | --- | --- | --- |
| API | `api` | Собирается из Python 3.12.11 image; `/health/ready`, каждые 3 s | Backend only; порт 8080 не публикуется | Только `database_url` Compose secret; `CACHE_URL` указывает на внутренний Redis |
| Load balancer | `nginx` | `nginx:1.27.5-alpine`; собственный readiness через API | Frontend + backend; host port 8080 | Не нужны |
| DB | `postgres` | `postgres:16.8-alpine`; `pg_isready` каждые 5 s | Named `postgres_data`, backend only | Только `postgres_password` Compose secret |
| Session store | `redis` | `redis:7.4.2-alpine`; `PING` каждые 5 s | Named `redis_data`, backend only; AOF `everysec` | Без пароля только внутри изолированной сети |
| Миграции | `migrate` | Тот же локально собранный API image; однократный exit | Backend only, volume не нужен | Только `database_url` Compose secret |
У `api` нет `container_name`, используются динамические Compose DNS-имена и `deploy.replicas`; масштабирование выполняется `docker compose up -d --scale api=N`. Nginx OSS периодически обновляет DNS через Docker DNS (`valid=5s`) и использует passive health: при одной ошибке соединения/таймауте или ответе 502/503/504 backend исключается на 2 s (`max_fails=1`, `fail_timeout=2s`). Это не активная проверка каждого backend коммерческим Nginx Plus. Docker healthcheck проверяет готовность экземпляра отдельно. Максимум наблюдаемого восстановления при остановке API в тестах был меньше секунды; при DNS-кэше/таймауте консервативная верхняя граница настройки — около 7 s, не включая длительный сбой зависимости.
В сессиях нет локального состояния API: opaque токен сопоставлен с пользователем в Redis через TTL; Redis AOF и volume переживают перезапуск. Источник истины бизнес-данных — PostgreSQL. `migrations/002_message_idempotency.sql` добавляет уникальную область `(user, method, chat path, key)`, hash запроса, тело исходного ответа и expiry 24 часа. Создание записи и сообщения происходит в одной транзакции. `pg_advisory_xact_lock` сериализует параллельные повторы одного ключа; другой body возвращает 409, совпадающий — прежний Message/201. Транзиентный сбой транзакции не сохраняет результат и не оставляет сообщение-дубль. Старые истёкшие ключи для пользователя очищаются при следующей записи.
Перенесены из lab2 собственные `app.py`, `auth.py`, `db.py`, `sessions.py`, схема PostgreSQL и библиотеки Argon2/psycopg/Redis. Контрактные `tests/`, `contracts/`, README и миграции skeleton lab3 не заменялись. В lab3 добавлены общий idempotency store, X-Instance-Id, DNS-балансировка, отдельный migration job, failover и масштабный эксперимент.
## Проверки и фактические результаты
| Критерий | Команда / доказательство | Наблюдаемый результат |
| --- | --- | --- |
| Offline contract / syntax | `make check` | PASS |
| Полная OpenAPI 3.1 / JSON Schema | `make validate` | PASS |
| Публичный сценарий API | `make test` | PASS: lab3 smoke, включая обязательный ключ и replay |
| Конкурентный idempotency на нескольких репликах | `make student-test` | 4 теста OK: replay, conflict при ином body, обязательность/формат ключа, 16 параллельных повторов; один Message, минимум 2 X-Instance-Id |
| PostgreSQL migration/bootstrap | `docker compose up -d --build`; `docker compose exec -T postgres psql -U messenger -d messenger -c "SELECT version FROM schema_migrations ORDER BY version"` | PASS: `001_schema.sql`, `002_message_idempotency.sql`; `migrate` завершился до запуска API |
| Сохранность при полном restart | `tests/resilience.py --mode persistence --action-script scripts/restart.bat` | PASS: подтверждённое сообщение и прежний Bearer токен доступны после restart API, PostgreSQL и Redis с сохранёнными volumes |
| Отказ одной API-реплики | `tests/resilience.py --mode failover --action-script scripts/stop-one.bat` | Два успешных resilience-прогона: восстановление за 0.634 s и 0.613 s, 0/1 переходных ошибки. Дополнительно обе конкретные реплики поочерёдно адресно остановлены: восстановление записи за 1.094/1.092 s, без ошибок; существующая сессия сохранялась, replay вернул тот же Message, дублей нет. `evidence/failover-targets.json` |
| Последовательный restart под нагрузкой | `scripts/rolling_restart.py --duration 40 --concurrency 16` | Две реплики последовательно восстановили health за 6.126 s и 6.148 s. За 40.161 s подтверждено 7054 POST (175.644 successful RPS), 2 ошибки из-за перехода (0.0283%); успешные p50/p95/p99 — 104.831/196.305/278.076 ms. Файлы `evidence/rolling-restart.json` и `evidence/rolling-restart-load.json` |
| Замена контейнеров новым API image под нагрузкой | `scripts/rolling_update.py --duration 90 --concurrency 16` | PASS: revision `lab3-4ef7756dc6dc`; каждый из двух новых контейнеров стал healthy и получил запрос через Nginx за 7.035/7.043 s. За 90.142 s нагрузки — 16,479 успешных POST, 13 ошибок (0.0788%), p50/p95/p99 успешных запросов — 45.288/195.030/285.894 ms. В конце Compose восстановил 2 здоровых API; `evidence/rolling-update.json` |
| Цена масштабирования, трек 1 | `scripts/track1_benchmark.py --duration 30 --warmup 5 --concurrency 16 --repeats 3` | PASS: все 6 конфигураций, 3 повтора. При фиксированных 4 CPU/2048 MiB: 1/2/4 API дали 161.966/293.019/346.607 успешных RPS; подробности ниже и в `evidence/track1/benchmark.json` |
| Saturation check, concurrency 64 | `scripts/track1_benchmark.py --duration 20 --warmup 5 --concurrency 64 --repeats 2 --output evidence/track1/high-concurrency/benchmark.json` | PASS: шесть конфигураций, по два повтора, ошибок нет. При фиксированном API-бюджете 4 CPU throughput 2→4 вырос только на 9.2%, API достиг пикового агрегированного CPU 376.265%; детали в отдельном JSON |
## Трек 1 — гипотеза и методика
**Гипотеза:** при одном и том же общем CPU/RAM увеличение числа API с 1 до 2 может повысить успешный HTTP throughput за счёт параллельного обслуживания запросов, но затем эффект ограничат общий PostgreSQL/однопоточные ресурсы LB или пул соединений. При росте суммарных ресурсов сравниваются те же профили; увеличение API-процессов не должно скрывать фиксированные ограничения PostgreSQL/Nginx.
`scripts/track1_benchmark.py` выполняет 6 конфигураций: 1/2/4 API при фиксированных 4 CPU и 2048 MiB суммарных лимитов API, затем 1/2/4 API с ростом по 1 CPU и 512 MiB на реплику. На конфигурацию — 5 s прогрева, 3 × 30 s, 16 closed-loop workers; перед тестом сверяет число реально наблюдаемых instance IDs и ждёт обновления DNS-кэша Nginx при необходимости. Между конфигурациями меняется только лимит/число API, PostgreSQL и Nginx остаются с фиксированными лимитами Compose. `docker stats` снимается раз в секунду для API/PostgreSQL/Nginx; JSON включает RPS, ошибки, успешные p50/p95/p99 и пиковые CPU/RAM-сэмплы. После эксперимента Compose возвращается к двум API-репликам.
Фиксированный бюджет API, 4 CPU/2048 MiB: 1→2 реплики повысили throughput с 161.966 до 293.019 RPS (+80.9%), а 2→4 — до 346.607 RPS (+18.3%); p95 для 1/2/4 составил 121.277/103.484/145.922 ms. Для растущего бюджета 1/2/4 CPU и 512/1024/2048 MiB получено 91.964/178.185/346.725 RPS, без ошибок в трёх повторах каждой конфигурации. Четыре реплики при одинаковом суммарном лимите дали практически одинаковый throughput в обеих сериях (346.607/346.725 RPS).
В основной серии была одна переходная ошибка в суммарно однорепличной конфигурации с лимитом 4 CPU (средняя доля 0.0068%); в остальных пяти конфигурациях ошибок не было.
При concurrency=16 насыщение ресурсов не подтверждено: пиковый агрегированный CPU API для фиксированных 4 CPU составил 250.420% при четырёх репликах, PostgreSQL — 67.920%, Nginx — 18.280%. При concurrency=64 throughput для фиксированного бюджета составил 155.580/284.255/310.259 RPS для 1/2/4 реплик; переход 2→4 дал лишь +9.2%, p95 вырос с 274.215 до 458.187 ms, а пиковый CPU API достиг 376.265% из 400% доступных по лимиту. Это указывает на насыщение CPU API и низкую отдачу дальнейшего масштабирования в данной нагрузке; PostgreSQL достиг пика 74.370%, поэтому его насыщение не установлено. Nginx достиг 16.975%. Ошибок в supplemental серии не было. Лимиты памяти API не были близки к исчерпанию. Основные графики находятся в `evidence/track1/`, supplemental-графики и 12 исходных повторов — в `evidence/track1/high-concurrency/`.
Скрипт нагрузки `tests/load.py` не является open-loop генератором и измеряет HTTP-подтверждения, не SQL COMMIT; он подвержен coordinated omission и overhead клиента. Сэмплирование `docker stats` может пропускать короткие пики. Если серия не достигает saturation, это будет указано как ограничение, а не будет выдуман предел БД. Исходные повторы и автоматически построенные SVG-графики являются частью evidence.
## Отказы, улучшение и ограничения
Измеренный failover относится только к процессу API при работающих Nginx, PostgreSQL и Redis на одном Docker host. PostgreSQL, Redis, Nginx, Docker host и host ОС остаются SPOF; их HA и потеря узла не заявляются. Nginx OSS применяет пассивное исключение, поэтому отдельный readiness probe каждого upstream не выполняется активно. Restart Redis с AOF/volume проверен, но это не кластерная репликация и не гарантия потери менее одной секунды при любой аварии.
Проверенный функциональный результат — общий транзакционный ключ идемпотентности: 16 одновременных повторов через балансировщик дают один и тот же Message, несмотря на распределение между экземплярами. Обе API-реплики адресно проверены как цели отказа; подтверждения и действующая сессия сохранились. Под нагрузкой при поочерёдном рестарте сервера подтверждения продолжались; переходные ошибки учтены, а не скрыты. Основной трек и supplemental saturation check завершены; вывод о насыщении ограничен API CPU при concurrency=64, а не переносится на PostgreSQL или весь стенд.