Files
mtusi2026lab3/REPORT.md
T
2026-11-02 11:42:24 +03:00

34 KiB
Raw Blame History

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

  • Автор, группа: Лукьянов К.Р. БПИ2303
  • Целевая оценка; выбранный трек 5, если нужен: 4 (трек 5 не заявлен)
  • Commit/PR: TODO после публикации
  • Использованные источники, библиотеки и помощь ИИ: FastAPI, Pydantic v2, Uvicorn, Psycopg 3, redis-py, argon2-cffi, pytest; документация Nginx load balancing, upstream/resolve и proxy_next_upstream, Docker Compose services, PostgreSQL transactions. Реализация выполнена совместно мной и Codex: часть кода, тестов и отчёта написана с помощью Codex, результат проверен запуском тестов, описанных ниже.

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

Prerequisites: Docker с Compose v2 (проверено на Docker Desktop 29.8.2, macOS), Python ≥ 3.9 на хосте для публичных тестов и скриптов (стандартная библиотека), Make. Внешние установленные PostgreSQL/Redis/Nginx не нужны. Порт localhost:8080 должен быть свободен от предыдущего стенда.

git clone <fork-url> && cd <каталог-fork-лабораторной-3>
make up              # secrets/.env → build API → migrate → api×2 → LB → дождаться 2 alias
curl -fsS http://localhost:8080/health/ready
docker compose ps    # две API-реплики, postgres, redis, lb — healthy; migrate — Exited(0)

make check
make validate-container  # полный валидатор OpenAPI без локальных pip-зависимостей
make test            # публичный smoke через LB
make test-student    # собственные интеграционные тесты: 14
make test-fresh      # обе миграции и 14 тестов на отдельных пустых volumes
make test-cluster    # все распределённые проверки, включая реальные отказы и rolling
make load-evidence   # отдельные 30 с нагрузки и CPU/RAM

Эквивалент make up: ./scripts/bootstrap.sh, docker compose build api, docker compose up -d --wait --wait-timeout 120, python3 scripts/cluster.py wait. Образ собирается до запуска migrate, поэтому готовый сервер из registry не требуется. Хосту доступен только LB 127.0.0.1:8080; API и хранилища напрямую не опубликованы.

Отдельные публичные проверки:

make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
# Публичный failover намеренно оставляет одну выбранную реплику остановленной.
# Восстановление:
docker compose up -d --no-recreate --wait --wait-timeout 90
python3 scripts/cluster.py wait

make verify-persistence дополнительно сохраняет снимки реальных контейнеров до/после. make verify-failover выполняет публичный failover и последовательные проверки каждого исходного контейнера, с восстановлением между ними. Полный make test-cluster последовательно запускает concurrent replay, persistence, публичный и собственные failover, SIGTERM, rolling, отказы Redis/БД и аудит инфраструктуры. Он меняет состояние стенда и собирает новый локальный образ с новым идентификатором релиза; не запускать параллельно с другими проверками.

bootstrap.sh создаёт случайный пароль PostgreSQL и файлы secrets один раз; существующие значения не меняет. Каталог secrets/ — 0700 на хосте, файлы доступны uid 10001 контейнера через Compose secrets; .env и secrets исключены из Git и Docker build context. Для lab3 созданы собственные secrets/volumes, данные и credentials lab2 не копировались.

Безопасная остановка: make down — контейнеры и сети удаляются, именованные volumes сохраняются. После make up доступны прежние данные, действующие сессии и результаты идемпотентности. Намеренное удаление всех учебных данных: docker compose down --volumes. Hook restart.sh volumes не удаляет. make test-fresh удаляет только созданные им временные volumes отдельного проекта. Синтетические данные обычных тестов остаются в основной БД.

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

                          ┌──► API-процесс A ──┐
клиент ──HTTP──► Nginx ──┤                   ├──► PostgreSQL: данные, сессии, результаты POST
127.0.0.1:8080            └──► API-процесс B ──┤
                                              └──► Redis: кэш публичного профиля

