24 KiB
Отчёт — лабораторная 3
- Автор, группа: Пластинин Денис, БВТ2303
- Целевая оценка: 5
- Выбранный трек: 1 — цена масштабирования
- Ветка/PR:
solution/bvt2303-plastinin, PR #1 - Среда эксперимента: Docker,
linux/arm64, Go 1.26.5
Запуск из чистого clone
Требуются Git, Docker Engine с Docker Compose v2 и свободные локальные порты 8080, 8081, 9090 и 3000. Все внешние образы закреплены по версиям. Локальные пароли из примера предназначены только для изолированного стенда. Compose передаёт каждому контейнеру только нужные ему переменные: API получает строки подключения PostgreSQL/Valkey без отдельных исходных паролей и пароля Grafana, а migrate — только настройки PostgreSQL и миграций.
cp lab3.env.example .env
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --scale api=2 --wait --wait-timeout 120
Compose сначала ожидает PostgreSQL, затем однократно запускает контейнер migrate. API-реплики стартуют только после успешного завершения миграций. Единственная публичная точка API — Nginx на http://localhost:8080; порты отдельных API-контейнеров на хост не публикуются.
Доступные интерфейсы:
- Swagger UI:
http://localhost:8081; - Prometheus:
http://localhost:9090; - Grafana:
http://localhost:3000, логинadmin, локальный пароль берётся из.env; - Nginx API:
http://localhost:8080.
Проверки запущенного стенда:
make check
make test
docker compose --profile tests run --rm --build tests
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
Безопасная остановка сохраняет данные в named volumes:
docker compose stop
Повторный запуск выполняется командой docker compose up -d --scale api=2 --wait. Намеренное удаление всех учебных данных:
docker compose down -v
Архитектура и решения
flowchart LR
C[Клиент] -->|HTTP :8080| N[Nginx]
N --> A1[API replica 1]
N --> A2[API replica 2]
N -. scale .-> AN[API replica N]
A1 --> P[(PostgreSQL)]
A2 --> P
AN --> P
A1 --> V[(Valkey)]
A2 --> V
AN --> V
M[Однократный migrate] --> P
PR[Prometheus] --> A1
PR --> A2
PR --> NE[Nginx exporter]
PR --> PE[PostgreSQL exporter]
PR --> VE[Valkey exporter]
G[Grafana] --> PR
PostgreSQL является источником истины для пользователей, чатов, сообщений и записей идемпотентности. Valkey хранит общие сессии, поэтому запросы с одним bearer token могут обслуживаться разными API-репликами. В Valkey ключ имеет вид session:<sha256(token)>, а значением служит JSON с user_id и сроком действия. Исходный случайный 256-битный токен возвращается клиенту один раз и не записывается в хранилище.
API остаётся stateless относительно пользовательских данных. Локально в процессе находятся только конфигурация, подключения, метрики конкретной реплики и флаг readiness. Каждый HTTP-ответ содержит X-Instance-Id, равный hostname контейнера.
Балансировка и отказ реплики
Nginx OSS 1.30.5 использует round-robin, Docker DNS 127.0.0.11, повторное разрешение имени api каждые 2 секунды и общий upstream zone. Keep-alive соединения ограничены 32. Таймаут подключения равен 1 секунде, таймауты отправки и чтения — 10 секунд. Ошибка соединения или ответ 502/503/504 временно исключают backend на 3 секунды; небезопасные POST автоматически не повторяются.
Docker проверяет /health/ready каждой API-реплики раз в 2 секунды с таймаутом 1 секунду. Readiness обращается к PostgreSQL и Valkey. При SIGTERM приложение сначала снимает readiness, затем вызывает http.Server.Shutdown с лимитом 5 секунд; Compose даёт контейнеру 8 секунд до принудительной остановки.
Nginx OSS в этом стенде использует пассивное исключение backend. Docker healthcheck не передаёт своё состояние напрямую в Nginx. Поэтому верхняя практическая граница обнаружения отказа складывается из connect timeout и fail timeout; в проверках восстановление произошло примерно за 1.4 секунды, что ниже требуемых 10 секунд.
Общая идемпотентность
Для POST /api/v1/chats/{chat_id}/messages обязателен один заголовок Idempotency-Key длиной до 128 символов. Область ключа — (user_id, chat_id, key), поэтому одинаковая строка независима для другого пользователя или чата. Минимальный TTL равен 24 часам.
Запись сообщения и запись идемпотентности создаются в одной транзакции PostgreSQL:
- Проверяется участие пользователя в чате.
- Из текста считается SHA-256 для выявления повторного использования ключа с другим запросом.
- Строка идемпотентности блокируется через
SELECT ... FOR UPDATE; конкурентные вставки разрешаются первичным ключом иON CONFLICT DO NOTHING. - Победившая транзакция резервирует UUID сообщения и вставляет сообщение. Отложенный внешний ключ проверяется при commit.
- Повтор с тем же телом читает исходное сообщение и возвращает тот же объект. Повтор с другим телом получает
409 Conflict.
Это позволяет безопасно повторить POST после timeout: подтверждённая ранее запись не дублируется, даже если повтор попал на другую реплику. Каждый успешный запрос также удаляет до 100 истёкших записей по индексу expires_at; SKIP LOCKED не даёт параллельным репликам ждать одну и ту же пачку.
Миграции, обновление и развёртывание
API не выполняет DDL при старте. Отдельная команда /app/messenger migrate берёт advisory lock и применяет versioned SQL один раз. Миграция идемпотентности только добавляет таблицу и индекс, поэтому совместима с уже работающей предыдущей версией.
scripts/rolling-update.sh собирает образы, запускает миграции, временно увеличивает число API с двух до трёх и поочерёдно заменяет старые контейнеры. Скрипт ждёт health каждого состава и затем возвращает две реплики. Workflow deploy запускается только вручную из main через workflow_dispatch; перед подключением к серверу он повторяет check, formatting, Go tests и build для SHA запуска. На сервере выполняется reset именно на этот SHA, даже если main успел измениться. Для SSH используются environment secrets DEPLOY_HOST, DEPLOY_USER, DEPLOY_SSH_KEY и заранее проверенный DEPLOY_KNOWN_HOSTS; изменяемых actions для SSH нет.
Наблюдаемость
HTTP middleware каждой реплики публикует число запросов по route/status class, histogram latency, in-flight gauge, число replay идемпотентности, Go runtime и process metrics. Prometheus использует DNS service discovery имени api с периодом обновления 2 секунды и отдельно опрашивает Nginx, PostgreSQL и Valkey exporters каждые 5 секунд. Данные хранятся в Prometheus TSDB с retention 7 суток в named volume.
Provisioned dashboard Grafana показывает общий RPS, RPS и p95 по репликам, классы HTTP-ответов, число healthy replicas, in-flight, heap, replay rate, активные соединения и запросы Nginx, соединения PostgreSQL и состояние Valkey.
Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|---|---|---|---|
| Публичный smoke | make test через Nginx |
PASS: регистрация, сессия, чат, пагинация, доступ и идемпотентность | evidence/lab3-verification.txt |
| Общие сессии и ≥2 реплики | make test-failover ACTION_SCRIPT=scripts/stop-one.sh |
Одна сессия обслужена двумя instance ID | evidence/lab3-verification.txt |
| Конкурентная идемпотентность | Go black-box через Nginx и database integration suite | 16 одновременных HTTP-запросов обработаны минимум двумя instance ID и вернули один message ID; история содержит одну запись | evidence/lab3-verification.txt |
| Сохранность | make test-persistence ACTION_SCRIPT=scripts/restart.sh |
API, PostgreSQL и Valkey перезапущены; старые данные и token доступны | evidence/lab3-verification.txt |
| Отказ API | Два запуска failover с остановкой разных реплик | 125–131 успешная запись; 0–1 переходная ошибка; восстановление 1.35–1.44 с; дублей нет | evidence/lab3-verification.txt |
| Rolling update | 60 секунд Go-нагрузки и scripts/rolling-update.sh |
134894 подтверждения, 2248.16 RPS, 0 ошибок, p95 13.12 ms | evidence/lab3-rolling-update.json |
| CPU/RAM-лимиты | docker compose config и scale experiment |
Лимиты заданы всем сервисам; при 128 MiB API не хватает памяти для Argon2id, поэтому рабочий минимум эксперимента — 256 MiB | evidence/lab3-verification.txt |
| Трек 1 | scripts/run-scale-experiment.sh |
1/2/4 реплики, два бюджета, concurrency 8/32/64, три повтора | evidence/lab3-scale-results.json, evidence/lab3-scale-rps.svg |
Эксперименты и отказы
Методика исследования масштабирования
Гипотеза: при фиксированном суммарном бюджете дробление ресурсов между большим числом процессов сначала улучшит распределение конкурентных запросов, но затем проиграет из-за меньших CPU-квот и пулов каждой реплики. При добавлении одинаковых ресурсов на реплику RPS должен расти до насыщения PostgreSQL или Nginx.
Используется Go-клиент cmd/lab3experiment. Он создаёт отдельного пользователя, сессию и чат, прогревает стенд 2 секунды, затем 6 секунд выполняет closed-loop POST сообщений через Nginx. Для каждого запроса генерируется уникальный idempotency key. Считаются только HTTP-подтверждения; автоматических retry измеряемого трафика нет. Для каждой точки используются concurrency 8, 32 и 64 и три изолированных повтора с новой базой.
CPU и Nginx RPS считаются по разности монотонных process_cpu_seconds_total и nginx_http_requests_total, прочитанных непосредственно до и после измеряемого интервала. Поэтому bootstrap, warmup и простой между точками в них не входят. Resident memory и число healthy replicas снимаются после нагрузки с /metrics каждой реплики, соединения PostgreSQL — instant query к Prometheus. Короткая контрольная точка дала 2355.97 client RPS и 2359.64 RPS по Nginx-счётчику, расхождение 0.16%.
Фиксированная серия имеет общий бюджет API 2 CPU и 1 GiB RAM: 1×(2 CPU, 1 GiB), 2×(1 CPU, 512 MiB), 4×(0.5 CPU, 256 MiB). Пулы PostgreSQL соответственно равны 16, 8 и 4 соединениям на реплику. В растущей серии каждая реплика получает 1 CPU, 256 MiB и пул 8, поэтому суммарный бюджет растёт вместе с числом процессов.
Предварительный прогон с общим лимитом 512 MiB показал, что вариант 4×128 MiB не выполняет регистрацию: базовое потребление процесса около 71 MiB, а Argon2id временно требует ещё 64 MiB. Cgroup завершает реплику, Nginx наблюдает premature upstream close. Этот результат определил минимальный рабочий лимит 256 MiB и не включён в сравнение throughput.
Медианные результаты фиксированного суммарного бюджета:
| Concurrency | 1 реплика: RPS / p95 ms | 2 реплики: RPS / p95 ms | 4 реплики: RPS / p95 ms |
|---|---|---|---|
| 8 | 2412 / 5.86 | 2484 / 5.59 | 2242 / 6.35 |
| 32 | 2731 / 18.63 | 2365 / 24.93 | 2013 / 34.58 |
| 64 | 2733 / 32.99 | 2198 / 55.06 | 2103 / 67.89 |
При фиксированных 2 CPU и 1 GiB увеличение числа процессов не даёт линейного выигрыша. Две реплики дают небольшой выигрыш только при concurrency 8, одна быстрее при 32 и 64, а четыре проигрывают во всех профилях из-за квоты 0.5 CPU на процесс и расходов четырёх runtime. Для рабочего стенда две реплики остаются осознанным компромиссом ради отказоустойчивости, дальнейшее дробление бюджета не оправдано.
Медианные результаты серии с 1 CPU и 256 MiB на каждую реплику:
| Concurrency | 1 реплика: RPS / p95 ms | 2 реплики: RPS / p95 ms | 4 реплики: RPS / p95 ms |
|---|---|---|---|
| 8 | 2712 / 4.95 | 2554 / 5.28 | 2185 / 7.05 |
| 32 | 2818 / 15.34 | 2471 / 21.94 | 2130 / 24.14 |
| 64 | 2044 / 61.44 | 2239 / 57.76 | 1859 / 67.42 |
Даже при росте суммарного CPU практический предел не превышает двух реплик. При concurrency 64 переход 1→2 повышает медианный RPS на 9.6%, а 2→4 снижает его на 17.0%. Одновременно число соединений PostgreSQL растёт 9→17→33, суммарная resident memory — примерно 36→65→397 MiB, а p95 у четырёх реплик достигает 67.42 ms. Точная средняя загрузка API составляет примерно 0.43→0.52→0.54 core при доступных 1→2→4 core. API не упирается в CPU-квоту. Вместе с ростом DB connections и tail latency это указывает на насыщение общего пути PostgreSQL/Nginx/network и расходы дополнительных процессов, но данный эксперимент не разделяет вклад этих компонентов.
Во всех 54 основных точках было 0 HTTP-ошибок; каждая конфигурация наблюдала все заявленные реплики. Диапазоны трёх повторов заметно пересекаются и доступны в raw JSON, поэтому небольшие отличия нельзя считать точной оценкой абсолютной производительности.
Для настройки пула конфигурация 4×0.5 CPU, 256 MiB при concurrency 64 дополнительно сравнивалась с 10 и 4 соединениями PostgreSQL на реплику:
| Пул на реплику | Median RPS | p50 / p95 / p99, ms | Соединения PostgreSQL | Ошибки |
|---|---|---|---|---|
| 10 | 1918 | 30.00 / 59.52 / 101.70 | 41 | 0 |
| 4 | 2179 | 23.61 / 66.76 / 80.91 | 17 | 0 |
Уменьшение пула 10→4 сократило число соединений на 58.5%, повысило медианный RPS на 13.6%, уменьшило p50 на 21.3% и p99 на 20.4%. p95 вырос на 12.2%, то есть распределение задержек изменилось неравномерно. Для данного стенда выбран пул 4: он соответствует CPU-квоте 0.5 core и заметно снижает давление на общую БД. При строгом SLO на tail latency значение следует подбирать повторно на более длинном open-loop тесте.
Итоговый график находится в evidence/lab3-scale-rps.svg, обезличенные исходные точки, медианы и диапазоны — в evidence/lab3-scale-results.json.
Отказ и обновление
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|---|---|---|---|
| SIGTERM одной API-реплики | Nginx исключает backend, другая реплика продолжает работу | 0–1 переходная ошибка, старый instance ID исчез из последующих ответов | 1.35–1.44 с; подтверждённые сообщения сохранены, дублей нет |
| Полный restart API, PostgreSQL и Valkey без удаления volumes | Данные и сессия сохраняются | Старый bearer token и созданные сущности доступны после запуска | В пределах 90-секундного окна теста; потерь не обнаружено |
| Rolling update API 2→3→2 | Во время замены остаются healthy backend | 134894 успешных POST, 0 ошибок; наблюдались старые и новые instance ID | Перерыва по подтверждённым ответам не зафиксировано |
| Остановка PostgreSQL или Valkey | Readiness становится отрицательной | Все API теряют готовность, потому что хранилища общие | Автоматический failover хранилищ не реализован |
Ограничения и следующие шаги
- Все компоненты работают на одном Docker-хосте. Отказ хоста, Nginx, PostgreSQL или Valkey останавливает сервис; выполнен отказ процесса API, а не отказ узла.
- Nginx является одной публичной точкой и SPOF. Для эксплуатации потребуются несколько LB с внешним virtual IP или управляемый балансировщик.
- PostgreSQL и Valkey не реплицированы. AOF Valkey с
appendfsync everysecограничивает возможную потерю примерно последней секундой при аварии хранилища, но этот сценарий в работе не заявляется как защищённый. - Нагрузочный клиент closed-loop и подвержен coordinated omission. Результаты сравнивают конфигурации на одной машине и не являются абсолютной производительностью production-системы.
- Все реплики и клиент делят ресурсы одного хоста; дельта process CPU показывает потребление API, а не полную стоимость Docker/network/storage.
- Для эксплуатации нужны TLS, внешнее управление secrets, репликация хранилищ, алерты и длительный soak test; при большом потоке следует отдельно измерить стоимость пакетной очистки idempotency records.
Источники и инструменты
- Nginx upstream и динамическое DNS: https://nginx.org/en/docs/http/ngx_http_upstream_module.html
- Docker Compose services и healthcheck: https://docs.docker.com/reference/compose-file/services/
- PostgreSQL explicit locking: https://www.postgresql.org/docs/current/explicit-locking.html
- Valkey persistence: https://valkey.io/topics/persistence/
- Argon2: RFC 9106, https://www.rfc-editor.org/rfc/rfc9106
- Go packages:
pgx/v5,valkey-go,prometheus/client_golang,google/uuid,viper,x/crypto/argon2. - OpenAI Codex использовался для подготовки кода, конфигурации и текста; реализация и результаты проверены запуском тестов и экспериментов.