28 KiB
Отчёт — лабораторная 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.