migrate ──► PostgreSQL    (один отдельный job до запуска API)
  • Перенос из lab2. Перенесены исходники FastAPI, миграция 001, Argon2id/Basic/Bearer, users/chats/messages, keyset-пагинация, Redis cache-aside профиля, ограниченные пулы и собственные проверки. Отправка сообщений и тесты адаптированы к обязательному Idempotency-Key. Dockerfile/Compose изменены для отдельных миграций, нескольких API и LB. Публичные tests/, contracts/, README и COURSE сохранены из skeleton lab3.
  • Общее состояние. PostgreSQL — источник истины для пользователей, чатов, участников, сообщений, сессий и результатов POST. API не держит в локальной памяти данных, от которых зависит корректность. Каждое защищённое обращение проверяет сессию в БД; X-User-Id игнорируется. Разные реплики обслуживают один Bearer без повторного входа. Sticky session не используется.
  • Идентификатор процесса. X-Instance-Id — случайный UUID alias, стабильный для жизни конкретного процесса; добавляется ко всем его ответам, включая health/ошибки. После restart alias меняется. X-App-Release — дополнительный заголовок для различения сборок в rolling-эксперименте. Ошибка, сформированная самим LB при недоступных backend, может не иметь API-заголовков и JSON.
  • Общая идемпотентность (src/messenger/messages.py, миграция 002). Таблица idempotency_records: PK(user_id,chat_id,key), request_hash, message_id FK, expires_at. Таблица обслуживает только POST сообщений, поэтому эта область соответствует user+method+chat path+key. Ключ строго ASCII [A-Za-z0-9._:-]{1, 128}, иначе 400. Валидированный JSON канонизируется независимо от форматирования/порядка полей, fingerprint — SHA-256. В схеме lab3 допустим только text; attachment_ids появится по контракту lab4.
  • Атомарность повтора. После проверки сессии и членства одна транзакция выполняет INSERT ключа ON CONFLICT DO NOTHING и SELECT FOR UPDATE. Конкурирующие процессы сериализуются на одной записи. При действующем ключе тот же fingerprint возвращает тот же Message и 201, другой — 409. Для нового/истёкшего ключа INSERT сообщения и обновление результата фиксируются одним COMMIT. Исключение откатывает оба эффекта, транзиентный 5xx не сохраняется как результат. Replay снова проверяет авторизацию. Срок ключа — 24 ч; после истечения разрешена новая запись с тем же ключом, старое сообщение не удаляется.
  • Миграции. migrate — отдельный одноразовый service, API зависит от service_completed_successfully. В API CMD мигратора нет. SQL-файлы 001/002, checksum и advisory lock сохраняют повторяемость и сериализуют возможные ручные запуски. Новая 002 только добавляет таблицу/индекс, не меняет старые поля lab2. Перед rolling один раз выполняется docker compose run --rm --no-deps migrate, пока старые API продолжают работу.
  • Балансировка и DNS. Nginx OSS 1.28: upstream messenger с общей zone messenger 64k и server api:8080 resolve. Все A-записи одного Compose-service api участвуют в round-robin; resolver 127.0.0.11 valid=1s ipv6=off обновляет IP без restart/reload Nginx. Адреса не зашиты в конфигурации.
  • Пассивные проверки upstream. max_fails=1 fail_timeout=2s: первая ошибка подключения/таймаут/503 исключает адрес на 2 с, затем допускается новая попытка. Активного health_check Nginx Plus здесь нет. Docker healthcheck каждого API раз в 2 с вызывает его readiness; healthcheck LB раз в 1 с делает GET readiness через Nginx и создаёт фоновый трафик даже без клиента. При двух backend, работающем Docker DNS и настроенных таймаутах консервативный бюджет обнаружения — до 8 с; фактические чтения/записи после отказа проверяются в пределах 10 с. В отличие от активного мониторинга, пассивное исключение происходит только после обращения к backend.
  • Таймауты и повтор. Nginx connect 1 с, read/send 5 с; proxy_next_upstream error timeout http_503, не более 2 upstream-попыток и 6 с на переключение. GET может уйти на другую реплику при ошибке. Параметр non_idempotent не включён: уже отправленный POST автоматически не пересылается; при connect error до отправки запроса допустим безопасный выбор другого адреса. Неопределённую отправку сообщения повторяет клиент с прежним Idempotency-Key.
  • Readiness и graceful. /health/live проверяет процесс; /health/ready требует доступную PostgreSQL и таблицу новой схемы. Несовместимая схема/ошибка зависимости →503. Redis — некритичный кэш с fallback, его отказ readiness не меняет. Uvicorn работает PID1, один worker на контейнер, graceful timeout5 с. Docker stop_grace_period10 с; hook stop-one использует 7 с, укладываясь в публичный бюджет 10 с. SIGTERM закрывает listening socket и даёт активным запросам завершиться.
  • Остановка выбранной реплики. scripts/stop-one.sh — короткий wrapper Python-оркестратора cluster.py. Тот сопоставляет TARGET_INSTANCE_ID с реальным контейнером внутренним GET /health/live, останавливает ровно его, проверяет exit 0 и оставляет остановленным. Идентификаторы контейнеров/процессов и время записываются без credentials. restart.sh перезапускает все API, PostgreSQL, Redis и LB с прежними volumes.
  • Поочерёдная замена. Compose не предоставляет здесь автоматический Swarm rolling update. Проверен эквивалент start-first: временно scale api=3 с --no-recreate, дождаться новой healthy-реплики и трёх alias через LB, затем stop/remove одного старого контейнера и возврат к 2. Второй старый контейнер в этом шаге не пересоздаётся. Создание до удаления старого гарантирует другой IP; оба адреса сохраняются. Шаг повторяется для второго исходного контейнера.
  • Пароли, сессии, кэш. Argon2id (19456 KiB, time_cost2, parallelism1), opaque token256 бит, в БД только SHA-256 токена и абсолютный expiry; logout удаляет сессию. Redis хранит только User по user:<UUID> на 60 с после проверки сессии. Профиль неизменяем в обязательном API, инвалидация по событию не нужна. История читается из PostgreSQL и не бывает устаревшей из-за кэша.
  • Запросы/ошибки. SQL параметризован; каждый API-пул min 1/max 8, очередь 16, ожидание 2 с, connect_timeout3 с, statement_timeout3 с, lock_timeout2 с. Redis-пул 8, connect/read по 0.2 с без retry. JSON строго UTF-8, неверные типы/поля/формат →400, неподдерживаемый media type →415; чужие чаты →404. X-Request-Id совпадает с request_id ошибки. Access-лог Uvicorn отключён, тела/токены/SQL в логи не выводятся.

