28 KiB
Отчёт — лабораторная 3
- Автор, группа: Кораблев Петр, БВТ2304
- Целевая оценка: 5 (уровень 3 + уровень 4 + трек 1 «Цена масштабирования»)
- Commit/PR: ветка
solution/BVT2304-korablev - Использованные источники, библиотеки и помощь ИИ: Go 1.23.4, net/http, pgx/v5 5.7.2 (pgxpool), go-redis/v9 9.7.0, golang.org/x/crypto (Argon2id), google/uuid 1.6.0,
log/slog. Образы: PostgreSQL 17.2-alpine3.21, Valkey 8.0.2-alpine3.21, HAProxy 3.0.5-alpine, golang:1.23.4-alpine3.21 → alpine:3.21.2, k6 0.54.0 (только трек 1). Документация: Compose services/deploy, HAProxy configuration manual (resolvers, http-check, retry-on), PostgreSQL docs (INSERT … ON CONFLICT, data-modifying CTE). Помощь ИИ использовалась для создания отчета.
Запуск из чистого clone
Prerequisites:
- Docker 29.1.3 (Docker Desktop для Windows + WSL2) с Compose v2
- Python 3.9+ (тесты и генерация секретов)
- Git; make по желанию (на Windows команды можно запускать напрямую через
py -3 ...) - Go локально не нужен: приложение собирается внутри Docker
Шаги:
-
Клонировать репозиторий и создать локальные секреты и
.env:python3 scripts/init_secrets.py # = make secretsСкрипт генерирует случайные пароли в
secrets/(pg_password,database_url,cache_url,valkey_auth.conf) и копирует.env.example→.env. Обе папки исключены из Git и из Docker build context. Пароли передаются контейнерам как Compose secrets (/run/secrets/...), в.envсекретов нет:APP_PORT=8080 SESSION_STORE=valkey SESSION_TTL_SECONDS=3600 SESSION_CACHE_MAX_TTL_SECONDS=60 API_REPLICAS=2 IDEMPOTENCY_TTL_SECONDS=86400 DB_MAX_CONNS=10 # пул на одну реплику API_CPUS=1.0 # лимиты одной реплики API_MEMORY=256M SHUTDOWN_DRAIN_MS=3000 # пауза drain при SIGTERM MESSAGE_WRITE_PATH=oneshot # tx — только для A/B трека 1 -
Запустить стенд:
docker compose up -d --build --wait # = make upCompose:
postgres— 17.2-alpine3.21, volumepgdata, только внутренняя сетьdata, 2 CPU / 1 GiB.valkey— 8.0.2-alpine3.21, кэш сессий с паролем из secret, сетьdata, 0.5 CPU / 128 MiB.migrate— тот же образ с командойmigrate: однократно применяет миграции под advisory lock и завершается.api— 2 реплики (deploy.replicas: ${API_REPLICAS}), безportsи безcontainer_name, 1 CPU / 256 MiB каждая.lb— HAProxy 3.0.5-alpine, единственный опубликованный порт127.0.0.1:8080(и[::1]:8080).
-
Дождаться готовности:
docker compose psОжидаемо: postgres, valkey, api-1, api-2, lb — healthy, migrate — Exited (0).
-
Прогнать тесты:
make check make test make test-persistence ACTION_SCRIPT=scripts/restart.sh make test-failover ACTION_SCRIPT=scripts/stop-one.sh docker compose up -d --wait # вернуть остановленную реплику (= make restore) make test-student # собственные тестыWindows: Python не запускает
.shчерезsubprocess, поэтому рядом лежатscripts/stop-one.cmdиscripts/restart.cmdс теми же командами. Перед тестами нужно выполнить$env:PYTHONUTF8="1", иначе Python читаетcontracts/openapi.jsonв cp1251. Пошаговый сценарий для защиты — вЗАЩИТА.txt. -
Остановить:
docker compose stop # = make downДанные сохраняются в named volume
mtusi-lab3_pgdata.Намеренное удаление:
docker compose down -v
Архитектура и решения
-
Топология. Клиент → HAProxy (LB, порт 8080) → 2 API-реплики (сеть
app, порт 8080 только внутри) → общие PostgreSQL и Valkey (сетьdata). LB не видит БД; пароль БД получают толькоapiиmigrate. -
Балансировка. HAProxy
roundrobin, без sticky. HealthcheckGET /health/readyкаждую 1 с (inter 1s fastinter 500ms fall 2 rise 2,timeout check 500ms). Отказ реплики обнаруживается не позже чем за ~2,5 с. -
Динамическое обнаружение реплик. HAProxy резолвит имя
apiчерез Docker DNS127.0.0.11(server-template api 8 api:8080,hold valid 2s). Масштабирование--scale api=Nне требует правки конфига. -
Повторы на LB.
retry-on conn-failure+option redispatch: запрос пересылается на другую реплику, только если соединение не установилось. POST, который мог дойти до реплики, LB не повторяет: это делает клиент с тем жеIdempotency-Key. -
X-Instance-Id. Hostname контейнера (короткий ID Docker) или
INSTANCE_ID. Ставится самым внешним middleware (instanceIDMiddlewareвsrc/internal/api/middleware.go), поэтому есть в каждом ответе API, включая ошибки и health. Стабилен в жизни процесса. Его же используетstop-oneдля поиска контейнера. -
Идемпотентность. Таблица
message_idempotency(миграция0002), PK(user_id, chat_id, idem_key)= область «пользователь + POST + путь чата + ключ».request_hash— SHA-256 канонического JSON тела (порядок ключей и пробелы не влияют), TTL 24 ч с фоновой очисткой. Логика (store.AddMessageOneShot) — один SQL-оператор с data-modifying CTE:- проверить членство в чате;
INSERTключаON CONFLICT DO UPDATE … WHERE просрочен(перезахват только просроченного ключа);INSERTсообщения, только если ключ захвачен этим запросом.
Ключ и сообщение пишутся атомарно: при сбое не остаётся ни того, ни другого, и клиент может безопасно повторить запрос. При конкурентном повторе через другую реплику PostgreSQL заставляет второй запрос ждать на PK. После коммита первого второй отдельным оператором читает сохранённое сообщение: тот же
201и тот же Message. Другое тело —409. -
Порядок проверок. Токен (401) → доступ к чату (404) → валидация (400). Посторонний с невалидным телом получает 404, а не 400.
-
Graceful shutdown. По SIGTERM
/health/readyсразу отдаёт 503, процесс ещё 3 с обслуживает запросы (это больше максимального времени обнаружения отказа), затем отключает keep-alive и выполняетShutdownс бюджетом 5 с.stop_grace_period: 15s. -
Таймауты согласованы. Контекст запроса в приложении 8 с <
timeout serverHAProxy 10 с; в PostgreSQLstatement_timeout5 с,lock_timeout2 с. -
Источник истины — PostgreSQL. Сессии хранятся в PostgreSQL (SHA-256 токена), Valkey — кэш перед ним (не более 60 с). При отказе Valkey проверка сессии уходит в PostgreSQL; logout в этом случае отвечает 503, чтобы в кэше не осталась отозванная сессия.
-
Пароли. Argon2id (перенесено из lab2).
-
Миграции. Версионируемые SQL в
src/internal/db/migrations, отдельный сервисmigrate,pg_advisory_lock, API ждётservice_completed_successfully. Миграция0002аддитивная, поэтому совместима со старой версией кода при rolling update. -
CPU/RAM-лимиты на всех сервисах (
deploy.resources.limits), включаяmigrateиlb. -
API не публикуют порты: опубликован только LB.
Доказательства критериев
Уровень 3
| Критерий | Команда/сценарий | Результат |
|---|---|---|
| Структура и контракт | make check, make validate |
PASS / PASS (evidence/check-smoke.txt, evidence/validate.txt) |
| Публичный smoke | make test |
PASS: lab3 public API scenario |
| ≥2 API-реплики | docker compose ps |
mtusi-lab3-api-N ×2 healthy, lb healthy, migrate Exited (0) (evidence/infra.txt) |
| Разные реплики обслуживают одну сессию | python scripts/demo/instances.py, student-test no stickiness |
30 запросов одним токеном: 15 / 15 по двум X-Instance-Id, без повторного входа |
| LB — единая точка входа | docker inspect … PortBindings |
порт только у lb; у api/postgres/valkey {} |
| Остановка одной реплики | make test-failover ACTION_SCRIPT=scripts/stop-one.sh |
7/7 PASS, failed_attempts: 0, first_recovery_seconds 3,76–3,91 |
| Идемпотентность | smoke + python scripts/demo/idempotency.py |
повтор → тот же Message, другое тело → 409, без ключа → 400 |
| make test-persistence | make test-persistence ACTION_SCRIPT=scripts/restart.sh |
PASS; StartedAt всех контейнеров до и после разный (evidence/persistence.txt) |
Уровень 4
| Критерий | Команда/сценарий | Результат |
|---|---|---|
| LB исключает недоступный backend, SIGTERM | python scripts/failover_series.py --mode stop |
остановленная реплика последний раз ответила через 1,4–1,6 с; 0 ошибок при ~800 RPS |
| Последовательная остановка каждой реплики | make test-failover по обеим репликам + failover_series.py (stop и kill) |
обе реплики остановлены по очереди с восстановлением; все PASS |
| Параллельная идемпотентность | make test-student (concurrent replay) |
24 параллельных запроса через 2 реплики → 1 сообщение |
| CPU/RAM-лимиты | docker inspect … NanoCpus/Memory |
на всех сервисах (evidence/infra.txt) |
| API не публикуют порты | docker compose ps |
у api только 8080/tcp внутри сети, порт на хосте только у lb |
| Нет container_name | grep container_name compose.yaml |
пусто; масштабирование --scale api=N работает |
| Rolling update под нагрузкой | python scripts/rolling_update.py |
0 ошибок, 812 RPS во время замены, обе реплики на новом образе |
| Миграции однократно и совместимо | сервис migrate + повторный docker compose run --rm migrate в rolling update |
Exited (0), migrations up to date; 0002 только добавляет таблицу |
Метрики failover
Публичный тест, 7 прогонов. Остановлены обе реплики: api-8 (прогоны 1–6) и api-10 (прогон 7, после сдвига round-robin одним запросом):
{"observed_instances_before": 2, "successful_writes": 136, "failed_attempts": 0, "first_recovery_seconds": 3.888}
{"observed_instances_before": 2, "successful_writes": 137, "failed_attempts": 0, "first_recovery_seconds": 3.869}
{"observed_instances_before": 2, "successful_writes": 136, "failed_attempts": 0, "first_recovery_seconds": 3.763}
{"observed_instances_before": 2, "successful_writes": 138, "failed_attempts": 0, "first_recovery_seconds": 3.842}
{"observed_instances_before": 2, "successful_writes": 139, "failed_attempts": 0, "first_recovery_seconds": 3.913}
{"observed_instances_before": 2, "successful_writes": 137, "failed_attempts": 0, "first_recovery_seconds": 3.806}
{"observed_instances_before": 2, "successful_writes": 139, "failed_attempts": 0, "first_recovery_seconds": 3.905}
Интерпретация:
observed_instances_before: 2— балансировка работала до отказа, sticky нет.failed_attempts: 0— ни один запрос не получил ошибку: реплика при SIGTERM сначала выходит из ротации (readiness 503, HAProxy исключает её за ≤2,5 с) и только потом завершается (drain 3 с).first_recovery_seconds: ~3,8— тест считает восстановление от старта hook до первой успешной записи после завершения hook. Почти всё это время уходит на самdocker stopс 3-секундным drain; запись при этом не прерывалась. Требование lab3 — ≤10 с.- После теста
docker ps -aпоказывает именно этот контейнер в состоянииExited (0)(evidence/failover.txt).
Отказ каждой реплики под нагрузкой
scripts/failover_series.py: 8 потоков closed-loop POST через LB, таймаут клиента 2 с. Неопределённый POST повторяется с тем же ключом, в конце вся история сверяется с подтверждёнными 201.
{"replica": "mtusi-lab3-api-10", "action": "docker stop", "errors": 0, "ok_rps_before": 802.0, "ok_rps_after": 805.1, "target_last_served_s": 1.57, "back_in_rotation_s": 5.87}
{"replica": "mtusi-lab3-api-8", "action": "docker stop", "errors": 0, "ok_rps_before": 651.6, "ok_rps_after": 747.4, "target_last_served_s": 1.42, "back_in_rotation_s": 6.1}
{"replica": "mtusi-lab3-api-10", "action": "docker kill", "errors": 4, "ok_rps_before": 704.2, "ok_rps_after": 582.1, "last_error_s": 0.1, "back_in_rotation_s": 6.1}
{"replica": "mtusi-lab3-api-8", "action": "docker kill", "errors": 2, "ok_rps_before": 729.6, "ok_rps_after": 618.4, "last_error_s": 0.12, "back_in_rotation_s": 5.89}
Проверка данных: stop — stored 38100 = confirmed 38100, lost 0, duplicates 0; kill — stored 32533 = confirmed 32533, lost 0, duplicates 0.
Интерпретация: при штатной остановке (SIGTERM) ошибок нет совсем. При crash (docker kill, без SIGTERM) 2–4 запроса, которые были в работе у убитого процесса, получили 502 от LB в первые 0,1 с. Клиент повторил их с тем же ключом, поэтому нет ни потерь, ни дублей. В первую секунду после kill p99 ≈ 1 с — это timeout connect к исчезнувшему адресу, после которого срабатывает redispatch. Восстановленная реплика возвращается в ротацию через ~6 с после docker start (старт, затем 2 успешные проверки).
Метрики rolling update
scripts/rolling_update.py: сборка нового образа → миграции один раз → для каждой старой реплики: поднять новую (surge +1) → дождаться healthy и появления в ротации → docker stop старой (drain) → удалить.
{
"before_rollout_5s": {"ok_rps": 789.2, "errors": 0, "p50_ms": 6.8, "p95_ms": 28.0, "p99_ms": 31.8},
"during_rollout": {"seconds": 27.61, "ok": 22423, "errors": 0, "ok_rps": 812.1, "p50_ms": 7.2, "p95_ms": 26.7, "p99_ms": 31.2},
"after_rollout_5s": {"ok_rps": 804.6, "errors": 0, "p50_ms": 6.7, "p95_ms": 29.1, "p99_ms": 31.8},
"client_retries": 0,
"all_new_label": true,
"data_check": {"stored_messages": 30400, "confirmed_201": 30400, "lost_confirmed": 0, "duplicate_texts": 0}
}
Интерпретация: обе реплики заменены на образ final-rollout без единой ошибки и без retry. Пропускная способность во время замены не просела: в каждый момент работают ≥2 реплики, старая уходит только после того, как новая принимает трафик.
Параллельная идемпотентность
PASS concurrent replay of one key through different replicas -> exactly one message - 24 parallel requests via 2 replicas -> 1 message
PASS replay is semantic: JSON key order/whitespace does not matter; other body -> 409
PASS key scope = user + chat: same key is independent for other user / other chat
PASS replay re-checks the session and chat access
8/8 passed
24 потока одновременно отправили POST с одним Idempotency-Key и одинаковым телом через обе реплики. Все получили 201 с одним и тем же Message, в истории одно сообщение. Тот же ключ с другим телом даёт 409 и не перезаписывает сохранённый результат.
Эксперименты и отказы
| Воздействие | Ожидаем | Наблюдали | Восстановление / потери |
|---|---|---|---|
docker stop api-10, затем api-8, под нагрузкой |
Вторая продолжает, drain без ошибок | 0 ошибок, RPS 802→805 и 652→747 | без перерыва; возврат в ротацию ~6 с; потерь 0 |
docker kill api-10, затем api-8, под нагрузкой |
Ошибки только у запросов «в полёте» | 4 и 2 ответа 502 в первые 0,1 с |
клиент повторил с тем же ключом; потерь 0, дублей 0 |
Публичный test-failover, 7 прогонов |
≤10 с, нет потерь | 7/7 PASS, 0 failed_attempts | ~3,8 с (длительность docker stop) |
| Перезапуск всего стека с volumes | Данные и сессия выживают | PASS persistence | данные и прежний токен на месте |
| Параллельные POST с одним ключом | Одно сообщение | 24 → 1 | — |
| Rolling update под нагрузкой | Без ошибок | 0 ошибок, 812 RPS | замена ~28 с; потерь 0 |
Трек 1. Цена масштабирования
Гипотеза. При фиксированном суммарном CPU/RAM больше реплик — не быстрее. При росте числа реплик пропускная способность упрётся в единственный PostgreSQL (2 CPU), а именно в фиксацию транзакций. Поднять потолок можно, уменьшив работу БД на запрос, а не добавляя реплики.
Методика (scripts/track1/run_track1.py, сценарий infra/k6/track1.js):
- Генератор. k6 0.54 в контейнере внутри сети стенда (
lb:8080) с лимитом 4 CPU. Контроль: при 8 CPU у k6 получилось 3516 RPS против 3474, значит k6 не ограничивает. - Профиль. Closed model: 128 VU без пауз, 70%
POST /messages(уникальный ключ), 30%GET /messages?limit=20. 32 синтетических пользователя, у каждого свой чат. - Измерение. Прогрев 10 с, замер 30 с, 3 повтора, конфигурации чередуются (A, B, C, A, B, C…).
- Метрики. Параллельно снимаются
docker stats(CPU и RAM по сервисам) иpg_stat_activity(активные backend и события ожидания). - Фиксировано: PostgreSQL 2 CPU / 1 GiB, LB 1 CPU.
- Стенд: i7-14700KF, 64 GB RAM, Windows 11, Docker Desktop (WSL2).
- Данные: сырые —
evidence/track1/raw/, сводка —evidence/track1/summary.mdиresults.json, графики —evidence/track1/*.svg.
Серия 1. Фиксированный бюджет API (2 CPU, 512 MiB, 20 соединений с БД на всех):
| Раскладка | RPS, среднее (min–max) | p50 / p95 / p99, мс | CPU api / pg, % ядра |
|---|---|---|---|
| 1 × 2.0 CPU, пул 20 | 3636 (3272–3835) | 26,6 / 63,7 / 71,6 | 179 / 171 |
| 2 × 1.0 CPU, пул 10 | 3537 (3519–3572) | 30,2 / 79,4 / 91,3 | 182 / 154 |
| 4 × 0.5 CPU, пул 5 | 3110 (2985–3204) | 31,3 / 96,7 / 121,9 | 187 / 146 |
При том же бюджете 4 мелкие реплики дают на 14% меньше RPS, а p95 у них в 1,5 раза выше. Маленькая CPU-квота чаще троттлит Go-рантайм, а пул из 5 соединений быстрее превращается в очередь. Реплики нужны ради отказоустойчивости, а не ради скорости.
Серия 2. Рост числа реплик (по 1 CPU / 256 MiB / пул 10):
| Реплик | RPS (min–max) | Прирост | CPU api (сумма) / pg | Активных backend PG | Главное ожидание PG |
|---|---|---|---|---|---|
| 1 | 2051 (2033–2065) | — | 95 / 82 | 5,6 | WALWriteLock 4,4 |
| 2 | 3440 (3264–3564) | +68% | 188 / 161 | 9,3 | WALWriteLock 7,7 |
| 4 | 3645 (3559–3740) | +6% | 198 из 400 / 187 из 200 | 28,4 | WALWriteLock 24,4 |
| 8 | 3408 (3334–3494) | −7% | 185 из 800 / 180 | 48,3 | WALWriteLock 40,4 |
Saturation point ≈ 3,6k RPS, узкое место — PostgreSQL.
- С 1 до 2 реплик упиралась сама реплика API (95% CPU).
- С 4 реплик API загружен наполовину, а PostgreSQL — на 187% из 200%. Очередь в нём растёт с числом соединений (9 → 28 → 48), ~85% из них ждут
WALWriteLock, то есть фиксацию журнала при commit. - 8 реплик медленнее 4: больше соединений — длиннее очередь.
- LB (~47% одного CPU) и Valkey (<10%) не ограничивают.
Подтверждённое улучшение: запись сообщения одним SQL-оператором. Было (tx): 5 обращений к БД на сообщение — SELECT членства, BEGIN, INSERT ключа, INSERT сообщения, COMMIT. Стало (oneshot): 1 оператор с CTE. Гарантии те же (атомарность, ожидание конкурента на PK), durability не ослаблена: fsync и synchronous_commit не трогались. A/B на одном образе (MESSAGE_WRITE_PATH), по 3 повтора, вперемешку:
| Конфигурация | tx: RPS, p95 | oneshot: RPS, p95 | Эффект |
|---|---|---|---|
| 2 × 1 CPU | 3390 (3374–3419), 80,0 мс | 4579 (4453–4681), 61,4 мс | +35% RPS, −23% p95 |
| 4 × 1 CPU | 3474 (3249–3600), 87,6 мс | 4301 (4241–4350), 79,0 мс | +24% RPS, −10% p95 |
Диапазоны min–max не пересекаются, поэтому эффект больше разброса между повторами. Saturation point сдвинулся с ~3,6k до ~4,6k RPS. Его природа не изменилась: при 4 репликах oneshot снова медленнее, чем при 2, потому что очередь на WAL растёт.
Выводы трека:
- При фиксированных ресурсах больше реплик — не быстрее. Минимум 2 реплики нужны для отказоустойчивости.
- Реплики помогают, пока узкое место — CPU API (здесь до 2 реплик). Дальше упираемся в PostgreSQL (WAL commit).
- Поднять потолок можно, уменьшив работу БД на запрос: подтверждено, +24…35%. Следующие шаги — более мощная БД, ограничение суммарного пула или pgbouncer, реплики БД для чтения.
Ограничения измерения:
- Один хост: k6, LB, API и БД делят CPU и виртуальный диск WSL2. Переносить можно только относительные выводы, не абсолютные числа.
- Closed model; open model (arrival rate) не исследовалась.
docker statsдаёт средние с шагом ~2 с.- Отдельную серию с ростом CPU PostgreSQL я не проводил: вывод об узком месте основан на загрузке CPU (~93% лимита) и доминирующих ожиданиях WAL.
Ограничения и следующие шаги
- SPOF: LB (HAProxy), PostgreSQL и сам Docker-хост — единственные экземпляры. Падение LB делает сервис недоступным, падение PostgreSQL даёт 503. Это осознанное ограничение lab3: несколько API-процессов не делают БД или LB высокодоступными (это тема трека 2 «Отказ узла»).
- Crash реплики: запросы, которые были в работе, получают
502от LB (2–4 за отказ при ~700 RPS). Безопасно повторять только POST сообщения с ключом. Создание пользователя или чата вслепую повторять нельзя (контракт). - Valkey без persistence: это кэш, источник истины — PostgreSQL. При его рестарте сессии перечитываются из БД.
- Rolling update сделан скриптом (в Compose нет встроенного rolling update). Миграции совместимы, пока они аддитивные. Для удаляющих или переименовывающих миграций нужен expand/contract в два релиза.
- Детерминированный round-robin: публичный failover-тест после восстановления попадает в ту же реплику. Для второй реплики очередь сдвигалась одним дополнительным запросом к LB.
- Учебные упрощения:
X-Instance-Idраскрывает ID контейнера (в lab7 нужен случайный alias); HTTP без TLS; путьtxоставлен в коде только для воспроизводимости A/B трека 1.