- доказательства уровней 3–4 (прогон 2 на GitHub runner) - трек 1: 129 прогонов серий A–E, анализ, графики, подтверждённое улучшение - Dockerfile: базовые образы закреплены по digest - собственные тесты перенесены в student-tests/ Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
30 KiB
Отчёт — лабораторная 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:
- X-Instance-Id — middleware на самом внешнем уровне, есть в каждом ответе API, включая ошибки и health. Значение = hostname процесса; в Docker это короткий ID контейнера, поэтому
stop-one.shоднозначно находит контейнер (docker compose ps -q api+ сравнение префикса). ПереопределяетсяINSTANCE_ID. В lab7 будет заменён на непрозрачный alias. - Идемпотентность 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, безопасен с любой реплики).
- заголовок обязателен,
- Миграции — отдельный one-shot сервис
migrate(golang-migrate хранит версию и берёт advisory lock);apiзависит от него черезservice_completed_successfully, поэтому реплики не гоняются за схему. DSN читается из secret, пароль не хранится в compose.yaml (в lab2 был захардкожен — исправлено). - 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 не обрывает запросы. - 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 нет: состояние общее. - Ресурсы (переопределяются переменными для трека 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 генератора нагрузки не измерялся.
Выводы трека
- При фиксированном CPU реплики не увеличивают пропускную способность и ухудшают p95 (A).
- При росте ресурсов насыщение наступает на 2 репликах из-за общей зависимости — Redis (B); это подтверждено изменением только её ресурса (C).
- Подтверждённое улучшение — инвалидация кэша по версии вместо SCAN: ×2.5 RPS и −57% p95 на той же конфигурации (D).
- После улучшения точка насыщения смещается к 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 всё воспроизводится теми же командами.