Files
mtusi2026lab3-fork/REPORT.md
T

18 KiB
Raw Blame History

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

  • Автор, группа: Голиков, БВТ2303
  • Целевая оценка: на 5, трек 1 "Цена масштабирования"
  • Commit/PR: e769e08
  • Использованные источники, библиотеки и помощь ИИ:
    • Скелет лабы 3 и материалы курса: COURSE.md, contracts/openapi.json, contracts/README.md
    • Документация Docker Compose (services, deploy.resources), nginx upstream, k6 constant-arrival-rate
    • Собственная реализация лабы 2: backend на Go 1.26, gin, pgx, goose, Redis
    • ИИ использовался для структуры отчёта и вычитки формулировок; весь код, конфигурация и измерения выполнены самостоятельно

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

Prerequisites:

  • Docker Desktop 4.30+ (WSL2 backend) или Docker Engine с Compose v2.20+
  • Go 1.26+ (для локальной сборки без Docker; в Docker-варианте не нужен)
  • Python 3.9+ (для публичных тестов из scaffold)
  • k6 v0.55+ (для нагрузочных экспериментов и трека 1)
  • git, make

Шаги запуска:

  1. Клонировать fork и перейти на ветку solution:
    git clone https://gitea.privcloud.tech/Maximillan_Mercer/mtusi2026lab3-fork.git mtusi2026lab3
    cd mtusi2026lab3
    git checkout solution/BVT2303-Golikov
  1. Создать локальные secrets. Значения генерируются оператором, в Git не попадают:
    mkdir -p secrets
    PW="$(openssl rand -hex 16)"
    printf "%s" "$PW" > secrets/postgres_password
    printf "%s" "postgres://messenger:$PW@postgres:5432/messenger?sslmode=disable" > secrets/database_url
    printf "%s" "redis://redis:6379/0" > secrets/cache_url
    chmod 600 secrets/*
  1. Создать .env из .env.example:
    cp .env.example .env

Переменные и дефолты:

  • API_REPLICAS=2 - число API-реплик
  • API_CPUS=0.5, API_MEMORY=256M - лимиты на одну реплику
  • POSTGRES_CPUS=1.0, POSTGRES_MEMORY=1G
  • REDIS_CPUS=0.5, REDIS_MEMORY=256M
  • LB_PORT=8080 - публичный порт LB на хосте
  • SESSION_TTL_SECONDS=3600
  • IDEMPOTENCY_TTL_SECONDS=86400
  • SHUTDOWN_DRAIN_SECONDS=3
  1. Собрать образ API и запустить стек:
    docker compose build api
    docker compose up -d
  1. Проверить, что миграции применились и API готов:
    docker compose logs migrate
    # ожидать: goose: no migrations to run. current version: 2
    # (при первом запуске: OK 0002_idempotency.sql)
    curl -sS http://localhost:8080/health/ready
    # ожидать: {"status":"ok"}
  1. Прогнать публичный smoke и проверки от scaffold:
    PYTHONUTF8=1 make check
    PYTHONUTF8=1 make test
  1. Проверки сохранности и отказа (требуют реализации scripts/restart.sh и scripts/stop-one.sh):
    PYTHONUTF8=1 make test-persistence ACTION_SCRIPT=scripts/restart.sh
    PYTHONUTF8=1 make test-failover ACTION_SCRIPT=scripts/stop-one.sh

Примечание для Windows. tests/resilience.py запускает хук через subprocess.Popen, который на Windows не умеет исполнять .sh-файлы (WinError 193). Локально созданы scripts/restart.cmd и scripts/stop-one.cmd, вызывающие ту же логику через docker compose. В репозиторий .cmd не коммитятся (в .gitignore), на Linux работают .sh-варианты.

Безопасная остановка:

docker compose stop       # остановить контейнеры, volumes сохранить
docker compose down       # удалить контейнеры и сеть, volumes сохранить

Остановка с удалением учебных данных (необратимо, удалит volumes postgres_data и redis_data):

docker compose down -v

Отдельно про .env и secrets: оба пути в .gitignore, в репозиторий не попадают. Значения паролей синтетические, для локального стенда.

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

Схема:

client (k6 или curl)
  |
  v
nginx LB (:8080)         единственная публичная точка
  |
  +-> api-1 :8080        реплика 1
  +-> api-2 :8080        реплика 2
  |
  +-> postgres :5432     общая БД (users, chats, messages, sessions, idempotency_keys)
  +-> redis  :6379       общее хранилище сессий

Источник истины - PostgreSQL. Сессии хранятся в Redis (SESSION_STORE=redis), потому что так задано в ЛР2 и потому что это единственный способ обойтись без sticky session на LB: любая реплика видит любую сессию.

Транзакционные границы. Идемпотентная отправка сообщения - одна транзакция в Postgres. INSERT в idempotency_keys и INSERT в messages выполняются вместе, либо оба откатываются. Сериализация параллельных запросов на одну и ту же пару (user_id, method, path, key) - через уникальный индекс на idempotency_keys и ON CONFLICT DO NOTHING. Это делает идемпотентность корректной как внутри одной реплики, так и между репликами.

Что перенесено из ЛР2 без изменений:

  • Схема БД: users, chats, chat_members, messages, sessions
  • Argon2id для паролей, opaque bearer token (SHA-256 от 32 случайных байт)
  • Миграции goose
  • Публичный HTTP-контракт: /api/v1/users, /chats, /messages, /auth/sessions

Что изменено в этой работе:

  1. Добавлен обязательный Idempotency-Key на POST /chats/{chat_id}/messages. Хранится в новой таблице idempotency_keys. TTL из IDEMPOTENCY_TTL_SECONDS, дефолт 24 часа.
  2. Добавлен заголовок X-Instance-Id во все ответы API. Значение - os.Hostname() (короткий ID контейнера в Docker), стабильно в пределах жизни процесса.
  3. Миграции вынесены в отдельный процесс /server migrate. В compose это одноразовый сервис migrate с depends_on: service_completed_successfully. Реплики больше не запускают goose при старте.
  4. Graceful drain на SIGTERM. Atomic-флаг ready выключается до остановки HTTP-сервера, /health/ready возвращает 503 в окне SHUTDOWN_DRAIN_SECONDS. Затем srv.Shutdown ждёт завершения in-flight запросов.
  5. CPU/RAM лимиты на api, postgres, redis через deploy.resources.
  6. LB на nginx перед двумя репликами. Публичный порт только у LB, реплики доступны только через expose.
  7. Включён upstream keepalive в nginx (см. трек 1, это подтверждённое улучшение пропускной способности).

Соответствие переменных .env.example реальной конфигурации:

  • APP_HOST, APP_PORT - читаются в main.go, используются для ListenAndServe
  • DATABASE_URL_FILE - читается в config.Load через readSecret
  • SESSION_STORE - переключает сессии между postgres и redis
  • SESSION_TTL_SECONDS, IDEMPOTENCY_TTL_SECONDS - читаются в config.Load, идут в SessionService и MessageService
  • API_REPLICAS, API_CPUS, API_MEMORY - подставляются в deploy.replicas и deploy.resources в compose.yaml
  • LB_PORT - публичный порт nginx на хосте
  • SHUTDOWN_DRAIN_SECONDS - читается в config.Load, используется в main.go перед srv.Shutdown

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

Уровень 3:

Критерий Команда Наблюдаемый результат Файл
Публичный smoke PYTHONUTF8=1 make test PASS: lab3 public API scenario вывод на экран
>= 2 API-реплики за LB docker compose ps api-1 и api-2 Up (healthy), LB публикует :8080 evidence/docker-stats-limits.txt
Разные X-Instance-Id при одной сессии for i in 1..10; curl -D- health/live два чередующихся ID evidence/test-failover.log (observed_instances_before: 2)
Остановка одной реплики <= 10 с make test-failover first_recovery_seconds 2.466 evidence/test-failover.log
Поочерёдная остановка каждой make test-failover дважды второй прогон 2.487 с, останавливалась другая реплика evidence/test-failover-second.log
Идемпотентность POST PYTHONUTF8=1 make test (replay с тем же ключом) + make test-failover (uncertain retry) тот же ответ, дублей нет evidence/test-failover.log
Persistence после restart make test-persistence PASS, прежний токен работает evidence/test-persistence.log

Уровень 4:

Критерий Команда Наблюдаемый результат Файл
Health/readiness, timeouts, SIGTERM согласованы docker stop с замером wall-clock 3.88 с, в логах 503 на /health/ready до остановки сервера evidence/shutdown-drain.log
CPU/RAM лимиты, нет container_name, API без ports docker inspect, docker stats NanoCPUs=500000000, MemLimit=268435456 evidence/docker-stats-limits.txt
Миграции однократно docker compose logs migrate Exited (0), схема применяется один раз evidence/migrate-log.txt
Rolling update под нагрузкой scripts/run-rolling-experiment.sh RATE=50, 3 мин, write_errors 0.26 процента evidence/k6-rolling.json, evidence/rolling-update.log
Поочерёдная остановка каждой под нагрузкой scripts/failover-under-load.sh 1, scripts/failover-under-load.sh 2 прогон 1: 0 ошибок, 8.67 с; прогон 2: 1.38 процента в окне переключения nginx, 8.65 с evidence/failover-load-api-1-k6.json, evidence/failover-load-api-2-k6.json

Отказоустойчивость: эксперименты и отказы

Общая среда: Windows 10, Docker Desktop (WSL2 backend), одна физическая машина, на которой работают и нагрузочный генератор, и весь стек. Все пользователи и сообщения синтетические. Версии: Postgres 16.4, Redis 7.4, nginx 1.27.4, Go 1.26.

Профиль нагрузки на k6: constant-arrival-rate, executor open-loop. Устраняет coordinated omission по сравнению с tests/load.py. Подробности в разделе трека 1.

Воздействие Что ожидаем Что наблюдали Время восстановления, потеря данных
SIGTERM одной реплике drain 3 с, 503 на /health/ready, exit 0 ровно так, 3.88 с wall-clock 3.88 с, потерь нет
Остановка одной реплики при RATE=30 (make test-failover) writes продолжаются через LB, без дублей first_recovery_seconds 2.466, повтор с тем же ключом даёт то же сообщение 2.5 с, потерь нет
Перезапуск всего стека (scripts/restart.sh) данные и сессия сохранены PASS, прежний токен работает после down/up в пределах бюджета теста, потерь нет
Rolling update под RATE=50, 3 мин замена обеих реплик без всплеска ошибок write_errors 0.26 процента, p95 6.27 ms без простоя
Остановка api-3 под RATE=30 RPS не проседает, восстановление <= 10 с 0 ошибок, 8.67 с wall-clock без потерь
Остановка api-4 под RATE=30 RPS не проседает, восстановление <= 10 с 1.38 процента ошибок в окне переключения, 8.65 с без потерь

Ошибки в окне переключения nginx (0.26 и 1.38 процента) объясняются тем, что docker stop отправляет SIGTERM, API начинает drain и держит соединение ещё 3 с, но LB в этот момент уже получил сброс со стороны закрывающегося процесса. Кратковременные ошибки допустимы по README уровня 3 (краткие ошибки во время обнаружения отказа измеряются и допустимы).

Трек 1. Цена масштабирования

Постановка и ошибки первой версии

Задача трека по README: при фиксированном суммарном CPU/RAM сравнить 1/2/4 API-реплики на одном профиле нагрузки, затем провести серию с ростом ресурсов, найти saturation point, показать, почему рост реплик перестаёт помогать, дать исходные данные, графики и одно подтверждённое улучшение.

Первая версия отчёта содержала три ошибки методики, отмеченные на ревью:

  1. Вывод о потолке 395 RPS был сделан из нагрузки RATE=400. Это точка, где система справляется, а не упирается. Настоящее насыщение выше.
  2. Отсутствовала серия с ростом ресурсов при фиксированном числе реплик, хотя README требует её явно.
  3. Метрики не разделяли успешные запросы, попытки и потерянные итерации. Доля ошибок и потери k6 смешивались.

Отдельно: объяснение улучшения через «включение keepalive» расходилось с Git. Директива keepalive 32 присутствовала в infra/nginx.conf с первого коммита (2211eaa), а коммит e769e08 добавил только keepalive_requests, keepalive_timeout и увеличил worker_connections 512 -> 1024. Значит, приписывать +80 % пропускной способности включению keepalive было неверно.

Настоящий раздел написан заново. Серии A, B, C переделаны с нуля, метрики разделены, выводы пересмотрены.

Методика

Нагрузочный генератор: k6 v0.55, executor constant-arrival-rate (open-loop). Скрипт student-tests/load-k6.js. Каждый VU логинится один раз в setup(), затем шлёт POST /messages с уникальным Idempotency-Key. Open-loop устраняет coordinated omission, в отличие от tests/load.py.

Каждый замер - 2 или 3 прогона в зависимости от серии. Между прогонами стек не пересоздаётся, но между конфигурациями - да, чтобы избежать накопленного состояния. Медиана по прогонам в сводных таблицах.

Метрики разделены:

  • Успешные (write_total.rate) - POST, завершившиеся 201.
  • Попытки (http_reqs.rate) - все отправленные POST.
  • Потерянные (dropped_iterations.rate) - k6 не смог даже отправить запрос из-за нехватки VU. Это клиентский предел, не серверная ошибка.
  • Ошибки (write_errors.rate) - POST, вернувшие не-201.
  • p95 / max (write_latency_ms) - хвосты latency успешных.

Среда: Windows 10, Docker Desktop (WSL2), одна физическая машина. На ней и стек, и k6. Postgres 16.4, Redis 7.4, nginx 1.27.4, Go 1.26. Аппаратные лимиты: api - 0.25-2.0 CPU / 128M-1G в зависимости от конфигурации, postgres - 1.0 CPU / 1G, redis - 0.5 CPU / 256M, lb - 0.5 CPU / 128M.

Данные: evidence/new_ev/ (JSON summary k6 + CSV docker stats). Скрипты запуска серий и сборки CSV в репозитории не публикуются, это вспомогательные утилиты.