Files
mtusi2026lab3/REPORT.md

28 KiB
Raw Permalink Blame History

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

  • Автор, группа: Саватеев Артём, БВТ2302
  • Целевая оценка: 4 (весь уровень 3 + весь уровень 4);
  • Источники: документация nginx upstream (resolve, max_fails, keepalive_timeout) и proxy (proxy_next_upstream, повтор неидемпотентных запросов), Compose services/deploy, исходники uvicorn 0.54 (Server.shutdown, h11 keep-alive). Библиотеки — из lab2 (FastAPI, asyncpg, redis-py, argon2-cffi), новых зависимостей нет. Помощь ии

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

cp .env.example .env              # затем задать свои DB_PASS и VALKEY_PASS (синтетические)
docker compose --env-file .env config --quiet
make up                           # = docker compose up -d --build --wait: build → postgres/valkey →
                                  #   migrate (однократно) → api ×API_REPLICAS → nginx; ждёт healthy
make check test                   # стенд доступен только через LB: http://localhost:8080
python3 -m venv .venv-validate && .venv-validate/bin/python -m pip install -r requirements-dev.txt
make validate PYTHON=.venv-validate/bin/python   # полная OpenAPI-валидация; не в .venv —
                                  #   его Poetry принял бы за окружение проекта (Python 3.9)
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
make instances                    # какой контейнер остановлен: контейнер ↔ X-Instance-Id ↔ PID ↔ ревизия
make restore                      # вернуть остановленную реплику (работающие не пересоздаются)
make student-test                 # собственные тесты (poetry install --no-root один раз)
make rolling-update               # выкладка новой сборки по одной реплике без простоя
make down                         # безопасная остановка, volume с данными сохраняется
make destroy-data                 # намеренное удаление учебных данных (down -v)

Действия оператора: создать .env с секретами (в Git не попадает), после stop-one.sh вручную выполнить make restore. Миграции отдельно запускать не нужно — их выполняет сервис migrate внутри make up/rolling-update. Сборку через make/скрипты лучше, чем голый docker compose up --build: Makefile экспортирует BUILDX_NO_DEFAULT_ATTESTATIONS=1, иначе Docker Desktop добавляет к образу provenance-attestation, ID образа меняется на каждой сборке и Compose пересоздаёт все реплики разом. Обновлять работающий стенд — только make rolling-update.

Воспроизводимость проверена копией ровно тех файлов, что попадут в Git (без .env), отдельным compose-проектом на пустом volume: build, migrate с нуля, smoke, failover, persistence — evidence/15-clean-clone.txt.

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

клиент ──► nginx :8080 (127.0.0.1, единственный опубликованный порт)
             │  round-robin, без sticky; Docker DNS «api» перечитывается каждые 2 с
             ├──► api-1 ─┐   сеть edge: только LB и API
             └──► api-2 ─┤
                         ├──► postgres (источник истины: пользователи, чаты, сообщения,
                         │              сессии, ключи идемпотентности; volume postgres_data)
             migrate ────┤
                         └──► valkey (read-through кэш сессий, не источник истины)
                              сеть backend: internal, LB туда не подключён

Перенесено из lab2: API, PostgreSQL как источник истины, сессии в PostgreSQL с кэшем в Valkey (logout инвалидирует общий кэш), Argon2id, keyset-пагинация, монотонный created_at под advisory lock чата, обработка отказов Valkey/PostgreSQL. Локального состояния, от которого зависит корректность, в API нет: circuit breaker Valkey и пул соединений — только оптимизации процесса.

Изменено в lab3:

