Files
mtusi2026lab3/REPORT.md
T

21 KiB
Raw Blame History

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

  • Автор, группа: Аккуратов Тимофей, бвт2304
  • Целевая оценка: 5; выбран трек 1 — цена масштабирования
  • Commit/PR: ещё не созданы; изменения находятся в локальном рабочем каталоге
  • Источники, библиотеки и помощь ИИ: перенесена собственная реализация из mtusi2026lab2; Python stdlib, psycopg 3.2.10 и psycopg-pool 3.3.3; официальные образы PostgreSQL и HAProxy. При разработке использовалась помощь Copilot в VS Code; код и результаты проверены локально. Чужие исходники не переносились.

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

Требуются Docker Desktop с Compose v2, openssl, make и Python 3.9+ для локальных проверок. API работает в образе Python 3.12.7; клиентские тесты используют только стандартную библиотеку.

cp .env.example .env
./scripts/bootstrap-secrets.sh
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --scale api=2 --wait --wait-timeout 120

make check
make test
make test-idempotency
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh

Для полной OpenAPI-валидации:

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-dev.txt
make validate PYTHON=.venv/bin/python

bootstrap-secrets.sh создаёт локальные secrets/postgres_password и secrets/database_url, не печатая их. .env и secrets/ игнорируются Git. Миграции применяются одноразовым сервисом migrate; дождитесь состояния healthy у PostgreSQL и API. По умолчанию тесты обращаются к http://127.0.0.1:8080; при изменении APP_PORT задайте, например, make test BASE_URL=http://127.0.0.1:8081.

Безопасная остановка с сохранением данных: docker compose --env-file .env down. Намеренное удаление всех учебных данных — только отдельной командой docker compose --env-file .env down -v; эта команда не используется проверками restart/failover.

Исследовательский эксперимент целиком повторяется одной командой после запуска Compose-стенда:

make track1

Команда запускает все семь случаев матрицы: 1/2/4 реплики при фиксированном бюджете и 1/2/4/8 при росте ресурсов. Для сопоставимости используйте тот же Docker host, порт, число клиентов и длительность. Экспериментальные записи удаляются при восстановлении сохранённого baseline.

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

Клиент → HAProxy → API × 2+ → общая PostgreSQL. В Compose нет container_name; API-порты не опубликованы на хост. Единственный внешний порт — 127.0.0.1:${APP_PORT}:8080 у HAProxy. Реплики не используют sticky sessions. Сессии, сообщения и результаты идемпотентности хранятся в PostgreSQL; это единственный источник истины. Redis из предыдущей реализации остаётся необязательной возможностью в коде, но в этом стенде не развёрнут и для корректности не нужен.

Из lab2 перенесены src/, migrations/001_initial.sql, Dockerfile и зависимости. Изменения этой работы:

  • API больше не запускает миграции при старте. Сервис migrate применяет версионированные SQL-файлы до запуска реплик; таблица schema_migrations и advisory transaction lock защищают от повторного применения.
  • migrations/002_idempotency.sql добавляет общую таблицу ключей. Ключ уникален в области user + POST + chat + key; хранится SHA-256 канонического JSON и исходный ответ. Проверка повтора, создание сообщения и сохранение ответа выполняются в одной транзакции PostgreSQL. Transaction-level advisory lock сериализует конкурентные запросы с тем же ключом на разных репликах. Конфликтующий body возвращает 409, успешный повтор — исходное сообщение; срок хранения не меньше 24 часов.
  • X-Instance-Id берётся из hostname контейнера и неизменен в пределах процесса. scripts/stop-one.sh сопоставляет его с конкретным контейнером.
  • HAProxy обнаруживает backend через DNS Docker (127.0.0.11, hold valid 2s) и проверяет GET /health/ready каждую секунду; backend считается недоступным после двух неудач. С учётом DNS TTL и таймаута проверки консервативный бюджет обнаружения — до 5s, что ниже лимита 10s; connect timeout — 2s, client/server timeout — 15s. У API есть readiness healthcheck, лимиты БД: statement 5s, lock 2s, pool wait 3s. При SIGTERM сервер прекращает приём и завершает активные запросы; stop_grace_period — 20s.
  • Все контейнерные образы закреплены тегами: Python 3.12.7-slim, PostgreSQL 16.4-alpine, HAProxy 3.0.7-alpine. PostgreSQL использует именованный postgres_data. API по умолчанию ограничен 1 CPU/512 MiB на реплику; PostgreSQL — 1 CPU/1 GiB, HAProxy — 0.5 CPU/128 MiB. В переменных .env.example настраиваются host port, TTL и per-replica лимиты API.

