Files
mtusi2026lab3/REPORT.md
T
Weinmaier_AndrewandClaude Opus 5.5 7366f430ca lab3: результаты Docker-стенда и трека 1, отчёт
- доказательства уровней 3–4 (прогон 2 на GitHub runner)
- трек 1: 129 прогонов серий A–E, анализ, графики, подтверждённое улучшение
- Dockerfile: базовые образы закреплены по digest
- собственные тесты перенесены в student-tests/

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-23 18:06:45 +03:00

30 KiB
Raw Blame History

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

  • Автор, группа: Вейнмайер Андрей Андреевич, БВТ2303
  • Целевая оценка: 5 (уровни 3, 4 и трек 1 «Цена масштабирования»)
  • Commit/PR: ветка solution/bvt2303-weinmaier в https://gitea.privcloud.tech/WeinmaierAndrew/mtusi2026lab3, PR в mtusi2026/mtusi2026lab3
  • Основа: собственная lab2 — https://gitea.privcloud.tech/WeinmaierAndrew/mtusi2026lab2
  • Использованные источники:
    • Контракт: contracts/openapi.json, contracts/README.md (раздел «Балансировка и повторная отправка»)
    • Go: net/http (Server.Shutdown), log/slog, sync/atomic, crypto/sha256
    • Библиотеки: github.com/jackc/pgx/v5, github.com/redis/go-redis/v9, golang.org/x/crypto/argon2
    • Документация: HAProxy 3.0 (server-template, resolvers, http-check, retry-on), Docker Compose services/deploy, PostgreSQL INSERT … ON CONFLICT
    • AI-ассистент (Claude) использован для переноса кода lab2, реализации идемпотентности, конфигурации LB, скриптов, генератора нагрузки и анализа. Все результаты ниже — реальные прогоны, ссылки на них приведены.

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

Версии

Компонент Образ / версия
API builder / runtime golang:1.26-alpine / alpine:3.20, закреплены по digest в Dockerfile (multi-stage, static, USER 1001)
LB haproxy:3.0.5-alpine
БД postgres:16.4-alpine
Сессии + кэш redis:7.4.1-alpine (AOF, appendfsync everysec)
Миграции migrate/migrate:v4.17.0

Prerequisites: Docker Engine/Desktop с Compose v2, Python 3.9+, POSIX shell (Linux/macOS/WSL или Git Bash).

Команды

# 1. Локальные .env и secrets/ (случайный пароль БД; повторный запуск ничего не перезаписывает)
sh scripts/init-secrets.sh

# 2. Проверка и запуск: postgres/redis → migrate (однократно) → api ×2 → lb
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --wait

# 3. Готовность и проверки
curl -i http://localhost:8080/health/ready
make test
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
sh scripts/restore.sh                       # вернуть остановленную реплику
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-idempotency
make test-failover-series

# Все доказательства одной командой (пишет в evidence/):
sh scripts/collect-evidence.sh

Windows: python3 там часто заглушка — используйте make ... PYTHON=python и PYTHONUTF8=1. Python на Windows не исполняет .sh напрямую (WinError 193), поэтому для публичных тестов есть обёртки: ACTION_SCRIPT=scripts/win/stop-one.cmd, scripts/win/restart.cmd (вызывают Git Bash).

Число реплик: API_REPLICAS в .env или docker compose up -d --scale api=4.

Остановка без потери данных: docker compose --env-file .env stop. Намеренное удаление учебных данных: docker compose --env-file .env down -v (удаляет volumes pg_data и redis_data).

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

клиент ──► lb (HAProxy :8080, единственный опубликованный порт; :8404 stats, только 127.0.0.1)
             │  roundrobin, active check GET /health/ready каждые 1 s, DNS Docker
             ▼
           api × N (сеть front+back, портов наружу нет, без container_name)
             │
             ├──► postgres (сеть back): users, chats, chat_members, messages, idempotency_keys
             └──► redis    (сеть back): сессии (AOF), кэш истории (версия чата)