Конфигурация и ресурсы:

Переменная / service Значение Использование
SESSION_TTL_SECONDS (.env) 3600 по умолчанию абсолютный срок сессии, в собственном тесте expiry — 2 с
DATABASE_URL_FILE /run/secrets/database_url API и migrate читают адрес/credentials БД
CACHE_URL_FILE /run/secrets/cache_url только API читает адрес Redis
POOL_MAX_SIZE 8 на API-процесс ограничение числа соединений
api mtusi-lab3-api:lab3; каждая 0.75 CPU / 384 MiB один scale-able service, штатно 2 реплики, без container_name и host ports; сети front+data
lb nginx:1.28.0-alpine; 0.5 CPU / 128 MiB единственный публичный порт 127.0.0.1:8080; только front, без DB secrets
postgres postgres:17.5-bookworm; 1 CPU / 512 MiB только internal data; volume postgres_data; pg_isready
redis redis:7.4.4-bookworm; 0.25 CPU / 128 MiB только internal data; volume redis_data; AOF; maxmemory64 MiB/allkeys-lru
migrate тот же образ API; 0.5 CPU / 256 MiB только data, только database_url secret; Exited(0) после применения

Dockerfile: python:3.13.5-slim, полностью закреплённые зависимости в requirements.lock, пользователь messenger uid 10001. Установка зависимостей предшествует копированию исходников; ARG APP_RELEASE расположен после этих слоёв, поэтому смена только метки релиза не переустанавливает библиотеки. CMD — exec Uvicorn. Healthchecks задаются Compose; .dockerignore исключает Git, secrets/.env, сертификаты, volumes и evidence. Публичные и собственные проверки включены в образ для запуска без pip на хосте. Номера контейнеров после замен могут иметь пропуски: cluster.py exec выбирает реально живой контейнер, не предполагает существование api-1.

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

