Files

30 KiB
Raw Permalink Blame History

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

  • Автор, группа: Бабиченко Максим, БВТ2303
  • Целевая оценка; выбранный трек 5, если нужен: 4, трек 5 не выбран
  • Commit/PR: <<ссылка на MR в Gitea после публикации>>
  • Использованные источники, библиотеки и помощь ИИ: всё из lab2 (FastAPI, Uvicorn, Pydantic, psycopg 3 и psycopg-pool, argon2-cffi, redis-py; точные версии в requirements.txt); образы python:3.11.13-slim, postgres:17.11-alpine, redis:7.4.11-alpine и новый haproxy:3.2.25-alpine; документация HAProxy 3.2 (resolvers, server-template, http-check, retries, observe), документация Docker Compose (deploy.replicas и resources, depends_on с condition, healthcheck), документация PostgreSQL (INSERT ... ON CONFLICT, уникальные ограничения).

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

Проверял на Windows 11, все команды в PowerShell. Версии Docker, Compose и ресурсы машины — в evidence/stack.txt. Python нужен только для тестов (стандартная библиотека). Перед запуском остановить стенд lab2 (docker compose down в его папке), иначе занят порт 8080.

git clone https://gitea.privcloud.tech/Kalibr/mtusi2026lab3.git
cd mtusi2026lab3
git checkout solution/bvt2303-babichenko
$env:PYTHONUTF8 = "1"                    # contracts/openapi.json в UTF-8, без этого тесты на Windows падают
Copy-Item .env.example .env
python scripts/init_secrets.py           # случайные пароли в secrets/ (папка в .gitignore)
docker compose up -d --build --wait      # migrate -> 2 реплики api -> lb; ждём healthy
docker compose ps

python student-tests/collect_evidence.py # все проверки по очереди (~10 мин), вывод в evidence/, таблицы в этот отчёт

Отдельные проверки (make на моём Windows нет, ниже то же самое без make):

Команда из README То же в PowerShell
make check python scripts/check_contract.py
make test python tests/smoke.py --base-url http://127.0.0.1:8080
make test-persistence ACTION_SCRIPT=... python tests/resilience.py --mode persistence --action-script scripts/restart.cmd --base-url http://127.0.0.1:8080
make test-failover ACTION_SCRIPT=... python tests/resilience.py --mode failover --action-script scripts/stop-one.cmd --base-url http://127.0.0.1:8080

После test-failover одна реплика остаётся остановленной (так требует тест). Вернуть её: docker start <ID из docker compose ps -a> или docker compose up -d --wait. На Linux/macOS вместо .cmd — scripts/restart.sh и scripts/stop-one.sh: тест запускает hook без shell, а Python на Windows не умеет запускать .sh (WinError 193).

Миграции применяет одноразовый сервис migrate при docker compose up, отдельной команды нет. Остановка без потери данных: docker compose down (volumes pgdata, redisdata остаются). Намеренное удаление учебных данных: docker compose down -v, затем удалить папку secrets и снова python scripts/init_secrets.py.

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

Клиент --HTTP--> lb: HAProxy 3.2, 127.0.0.1:8080 (единственный опубликованный порт)
                  |  round robin, без привязки клиента к реплике
                  +--> api-1 --+
                  +--> api-2 --+--> postgres: пользователи, чаты, сообщения, ключи идемпотентности (volume pgdata)
                               +--> redis: сессии (AOF, volume redisdata)
