Files
mtusi2026lab3/REPORT.md
T

20 KiB
Raw Blame History

Отчёт — лабораторная 3

  • Автор, группа: Каменски Лин, БПИ2301
  • Целевая оценка; выбранный трек 5, если нужен: 5; трек 1
  • Commit/PR: Pull Request 23
  • Использованные источники, библиотеки и помощь ИИ: материалы лабораторной; Go, chi, pgx v5, sqlc, goose, PostgreSQL 18.6, Redis 8.8.3, Nginx 1.31.7, Docker Compose; Claude - для ускорения работы и оформления отчёта

Запуск из чистого clone

Требуются Go 1.26+ и Docker с Compose. Образы: PostgreSQL 18.6, Redis 8.8.3, Nginx 1.31.7.

Создать локальные secrets - файлы в secrets/, в каждый записать значение без лишних символов:

  • database_url.txt - URL PostgreSQL для API;
  • cache_url.txt - URL Redis;
  • postgres_password.txt - пароль пользователя messenger;
  • test_database_url.txt - URL БД для тестов.

Пример (значения заменить своими):

mkdir -p secrets
printf '%s' 'CHANGE_ME' > secrets/postgres_password.txt
printf '%s' 'postgres://messenger:CHANGE_ME@postgres:5432/messenger?sslmode=disable' > secrets/database_url.txt
printf '%s' 'redis://redis:6379/0' > secrets/cache_url.txt
printf '%s' 'postgres://messenger:CHANGE_ME@127.0.0.1:5432/messenger?sslmode=disable' > secrets/test_database_url.txt

Скопировать шаблон переменных окружения:

cp .env.example .env

Сборка и запуск:

docker compose up --build -d

Готовность API проверяется запросом к /health/ready; после этого API доступен на http://localhost:8080.

Сваггер доступен на http://localhost:8080/swagger/.

Тесты:

make test
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh

scripts/stop-one.sh останавливает одну выбранную реплику, остановленную реплику вернуть командой docker compose up -d.

Безопасная остановка (данные в volume pgdata сохраняются):

docker compose down

Намеренное удаление учебных данных:

docker compose down -v

Архитектура и решения

Схема: клиент → load_balancer (Nginx, единственная публичная точка входа, 127.0.0.1:8080) → api × API_REPLICAS (по умолчанию 2) → redis (кэш сессий) и postgres (источник истины). Одноразовый migrate (goose) выполняется до старта API; реплики миграции не запускают. Порты API и Redis наружу не публикуются. Порт PostgreSQL открыт только на 127.0.0.1 для тестов с хоста.

Источник истины - PostgreSQL. API не хранит локального состояния: сессии доступны всем репликам через общее хранилище, режим выбирается переменной SESSION_STORE (postgres | redis). Все проверки и эксперименты lab3 выполнены с SESSION_STORE=redis: Redis хранит кэш сессий с TTL = min(60 с, оставшийся срок сессии), при промахе или недоступности Redis сессия читается из PostgreSQL. Разные запросы одного пользователя обслуживаются разными репликами без повторного входа. Sticky session не используются.

Идемпотентность отправки сообщения общая для всех реплик и хранится в PostgreSQL: таблица idempotency_keys, область ключа - пользователь + метод + путь чата + Idempotency-Key. Проверка ключа и вставка сообщения выполняются в одной транзакции в MessageService. Повтор с тем же ключом и телом возвращает исходный результат без дубля, в том числе при конкурентных запросах через разные реплики; тот же ключ с другим телом даёт 409.

Балансировщик. Nginx резолвит адрес сервиса api через встроенный DNS Docker (resolver 127.0.0.11 valid=2s, proxy_pass через переменную), поэтому список реплик обновляется не позднее чем через 2 с. Таймауты: соединение с репликой устанавливается не дольше 1 с (proxy_connect_timeout), ответ ожидается не дольше 6 с (proxy_read_timeout). При ошибке соединения, таймауте, 502 или 503 запрос передаётся другой реплике (proxy_next_upstream error timeout http_502 http_503, не более 2 попыток). Это относится к POST только пока запрос не передан реплике, переданный запрос Nginx не повторяет. Повтор POST безопасен только за счёт Idempotency-Key на стороне клиента. Проверки пассивные: отдельного активного health check в открытой версии Nginx нет.