Прогоны 2026-11-02, macOS, Apple M4 Pro /24 GiB RAM, Docker Desktop29.8.2. Docker VM:12 CPU, около 7.75 GiB RAM. Ветка solution/bpi2303-lukyanov; сведения о процессах/образах, лимитах и сети — в evidence. Коммиты/публикация выполняются автором отдельно.

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Nginx, конфигурация и две реплики verify_cluster.py nginx nginx -t PASS, Server:nginx, два alias через LB evidence/nginx.json
Контракт и публичный smoke (3) make check, make validate-container, make test PASS, lab3 public API scenario через LB evidence/check.txt, openapi.txt, smoke.txt
≥2 API, один LB, общая БД и сессии (3) cluster.py wait; concurrent replay; infrastructure один Bearer работает на разных alias; реально два API-контейнера, порты только у LB evidence/concurrent-idempotency.json, infrastructure.json
Отказ любой одной реплики, чтение/запись ≤10 с (3) публичный failover + остановка каждого исходного контейнера оба сценария PASS; чтение известного сообщения, пока target ещё остановлен; post-stop POST в пределах 10 с evidence/public-failover.txt, sequential-failover.json
Общая идемпотентность и отсутствие дублей (3) 8 параллельных повторов через 2 alias все 201 с одним Message, в истории 1 сообщение; другой body409 evidence/concurrent-idempotency.json
Сохранность и прежняя сессия (3) make verify-persistence API/БД/Redis/LB действительно перезапущены; volumes те же; прежний токен и данные доступны evidence/persistence.txt, persistence.json
Обязательные key/alias, TTL 24 ч, scope, rollback, повторная авторизация make test-student 14/14 PASS, включая отказ после INSERT и rollback ключа+сообщения evidence/student-tests.txt
Миграции отдельно, с нуля и повторяемо make test-fresh; migration test применены 001/002, повтор без дублей, 14/14 PASS на новых volumes evidence/fresh-migrations.txt
Health/readiness/timeouts/SIGTERM (4) Nginx config; test_ready_requires_compatible_schema; SIGTERM с активным POST схема недоступна→503; активный POST 201, новые TCP отвергнуты пока процесс ещё жив, exit 0 за 1.9171 с evidence/student-tests.txt, graceful-shutdown.json
Последовательно остановлена каждая реплика, RPS/errors/recovery (4) verify_cluster.py failover два разных исходных container id; предыдущий восстановлен; подтверждения сохранены без дублей evidence/sequential-failover.json
CPU/RAM, нет API host ports/container_name (4) verify_cluster.py infra; реальное scale 2→3→2 лимиты есть у всех сервисов, единственный public endpoint у LB, api масштабируется evidence/infrastructure.json, rolling-update.json
Rolling-equivalent под нагрузкой, отдельные совместимые миграции (4) verify_cluster.py rolling два старых контейнера заменены новым образом, оба новых IP обнаружены LB; 14 975 подтверждённых сообщений сохранены evidence/rolling-update.json
Предыдущая авторизация и отказ зависимостей сохранены verify_cluster.py dependencies; собственные auth/expiry tests Redis fallback200; PostgreSQL 503; после восстановления тот же токен работает evidence/dependency-failures.json, student-tests.txt