migrate (one-shot) ──► postgres  — до старта api

Перенесено из lab2 без изменений: API, валидация, Argon2id, keyset-пагинация, сессии в Redis с TTL (переживают рестарт благодаря AOF), кэш истории с версионированием чата.

Изменено в lab3:

  1. X-Instance-Id — middleware на самом внешнем уровне, есть в каждом ответе API, включая ошибки и health. Значение = hostname процесса; в Docker это короткий ID контейнера, поэтому stop-one.sh однозначно находит контейнер (docker compose ps -q api + сравнение префикса). Переопределяется INSTANCE_ID. В lab7 будет заменён на непрозрачный alias.
  2. Идемпотентность POST сообщения (internal/repository/postgres/message.go, миграция 0002_idempotency):
    • заголовок обязателен, ^[A-Za-z0-9._:-]{1,128}$, иначе 400;
    • область: PRIMARY KEY (user_id, chat_id, key) (метод всегда POST, путь задаётся chat_id);
    • request_hash = SHA-256 от канонического JSON уже разобранного тела, поэтому порядок ключей/пробелы не важны;
    • в одной транзакции: удалить просроченный ключ этой области → INSERT message → INSERT idempotency_keys … ON CONFLICT DO NOTHING. Конкурентный запрос с тем же ключом через другую реплику блокируется на уникальном индексе до COMMIT первой транзакции, получает конфликт, откатывает своё сообщение и возвращает сохранённое (тот же 201 и тот же Message) или 409 при другом body;
    • если первая транзакция откатилась (транзиентная 5xx), ключ не фиксируется и повтор выполняется заново;
    • авторизация и членство в чате проверяются до обращения к ключу, т. е. при каждом повторе;
    • TTL IDEMPOTENCY_TTL_SECONDS (86400); фоновая очистка раз в час (идемпотентный DELETE, безопасен с любой реплики).
  3. Миграции — отдельный one-shot сервис migrate (golang-migrate хранит версию и берёт advisory lock); api зависит от него через service_completed_successfully, поэтому реплики не гоняются за схему. DSN читается из secret, пароль не хранится в compose.yaml (в lab2 был захардкожен — исправлено).
  4. Graceful shutdown: по SIGTERM /health/ready сразу отвечает 503, процесс продолжает обслуживать запросы DRAIN_DELAY=3s (HAProxy за это время исключает его: inter 1s × fall 2), затем http.Server.Shutdown с SHUTDOWN_TIMEOUT=8s. stop_grace_period: 15s > 3 + 8, поэтому SIGKILL не обрывает запросы.
  5. LB HAProxy: server-template api 8 api:8080 + resolvers docker (127.0.0.11) — новые/пересозданные реплики подхватываются без перезапуска LB; retry-on conn-failure + option redispatch — повтор только когда запрос ещё не отправлен, поэтому неидемпотентные POST /users и /chats не дублируются. Sticky sessions нет: состояние общее.
  6. Ресурсы (переопределяются переменными для трека 1): api 0.5 CPU/256M, lb 0.5/128M, postgres 1.0/512M, redis 0.5/256M. Сети: front (lb↔api) и back (api↔хранилища) — LB не видит БД.

Критичные зависимости readiness: PostgreSQL и Redis (сессии нужны каждому защищённому запросу) + флаг drain. /health/live — только жизнь процесса.

Тайминги обнаружения отказа:

Механизм Параметры Максимальное время
Graceful stop (SIGTERM) readiness 503 → inter 1s, fall 2 ≈2 s, всё это время реплика ещё обслуживает запросы → ошибок нет
Падение процесса (kill) conn refused → retry-on conn-failure, redispatch; check fall 2 запросы перенаправляются сразу; из пула ≈2 s
Зависание без ответа timeout server 15s, check timeout = inter ≈2 s до исключения; запросы в полёте получат 504

