Files
mtusi2026lab4/REPORT.lab3.md

24 KiB
Raw Permalink Blame History

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

  • Автор, группа: Савельев Иван, БВТ2304.
  • Целевая оценка: 4, весь уровень 3 и все пункты уровня 4. Треки оценки 5 не заявлены.
  • Решение: Docker Compose + HAProxy, две реплики FastAPI, общий PostgreSQL и Valkey.
  • Commit/PR: после публикации. Локальные проверки относятся к рабочим изменениям поверх source_commit из evidence/lab3-checks.json.

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

Нужны Docker Engine с Compose v2, Python 3.11, Bash и make. Для демонстрации demo.sh также нужны curl и jq. Проверено на Docker Engine 29.0.1, Compose 2.40.3, macOS arm64. Команды выполнять из корня репозитория:

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt -r requirements-dev.txt
./scripts/start.sh
./scripts/check.sh
./scripts/demo.sh

start.sh создаёт локальные .env и secrets/, собирает образ, поднимает PostgreSQL и Valkey, выполняет отдельный сервис migrate, запускает две API-реплики и HAProxy. API ожидают успешного завершения миграций. Скрипт возвращает управление после проверки обеих реплик через LB. Основной адрес — http://localhost:8080.

Пароль PostgreSQL генерируется случайно в secrets/postgres_password; DSN и URL Valkey находятся в secrets/database_url и secrets/cache_url. Существующие значения не перезаписываются. Каталог имеет права 0700, файлы — 0444 для чтения пользователем контейнера 10001. .env, secrets/, .venv исключены из Git и Docker build context. .env.example содержит настройки и пути, без значений секретов.

Переменная Использование
APP_HOST, APP_PORT Адрес API внутри контейнера: 0.0.0.0:8080
HOST_PORT Порт единственного публичного входа HAProxy на 127.0.0.1, по умолчанию 8080
API_REPLICAS Количество реплик сервиса api, по умолчанию 2; конфигурация LB содержит 10 мест
SESSION_STORE valkey, общее хранилище серверных сессий
SESSION_TTL_SECONDS TTL новой сессии, по умолчанию 3600; рестарт TTL не продлевает
DATABASE_URL_FILE, CACHE_URL_FILE Пути к Docker secrets
IDEMPOTENCY_TTL_SECONDS Срок результата повтора, по умолчанию 86400, меньше 24 часов запрещено
APP_ENV Учебная метка окружения; поведение приложения не переключает

Если порт занят, например стендом lab2:

HOST_PORT=8081 ./scripts/start.sh
BASE_URL=http://localhost:8081 ./scripts/check.sh

Для дальнейших команд с нестандартным портом сохранить HOST_PORT=8081 в .env или передавать его в окружении. Для HTTP-проверок передавать соответствующий BASE_URL.

docker compose ps -a
docker compose logs --tail 30 api lb
./scripts/restart.sh    # API, PostgreSQL, Valkey и LB; volumes сохраняются
./scripts/stop.sh       # удаление контейнеров и сети с сохранением volumes

# Только для намеренного удаления учебных данных текущего Compose project:
docker compose down --volumes

Compose project mtusi-lab3 отделён от lab2. Тестовый сценарий использует своё случайное имя и порт; в конце удаляет только свои тестовые контейнеры и volumes.

Архитектура и перенос из lab2

Клиент → HAProxy :8080 → api × 2 → PostgreSQL (данные и результаты повторов)
                              ↘ Valkey (общие Bearer-сессии)
Отдельный migrate → PostgreSQL; завершается до первого запуска API

Сохранены пользователи, Argon2id, Basic-вход, Bearer-сессии с TTL и отзывом, чаты, проверки доступа, сообщения, единые ошибки, X-Request-Id и keyset-пагинация. PostgreSQL остаётся источником истины для данных. Valkey хранит SHA-256 токена → пользователя и время окончания, с AOF appendfsync always, noeviction и постоянным volume. Подтверждённые данные и действующие сессии переживают обычный рестарт. Локального состояния, от которого зависит корректность, в API нет.