Чтобы повторно сохранить вывод: make test > evidence/smoke.txt, make test-student > evidence/student-tests.txt, make validate-container > evidence/openapi.txt, make test-fresh > evidence/fresh-migrations.txt. Распределённые сценарии сами обновляют свои JSON/text в evidence. Контракт и публичные tests не ослаблены; source lab2 переносился без них. Secrets, пароли и Bearer-токены в отчёт/evidence не записываются.

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

Исследовательский трек 5 не проводился. Во всех сценариях используется реальный PostgreSQL/Redis и два API-процесса за Nginx. Генератор отказов/rolling — closed-loop4 потока; после неопределённого результата повторяет только POST сообщения, с прежним key/body. Подтверждённые ответы сверяются с полной историей, проверяются уникальность UUID и текста. Это проверка конкретных ограниченных отказов одного локального стенда.

В последовательном сценарии перед воздействиями есть 3 с базовой работы, каждое окно остановки — около 8 с, предыдущий контейнер запускается и обнаруживается через LB перед следующим. Время записи считается только по запросу, начатому после возврата stop hook, а общий deadline10 с отсчитывается от старта hook. Чтение известного подтверждённого сообщения также выполняется до восстановления target.

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
Первый исходный API остановлен другая реплика читает/пишет, остановленная не обслуживает 400.056 RPS, 1 ошибочная попытка в окне; GET 200 и прежнее сообщение POST через 1.3835 с от начала hook /0.0138 с после его завершения; GET через 1.38 с от начала
Второй исходный API остановлен после восстановления первого те же гарантии 401.166 RPS, 1 ошибочная попытка; GET 200, target оставался stopped POST через 1.4405 с от начала hook /0.0151 с после завершения; GET через 1.4375 с от начала
Оба последовательных отказа подтверждённые записи не теряются, retry не создаёт дубль 15 915 подтверждённых сообщений =15 915 в истории потерь/дублей не обнаружено
SIGTERM во время активного POST прекратить новые соединения, завершить активный запрос SQL-запрос наблюдался в PgSleep; POST 201, новые TCP получили ConnectionRefusedError ещё при живом процессе; exit 0 1.9171 с от SIGTERM / сообщение сохранено
Новый образ, поочерёдная start-first замена адреса обновляются без рестарта LB, другая API продолжает работу два шага 5.864/5.6574 с; разные IP, 3 alias при старте; во время замены 687.069 RPS, 1 ошибочная попытка (0.0126%) 14 975 подтверждённых сообщений сохранены, дублей 0
Полный restart API/PG/Redis/LB с volumes прежний токен читает прежние данные без повторного входа public persistence PASS, реальные StartedAt изменились потерь подтверждённого сообщения и сессии не обнаружено
Redis остановлен fallback в PostgreSQL без ослабления авторизации GET 200 за 0.0138 с, ready 200, аноним 401 данные/сессии в БД сохранены
PostgreSQL остановлен защищённый запрос 503, процесс остаётся жив 503; обе внутренние live 200; после старта БД та же сессия работает ошибки не приводят к доверию по кэшу

Как проверялся SIGTERM: временный BEFORE INSERT trigger задерживает ровно один синтетический текст через pg_sleep(2). После наблюдения активного запроса в pg_stat_activity процесс получает SIGTERM. Проверяется отказ новых TCP, пока процесс ещё работает, затем 201 исходного запроса, exit 0 и чтение результата через surviving API. Trigger/function удаляются в finally, контейнер восстанавливается. В коде приложения тестового endpoint/режима нет.