Миграция 002 аддитивна и не меняет существующие таблицы lab2, поэтому старый API не использует новую таблицу. CI workflow .github/workflows/application.yml собирает Compose-стенд, запускает публичные и конкурентные тесты, persistence и отказ API-реплики; он не тестирует обновление приложения на новую версию бизнес-кода. Локально проверен поочерёдный restart одинакового образа под нагрузкой.

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

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Контракт и OpenAPI make check; make validate PYTHON=.venv/bin/python PASS для структуры, синтаксиса и полной OpenAPI 3.1/JSON Schema валидации; контракт и публичные проверки не менялись evidence/openapi-validation.txt
Стенд и миграции docker compose ... up --scale api=2; SQL schema_migrations 2 API healthy, PostgreSQL и HAProxy healthy; применены ровно 001_initial.sql, 002_idempotency.sql; API опубликованных host ports не имеет evidence/deployment-checks.txt
Smoke и общая сессия make test через HAProxy PASS: полный публичный сценарий lab3 evidence/public-tests.txt
Общая идемпотентность make test-idempotency 12 конкурентных запросов с одинаковым ключом прошли через 2 наблюдаемые реплики, вернули одно сообщение; в истории ровно одна запись. Публичный smoke также проверяет повтор и 409 при другом body evidence/public-tests.txt
Persistence lab2 make test-persistence ACTION_SCRIPT=scripts/restart.sh PASS: после перезапуска PostgreSQL, API и LB подтверждённые данные доступны, прежняя сессия действительна; volumes сохранены evidence/persistence.txt
Failover первой и второй API Дважды make test-failover ACTION_SCRIPT=scripts/stop-one.sh, восстановление между прогонами Проверки увидели ≥2 экземпляра. Для первого: 108 успешных записей, 2 неуспешные попытки, восстановление за 2.684s. Для второго: 109 успешных, 1 неуспешная, восстановление за 2.566s. Подтверждённые сообщения и сессия сохранились evidence/failover-1.txt, evidence/failover-2.txt, evidence/failover-targets.txt
Readiness, timeouts, SIGTERM HAProxy health checks и scripts/rolling-restart.sh Backend исключается после 2 проверок с интервалом 1s; отказная проверка восстановила записи за 2.566–2.684s. Поочерёдный restart обоих контейнеров завершился healthy haproxy.cfg, compose.yaml, evidence/failover-1.txt, evidence/failover-2.txt, evidence/rolling-restart-actions.txt
Лимиты и отсутствие обходного API-порта docker compose config; docker inspect Реально установлены API 1 CPU/512 MiB, PostgreSQL 1 CPU/1 GiB, HAProxy 0.5 CPU/128 MiB. На хост опубликован только loopback-порт LB; в ps у API показан только внутренний 8080/tcp evidence/deployment-checks.txt
Rolling restart под нагрузкой tests/load.py --duration 35 --concurrency 8 одновременно с scripts/rolling-restart.sh 19,968 успешных POST, 6 ошибок переходного периода; successful RPS 570.303, p50/p95/p99 8.385/45.880/73.085 ms. Оба API контейнера были поочерёдно перезапущены и стали healthy evidence/rolling-restart-load.json, evidence/rolling-restart-actions.txt
Трек 5 — цена масштабирования make track1 Матрица 1/2/4 при фиксированных ресурсах, затем рост до 1/2/4/8; одна исходная custom-format копия PostgreSQL восстанавливается до каждого прогрева и измерения; три повтора на случай; исходная БД восстанавливается в finally evidence/track1/results.json, evidence/track1/throughput.svg
CI сборка и проверка приложения .github/workflows/application.yml (push, pull_request) Отдельный job устанавливает requirements-dev, собирает/ожидает Compose, выполняет make check validate, smoke, параллельную идемпотентность, persistence и failover. Workflow добавлен; выполнение на GitHub Actions ожидает push/PR .github/workflows/application.yml

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

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

Гипотеза: при фиксированном суммарном бюджете API увеличение числа реплик само по себе не даст прироста; при добавлении ресурсов оно ускорит запись до насыщения общей PostgreSQL, после чего новые API-процессы почти не помогут.

Одна машина macOS 27.0.1 arm64, физически 10 CPU и 16 GiB RAM; Docker Desktop 28.0.4 / Compose 2.34.0-desktop.1 предоставлял контейнерам 10 vCPU и около 7.65 GiB. API: Python 3.12.7; фиксированные ресурсы PostgreSQL 1 CPU/1 GiB и HAProxy 0.5 CPU/128 MiB. На каждый случай — прогрев 5s и три измеряемых прогона по 30s, 16 параллельных клиентов. Генератор — штатный closed-loop tests/load.py, только POST сообщений через LB; прозрачных retry нет. Перед каждым прогревом и измеряемым прогоном API остановлен, PostgreSQL восстановлена из одного custom-format snapshot, проверены контрольные количества строк, затем запускается выбранное число реплик. После всей матрицы в finally возвращается исходная БД и две реплики; синтетические benchmark-записи не остаются в volume. Во время запуска исключены внешние записи в БД. В таблице latency — среднее p50/p95/p99 по успешным запросам, RPS — среднее ± стандартное отклонение между тремя прогонами. CPU — максимальная 1-секундная выборка Docker stats; 100% соответствует примерно одному CPU.