Период проверок и обнаружение отказа: Nginx проверяет backend пассивно, healthcheck Docker (период 10 с) на маршрутизацию не влияет. Остановленная реплика исключается не позднее чем через ~3 с (кэш DNS 2 с + proxy_connect_timeout 1 с); по замеру под нагрузкой пропускная способность возвращалась к норме за ~2 с.

Пул соединений: pgxpool, MaxConns = 10 на реплику (при 2 репликах до 20 соединений, при 4 до 40), ConnectTimeout 5 с, statement_timeout 5000 мс.

Ресурсы (лимиты из compose.yaml): api - API_CPUS (по умолчанию 0,5 CPU) и API_MEM (256 МБ) на реплику; postgres - 1,0 CPU, 512 МБ; redis - 0,25 CPU, 128 МБ; load_balancer - LB_CPUS (по умолчанию 0,5 CPU), 128 МБ. container_name не используется, api масштабируется одним параметром API_REPLICAS.

Перенесено из lab2: слои handler и service, PostgreSQL с sqlc/pgxpool, Bearer-сессии, кэш сессий в Redis, миграции goose, скрипт restart.sh. Изменено в lab3: добавлены X-Instance-Id, обязательный Idempotency-Key для отправки сообщения, переключатель режима хранения сессий SESSION_STORE (postgres | redis), Nginx и несколько реплик, лимиты ресурсов, скрипт stop-one.sh; restart.sh теперь выполняет запуск с ожиданием готовности стенда вместо простого перезапуска.

Переменные .env.example: APP_HOST, APP_PORT - адрес и порт API внутри контейнера; MAX_INFLIGHT_REQUESTS - ограничитель одновременных запросов (0 - выключен); SESSION_TTL_SECONDS - срок жизни сессии; LOG_LEVEL - уровень логов; DATABASE_URL_FILE, CACHE_URL_FILE - пути к secrets с URL PostgreSQL и Redis; SESSION_STORE - режим хранения сессий, postgres или redis; IDEMPOTENCY_TTL_SECONDS - срок хранения ключей идемпотентности; API_REPLICAS - число реплик api; API_CPUS, API_MEM - лимиты CPU и памяти каждой реплики; LB_CPUS - лимит CPU Nginx.

Доказательства критериев

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Публичный smoke make test PASS evidence/make-test.txt
Уровень 3
Одна сессия на разных репликах make test-failover ACTION_SCRIPT=scripts/stop-one.sh PASS evidence/make-test-failover.txt
Отказ одной реплики, запись ≤ 10 с make test-failover ACTION_SCRIPT=scripts/stop-one.sh PASS; "first_recovery_seconds": 1.324 evidence/make-test-failover.txt
Идемпотентность между репликами make race-go (TestConcurrentIdempotencyAcrossReplicas) PASS evidence/make-race-go.txt
Сохранность после перезапуска make test-persistence ACTION_SCRIPT=scripts/restart.sh PASS evidence/make-test-persistence.txt
Уровень 4
Последовательная остановка каждой реплики: RPS, ошибки, восстановление make load-action-go LOAD_DURATION=30s REPLICA=1 ACTION_AT=10s, затем docker compose up -d --wait и то же для REPLICA=2 Реплика 1: 0 ошибок, RPS 386,56, просадка до 103 запросов/с, возврат к 400/с за ~2 с; реплика 2: 0 ошибок, RPS 386,66, просадка до 161 запроса/с, ~2 с evidence/make-load-action-go.txt
Rolling update под нагрузкой make load-action-go ACTION=rolling-update.sh LOAD_DURATION=60s ACTION_AT=10s 0 ошибок, RPS 380,98; скрипт отработал за 20,3 с, обе реплики заменены (api-1, api-2 → api-3, api-4); просадки до 189 и 47 запросов/с по ~2–3 с на каждую реплику evidence/rolling-update.txt
Уровень 5
Трек 1: 1/2/4 реплики при бюджете CPU API = 2 RATES="20 40 80" CONFIGS="1:2.0:512M 2:1.0:256M 4:0.5:128M" sh scripts/bench.sh До улучшения, медиана RPS / p95: 1 реплика 586 / 74 мс, 2 реплики 1071 / 65 мс, 4 реплики 1571 / 9,7 мс (target 1600, у предела генератора) evidence/track1/before/, evidence/track1/plots/
Трек 1: 2 реплики, CPU API = 0,5 / 1,0 / 2,0 RATES="20 40 80" CONFIGS="2:0.5:256M 2:1.0:256M 2:2.0:256M" sh scripts/bench.sh Монотонного роста нет: RPS 1254 / 1071 / 1031 до улучшения (диапазоны 706-1259, 735-1273, 810-1241 пересекаются), 1352 / 1347 / 1374 после; CPU API не узкое место evidence/track1/before/, evidence/track1/after/, evidence/track1/plots/
Трек 1: Улучшение LB_CPUS 0,5 → 1,0 то же, что «до», LB_CPUS=1.0, OUT_DIR=evidence/track1/after 2 реплики по 1,0 CPU, ступень 80: RPS 1071 → 1347 (+26 %), p95 64,6 → 23,6 мс, диапазон RPS 735–1273 → 1279–1405, медленных прогонов (p95 > 60 мс) 2 из 3 → 0 из 3 evidence/track1/after/
Трек 1: Saturation point LB_CPUS=1.0 WORKERS=40 RATES="40 60 80" CONFIGS="2:1.0:256M 4:0.5:128M" sh scripts/bench.sh, docker stats При 40 воркерах 4 реплики упираются примерно в 2000 RPS: при росте target 2400 → 3200 RPS не растёт (2018 → 1928), p95 45 → 61 мс; Postgres на 94-103 % квоты evidence/track1/generator_check/, evidence/track1/before/stats/