Добавлены X-Instance-Id, общая идемпотентность, LB и управление репликами. X-Instance-Id равен hostname контейнера и стабилен в течение жизни процесса. В доказательствах он сопоставлен с настоящим container ID; заголовок не подменяется балансировщиком. Любой ответ, сформированный API, включая health и ошибки, содержит оба служебных заголовка.

HAProxy использует round robin без sticky session. server-template получает адреса масштабируемого сервиса api из Docker DNS 127.0.0.11; записи переопрашиваются, устаревшие адреса удаляются. hold valid/obsolete=1s, повтор разрешения — 1s. Новые IP после пересоздания обнаруживаются без рестарта LB. wait-ready.sh проверяет Docker health всех работающих API и наблюдает каждую через LB.

API не публикуют порты на хост, работают от UID/GID 10001, без volumes данных и без container_name. Только LB публикует порт. Секрет PostgreSQL доступен БД; DSN — API и мигратору; URL Valkey — только API. LB не получает секреты. PostgreSQL и Valkey используют отдельные именованные volumes.

Контейнер CPU RAM
Каждый API 1 256 MiB
HAProxy 0.5 64 MiB
PostgreSQL 1 512 MiB
Valkey 0.5 128 MiB
Одноразовый migrate 1 256 MiB

Готовность, таймауты и SIGTERM

/health/live проверяет жизнь процесса. /health/ready проверяет PostgreSQL и Valkey: обе зависимости критичны для обязательного синхронного пути. При отказе любой зависимости live остаётся 200, ready становится 503. При старте API также проверяет наличие и checksum всех миграций, не выполняя DDL.

HAProxy проверяет /health/ready каждую 1 секунду. Два последовательных неуспеха исключают backend (fall 2), два успеха возвращают (rise 2). Таймаут подключения — 1s, ответа healthcheck — 1s. Консервативная верхняя оценка обнаружения отказа по этим настройкам — 6 секунд: ожидание ближайшей проверки, два подключения/ответа и интервал между ними; задержки планирования ОС в оценку не входят. Отказ с немедленным connection refused обычно обнаруживается быстрее. Это укладывается в требование восстановления за 10 секунд.

Остальные таймауты HAProxy: server 8s, client 10s, чтение HTTP-заголовков 5s. retries 1 относится к установлению backend-соединения; повторов уже отправленных HTTP POST по статусам не включено. Клиент повторяет неопределённый POST сообщения с исходным ключом.

API является PID 1. При SIGTERM Uvicorn прекращает приём новых соединений, даёт текущим запросам до 5 секунд и закрывает пул. Docker даёт 8 секунд до принудительного завершения. Проверка с незавершённым телом POST измеряет отказ новых соединений и выход до 8 секунд; проверяется Application shutdown complete, exit code 0 и отсутствие OOM. Переходные ошибки до исключения backend из LB учитываются в нагрузочном сценарии.

Общая идемпотентность

Для POST сообщения требуется ровно один Idempotency-Key по шаблону [A-Za-z0-9._:-]{1,128}. Отсутствие и неверный формат дают 400. Область ключа — пользователь, POST, путь конкретного чата, ключ. Метод и тип пути фиксированы единственным обработчиком; таблица хранит (user_id, chat_id, key) как первичный ключ.

В одной транзакции PostgreSQL:

  1. Проверяется членство в чате; сессия повторно проверяется middleware при каждом запросе.
  2. Берётся транзакционная advisory lock для области ключа. Она общая для всех реплик; возможная коллизия хеша лишь сериализует независимые запросы.
  3. При действующем результате сравнивается значение text, а не исходные JSON-байты. Совпадение возвращает прежний 201 и Message; другой текст даёт 409.
  4. Для нового или истёкшего ключа создаются сообщение и строка результата с TTL, затем выполняется COMMIT. Ответ отправляется после COMMIT.