migrate (одноразовый): применяет migrations/*.sql до старта api и завершается
сети: edge (lb <-> api) и data (api, migrate <-> postgres, redis; internal, без выхода наружу)
Роль Сервис Compose Версия Health / готовность Volume Сеть / порт Credentials
Балансировщик lb haproxy:3.2.25-alpine /lb-health на 8404 (есть куда отправить запрос) нет edge; 127.0.0.1:8080, статистика 127.0.0.1:8404/stats не нужны
API ×2 api (из Dockerfile, deploy.replicas: 2) python:3.11.13-slim /health/ready (Docker раз в 5 с, HAProxy раз в 1 с) нет edge + data; порт наружу не публикуется /run/secrets/database_url, /run/secrets/cache_url
Миграции migrate (тот же Dockerfile) python:3.11.13-slim завершается с кодом 0 нет data только /run/secrets/database_url
База данных postgres postgres:17.11-alpine pg_isready pgdata data, 5432 POSTGRES_PASSWORD_FILE
Сессии redis redis:7.4.11-alpine redis-cli ping с паролем redisdata (AOF) data, 6379 include /run/secrets/redis_auth

Что перенесено из lab2: весь код API (main.py, db.py, auth.py, settings.py, errors.py), миграции 001–002, свои тесты, Dockerfile, compose.yaml, infra/redis.conf, scripts/init_secrets.py, restart-скрипты. Сессии и данные уже были в Redis и PostgreSQL, в памяти API ничего не хранится, поэтому реплики взаимозаменяемы.

Что изменено в lab3:

  • compose.yaml: две реплики api без ports и container_name, балансировщик lb, сервис migrate, лимиты CPU/RAM у всех контейнеров, две сети.
  • infra/haproxy.cfg: список реплик HAProxy берёт из DNS Docker (имя api -> IP всех реплик, перечитывается раз в 2 с), поэтому подхватывает остановленные и новые реплики без перезапуска.
  • X-Instance-Id в каждом ответе (middleware в main.py) — hostname контейнера, то есть его короткий ID. По заголовку сразу видно контейнер в docker ps, а scripts/stop_one.py останавливает именно его.
  • Обязательный Idempotency-Key у POST сообщения (main.py, db.add_message, migrations/003_idempotency.sql).
  • Миграции больше не применяет API: это делает migrate.py (сервис migrate), а реплика при старте только проверяет, что все миграции её образа применены (db.wait_for_schema).
  • Остановка по SIGTERM в два шага (класс Server в main.py).

Идемпотентность. Ключ и SHA-256 тела запроса хранятся прямо в строке сообщения. Уникальное ограничение (chat_id, sender_id, idempotency_key) — это область ключа из контракта: пользователь + чат (метод и путь у ключа всегда POST .../messages). Запись — один INSERT ... ON CONFLICT DO NOTHING, поэтому сообщение и «запомненный результат» сохраняются атомарно. Если ключ уже есть: то же тело (сравнивается хеш, порядок полей и пробелы в JSON не важны) -> тот же 201 и то же сообщение, другое тело -> 409. Если два запроса с одним ключом пришли одновременно на разные реплики, PostgreSQL заставляет второй INSERT ждать, пока завершится первая транзакция, после чего второй видит готовую строку. Повтор снова проверяет сессию (middleware) и членство в чате (404). Ответы 400/404/503 не сохраняются: после ошибки тот же ключ можно использовать снова. Ключ хранится столько же, сколько сообщение (удаления в API нет), то есть не меньше 24 ч из контракта.

Балансировщик и отказ реплики:

  • Проверка готовности: HAProxy раз в 1 с запрашивает /health/ready у каждой реплики (при смене состояния раз в 0,5 с, timeout check 1s). 2 неудачи подряд -> реплика выведена, 2 удачи -> возвращена. Худший случай для зависшей реплики: около 1 + 1 + 0,5 + 1 = 3,5 с. Кроме того, observe layer4 выводит реплику сразу после первой ошибки соединения у живого запроса, а DNS Docker убирает остановленный контейнер (HAProxy замечает это за 2–4 с).
  • Повторы в HAProxy только при ошибке соединения (запрос ещё не отправлен) и на другую реплику (retries 2, option redispatch). Уже отправленный POST HAProxy сам не повторяет: это делает клиент с тем же Idempotency-Key.
  • Аварийный режим: если готовых реплик нет совсем (например, упал Redis или PostgreSQL), запросы всё равно идут в API через резервные записи fallback в HAProxy. Клиент получает ответ самого API (503 в формате контракта, с X-Request-Id), /health/live отвечает 200, регистрация без Redis работает. Пока готова хоть одна реплика, резервные записи не используются.
  • SIGTERM: /health/ready сразу отвечает 503, но запросы ещё обслуживаются 3 с (SHUTDOWN_DRAIN_SECONDS). За это время HAProxy выводит реплику, затем uvicorn закрывает приём и доделывает начатые запросы (не дольше SHUTDOWN_TIMEOUT_SECONDS=10). Docker ждёт stop_grace_period: 15s. Самый долгий запрос — 8 с (пул 3 с + statement_timeout 5 с), поэтому у HAProxy timeout server 15s.

Миграции: сервис migrate применяет migrations/*.sql один раз (schema_migrations, pg_advisory_lock на случай двух запусков). api стартует только после его успешного завершения (depends_on: condition: service_completed_successfully). Реплика с кодом новее схемы не стартует. Миграция 003 только добавляет столбцы и ограничение, у старых сообщений ключ NULL, поэтому API из lab2 продолжает работать на новой схеме (проверено: старый API пишет без ключа и читает новые сообщения).

Соответствие .env.example:

Переменная Что делает в этом решении
APP_HOST, APP_PORT, APP_ENV где слушает API (0.0.0.0:8080 внутри контейнера), APP_ENV пишется в лог
SESSION_TTL_SECONDS срок жизни сессии, 3600 с
DATABASE_URL_FILE, CACHE_URL_FILE пути к секретам с адресами PostgreSQL и Redis
SESSION_STORE=redis сессии в Redis (как в lab2)
API_REPLICAS число реплик api (deploy.replicas), по умолчанию 2
IDEMPOTENCY_TTL_SECONDS не используется: ключ хранится вместе с сообщением бессрочно (не меньше 24 ч)
SHUTDOWN_DRAIN_SECONDS, SHUTDOWN_TIMEOUT_SECONDS остановка: 3 с на выход из балансировки, до 10 с на начатые запросы
DB_, REDIS_ размеры пулов и таймауты (как в lab2)

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

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Публичный smoke python tests/smoke.py --base-url http://127.0.0.1:8080 PASS через балансировщик evidence/smoke.txt
Skeleton и контракт не изменены python scripts/check_contract.py PASS evidence/check.txt
3: весь стенд в compose.yaml, одна команда запуска docker compose up -d --build --wait migrate Exited (0), api ×2 и lb healthy evidence/stack.txt
3: ≥2 API-реплики, одна точка входа, общая БД и общее хранилище сессий python student-tests/check_stack.py 2 реплики api без портов; наружу только lb на 127.0.0.1; один postgres, один redis evidence/stack.txt
3: запросы одного пользователя обслуживают разные реплики без повторного входа test_balancing.py (test_requests_spread_over_replicas) 20 запросов с одним токеном, ответы от 2 разных X-Instance-Id evidence/balancing.txt
3: состояние общее: запись на одной реплике сразу видна на другой, logout действует везде test_balancing.py записано одной репликой, прочитано другой; после logout обе отвечают 401 evidence/balancing.txt
3: X-Instance-Id в каждом ответе, это реальный контейнер test_balancing.py (test_instance_header_everywhere) 200/201/400/401/404/409 с X-Instance-Id = ID контейнера api evidence/balancing.txt
3: доступ через LB — основной маршрут, без sticky session все тесты идут на 127.0.0.1:8080; infra/haproxy.cfg (balance roundrobin, без cookie) ответы чередуются между репликами evidence/balancing.txt, evidence/stack.txt
3: остановка любой реплики: не позднее 10 с новые чтения/записи, подтверждённое на месте, ошибки измерены python student-tests/run_failover.py (публичный failover для каждой реплики, scripts/stop-one.cmd) PASS для каждой реплики; видно, какой контейнер остановлен (docker compose ps до/после) evidence/failover.txt
3: повтор POST с тем же ключом не создаёт дубль, в том числе одновременный и через другую реплику test_idempotency.py, test_balancing.py (test_idempotent_retry_on_other_replica) повтор -> тот же 201 и то же сообщение; 20 одновременных запросов через 2 реплики -> 1 сообщение evidence/idempotency.txt, evidence/balancing.txt
3: неподтверждённую запись можно безопасно повторить test_idempotency.py (test_lost_response_then_retry); публичный failover повторяет POST с тем же ключом ответ потерян -> повтор 201, сообщение одно; в failover дублей нет evidence/idempotency.txt, evidence/failover.txt
3: миграции отдельно и согласованно, не гонкой реплик сервис migrate; test_db.py миграции применяет только migrate (Exited 0), в логах api — только проверка схемы; повторный запуск migrate ничего не применяет evidence/db.txt
3: make test, persistence и failover проходят smoke, run_persistence.py, run_failover.py все PASS; в failover до отказа наблюдались 2 реплики evidence/smoke.txt, evidence/persistence.txt, evidence/failover.txt
3: hook перезапуска реально перезапускает процессы python student-tests/run_persistence.py у postgres, redis, обеих api и lb тот же ID контейнера и новое время старта; данные и прежний токен на месте evidence/persistence.txt
3: Swarm — выбран Compose, пункт про сборку образа для узлов Swarm не нужен —
3: возможности lab1/lab2 сохранены test_api.py, test_race.py, test_db.py, test_expiry.py, test_failures.py, redis_info.py, explain.py через балансировщик все PASS evidence/student-tests.txt, race.txt, db.txt, expiry.txt, failures.txt, redis.txt, explain-history.txt
4: health/readiness, таймауты и SIGTERM согласованы; LB исключает недоступную реплику; период проверок и время обнаружения infra/haproxy.cfg, класс Server в main.py; failover_metrics.py проверка раз в 1 с (0,5 с при смене), 2 неудачи; худший случай ~3,5 с; измеренное время вывода — в таблице ниже evidence/failover-metrics.txt
4: остановлена каждая реплика по очереди с восстановлением предыдущей; RPS, ошибки, время восстановления python student-tests/failover_metrics.py (docker stop и docker kill, нагрузка 4+1 потока) таблица ниже; потерь и дублей 0 evidence/failover-metrics.txt, evidence/failover-metrics.json
4: общая идемпотентность проверена параллельными запросами с одним ключом test_idempotency.py (test_same_key_parallel_through_replicas, test_same_key_different_bodies_parallel) 20 одновременных запросов: 1 сообщение, 20 одинаковых ответов; с разными телами: одно сохранено, другие 409 evidence/idempotency.txt
4: CPU/RAM-лимиты у контейнеров check_stack.py лимиты у всех: api 1 CPU / 512 MiB, postgres 1 CPU / 512 MiB, redis и lb 0,5 CPU / 128 MiB evidence/stack.txt
4: API не публикует порты в обход LB check_stack.py у api нет опубликованных портов, у postgres и redis тоже; lb только на 127.0.0.1 evidence/stack.txt
4: секреты и хранилища общие только где нужно check_stack.py lb без секретов, migrate только database_url; postgres и redis только во внутренней сети data evidence/stack.txt
4: нет container_name check_stack.py ни у одного сервиса нет container_name evidence/stack.txt
4: rolling update под нагрузкой python student-tests/rolling_update.py реплики заменены новой версией по одной, ошибки и RPS — ниже evidence/rolling-update.txt, evidence/rolling-update.json
4: миграции однократные и совместимые с работающей версией сервис migrate, migrations/003_idempotency.sql; test_db.py 003 только добавляет, API из lab2 работает на новой схеме; ограничение см. ниже evidence/db.txt
Выбранный трек 5 — не выбран —

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

Гипотезы:

  1. Плановая остановка реплики (docker stop) проходит без ошибок у клиента: по SIGTERM реплика сначала отвечает 503 на readiness и уходит из балансировки, а приём закрывает только через 3 с.
  2. При аварии (docker kill) ошибки получают только запросы, начатые на убитой реплике, а HAProxy выводит её быстрее, чем за 3,5 с. Клиент повторяет с тем же ключом, и дублей не появляется.
  3. Rolling update (новая реплика -> готова -> старая уходит) проходит без ошибок при постоянной нагрузке.

Методика: стенд из compose.yaml с лимитами из таблицы выше; нагрузка — student-tests/loadgen.py: 4 потока пишут сообщения без пауз (closed loop), 1 поток читает историю, timeout клиента 2 с, неподтверждённый POST повторяется с тем же ключом. Отказ — через 3 с нагрузки, наблюдение 10 с. Состояние HAProxy читается со страницы статистики раз в 0,1 с. После каждого прогона реплика запускается (docker start) и ждём, пока HAProxy вернёт её. Это closed-loop генератор на той же машине, поэтому RPS ограничен и клиентом, и лимитами CPU; это не предельная пропускная способность.

Машина: Windows 10, AMD64 Family 26 Model 68 Stepping 0, AuthenticAMD; Docker VM: 16 CPU, 15.2 GiB RAM; клиент Python 3.11.1; дата прогона 2026-10-14, commit 0ab3a34 + uncommitted changes. Лимиты контейнеров: api 1 CPU / 512 MiB каждая, postgres 1 CPU / 512 MiB, redis и lb по 0,5 CPU / 128 MiB.

Публичный тест отказа (make test-failover, 15 с записи во время остановки реплики):

Прогон Остановлена реплика Реплик до отказа Успешных записей Неудачных попыток (повторены с тем же ключом) Первая запись после hook, с
1 58542a53644c 2 128 0 4.203
2 9737b915ff2f 2 132 0 4.281

Остановка каждой реплики под нагрузкой (student-tests/failover_metrics.py: 4 потока записи без пауз + 1 поток чтения, timeout клиента 2 с, 3 с до и 10 с после отказа):

Реплика Как остановлена Команда, с HAProxy вывел из балансировки через, с Ошибок (коды) Ошибки прекратились через, с Записей/с до Записей/с после p95 после, мс Вернулась в балансировку после docker start, с
58542a53644c docker stop (SIGTERM) 4.12 1.11 0 (-) 0.0 304.7 202.2 47.0 3.25
58542a53644c docker kill (SIGKILL) 0.81 0.11 2 (502: 2) 0.05 328.7 228.2 32.0 1.55
9737b915ff2f docker stop (SIGTERM) 4.12 1.5 0 (-) 0.0 288.7 232.7 32.0 4.09
9737b915ff2f docker kill (SIGKILL) 0.83 0.11 2 (502: 2) 0.05 266.7 219.9 32.0 4.14

Во всех прогонах: потерянных подтверждённых сообщений 0, дублей 0, остановленная реплика после остановки не ответила ни разу.

Rolling update (student-tests/rolling_update.py): версия rolling-20261014-201405 -> rolling-20261014-202804, 2 реплики заменены по одной за 13.48 с под той же нагрузкой. Записей/с до: 284.7, во время замены: 346.3; ошибок: 0 (-); p95 31.0 мс, максимум 78.0 мс; подтверждено 6527 сообщений, потерь и дублей нет.

Публичный генератор нагрузки (tests/load.py, closed loop, concurrency 4, 30 с, 2 реплики): 308.848 успешных POST/с, ошибок 0 (доля 0.0), задержка успешных p50 15.0 мс, p95 32.0 мс, p99 46.0 мс.

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
docker stop реплики (SIGTERM) под нагрузкой ошибок нет: реплика сначала уходит из балансировки (readiness 503), потом закрывает приём ошибок: 0, 0 (по репликам); HAProxy вывел реплику через 1.11, 1.5 с ошибки прекратились через 0.0 с; потерь 0, дублей 0; реплика вернулась через 4.09 с после docker start
docker kill реплики (SIGKILL, авария) под нагрузкой единицы 502 на запросы, начатые на убитой реплике; клиент повторяет их с тем же ключом ошибок: 2, 2 (по репликам); HAProxy вывел реплику через 0.11, 0.11 с ошибки прекратились через 0.05 с; потерь 0, дублей 0; реплика вернулась через 4.14 с после docker start
публичный make test-failover для каждой реплики запись продолжается не позже 10 с, подтверждённые сообщения на месте, дублей нет PASS 2 раз(а), неудачных попыток: 0, 0 первая запись после hook через 4.203, 4.281 с (hook ждёт остановки ~4 с); потерь нет
rolling update под нагрузкой ошибок нет, реплик всё время не меньше 2 ошибок: 0, замена заняла 13.48 с потерь 0, дублей 0
перезапуск всего стенда (restart hook: postgres, redis, api, lb) данные и прежний токен живы PASS, те же контейнеры с новым временем старта 8.5 с до готовности; потерь нет

Также проверено (как в lab2, теперь через балансировщик, evidence/failures.txt): остановка Redis -> /health/ready 503, запросы с токеном 503, без токена 401, регистрация 201; аварийная остановка Redis -> сессия на месте (AOF); остановка PostgreSQL -> 503 без подробностей, анонимов не пускаем; после запуска прежний токен и сообщения на месте.

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

  • Выдерживается отказ одной API-реплики (процесса или контейнера). Не выдерживается отказ единственных lb, postgres, redis и всей машины: стенд на одном узле, это SPOF. Реплика БД и Redis, второй балансировщик — не в этой работе.
  • HAProxy на время проверок может послать запрос на реплику, которая только что умерла. Такой запрос получает 502 (если он уже был отправлен) или уходит на другую реплику (если упало соединение). 502 на POST сообщения клиент безопасно повторяет с тем же ключом; HAProxy сам POST не повторяет.
  • Создание чата и регистрация не идемпотентны по контракту: их повтор после timeout может создать второй объект.
  • Миграция 003 добавляет уникальное ограничение: на большой таблице построение индекса заблокировало бы запись в messages. Для большой базы нужен CREATE UNIQUE INDEX CONCURRENTLY отдельным шагом; на учебной базе это доли секунды.
  • Rolling update сделан скриптом (Compose не умеет заменять реплики по одной сам). В Swarm это было бы update_config: order: start-first.
  • X-Instance-Id раскрывает ID контейнера; в lab7 его нужно заменить на случайный alias.
  • Ключи идемпотентности хранятся вместе с сообщениями бессрочно (место в индексе растёт вместе с числом сообщений).