Профиль API Суммарный лимит API Успешные RPS, среднее ± σ p50 / p95 / p99, ms Ошибки Peak PostgreSQL CPU
Фиксированный бюджет 1 1 CPU / 512 MiB 212.54 ± 1.34 79.36 / 115.01 / 181.42 0 28.22%
Фиксированный бюджет 2 1 CPU / 512 MiB 212.71 ± 10.81 83.45 / 166.94 / 224.07 0 40.58%
Фиксированный бюджет 4 1 CPU / 512 MiB 156.34 ± 17.60 92.69 / 260.44 / 663.89 0 46.22%
Рост ресурсов 1 1 CPU / 512 MiB 211.67 ± 1.56 79.53 / 115.35 / 182.46 0 26.54%
Рост ресурсов 2 2 CPU / 1 GiB 604.95 ± 6.29 19.72 / 60.32 / 79.17 0 62.93%
Рост ресурсов 4 4 CPU / 2 GiB 1,099.73 ± 11.87 11.01 / 29.91 / 51.29 0 108.47%
Рост ресурсов 8 8 CPU / 4 GiB 1,159.95 ± 16.88 11.75 / 27.90 / 37.07 0 105.96%

При фиксированном бюджете переход к 4 маленьким репликам снизил успешный throughput на 26.4% относительно одной реплики и увеличил p95 с 115.01 до 260.44 ms: дробление CPU между процессами не дало выигрыша. При росте бюджета до четырёх API CPU/2 GiB throughput вырос в 5.19 раза относительно одной реплики при том же per-instance лимите, а p95 уменьшился примерно в 3.86 раза — подтверждённое улучшение для этого стенда. Дальнейшее удвоение API до 8, CPU до 8 и памяти до 4 GiB увеличило throughput на 5.48%; одновременно PostgreSQL достигла выборки 105.96–108.47% одного CPU. Это указывает на насыщение общей БД и уменьшающуюся отдачу от добавления API-ресурсов; это наблюдение относится только к данному профилю, а не универсальная характеристика PostgreSQL.

Все данные синтетические. До матрицы был зафиксирован baseline snapshot; каждое измерение стартовало с одного и того же состояния БД и создавало свой тестовый набор в новом уникальном чате. Row counts после завершения совпали с baseline: users=156, chats=52, messages=445522, sessions=154, idempotency_records=445522. Пиковая выборка памяти за benchmark: PostgreSQL 252.6 MiB, API 73.1 MiB на контейнер, HAProxy 21.1 MiB. Подробные исходные метрики и выборки CPU/RAM, единый SHA-256 snapshot и контрольные количества строк сохранены в JSON.

Отказы

Воздействие Ожидание Наблюдение Восстановление / потеря данных
Остановка первой API-реплики LB продолжает читать/писать через оставшуюся реплику; повтор сообщения не создаёт дубль 108 успешных записей, 2 переходные ошибки; readiness восстановилась за 2.684s Данные и сессия сохранены; потеря подтверждённых сообщений — 0
Остановка второй API-реплики Те же гарантии для другой реплики 109 успешных записей, 1 переходная ошибка; readiness восстановилась за 2.566s Данные и сессия сохранены; потеря подтверждённых сообщений — 0
Поочерёдный SIGTERM/restart двух API под нагрузкой Вторая реплика остаётся доступной, остановленная возвращается healthy 19,968 успешных POST, 6 ошибок за 35s; оба экземпляра перезапущены последовательно Контейнеры вернулись в healthy; подтверждённые записи остаются в PostgreSQL
Restart PostgreSQL + API + LB Сохранить существующую сессию и сообщения на named volume Persistence-тест PASS с прежним токеном Потеря данных — 0; volumes не удалялись

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

  • Эксперимент закрытый (closed-loop), проводится на одном Mac и одним клиентским процессом; он подвержен coordinated omission и не задаёт независимый arrival rate. Процентили считаются только по успешным ответам, а выборка CPU/RAM снимается раз в секунду.
  • Сценарий проверяет отказ API-процесса, не отказ Docker-host, HAProxy, PostgreSQL или диска. PostgreSQL и единственный LB — SPOF; отказ узла не исследовался, multi-node failover не заявляется.
  • Порт HTTP открыт только на loopback для синтетического локального стенда. Для удалённой демонстрации необходим TLS. Секреты Compose — локальные bind-mounted файлы, не production secret manager.
  • Идемпотентность ограничена текстовым контрактом lab3 и 24-часовым минимумом; транзакция держит PostgreSQL advisory lock. HAProxy server-template настроен максимум на 10 адресов — при масштабировании выше нужно расширить диапазон и повторить проверки.
  • Rolling-сценарий проверяет поочерёдный restart текущего образа, не обновление на новую версию приложения. Миграции аддитивны, но совместимость произвольной смены версий приложения не проверялась.
  • Результаты относятся только к указанным лимитам, размеру данных и клиентской интенсивности. Snapshot теперь одинаков перед каждым прогоном, но нагрузка остаётся closed-loop, на одном ноутбуке, без открытого arrival-rate профиля.