Порядок/пробелы JSON и Unicode escaping не меняют результат. В контракте lab3 поле сообщения только text; вложения появляются с lab4. Ключи разных пользователей и чатов независимы. 5xx не сохраняется как результат; откат убирает и сообщение, и строку идемпотентности. При обрыве после COMMIT повтор на другой реплике читает прежнее сообщение. Результаты хранятся минимум 24 часа, переживают рестарт и замену API. Истёкшая строка заменяется при следующем использовании того же ключа; сообщения остаются в истории.

Миграции и поочерёдная замена

migrate — один отдельный Compose-service, выполняющий SQL под общей advisory lock и сохраняющий SHA-256 версий. API только проверяют схему. Ручная команда — ./scripts/migrate.sh; повтор безопасен и не создаёт повторных данных.

Миграция 001_initial.sql не изменялась. 002_message_idempotency.sql только добавляет таблицу и не изменяет существующие поля. Она совместима с уже работающей версией приложения. При последующих изменениях разрешены только обратно совместимые добавления перед rolling update; удаление/переименование полей потребует отдельного перехода или окна обслуживания. Автоматическая совместимость произвольных миграций не заявляется.

./scripts/rolling-update.sh

Скрипт сначала собирает образ и запускает миграции, затем для каждого исходного API-контейнера: проверяет наличие другой здоровой реплики, останавливает и удаляет выбранный контейнер, создаёт только недостающую реплику через up --no-deps --no-recreate --scale, ждёт её готовности через LB и переходит к следующей. PostgreSQL, Valkey и HAProxy не перезапускаются. Это поочерёдная замена с сохранением хотя бы одной готовой реплики; краткие переходные ошибки измеряются, нулевые ошибки не обещаются.

Команды проверки и доказательства

make check validate PYTHON=.venv/bin/python
./scripts/check.sh
make test-persistence PYTHON=.venv/bin/python ACTION_SCRIPT=scripts/restart.sh
make test-failover PYTHON=.venv/bin/python ACTION_SCRIPT=scripts/stop-one.sh
docker compose start api
./scripts/wait-ready.sh

# Полный воспроизводимый прогон в отдельном тестовом стенде:
./scripts/check-docker.sh

Для ручной остановки конкретной реплики задать TARGET_INSTANCE_ID из её X-Instance-Id и вызвать ./scripts/stop-one.sh. Скрипт сопоставляет hostname контейнерам только текущего Compose project, требует минимум две работающие реплики, останавливает ровно выбранную и оставляет её остановленной. docker compose ps -a показывает фактическое состояние. Восстановление — docker compose start api и ./scripts/wait-ready.sh. Полный сценарий последовательно повторяет отказ для каждой из двух реплик, восстанавливая предыдущую.

Критерий ТЗ Проверка Доказательство
Воспроизводимый стенд, две реальные API-реплики и единый вход start.sh, Docker inspect, общий Compose-service api compose.yaml; containers в lab3-checks.json
Общая сессия, запросы через разные реплики 20 параллельных повторов с одним Bearer-токеном test_parallel_replay_across_replicas; lab3-checks.txt
Публичный контракт, включая ошибки и идемпотентность make test, 28 собственных тестов lab3-checks.txt
Рестарт всех компонентов, прежняя сессия и сообщения make test-persistence, StartedAt до/после; повтор ключа после рестарта persistence в lab3-checks.json
Публичный отказ одной выбранной реплики, восстановление ≤10s make test-failover, реально остановленный container ID public_failover; lab3-checks.txt
Отказ каждой API-реплики, чтения и записи под нагрузкой Два отдельных load_action, восстановление предыдущей между ними failovers в lab3-checks.json
Параллельная общая идемпотентность, нет дублей 20 одновременных запросов через ≥2 реплики; сверка истории после отказов test_idempotency.py; duplicate_messages=0
Readiness, таймауты и SIGTERM Отказ PostgreSQL/Valkey; незавершённый запрос + TERM dependency_readiness и sigterm
CPU/RAM-лимиты, отсутствие обхода LB и container_name Проверки Docker inspect для всех контейнеров containers; compose.yaml
Поочерёдная замена под нагрузкой rolling-update.sh, новые ID обоих API; неизменный StartedAt остальных rolling_update в lab3-checks.json
Отдельные согласованные миграции Одноразовый сервис, повторный запуск дважды без изменения данных lab3-checks.txt; миграции 001/002

