33 KiB
Отчёт — лабораторная 3
- Автор, группа: Унру Д.В. БПИ2303
- Целевая оценка; выбранный трек 5, если нужен: 3 (трек 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.
Запуск из чистого clone
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_checkNginx 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.
Доказательства критериев
| Критерий 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 до выполнения зависимости аутентификации.