Что Решение Где
Реплики и LB api с deploy.replicas: ${API_REPLICAS:-2}, без container_name и портов; nginx 1.28 upstream api { server api:8080 resolve; } — новые/остановленные контейнеры подхватываются без reload compose.yaml, infra/nginx/nginx.conf
X-Instance-Id случайный alias процесса (secrets.token_hex(6)), без hostname/IP; в каждом ответе API; процесс пишет его в /tmp/instance-id для оператора request_context.py, settings.py
X-Request-Id nginx передаёт $request_id, API принимает его (только 32 hex) — одна строка access-лога LB и журнал реплики связаны одним ID там же, evidence/04
Idempotency-Key обязательный заголовок [A-Za-z0-9._:-]{1,128} (нет/неверный — 400); таблица message_idempotency_keys, PK (sender_id, chat_id, key), SHA-256 канонического тела, TTL IDEMPOTENCY_TTL_SECONDS = 24 ч 0002_message_idempotency.sql, postgres.py, message_service.py
Миграции one-shot сервис migrate (src/migrate.py) до реплик (service_completed_successfully); реплика миграции не применяет, а проверяет версию схемы и не стартует, если схема старее кода database.py, migrate.py
Graceful shutdown SIGTERM → drain 1 с (порт закрыт, readiness 503, ответы по открытым keep-alive с Connection: close) → graceful uvicorn до 5 с → закрытие пулов gateway.py
Ошибки LB 502/503/504, созданные nginx, отдаются как 503 {"error":{"code":"unavailable",…}} с X-Request-Id; ответы реплик проходят без изменений infra/nginx/errors.conf

Транзакционная граница идемпотентности. В одной транзакции: pg_advisory_xact_lock(чат) → поиск действующего ключа → (повтор: вернуть сохранённое сообщение или 409 при другом теле) → INSERT сообщения → INSERT ключа. Ключ привязан к чату, поэтому блокировка чата, уже нужная для монотонного created_at, сериализует и одновременные повторы с разных реплик: второй ждёт COMMIT первого и находит ключ (READ COMMITTED). Ошибка до COMMIT откатывает и сообщение, и ключ — транзиентный 5xx не фиксируется как результат. Повтор заново проходит проверку сессии и членства. Область «пользователь + метод + путь + ключ» сведена к (sender_id, chat_id, key): метод и путь фиксированы. Порядок ключей и пробелы JSON не влияют (хеш от тела, сериализованного по схеме). Истёкший ключ переиспользуется (ON CONFLICT … DO UPDATE) и создаёт новое сообщение.

Почему nginx не повторяет POST сам. proxy_next_upstream error timeout без non_idempotent: запрос, не дошедший до реплики (connect refused/timeout), nginx отправляет следующей реплике — это безопасно для любого метода. POST, уже отправленный реплике, не повторяется: прозрачный повтор POST /users//chats создал бы дубль (контракт это запрещает). Неопределённый POST сообщения повторяет клиент с тем же ключом. 503 приложения тоже не повторяется и не исключает реплику: он означает отказ общей зависимости, другая реплика зависит от той же БД.

Health, readiness, таймауты и время обнаружения

Механизм Значение Назначение
/health/live 200 пока жив процесс liveness, проверки через LB
/health/ready 200 если не завершается и PostgreSQL отвечает (Valkey не критичен — сессии читаются из БД) Docker healthcheck API: interval 5s, timeout 3s, retries 2, start_period 20s, start_interval 1s; используется up --wait, depends_on nginx, restore.sh, rolling-update.sh
Порт реплики открывается только после startup (БД + версия схемы), закрывается первым при SIGTERM LB не шлёт трафик в неготовую/завершающуюся реплику
nginx proxy_connect_timeout 0,5 с исчезнувший IP (SIGKILL/крах контейнера)
nginx proxy_read_timeout / send 10 с зависшая реплика; дольше самого долгого запроса API (ожидание пула 3 с + statement_timeout 5 с)
max_fails=1 fail_timeout=5s после ошибки соединения реплика исключена на 5 с, затем пробный запрос
resolver 127.0.0.11 valid=2s остановленный контейнер пропадает из upstream ≤ 2 с, новый появляется ≤ 2 с
keep-alive nginx → API keepalive_timeout 60s < uvicorn timeout_keep_alive 75 s idle-соединение закрывает LB, а не реплика: нет гонки «запрос в закрытое соединение»
SIGTERM drain 1 с + graceful ≤ 5 с < stop_grace_period 10s SIGKILL не прерывает завершение

