# Отчёт — лабораторная 3 - Автор, группа: Каменски Лин, БПИ2301 - Целевая оценка; выбранный трек 5, если нужен: 5; трек 1 - Commit/PR: [Pull Request 23](https://gitea.privcloud.tech/mtusi2026/mtusi2026lab3/pulls/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 БД для тестов. Пример (значения заменить своими): ```bash 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 ``` Скопировать шаблон переменных окружения: ```bash cp .env.example .env ``` Сборка и запуск: ```bash docker compose up --build -d ``` Готовность API проверяется запросом к `/health/ready`; после этого API доступен на http://localhost:8080. Сваггер доступен на http://localhost:8080/swagger/. Тесты: ```bash 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` сохраняются): ```bash docker compose down ``` Намеренное удаление учебных данных: ```bash 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. Инвалидация кэша: при logout сессия удаляется из PostgreSQL, затем ключ из Redis; сбой удаления ключа логируется и не отменяет logout, устаревший ключ истекает по TTL. Разные запросы одного пользователя обслуживаются разными репликами без повторного входа. 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 реплик](evidence/track1/plots/scaling.png) На ступени 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](evidence/track1/plots/lb_before_after.png) Улучшение подтверждено: 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 контейнеров на пределе](evidence/track1/plots/cpu_at_limit.png) | Воздействие | Что ожидаем | Что наблюдали | | --- | --- | --- | | Рост числа реплик 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`), перезапуск стенда без потери данных. **Не выдерживается или не реализовано:** - Отзыв сессии при сбое Redis. Logout удаляет сессию из PostgreSQL (источник истины), затем ключ из Redis. Если Redis недоступен, ошибка логируется, logout возвращает 204, а прежний токен может приниматься до истечения кэша (до 60 с). Окно не закрыто: для этого нужна проверка сессии в БД на каждый запрос, но тогда кэш теряет смысл. - Отказ 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 не узкое место.