Эксперименты и отказы

Трек 1: цена масштабирования

Стенд: Docker (PostgreSQL 18.6, Redis 8.8.3, Nginx 1.31.7). Сессии хранятся в Redis (SESSION_STORE=redis) во всех прогонах. Нагрузка: Go-тест TestLoad, 20 воркеров, ступени 20/40/80 запросов/с на воркера (400/800/1600 RPS), прогрев 5 с, прогон 20 с, пауза 5 с, 3 повтора. В таблицах медиана по трём прогонам, данные лежат в evidence/track1/.

Бюджет CPU API зафиксирован (2 CPU). Гипотеза: рост числа реплик повышает RPS, пока не упрёмся в общий компонент (Nginx, Redis или PostgreSQL), а не в CPU API.

Сравнение 1, 2 и 4 реплик с одним суммарным бюджетом (1:2.0, 2:1.0, 4:0.5). Ступень 80, медиана RPS / p95:

Конфигурация RPS p95, мс
1 реплика 586 74
2 реплики 1071 65
4 реплики 1571 9,7

Масштабирование 1/2/4 реплик

На ступени 40 прогоны с 2 репликами делились на быстрые (RPS ≈ 800, p95 ≈ 12 мс) и медленные (RPS 600–700, p95 ≈ 75 мс), поэтому разброс большой.

RPS в таблицах считается по успешным ответам 201. При 1 реплике часть запросов завершалась ответом 502 от Nginx (на ступени 80 до 44 % запросов за прогон после улучшения, до улучшения до 11 %). При 2 и 4 репликах таких ответов нет, вероятно, потому что Nginx повторяет запрос на другой реплике. Поэтому RPS одной реплики занижен и сильно меняется между прогонами (414-808 после улучшения).

Сравнение конфигураций с ростом ресурсов (2:0.5, 2:1.0, 2:2.0). RPS на ступени 80: 1254 / 1071 / 1031, диапазоны прогонов пересекаются, закономерности нет. Можно сделать вывод, что CPU API в этом случае не является узким местом.

Причина медленных прогонов проверялась в docker stats контейнера load_balancer (ступень 40, 2 реплики по 1,0 CPU, LB_CPUS=0,5). В быстром прогоне он держится около 11 % ядра, в медленных на несколько секунд поднимается до 49 % при квоте 0,5 CPU, то есть упирается в лимит. Отсюда гипотеза: при 1-2 репликах узкое место Nginx.

Для проверки подняли квоту Nginx LB_CPUS 0,5 → 1,0 и повторили те же прогоны. Ступень 80, 2 реплики по 1,0 CPU:

До После
Медиана RPS (диапазон) 1071 (735–1273) 1347 (1279–1405)
p95, мс 64,6 23,6
Прогонов с p95 > 60 мс 2 из 3 0 из 3

