# Отчёт — лабораторная 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. Команды выполнять из корня репозитория: ```sh 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: ```sh HOST_PORT=8081 ./scripts/start.sh BASE_URL=http://localhost:8081 ./scripts/check.sh ``` Для дальнейших команд с нестандартным портом сохранить `HOST_PORT=8081` в `.env` или передавать его в окружении. Для HTTP-проверок передавать соответствующий `BASE_URL`. ```sh 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 ```text Клиент → 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; удаление/переименование полей потребует отдельного перехода или окна обслуживания. Автоматическая совместимость произвольных миграций не заявляется. ```sh ./scripts/rolling-update.sh ``` Скрипт сначала собирает образ и запускает миграции, затем для каждого исходного API-контейнера: проверяет наличие другой здоровой реплики, останавливает и удаляет выбранный контейнер, создаёт только недостающую реплику через `up --no-deps --no-recreate --scale`, ждёт её готовности через LB и переходит к следующей. PostgreSQL, Valkey и HAProxy не перезапускаются. Это поочерёдная замена с сохранением хотя бы одной готовой реплики; краткие переходные ошибки измеряются, нулевые ошибки не обещаются. ## Команды проверки и доказательства ```sh 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.txt) и [evidence/lab3-checks.json](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](https://docs.docker.com/reference/compose-file/services/). - [Compose up: scale и no-recreate](https://docs.docker.com/reference/cli/docker/compose/up/). - [HAProxy: DNS и server-template](https://www.haproxy.com/documentation/haproxy-configuration-tutorials/proxying-essentials/dns-resolution/). - [HAProxy: active health checks, inter/fall/rise](https://www.haproxy.com/documentation/haproxy-configuration-tutorials/reliability/health-checks/). - [PostgreSQL: advisory locks](https://www.postgresql.org/docs/17/explicit-locking.html#ADVISORY-LOCKS). - [Uvicorn: graceful shutdown timeout](https://uvicorn.dev/settings/#timeouts). Стек приложения и закреплённые зависимости перенесены из 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 без отдельного результата не заявлен.