Files
mtusi2026lab3/REPORT.md
T

15 KiB
Raw Blame History

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

  • Автор, группа: Сергей Возжин, БПИ2301.
  • Целевая оценка: 4; трек 5 не выбран.
  • Commit/PR: коммит не создавался по условию выполнения; указать после публикации.
  • Использованные источники: материалы и контракт репозитория, документация Docker Compose и HAProxy.
  • Библиотеки: FastAPI, Uvicorn, SQLAlchemy, asyncpg, Alembic, redis-py, Argon2, pytest.
  • Помощь ИИ: OpenAI Codex использовался для плана, реализации lab3, тестов, сценариев отказа и оформления отчёта; результат проверен исполняемыми тестами.

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

Требуются Docker Engine с Compose v2, Python 3.9+ для публичных тестов и свободный host-порт 8080. Проверенный стенд: Docker 28.0.4, Compose 2.34.0, API на Python 3.13.15. Образы: python:3.13.15-slim, haproxy:3.2.26-alpine, postgres:17.4-alpine, redis:7.4.2-alpine.

Создать локальную конфигурацию, не добавляя её в Git:

cp .env.example .env

Перед запуском заменить учебный пароль PostgreSQL в .env и ту же часть пароля в DATABASE_URL. Сам .env игнорируется Git. Все данные тестов должны быть синтетическими.

Проверить конфигурацию, собрать образы, однократно применить миграции и дождаться готовности:

docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --wait
docker compose --env-file .env ps

migrate выполняет alembic upgrade head один раз. Две реплики api стартуют только после успешной миграции и готовности Redis; HAProxy стартует после готовности API. Единственная публичная точка входа — http://localhost:8080.

Полный набор проверок:

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-dev.txt
make check
make validate PYTHON=.venv/bin/python
make test
make test-idempotency PYTHON=.venv/bin/python
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh

После failover восстановить вторую реплику и дождаться готовности:

docker compose --env-file .env up -d --wait --wait-timeout 60 api lb

Для проверки другой реплики повторить make test-failover после восстановления первой. Для поочерёдной замены под нагрузкой запустить tests/load.py, параллельно выполнить scripts/rolling-update.sh и сохранить агрегаты.

Безопасная остановка с сохранением named volumes:

docker compose --env-file .env down

Намеренное необратимое удаление всех учебных данных выполняется только оператором:

docker compose --env-file .env down -v

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

HTTP client
    |
    v
HAProxy :8080
    |
    +-- round-robin --> API replica 1 --+
    |                                  +--> PostgreSQL
    +-- round-robin --> API replica 2 --+--> Redis sessions

PostgreSQL — источник истины для пользователей, чатов, участников и сообщений. Redis — общее хранилище действующих сессий с AOF. Локального значимого состояния у API нет; sticky sessions не используются.

Из lab2 перенесены REST API, PostgreSQL, Redis-сессии, password KDF и миграции. В lab3 добавлены HAProxy, две API-реплики, X-Instance-Id, обязательный Idempotency-Key, конкурентная проверка и сценарии отказа/замены.

Каждый API-процесс один раз берёт X-Instance-Id из hostname контейнера. Middleware добавляет его во все созданные API ответы. Значение меняется при замене контейнера.

Идемпотентность сообщения хранится в PostgreSQL. Уникальность (sender_id, chat_id, idempotency_key) соответствует области пользователь + метод отправки сообщения + путь чата + ключ. INSERT ... ON CONFLICT DO NOTHING и чтение существующей строки выполняются в одной транзакции. Одинаковое тело возвращает исходный 201 Message, другое тело — 409. Ограничение хранится дольше обязательных 24 часов.

Миграция выполняется отдельно. Поле idempotency_key nullable: старая версия может продолжать писать NULL, новая читает старые записи. Создание unique constraint может блокировать большую production-таблицу; это ограничение учебной миграции описано и не маскируется.

HAProxy использует round-robin и Docker DNS 127.0.0.11. /health/ready проверяется каждую секунду с fall 2, rise 2, timeout check 2s. При быстром отказе типичное исключение занимает 2–3 секунды; консервативная верхняя оценка с двумя полными timeout — около 6 секунд. Наблюдавшееся восстановление записи — 2,560–3,248 секунды, что меньше требуемых 10 секунд.

Таймауты HAProxy: connect/check 2 секунды, client/server 30 секунд. Uvicorn прекращает принимать новые соединения по SIGTERM, имеет graceful shutdown 5 секунд, Compose даёт API stop_grace_period 10 секунд.

Лимиты контейнеров:

Сервис CPU RAM
API, каждая реплика 0,5 256 MiB
HAProxy 0,25 128 MiB
PostgreSQL 1,0 512 MiB
Redis 0,25 128 MiB
migrate 0,5 256 MiB

Наружу опубликован только порт HAProxy. PostgreSQL, Redis и API доступны только в Compose-сети. DATABASE_URL получают только API и migrate; настройки PostgreSQL — только сам PostgreSQL. container_name отсутствует.

