Files
mtusi2026lab3/REPORT.md
2026-10-16 01:30:10 +03:00

28 KiB
Raw Permalink Blame History

Отчёт — лабораторная 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

Шаги:

  1. Клонировать репозиторий и создать локальные секреты и .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
    
  2. Запустить стенд:

    docker compose up -d --build --wait   # = make up
    

    Compose:

    • postgres — 17.2-alpine3.21, volume pgdata, только внутренняя сеть 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).
  3. Дождаться готовности:

    docker compose ps
    

    Ожидаемо: postgres, valkey, api-1, api-2, lb — healthy, migrate — Exited (0).

  4. Прогнать тесты:

    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.

  5. Остановить:

    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. Healthcheck GET /health/ready каждую 1 с (inter 1s fastinter 500ms fall 2 rise 2, timeout check 500ms). Отказ реплики обнаруживается не позже чем за ~2,5 с.

  • Динамическое обнаружение реплик. HAProxy резолвит имя api через Docker DNS 127.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:

    1. проверить членство в чате;
    2. INSERT ключа ON CONFLICT DO UPDATE … WHERE просрочен (перезахват только просроченного ключа);
    3. 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 server HAProxy 10 с; в PostgreSQL statement_timeout 5 с, lock_timeout 2 с.

  • Источник истины — 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

fixed

При том же бюджете 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

growth

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

improvement

Диапазоны min–max не пересекаются, поэтому эффект больше разброса между повторами. Saturation point сдвинулся с ~3,6k до ~4,6k RPS. Его природа не изменилась: при 4 репликах oneshot снова медленнее, чем при 2, потому что очередь на WAL растёт.

Выводы трека:

  1. При фиксированных ресурсах больше реплик — не быстрее. Минимум 2 реплики нужны для отказоустойчивости.
  2. Реплики помогают, пока узкое место — CPU API (здесь до 2 реплик). Дальше упираемся в PostgreSQL (WAL commit).
  3. Поднять потолок можно, уменьшив работу БД на запрос: подтверждено, +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.