Квота Nginx 0,5 и 1,0 CPU

Улучшение подтверждено: RPS +26 %, медленный режим исчез. При 4 репликах результат не изменился (1571 → 1572). После улучшения переход с 1 на 2 реплики даёт примерно ×2 (655 → 1347 RPS), с 2 на 4 только ×1,17 (1347 → 1572).

Также выполнили проверку генератора. При 20 воркерах 4 реплики дошли до target 1600, то есть до потолка генератора, поэтому их предел не был виден. Был выполнен прогон с 40 воркерами (4 реплики, target 1600 / 2400 / 3200): RPS 1590 → 2018 → 1928, p95 14 → 45 → 61 мс. Можно сделать вывод, что 4 реплики упираются примерно в 2000 RPS. На этом пределе PostgreSQL использует 94-103 % ядра при квоте 1,0 CPU, то есть работает у лимита, а Redis только 5-8 % ядра (около 20-33 % квоты 0,25 CPU) и Nginx около 22-29 % ядра (квота 1,0 CPU) остаются с запасом. CPU API тоже в запасе. Поэтому рост реплик перестаёт помогать: следующий предел задаёт PostgreSQL, а не API, Nginx или Redis.

CPU контейнеров на пределе

Воздействие Что ожидаем Что наблюдали
Рост числа реплик 1 → 2 → 4 при бюджете API 2 CPU (Nginx 0,5 CPU) RPS растёт, пока не упрёмся в общий компонент Ступень 80: RPS 586 → 1071 → 1571, p95 74 → 65 → 9,7 мс; при 1 реплике часть ответов 502
Рост CPU API при 2 репликах 0,5 → 1,0 → 2,0 (Nginx 0,5 CPU) Если CPU API узкое место, RPS растёт RPS 1254 / 1071 / 1031 до улучшения и 1352 / 1347 / 1374 после, диапазоны пересекаются: CPU API не узкое место
Рост квоты Nginx 0,5 → 1,0 CPU (2 реплики по 1,0 CPU) Исчезнет медленный режим RPS 1071 → 1347, p95 64,6 → 23,6 мс, медленных прогонов 2 из 3 → 0 из 3
Рост нагрузки до 40 воркеров (target до 3200 RPS), 4 реплики, Nginx 1,0 CPU RPS перестанет расти на пределе общего компонента RPS 1590 → 2018 → 1928, p95 14 → 45 → 61 мс; PostgreSQL 94–103 % квоты, Redis 5–8 % ядра, Nginx 22–29 %

Вывод: При фиксированном бюджете CPU API рост числа реплик помогает, но не бесконечно: переход с 1 на 2 реплики даёт примерно ×2 по RPS, с 2 на 4 только ×1,17. CPU самих реплик узким местом не был. При 1-2 репликах предел задавала квота Nginx: удвоение LB_CPUS до 1,0 подтверждённо подняло RPS на 26 % (1071 → 1347) и убрало прогоны с p95 > 60 мс. При 4 репликах предел около 2000 RPS задаёт PostgreSQL (94–103 % квоты 1,0 CPU), поэтому дальнейший рост числа реплик без ресурсов БД, вероятно, не поможет.

Ограничения и следующие шаги

Выдерживается: отказ одной реплики из двух, замена реплик под нагрузкой, повтор POST без дубля (Idempotency-Key), перезапуск стенда без потери данных.

Не выдерживается или не реализовано: отказ PostgreSQL, Redis или Nginx (по одному экземпляру); проверки Nginx пассивные, окно обнаружения отказа до ~3 с; повтор POST Nginx делает только до передачи запроса реплике.

Ограничения измерений:

  • Генератор и стенд на одной машине делят CPU; при 20 воркерах потолок генератора около 1600 RPS.
  • До улучшения прогоны делятся на быстрый и медленный режим, выполнялось по 3 повтора.
  • Все замеры сняты с сессиями в Redis. В режиме сессий из PostgreSQL каждый авторизованный запрос добавляет обращение к БД, а PostgreSQL уже работает у лимита квоты, поэтому saturation наступил бы раньше (не измерялось).

Подтверждено: улучшение LB_CPUS 0,5 → 1,0 при 2 репликах; CPU API не узкое место.