У nginx open source нет активных health checks — проверка пассивная, по реальным запросам. Максимальное время обнаружения: остановка процесса/SIGTERM — 0 с (порт закрыт → connection refused → тот же запрос сразу уходит на другую реплику, клиент ошибки не видит); крах контейнера — ≤ 0,5 с на запрос (connect timeout), затем исключение на 5 с и удаление из DNS ≤ 2 с; зависание без закрытия порта — ≤ 10 с (read timeout; GET повторяется, POST получает 503 и повторяется клиентом с тем же ключом). Docker healthcheck обнаруживает неготовность за ≤ 5 с × 2 = 10 с, но в Compose он не исключает контейнер из DNS — поэтому балансировку обеспечивает nginx, а не depends_on/healthcheck.

Ресурсы, сети, секреты

Роль Service Образ CPU / RAM Сети Порт наружу Volume Credentials
LB nginx nginx:1.28.0-alpine3.21 0,5 / 64M edge 127.0.0.1:8080 (+8081 только для test-expiry) — нет
API ×2 api mtusi-messenger:lab3 (из исходников) 1,0 / 512M каждая edge, backend нет — DB_PASS, VALKEY_PASS из .env
Миграции migrate тот же 0,5 / 256M backend нет — DB_PASS
БД postgres postgres:18.2-alpine3.22 1,5 / 512M backend нет postgres_data POSTGRES_PASSWORD = DB_PASS
Кэш сессий valkey valkey/valkey:8.1.4-alpine3.22 0,25 / 96M backend нет нет (не источник истины) VALKEY_PASS

Сеть backend — internal: nginx не видит БД и Valkey (даже не резолвит имя), хранилища не имеют выхода наружу. Порт PostgreSQL больше не публикуется на хост (в lab2 был 127.0.0.1:5432); тесты обращаются к БД через docker compose exec. Подтверждение: evidence/11-limits-ports-networks.txt. 512M на реплику: Argon2id RFC 9106 low-memory — 64 MiB × PASSWORD_HASH_WORKERS=4. Пул БД: 2 реплики × DB_POOL_MAX_SIZE=10 + migrate + реплика при rolling update = 40 ≤ max_connections=100.

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

Переменная Используется Примечание
APP_HOST, APP_PORT uvicorn 0.0.0.0:8080 внутри контейнера
APP_ENV, LOG_LEVEL журнал
APP_KEEPALIVE_TIMEOUT_SEC=75 uvicorn timeout_keep_alive новое; > keepalive_timeout nginx
SHUTDOWN_TIMEOUT_SEC=5 uvicorn timeout_graceful_shutdown
SHUTDOWN_DRAIN_SEC=1 DrainingServer новое
DB_* asyncpg pool DB_HOST/DB_PORT переопределены в compose (postgres:5432); DB_PORT больше не публикуется
VALKEY_* redis-py VALKEY_HOST/PORT переопределены в compose
SESSION_TTL_SECONDS, SESSION_CACHE_TTL_SECONDS, PASSWORD_HASH_WORKERS как в lab2 api-short-ttl переопределяет TTL = 2
API_REPLICAS=2 deploy.replicas
IDEMPOTENCY_TTL_SECONDS=86400 срок ключа
LB_PORT=8080 (+ LB_EXPIRY_PORT, по умолчанию 8081) публикация nginx новое
APP_REVISION build arg → метка образа и журнал старта не в .env; задаёт rolling-update.sh

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

Формат файлов — транскрипт терминала: $ команда, затем сырой вывод.