Переменные .env.example: APP_PORT задаёт host-порт HAProxy; POSTGRES_* настраивают PostgreSQL; DATABASE_URL используют API/migrate; REDIS_URL используют API/migrate; SESSION_TTL_SECONDS задаёт TTL серверной сессии; LOG_LEVEL задаёт логирование API. APP_HOST и APP_ENV оставлены как описательные учебные настройки и приложением не читаются.

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

Критерий README Команда/сценарий Наблюдаемый результат Доказательство
Публичный smoke make test PASS: lab3 public API scenario evidence/results.md
Две реплики и одна точка входа 20 запросов через localhost:8080, docker compose ps два X-Instance-Id; host-порт есть только у HAProxy evidence/results.md
Общая сессия smoke/idempotency через HAProxy одна Bearer-сессия работает на обеих репликах evidence/results.md
Общая идемпотентность make test-idempotency PYTHON=.venv/bin/python 20 конкурентных запросов, две реплики, одно сообщение; 5 passed evidence/results.md
Persistence make test-persistence ACTION_SCRIPT=scripts/restart.sh данные и прежний token доступны после рестарта API/PostgreSQL/Redis evidence/results.md
Отказ первой реплики make test-failover ACTION_SCRIPT=scripts/stop-one.sh восстановление 3,248 с; 111 успешных записей за 15 с (≈7,40 RPS), 1 переходная ошибка evidence/results.md
Отказ второй реплики восстановление первой и повтор failover восстановление 2,560 с; 110 успешных записей за 15 с (≈7,33 RPS), 1 переходная ошибка evidence/results.md
Health/timeouts/SIGTERM HAProxy checks и остановка выбранного контейнера backend исключён, другая реплика продолжила чтение/запись evidence/results.md
CPU/RAM и закрытые порты docker compose ps, docker stats --no-stream лимиты применены; наружу опубликован только 8080 HAProxy evidence/results.md
Поочерёдная замена scripts/rolling-update.sh во время tests/load.py обе реплики получили новые container ID, 10 512 успешных запросов, 0 ошибок evidence/rolling-update.md, evidence/rolling-update-load.json

Трек оценки 5 не заявлен.

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

Проверяемое ожидание: остановка любой одной API-реплики не приводит к потере подтверждённых сообщений или сессии, а новые чтения/записи возобновляются не позднее 10 секунд.

Аппаратная конфигурация локального стенда: Apple M4 Pro, 12 CPU cores, 24 GB RAM; Docker Desktop. Основной профиль — closed-loop POST сообщений, 30 секунд, concurrency 4, без автоматических retry и отдельного временного прогрева. Bootstrap выполняется до измеряемого интервала. После профиля: 39 пользователей, 13 чатов, 18 448 сообщений, PostgreSQL 14 MB.

Основной прогон: 9807 успешных запросов, 0 ошибок, 326,771 successful RPS, p50/p95/p99 6,436/52,344/63,559 мс. CPU/RAM по двум срезам приведены в evidence/results.md; обе API-реплики использовали около 50–52% CPU и 66–76 MiB RAM каждая.

Числа двух failover-запусков взяты из JSON summary, который печатает tests/resilience.py: successful_writes, failed_attempts и first_recovery_seconds. Приблизительный RPS рассчитан как число успешных записей, делённое на 15 секунд нагрузки. Результат persistence взят из успешного завершения того же теста в режиме persistence. Числа поочерёдной замены взяты из evidence/rolling-update-load.json, записанного tests/load.py во время работы scripts/rolling-update.sh.

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
Restart API + PostgreSQL + Redis данные и token сохраняются persistence PASS время отдельно не замерялось; потерь нет
Остановка первой API-реплики HAProxy оставляет вторую 111 записей за 15 с (≈7,40 RPS), 1 краткая ошибка 3,248 с; потерь и дублей нет
Остановка второй после восстановления первой симметричный failover 110 записей за 15 с (≈7,33 RPS), 1 краткая ошибка 2,560 с; потерь и дублей нет
Поочерёдная замена двух API трафик продолжается 10 512 успешных запросов, 0 ошибок явного перерыва не наблюдалось

tests/load.py — простой closed-loop генератор, ограниченный клиентом и подверженный coordinated omission. Перцентили учитывают только успешные запросы. Эти цифры описывают конкретный учебный стенд и не объявляются максимальной производительностью.

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

Стенд выдерживает остановку одного API-процесса при работающих HAProxy, второй API-реплике, PostgreSQL, Redis и Docker-host. Он не выдерживает потерю единственного HAProxy, PostgreSQL, Redis или всего host: это осознанные SPOF лабораторной работы.

HAProxy и хранилища не реплицированы. Redis AOF снижает риск потери сессий при штатном перезапуске, но не является HA. Docker Compose обеспечивает локальную воспроизводимость, а не перенос контейнеров между узлами. HTTP используется только локально с синтетическими данными; TLS здесь не заявлен. Универсальная идемпотентность остальных POST, WebSocket, UI, мониторинг и требования оценки 5 намеренно не реализованы.

Следующие возможные улучшения, не входящие в оценку 4: несколько Docker-узлов, HA для LB/БД/Redis, online-создание индекса на большой таблице и более строгий open-loop нагрузочный генератор.