Что именно обновлялось: собран действительно другой образ с отличающейся меткой APP_RELEASE, что видно по image id и X-App-Release. Код бизнес-API и схема совместимы; новой функциональной возможности в этом тестовом релизе не добавлялось. Мигратор запускается один раз перед заменами, не каждым новым API. Проверка доказывает поочерёдную замену сборки и обновление адресов, а не безопасное выполнение произвольной destructive migration.

Нагрузка без отказов: make load-evidence, 30 с, concurrency 4, две реплики, без автоматических retry, один сохранённый прогон. Перед ним стенд прогрет функциональными сценариями; отдельного измеряемого нагрузочного прогрева нет. 24 559 успешных запросов, 0 ошибок, 814.97 successful RPS; p50/p95/p99=4.03/5.822/47.235 мс. Число сообщений в БД: до запуска — 102 032, после — 126 591. Исходный summary — evidence/load.json, параметры и данные — environment.json, замеры ресурсов — resources.json.

Выборочные пики CPU/RAM за нагрузочный прогон (Docker CPU 100% = одно ядро; это пики отдельных samples, не одновременная сумма):

Контейнер CPU peak Memory peak
API-процесс 1 68.64% 78.41 MiB
API-процесс 2 69.43% 66.61 MiB
Nginx 10.01% 7.895 MiB
PostgreSQL 42.15% 99.4 MiB
Redis 0.99% 11.04 MiB

Имена конкретных контейнеров и исходные значения — evidence/resource-summary.json. Эти цифры не доказывают максимальную пропускную способность и не являются сравнением с lab2: ресурсы/набор данных отличаются. Closed-loop имеет coordinated omission, latency рассчитана только для успешных ответов, клиент и Docker работают на одном ноутбуке. Переходные ошибки во время отказов/замен измерены и учитывают клиентские результаты. Nginx может скрыть connect error до отправки запроса и повторить безопасный GET; уже отправленные POST не повторяются им автоматически.

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

  • Один Docker-host; LB, PostgreSQL и Redis — по одному экземпляру. Проверен отказ API-процесса, не узла/диска/БД с failover. Restart с volumes не заменяет backup и не обеспечивает HA.
  • Compose-замена — наш явный start-first сценарий с временной третьей репликой, не автоматический rolling-контроллер Swarm. Сам по себе обычный docker compose up не является доказанным безопасным rolling update. При обрыве нашего сценария может потребоваться ручное восстановление до двух healthy-реплик.
  • В миграциях используются только совместимые аддитивные изменения. Breaking schema change требует expand/contract, миграции данных или отдельного окна; в этой работе не проверен. Advisory lock предотвращает одновременное применение, но сам по себе не делает любую миграцию совместимой.
  • При SIGTERM/обнаружении отказа допускаются краткие HTTP/connection errors. Клиент повторяет только отправку сообщения с тем же Idempotency-Key. Создание чата и регистрация не имеют общей идемпотентности и после отправки тела автоматически не повторяются.
  • TTL идемпотентности 24 ч и expiry сессии проверяются при запросе; фоновой очистки старых строк пока нет. Истёкший ключ можно использовать заново, это создаст новое сообщение.
  • Redis без пароля в изолированной data-сети Compose; сессии всегда проверяются в PostgreSQL. Изменение профиля в будущем потребует инвалидации кэша. В этой работе нет TLS, rate limiting входа, PKI и secret manager.
  • Нет общего snapshot между страницами; конкурентная запись с ключом до cursor может остаться позади обхода. Порядок COMMIT не обязан совпадать с порядком created_at.
  • Когда БД недоступна и LB исключил обе API-реплики, даже /health/live через публичную точку может получить 502/503/504 от LB; внутренний /health/live каждого процесса остаётся 200. Это различие готовности маршрута и жизни процесса.
  • UI/WebSocket, изменение участников и редактирование/удаление сообщений не входят в обязательный API. Malformed JSON без Bearer может дать 400 до выполнения зависимости аутентификации.