Критерий README Команда/сценарий Наблюдаемый результат Файл
Публичный smoke make check test PASS lab3 public API scenario 02
3: стенд одной командой, ≥2 API, один вход, общие БД и сессии make up, docker compose ps, make instances 2 реплики healthy, migrate Exited (0), наружу только nginx 01
3: одна сессия → разные реплики без повторного входа pytest test_balancing.py -s, access-лог nginx 20 запросов одним токеном: 10/10 по двум X-Instance-Id; logout на одной реплике действует на всех 04
3: остановка любой реплики, чтение/запись ≤ 10 с make test-failover для api-1, затем для api-2 129 / 128 / 129 успешных записей, 0 неудачных попыток, первая запись после возврата hook 1,6–2,7 с; instances и docker inspect показывают реально остановленный контейнер (exit 0, журнал drain/shutdown) 05a, 05b
3: Idempotency-Key без дублей, включая конкурентный повтор и смену реплики pytest test_idempotency.py -s 20 одновременных POST с одним ключом через обе реплики (10/10): все 201, одно тело, 1 строка в БД; разные тела под одним ключом — один победитель, остальные 409; 400 для нет/неверного ключа; область user+chat; повтор после logout — 401, чужой — 404; истёкший ключ создаёт новое 04
3: persistence make test-persistence ACTION_SCRIPT=scripts/restart.sh PASS; StartedAt всех 5 контейнеров изменился, volume тот же (created 16:10:27Z) 06
Регрессия lab2 make student-test, test-expiry, test-failures 107 passed; TTL 2 с через LB :8081; отказ Valkey/PostgreSQL как в lab2 03, 07, 08
4: health/readiness/таймауты/SIGTERM согласованы; LB исключает backend make sigterm-check exit 0 за 1,53 с; 354 запроса через LB после SIGTERM без ошибок; после выхода реплика не отвечает 10
4: поочерёдная остановка каждой реплики, RPS/ошибки/восстановление make experiment-failover см. «Эксперименты»: SIGTERM — 0 ошибок; SIGKILL — 1 и 3 ошибки 503, повтор тем же ключом; потерь/дублей 0 13, json
4: идемпотентность параллельными запросами test_parallel_* см. строку уровня 3 04
4: лимиты CPU/RAM, API без портов, сети/секреты, нет container_name docker inspect, docker network inspect лимиты у всех контейнеров; порты только у nginx; backend internal 11
4: rolling update под нагрузкой make experiment-rolling обе реплики заменены новой ревизией, 0 ошибок, наибольший разрыв между подтверждениями записи 0,098 с 14, json
4: миграции однократно и совместимы с работающей версией make test-migrations, scripts/check_previous_version.sh с пустого volume, 3 повтора идемпотентны; API до migrate отказывается стартовать; lab2-код (aa971fb) работает на схеме v2: вход, чат, запись, чтение 09
Чистый clone копия файлов Git, отдельный проект build → smoke → failover → persistence PASS, затем down -v 15

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

Гипотеза. При остановке одной из двух реплик (SIGTERM) клиент не видит ошибок: порт закрывается раньше, чем реплика перестаёт отвечать, и nginx переотправляет ещё не доставленные запросы; при SIGKILL теряются только запросы, бывшие в обработке у убитой реплики, а повтор с тем же ключом не создаёт дублей. Пропускная способность при одной реплике падает, так как API ограничена 1 CPU.

Методика (scripts/experiment.py). Стенд из таблицы ресурсов на Apple M4 / Docker Desktop VM 10 CPU, 8 GiB. 4 потока closed loop через LB: POST сообщения (неподтверждённый POST повторяется с тем же ключом и телом каждые 50 мс до 201) + GET ?limit=1; timeout клиента 5 с; новый чат на прогон (≈ 10–12 тыс. сообщений за прогон). Фазы: 8 с до отказа → отказ (docker stop = SIGTERM, затем docker kill -s SIGKILL) → 10 с с одной репликой → scripts/restore.sh → 8 с. Порядок: api-1, api-2 для каждого сигнала, с восстановлением предыдущей. После прогона история читается целиком: каждое подтверждённое сообщение на месте и не изменено, нет дублей id/текстов. «Время восстановления записи» — от первой ошибки после отказа до первой успешной записи после последней ошибки; «разрыв» — наибольший интервал между подтверждениями записи. Один прогон на сценарий; CPU/RAM — docker stats в середине фазы «до».