Соответствие .env.example: APP_HOST/APP_PORT/APP_ENV/SESSION_TTL_SECONDS/IDEMPOTENCY_TTL_SECONDS — как есть; DATABASE_URL_FILE и CACHE_URL_FILE — docker secrets /run/secrets/*; SESSION_STORE=redis (сессии в Redis с lab2); API_REPLICAS → deploy.replicas; DRAIN_DELAY/SHUTDOWN_TIMEOUT — добавлены.

Где запускался стенд

На машине разработки Docker Desktop не запускается: в BIOS выключена аппаратная виртуализация (VirtualizationFirmwareEnabled=False, backend hasNoVirtualization=true). Поэтому все Docker-проверки выполнены на GitHub-hosted runner workflow .github/workflows/lab3-stand.yml — тот же compose.yaml и те же скрипты, что и в инструкции выше:

Прогон Что Ссылка
1 (commit fe4b4cf) уровни 3–4 (найден баг rolling update), трек 1: серии A, B, D https://github.com/CharaWein/2026_lab3/actions/runs/39970452644
2 (commit 0a37181) уровни 3–4 после исправления — доказательства ниже из этого прогона; трек 1: серии C, E https://github.com/CharaWein/2026_lab3/actions/runs/39972671424

Runner: 2 vCPU (AMD EPYC 7763 / 9V74, Intel Xeon 6973P — модель разная для разных job, записана в evidence/track1/runner_*.txt), 8 GB RAM, Docker 28.0.4, Compose v2.38.2 (evidence/runner.txt). Каждая серия трека 1 выполнялась целиком на одном runner, поэтому сравнения внутри серии корректны, а абсолютные RPS между сериями сравнивать нельзя.

До Docker-прогона логика приложения дополнительно проверялась нативно (PostgreSQL 17, fakeredis, 2 процесса API за временным прокси) — evidence/local_native_check.txt, evidence/idempotency_concurrent_native.json.

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

Уровень 3

Критерий README Команда/сценарий Наблюдаемый результат Файл
Стенд в compose.yaml, одна последовательность запуска scripts/init-secrets.sh → docker compose up -d --build --wait lb, 2×api, postgres, redis healthy; migrate отработал однократно evidence/docker_ps.txt
≥2 реплики, одна точка входа, общая БД и сессии docker compose ps опубликованы только 127.0.0.1:8080 (lb) и :8404 (stats); api — только 8080/tcp внутри сети evidence/docker_ps.txt
Запросы одной сессии обслуживают разные реплики 20 запросов через LB; 40 запросов /users/me в failover-тесте 259a4143c86a×10, 904a0714df9b×10; observed_instances_before: 2 evidence/instances.txt, evidence/failover_1.txt
Публичный smoke make test PASS: lab3 public API scenario evidence/smoke.txt
Отказ одной реплики ≤10 s make test-failover ACTION_SCRIPT=scripts/stop-one.sh, 2 прогона, между ними restore.sh PASS ×2; 143 и 144 успешных записи, 0 ошибок, первая запись после hook за 3.39 s и 3.36 s; остановленный контейнер Exited (0) evidence/failover_1.txt, failover_2.txt
Повтор POST с тем же ключом без дублей (конкурентно, через разные реплики) make test-idempotency: 10 раундов × 16 параллельных запросов 160/160 → 201 с одним Message, 1 сообщение на ключ, 2 реплики, duplicates_found: 0; другой body — 409; ключ изолирован по чату и пользователю evidence/idempotency_concurrent.json
Persistence с прежним токеном make test-persistence ACTION_SCRIPT=scripts/restart.sh PASS; перезапущены postgres, redis, api, lb (uptime до/после в файле), volumes сохранены evidence/persistence.txt

Публичный failover-тест останавливает реплику, обслужившую первый запрос; в обоих прогонах это была api-2. Остановка каждой реплики по очереди показана в серии уровня 4 ниже.

Уровень 4

Критерий README Команда/сценарий Наблюдаемый результат Файл
Health/readiness, timeouts, SIGTERM согласованы; LB исключает backend drain 3 s + HAProxy check inter 1 s × fall 2; docker stop после SIGTERM реплика отвечала ещё 0.75 s / 1.46 s, затем исчезла из ответов LB; 0 ошибок. Период проверки 1 s, максимальное время обнаружения ≈2 s evidence/failover_series.json
Поочерёдная остановка каждой реплики: RPS, ошибки, восстановление make test-failover-series (4 потока, POST+GET) таблица ниже evidence/failover_series.json
Параллельная идемпотентность см. уровень 3 0 дублей evidence/idempotency_concurrent.json
CPU/RAM-лимиты, api без портов, нет container_name compose.yaml, docker stats api 0.5 CPU/256M, lb 0.5/128M, postgres 1.0/512M, redis 0.5/256M evidence/docker_stats.txt, evidence/docker_ps.txt
Rolling update под нагрузкой scripts/rolling-update.sh во время 90 s tests/load.py api-1, api-2 → api-3, api-4 за 27 s; 33 461 запрос, 0 ошибок, 371 RPS, p99 27.7 ms evidence/rolling_update.txt, rolling_update_load.json
Миграции однократно и совместимы сервис migrate + docker compose run --rm migrate перед заменой no change; 0002 только добавляет таблицу (expand) evidence/rolling_update.txt

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

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
docker stop реплики 259a4143c86a под нагрузкой 0–единицы ошибок благодаря drain 347.8 RPS до → 361.9 RPS в окне 15 s, 0 ошибок; stop занял 3.57 s ошибок нет; после docker start healthy и в LB через 6.25 s; потерь нет
docker stop реплики 904a0714df9b то же 345.8 → 357.9 RPS, 0 ошибок; stop 4.12 s ошибок нет; возврат через 6.81 s; потерь нет
Итог серии нет потерь и дублей 9 388 подтверждённых записей, 9 389 в истории (+1 — сообщение до серии), дублей 0, потерь 0 —
Rolling update 0 ошибок 0 из 33 461 замена 27 s
Restart всего стенда данные и сессия сохранены PASS с прежним токеном ≈12 s до healthy
Прогон 1: rolling update 0 ошибок найден баг: wait_healthy перезаписывал cid внешнего цикла, удалялась новая реплика; сборка (72 s) не попадала в окно нагрузки исправлено в 0a37181, проверено прогоном 2

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

Вопрос и гипотезы

Помогает ли добавление API-реплик, где точка насыщения и почему рост реплик перестаёт помогать? Гипотезы A–D записаны до измерений в experiments/track1.json. Серия E и её гипотеза добавлены после прогона 1, чтобы проверить, куда смещается насыщение после улучшения.

Серия Что меняем Гипотеза
A_fixed_total 1×1.0 / 2×0.5 / 4×0.25 CPU API (сумма 1.0 CPU) RPS не растёт, p95 чуть хуже; реплики дают только отказоустойчивость
B_scale_out 1/2/4 реплики по 0.5 CPU рост, пока узкое место — CPU API, затем упор в общую зависимость
C_shared_resources 4×0.5 API; PG 1→2, LB 0.5→1, Redis 0.5→1 CPU RPS поднимает только ресурс насыщенной зависимости
D_improvement 4×0.5 API: baseline и 3 кандидата SCAN-инвалидация кэша (наследие lab2) — O(keyspace/100) запросов к Redis на запись; CACHE_INVALIDATION=version (1 INCR) поднимет RPS
E_scale_out_after_fix 1/2/4 × 0.5 CPU с version после снятия упора в Redis реплики снова помогают до следующей общей зависимости

Методика

  • Отдельный compose-проект mtusi2026lab3-bench (порт 18080). Конфигурация задаётся только переменными окружения (API_REPLICAS, API_CPUS, API_MEMORY, PG_CPUS, LB_CPUS, REDIS_CPUS, DB_POOL_MAX, CACHE_INVALIDATION, LB_BALANCE), образ один.
  • База: PostgreSQL 1.0 CPU / 512M, max_connections=200; Redis 0.5 CPU; LB 0.5 CPU; пул 20 на реплику; CACHE_INVALIDATION=scan (поведение lab2); фоновый keyspace Redis — 10 000 ключей pad:* (≈ активные сессии).
  • Нагрузка cmd/bench: closed-loop, 50% POST сообщения (уникальный Idempotency-Key) / 50% GET истории limit=50, 8 чатов × 2 участника, без повторов, таймаут 5 s.
  • Фактический объём (сокращён из-за времени работы runner): уровни параллелизма 4/16/64 (C: 16/64, D: 32/64), прогрев 3 s, измерение 15 s, 3 повтора каждой точки — всего 129 прогонов. Полная методика (6 уровней, 30 s, 3–5 повторов) запускается make track1.
  • Во время прогона раз в 1–2 s снимаются docker stats (CPU нормирован на лимит роли) и pg_stat_activity; до и после — счётчики пула pgx (внутренний порт 9090, не публикуется).
  • Правила анализа в scripts/track1_report.py: медиана повторов; насыщение — первый уровень с ростом RPS < 10%; узкое место — роль с максимальной утилизацией лимита (≥ 0.85 — насыщена); улучшение подтверждено, если min(RPS кандидата) > max(RPS baseline) по всем повторам, p95 не хуже, ошибок не больше. Метрика «CPU хоста» (сумма util × лимит × число контейнеров по ролям) добавлена после прогона 2.
  • Сырые данные: evidence/track1/raw.jsonl (одна строка — один прогон, без токенов). Сводка: summary.md, summary.csv. Графики RPS и p95 по каждой серии: report.html.

Ошибок (error_ratio) не было ни в одном из 129 прогонов.

Результаты (медианы 3 повторов)

A — фиксированный бюджет API 1.0 CPU

config RPS c=4 / 16 / 64 p95 c=16, ms util Redis util API
1×1.00 224 / 258 / 247 142 1.00 0.67
2×0.50 198 / 234 / 252 166 0.99 0.79
4×0.25 182 / 215 / 231 183 0.88 0.86

Гипотеза подтверждена частично: RPS не растёт (258 → 252 → 231), p95 растёт (142 → 166 → 183 ms при c=16). Но причина не в API: Redis упирается в свой лимит уже при одной реплике.

B — рост числа реплик по 0.5 CPU

config пик RPS × к 1 реплике узкое место на пике
1×0.50 295 1.00 API 1.00
2×0.50 372 1.26 Redis 1.00 (API 0.77)
4×0.50 357 1.21 Redis 0.97 (API 0.43)

Saturation point — 2 реплики. С одной на две реплики RPS растёт на 26% (снимается упор в CPU API), дальше роста нет: Redis (0.5 CPU) загружен на 100% лимита, а CPU API простаивает (0.43). Рост реплик перестаёт помогать, потому что каждая запись делает SCAN по keyspace Redis, и общий Redis насыщается раньше API.

C — проверка причины (4×0.5 API)

config RPS c=16 / 64 util Redis вывод
базовая 455 / 494 1.00 —
PG 2 CPU 463 / 501 1.00 +1%, в пределах шума
LB 1 CPU 453 / 486 0.99 0%
Redis 1 CPU 492 / 538 0.55 +8–9%, Redis перестаёт быть насыщенным

RPS поднимает только ресурс Redis — гипотеза C подтверждена. Прирост ограничен (+9%), потому что дальше сказывается CPU хоста (см. E).

D — подтверждённое улучшение (4×0.5 API)

кандидат RPS c=32 / 64 p95 c=32, ms util Redis подтверждено
baseline (scan) 214 / 222 346 1.00 —
CACHE_INVALIDATION=version 544 / 549 130 0.24 да: +148% RPS, −57% p95 при c=64; все 3 повтора лучше всех 3 повторов baseline
DB_POOL_MAX=8 208 / 234 347 1.00 нет (+5%, внутри разброса)
LB_BALANCE=leastconn 232 / 224 321 0.99 нет (+1%)

Изменение кода: ключ кэша истории включает версию чата, запись делает один INCR вместо SCAN+DEL (message_cache.go). Корректность сохранена: к моменту ответа на запись версия уже увеличена, и следующее чтение идёт по новому ключу (smoke и идемпотентность проходят в обоих режимах). Режим version — значение по умолчанию в compose.yaml.

E — рост реплик после улучшения

config пик RPS p95 c=64, ms util API / PG / Redis CPU контейнеров, ядер из 2
1×0.50 560 176 1.00 / 0.40 / 0.23 1.09
2×0.50 618 207 0.78 / 0.55 / 0.24 1.55
4×0.50 599 244 0.42 / 0.51 / 0.27 1.56

После улучшения одна реплика даёт почти вдвое больше, чем в B (на другом процессоре runner, поэтому сравнение приблизительное). Но вторая реплика добавляет лишь +10%, а четвёртая — ничего: RPS 618 → 599, p95 растёт (207 → 244 ms), активных соединений PostgreSQL в пике больше (29 → 45). Ни один контейнер не упирается в лимит; вместе они занимают ≈1.56 из 2 vCPU runner, остальное делят генератор нагрузки, dockerd и сетевой стек. Интерпретация: следующий потолок — CPU узла, и реплики на одном двухъядерном узле не добавляют вычислительной мощности. Это интерпретация, а не прямое измерение: CPU генератора нагрузки не измерялся.

Выводы трека

  1. При фиксированном CPU реплики не увеличивают пропускную способность и ухудшают p95 (A).
  2. При росте ресурсов насыщение наступает на 2 репликах из-за общей зависимости — Redis (B); это подтверждено изменением только её ресурса (C).
  3. Подтверждённое улучшение — инвалидация кэша по версии вместо SCAN: ×2.5 RPS и −57% p95 на той же конфигурации (D).
  4. После улучшения точка насыщения смещается к CPU узла (E): дальше масштабировать нужно узлами, а не репликами на одном узле.

Ограничения трека

  • Runner 2 vCPU: сумма лимитов в конфигурациях 4×0.5 (3.5–4 CPU) больше, чем у хоста; лимиты Docker — квоты CFS. Поэтому «утилизация лимита < 1» не значит, что CPU свободен.
  • Сокращённая методика: 3 уровня параллелизма, 15 s, 3 повтора; точка насыщения определена с шагом ×4 по параллелизму.
  • Разные job — разные модели CPU; абсолютные RPS сравнимы только внутри серии (база C даёт 494 RPS против 357 у B 4×0.5 при одинаковой конфигурации — другой процессор).
  • Аномалия: в 2 из 3 повторов A 4×0.25 c=64 сборщик docker stats почти не получил замеров (утилизация занижена, RPS нормальный). Медиана утилизации в этой точке недостоверна; вывод по A сделан по c=4/16.
  • Только closed-loop; задержки — успешных запросов (ошибок не было).
  • История растёт во время серии; GET читает первые 50 сообщений по индексу, поэтому стоимость чтения от объёма почти не зависит.

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

  • Выдерживается отказ одной API-реплики (процесс/контейнер). Не выдерживается отказ LB, PostgreSQL, Redis или хоста — это SPOF (один узел, БД не реплицирована).
  • Миграции совместимы с работающей версией только при подходе expand→contract; 0002 только добавляет таблицу. Деструктивные миграции так применять нельзя.
  • Ключи идемпотентности хранятся в PostgreSQL рядом с сообщением — атомарность без распределённых транзакций ценой одной лишней записи на POST.
  • Ошибки, сгенерированные самим HAProxy (502/503/504), не содержат X-Instance-Id — это допускается контрактом.
  • Docker-стенд на машине разработки не запускается (нет VT-x), доказательства получены на GitHub runner. На любой машине с Docker всё воспроизводится теми же командами.