Файлы текущего прогона: evidence/lab3-checks.txt и evidence/lab3-checks.json. Идентификаторы контейнеров, ресурсы, времена, ошибки и посекундные исходные счётчики сохранены без паролей и токенов. evidence/docker-checks.txt, research.*, query-plans.json и REPORT.lab2.md относятся ко второй лабораторной.

Измерения

Дата прогона — 29.10.2026. Среда: macOS arm64, Docker VM Linux aarch64, 10 CPU, 8217448448 байт RAM. Лимиты контейнеров приведены выше. Профиль — четыре закрытых клиента: POST сообщения и GET истории с существующими сессиями, пауза 50ms между парами запросов. Для неопределённого POST сохраняются прежние ключ и тело. При отказе нагрузка длится 15 секунд после начала воздействия; при замене — весь action и минимум 3 секунды после. Перед воздействием есть 1 секунда прогрева, которая входит в общие счётчики.

Численные результаты последнего успешного прогона приведены ниже.

Воздействие Длительность, с Успешные HTTP/с Ошибки Макс. пауза POST / GET, с Потеря подтверждённых / дубли
Остановка 7f6a80b69e32 16.009 98.44 4 1.957 / 2.004 0 / 0
Остановка f973eaec4d52 16.015 98.28 4 2.006 / 2.006 0 / 0
Поочерёдная замена обоих API 23.774 89.64 11 1.059 / 2.034 0 / 0

SIGTERM с незавершённым POST: новые соединения перестали приниматься за 0.167 с, выход за 5.393 с, exit code 0, OOM отсутствует. При остановке Valkey и PostgreSQL по отдельности подтверждены API live=200, API ready=503 и LB ready=503; после восстановления прежний токен продолжил работать.

RPS считается по всем успешным HTTP-запросам чтения и записи за полную длительность сценария; ошибки считаются отдельно. «Первый успех» показывает продолжение обслуживания после начала action, а максимальный промежуток между успешными запросами дополнительно показывает паузы во всём сценарии. После каждого воздействия проверяются все подтверждённые сообщения, исходное сообщение до отказа, отсутствие повторяющихся ID/текстов и работа прежней сессии.

Это короткие проверки отказоустойчивости для оценки 4. Нагрузка закрытая, присутствует coordinated omission; p50/p95 относятся только к успешным ответам. Предельная производительность и масштабирование 1/2/4 здесь не исследуются.

Ограничения

Выдерживается отказ одной API-реплики при работающей другой. PostgreSQL, Valkey, HAProxy и сам хост остаются точками отказа; отказ узла и HA хранилищ не заявлены. Остановка БД или Valkey делает обязательный API неготовым. При полном рестарте допустимо окно недоступности, данные и действующие сессии сохраняются в volumes. Удаление volumes намеренно уничтожает данные.

Нет автоматического TTL-удаления всех давно неиспользуемых ключей идемпотентности: они удаляются при повторном использовании ключа. Срок сессий зависит от часов; keyset-пагинация сохраняет ограничения lab2 при конкурентных записях и переводе часов. Поочерёдная замена останавливается при отсутствии здоровой резервной реплики, автоматический rollback образа не реализован.

Источники

Стек приложения и закреплённые зависимости перенесены из lab2 (requirements.txt): Python 3.11.15, FastAPI 0.142.4, Uvicorn 0.54.0, Psycopg 3.3.6, PostgreSQL 17.6, Valkey 8.1.3; добавлен HAProxy 3.2.6-alpine. README задания, OpenAPI и публичные tests не изменялись. CI запускает контрактные и Docker-проверки; успешный удалённый запуск GitHub Actions без отдельного результата не заявлен.