24 KiB
Отчёт — лабораторная 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:
- Проверяется членство в чате; сессия повторно проверяется middleware при каждом запросе.
- Берётся транзакционная advisory lock для области ключа. Она общая для всех реплик; возможная коллизия хеша лишь сериализует независимые запросы.
- При действующем результате сравнивается значение
text, а не исходные JSON-байты. Совпадение возвращает прежний 201 и Message; другой текст даёт 409. - Для нового или истёкшего ключа создаются сообщение и строка результата с 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 образа не реализован.
Источники
- Docker Compose services, replicas, secrets и depends_on.
- Compose up: scale и no-recreate.
- HAProxy: DNS и server-template.
- HAProxy: active health checks, inter/fall/rise.
- PostgreSQL: advisory locks.
- Uvicorn: graceful shutdown timeout.
Стек приложения и закреплённые зависимости перенесены из 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 без отдельного результата не заявлен.