Воздействие Что ожидаем Что наблюдали (запись ok RPS до / во время / после) Ошибки, восстановление, данные
SIGTERM api-1 0 ошибок 382 / 277 / 399 0 ошибок; разрыв 0,063 с; реплика в ротации через 0,97 с после restore; потерь/дублей 0
SIGTERM api-2 0 ошибок 401 / 282 / 362 0 ошибок; разрыв 0,071 с; в ротации через 3,7 с; 0 / 0
SIGKILL api-1 ошибки только у запросов в обработке 427 / 281 / 408 1 × 503 (POST, оборван убитой репликой), восстановление < 0,01 с, разрыв 0,070 с; повтор ключом создал сообщение один раз; 0 / 0
SIGKILL api-2 то же 387 / 277 / 373 3 × 503, восстановление 0,006 с, разрыв 0,061 с; 0 / 0
Rolling update 2 → 3 → 2 → 3 → 2 0 ошибок 420 / 308 / 345 0 ошибок; разрыв 0,098 с; старые alias исчезли через 8,1 и 14,9 с от начала, новые вошли на 4,9 и 13,9 с; обе реплики на новой ревизии; 0 / 0
Valkey / PostgreSQL недоступны обход кэша / ограниченный 503 как в lab2, через LB 08
Рестарт всего стенда данные и токен сохраняются PASS 06

Нагрузка до отказа: API ≈ 84 % от лимита 1 CPU каждая, PostgreSQL ≈ 28 %, nginx ≈ 9 %, память API ≈ 48 MiB. Во время отказа запись падает на ≈ 30 % (не вдвое: при двух репликах узким местом частично являются клиент и БД). Базовый публичный генератор (tests/load.py, 30 с, concurrency 4, только POST): 713 успешных RPS, 0 ошибок, p50/p95/p99 = 4,7 / 8,4 / 22,5 мс — evidence/12, load.json.

Подтверждённое улучшение — drain при SIGTERM. Без drain uvicorn по SIGTERM сразу закрывает idle keep-alive соединения, и nginx изредка отправлял запрос в уже закрываемое соединение: в пробном rolling update был upstream prematurely closed connection (GET nginx повторил; POST в той же ситуации получил бы 503). С drain в итоговых прогонах SIGTERM и rolling update таких событий 0 — все 4 случая «prematurely closed» в журнале nginx пришлись на прогоны SIGKILL (сопоставлено по времени, где это ожидаемо).

Ограничения измерения. Closed loop с 4 потоками страдает coordinated omission и ограничен клиентом на той же машине; по одному прогону на сценарий, без доверительных интервалов; RPS — подтверждения HTTP, а не COMMIT. Числа описывают этот ноутбук, не универсальную ёмкость.

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

  • Выдерживается: отказ/остановка/крах одного API-процесса или контейнера, поочерёдная замена реплик, перезапуск всего стенда с volumes, отказ Valkey. Не выдерживается: отказ nginx, PostgreSQL (одна реплика БД — SPOF; API честно отвечает 503) и Docker-host — все контейнеры на одном узле. Отказ процесса ≠ отказ узла: здесь проверен только первый.
  • nginx open source — только пассивные проверки: реплика, которая принимает соединения, но не отвечает, обнаруживается за proxy_read_timeout (10 с) и снова получает пробный запрос каждые 5 с; healthcheck Docker в Compose её не исключает. Активные проверки дал бы HAProxy/Traefik или nginx Plus.
  • docker stop/docker kill не перезапускаются политикой unless-stopped (так и задумано для stop-one.sh); автоматического восстановления упавшей реплики Compose не даёт — make restore выполняет оператор.
  • Истёкшие ключи идемпотентности удаляются только при повторном использовании ключа; фоновой очистки нет (строки маленькие, но таблица растёт).
  • Совместимость миграций обеспечивается правилом expand-only и проверена для пары lab2 → lab3 на уровне схемы; поведение API при смешанных версиях (старая реплика не требует ключа и не отдаёт X-Instance-Id) во время такой выкладки различается — это переход контракта, а не схемы.
  • api-short-ttl для make test-expiry тоже за LB (порт 8081), но 8081 публикуется nginx постоянно; без профиля expiry он отвечает 503.