FastAPI + PostgreSQL как единый источник истины: пользователи, Basic/Bearer-сессии, чаты, сообщения. Сессии и идемпотентные ключи хранятся в БД, поэтому реплики взаимозаменяемы. Общая идемпотентность POST сообщения по Idempotency-Key, включая конкурентный повтор через разные реплики. compose.yaml: postgres, one-shot migrate, api1, api2 и nginx как единственная публичная точка входа. Добавлены scripts/stop-one.sh и scripts/restart.sh, student-tests, evidence и заполненный REPORT.md.
19 KiB
Отчёт — лабораторная 3
- Автор, группа: TODO (заполнить перед PR)
- Целевая оценка: 3 — работающий минимум. Уровень 4 и трек 5 не заявлены.
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ:
contracts/openapi.json,contracts/README.md,README.md, публичные тестыtests/; FastAPI 0.115.0, uvicorn 0.30.6, psycopg 3.2.3, psycopg-pool 3.3.3, PostgreSQL 16.4, Nginx 1.26.2. Реализация и текст отчёта подготовлены с помощью ИИ-ассистента Koda; все приведённые проверки выполнены и воспроизведены локально.
Запуск из чистого clone
Проверено на: Windows 11 Pro 22621 x64, AMD Ryzen 7 7700 (8 ядер / 16 потоков), 32 GB RAM, Docker Engine 29.4.3, Docker Compose v5.1.3 (Linux containers), Python 3.10.11 для публичных тестов. Дата прогонов: 2026-11-07.
Версии зафиксированы: python:3.12.6-slim-bookworm, postgres:16.4-alpine, nginx:1.26.2-alpine; Python-зависимости — в requirements.txt.
# 1. Локальная конфигурация (значения в примере синтетические, .env не коммитится)
cp .env.example .env
# 2. Проверка и сборка/запуск всего стенда
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
# 3. Ожидание готовности (миграции выполняются автоматически отдельным сервисом)
curl -fsS http://localhost:8080/health/ready
# 4. Проверки
make check
make test BASE_URL=http://localhost:8080
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
# 5. Восстановление остановленной в failover реплики (api1 или api2)
docker compose --env-file .env start api1
docker compose --env-file .env restart lb
# 6. Штатная остановка без удаления данных
docker compose --env-file .env down
# 7. Намеренное удаление учебных данных и volumes (необратимо)
docker compose --env-file .env down -v
На Windows-хосте make не установлен, поэтому вместо целей Makefile выполнены те же команды напрямую: python scripts/check_contract.py, python tests/smoke.py --base-url http://localhost:8080, python tests/resilience.py --mode persistence|failover --action-script .... Скрипты restart.sh/stop-one.sh — POSIX shell, поэтому resilience-тесты запускались в Linux-контейнере docker:27-cli с смонтированным репозиторием и Docker-сокетом:
docker run --rm --network mtusi-lab3_appnet \
-v "<repo>:/repo" -v /var/run/docker.sock:/var/run/docker.sock \
-w /repo -e PYTHONUTF8=1 docker:27-cli \
sh -lc "apk add --no-cache python3 >/dev/null && \
python3 tests/resilience.py --mode failover \
--action-script scripts/stop-one.sh --base-url http://lb:8080"
На Linux/macOS те же проверки запускаются обычными командами Makefile из блока выше.
Архитектура и решения
клиент
|
v
lb (nginx :8080) — единственный опубликованный порт
| round-robin, passive health, retry на вторую реплику
+--> api1 (uvicorn :8080, INSTANCE_ID=api-1) --+
+--> api2 (uvicorn :8080, INSTANCE_ID=api-2) --+
v
postgres:16.4 (volume pgdata)
users, chats, chat_members, messages,
sessions, idempotency_keys
- Источник истины — PostgreSQL. В API нет локальных сессий, сообщений или идемпотентных ключей. Единственное локальное состояние процесса — стабильный
X-Instance-Id(api-1/api-2) из переменной окружения. - Реплики взаимозаменяемы.
api1иapi2собираются из одного Dockerfile и образа, не публикуют порты наружу, имеют одинаковыйDATABASE_URL. Клиент ходит только черезlb. - Балансировщик. Nginx upstream
api1:8080,api2:8080,max_fails=1 fail_timeout=5s,proxy_connect_timeout 1s,proxy_read_timeout 10s.proxy_next_upstream ... non_idempotentповторяет POST на второй реплике; это безопасно, потому что создание сообщения идемпотентно поIdempotency-Key. - Миграции отдельно. Сервис
migrateзапускается один раз, ждёт готовности PostgreSQL, берёт advisory lock, применяет идемпотентныйmigrations/001_init.sqlи завершается с кодом 0. Реплики стартуют только послеservice_completed_successfully, поэтому гонки DDL между ними нет. - Graceful shutdown. Uvicorn — PID 1, получает SIGTERM, перестаёт принимать соединения и до 5 с завершает текущие запросы (
--timeout-graceful-shutdown 5),stop_grace_period: 10s. Nginx в это время повторяет запрос на живую реплику. - Сессии. Basic используется только в
POST /api/v1/auth/sessions. Токен —secrets.token_urlsafe(48)(384 бита), в БД хранится только SHA-256 токена иexpires_at; TTL изSESSION_TTL_SECONDS(по умолчанию 3600). Перезапуск не продлевает TTL. - Пароли.
hashlib.scrypt(N=2^14, r=8, p=1, 32-байтовый digest, случайная соль), не SHA-256 и не plaintext. - Транзакционные границы. Регистрация — один INSERT с уникальным
username. Создание чата — чат и всеchat_membersв одной транзакции после проверки существования участников. Отправка сообщения — проверка членства, вставка/чтениеidempotency_keys, вставкаmessagesи запись сохранённого ответа в одной транзакции. - Идемпотентность. Первичный ключ
(user_id, method, path, key);INSERT ... ON CONFLICT DO NOTHINGопределяет владельца, конкурентный запрос ждёт завершения транзакции владельца и читает сохранённый ответ. Хранится канонический хеш тела: другой JSON при том же ключе —409, тот же JSON — исходный201и то же сообщение. Срок хранения —IDEMPOTENCY_TTL_SECONDS(24 ч). - История. Keyset-пагинация по
(created_at, id)по возрастанию,limit1–100 (по умолчанию 50), непрозрачный base64-cursor со scope. Cursor от другого чата/коллекции —400; последний элемент страницы не повторяется;next_cursor=null, если следующей записи нет. - Ошибки. Единый конверт
{"error":{"code","message","request_id"}},X-Request-Idсовпадает с телом,X-Instance-Idдобавляется middleware ко всем ответам API, включая ошибки и health. - Перенос из lab2. В этом репозитории нет кода lab2, поэтому обязательные возможности lab2 (PostgreSQL, регистрация с паролем, Basic → Bearer-сессия, миграции, сохранность) реализованы здесь же. In-memory fallback отсутствует.
Соответствие .env.example реальной конфигурации:
| Переменная | Где используется | Смысл |
|---|---|---|
APP_HOST, APP_PORT, APP_ENV |
compose | информационные параметры стенда |
SESSION_TTL_SECONDS |
API | TTL сессии, по умолчанию 3600 |
IDEMPOTENCY_TTL_SECONDS |
API | срок хранения результата, по умолчанию 86400 |
POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD |
compose → DATABASE_URL |
общая БД; пароль в примере синтетический |
DATABASE_URL / DATABASE_URL_FILE |
API, migrate | альтернативные способы передать строку подключения |
API_REPLICAS |
документация | фактическое число реплик задано сервисами api1/api2 |
Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|---|---|---|---|
| Офлайн-структура и контракт | python scripts/check_contract.py (эквивалент make check) |
PASS: offline skeleton structure... |
evidence/check.txt |
| Compose-стенд описан и валиден | docker compose --env-file .env config --quiet |
код 0, ошибок нет | вывод в отчёте, compose.yaml |
| Публичный smoke | python tests/smoke.py --base-url http://localhost:8080 (эквивалент make test) |
PASS: lab3 public API scenario |
evidence/smoke-final.txt, evidence/smoke.txt |
| ≥2 API-реплики, одна точка входа, общая БД | docker compose ps; 10 запросов /health/live |
api1/api2 healthy; опубликован только lb 8080; postgres healthy |
evidence/instances.txt, evidence/final-ps.txt |
| Одна сессия обслуживается разными репликами без повторного входа | python student-tests/session_across_replicas.py |
12 запросов с одним Bearer: api-1, api-2, api-1, api-2, ... |
evidence/session-across-replicas.txt |
| Остановка одной реплики: чтение/запись продолжаются | failover-тест, цель api-1 |
85 успешных записей, 0 ошибок, первое восстановление 0.558 с (в повторных прогонах 0.65–1.43 с); api1 — Exited (0), api2 работает |
evidence/failover-final.txt, evidence/failover-final-ps.txt |
| Остановка второй реплики | failover-тест, цель api-2 |
90 успешных записей, 0 ошибок, восстановление 0.546 с; api2 — Exited (0), api1 работает |
evidence/failover-final-2.txt, evidence/failover-final-2-ps.txt |
| Подтверждённые сообщения доступны после отказа, дублей нет | тот же failover-тест | тест читает всю историю, проверяет исходное сообщение, все подтверждённые записи и уникальность текстов | evidence/failover-final.txt |
Последовательный повтор Idempotency-Key |
публичный smoke | повтор возвращает то же сообщение; другой body — 409; без ключа — 400 |
evidence/smoke-final.txt |
| Конкурентный повтор через разные реплики | python student-tests/concurrent_idempotency.py |
40 одновременных POST с одним ключом: реплики api-1 и api-2, ровно 1 сообщение, другой body — 409 |
evidence/concurrent-idempotency.txt |
| Сохранность данных и сессии после перезапуска | persistence-тест + scripts/restart.sh |
PASS; прежний токен и данные доступны без повторного входа; в БД после всех прогонов 40 пользователей, 13 чатов, 4171 сообщение, 37 сессий |
evidence/persistence-final.txt, evidence/db-counts.txt |
| Hook действительно перезапустил хранилища | docker inspect до/после scripts/restart.sh |
у postgres, api1, api2, lb изменился State.StartedAt |
evidence/restart-scope.txt |
| Health/readiness | curl /health/ready |
{"status":"ok"}; readiness проверяет SELECT 1 к PostgreSQL |
evidence/instances.txt |
| Миграции не гоняются репликами | docker compose ps -a |
migrate завершился Exited (0) до старта API |
evidence/failover-final-ps.txt |
| Версии образов/зависимостей зафиксированы | Dockerfile, compose.yaml, requirements.txt |
явные теги/пины, без latest |
файлы репозитория |
| Нагрузочный профиль (дополнительно) | python tests/load.py --duration 15 --concurrency 4 |
3722 успешных запроса, 0 ошибок, 247.6 RPS, p50/p95/p99 = 16/32/46 мс | evidence/load.txt, evidence/load.json |
Эксперименты и отказы
Условия: один Docker-host, сервисные лимиты api 1 CPU / 256 MB, postgres 1 CPU / 512 MB, lb 0.5 CPU / 128 MB. Все запросы идут через http://localhost:8080 (nginx). Данные синтетические.
| Воздействие | Что ожидали | Что наблюдали | Время восстановления / потеря данных |
|---|---|---|---|
stop api1 во время 15-секундной серии POST |
Записи продолжаются через api2, подтверждённые сообщения не теряются |
85 успешных записей, 0 неудачных попыток; api1 остановлен (Exited (0)), api2 healthy |
первое восстановление 0.558 с; потерь и дублей нет |
stop api2 во время такой же серии |
То же через api1 |
90 успешных записей, 0 неудачных; api2 остановлен, api1 healthy |
0.546 с; потерь и дублей нет |
40 одновременных POST с одним Idempotency-Key |
Ровно одно сообщение, одинаковые ответы | Оба экземпляра обслужили запросы, все ответы совпали, в истории 1 копия; другой body — 409 |
потерь нет |
scripts/restart.sh: рестарт PostgreSQL, api1, api2, lb |
Данные, сессии и схема сохраняются | Persistence-тест PASS; у всех четырёх контейнеров новый StartedAt |
сессия и сообщения доступны без повторного входа |
Пересборка образа и up -d --build |
Сессии/сообщения не зависят от жизни процесса | Smoke после пересборки PASS; в PostgreSQL сохранились 40 пользователей, 13 чатов, 4171 сообщение и 37 сессий |
потерь нет |
Нагрузочный прогон: 15 с, concurrency 4, closed-loop генератор tests/load.py без автоматических retry. Получено 3722 успешных POST, 0 ошибок, 247.6 успешных RPS, p50 16 мс, p95 32 мс, p99 46 мс. Это throughput HTTP-подтверждений через LB, а не точный счётчик COMMIT; генератор ограничен клиентом, страдает coordinated omission, а latency посчитана только по успешным запросам. CPU/RAM контейнеров в этом прогоне не сэмплировались, поэтому цифры не заявляются как saturation point.
Ограничения и следующие шаги
- Стенд работает на одном Docker-host. Потеря узла, а также отказ единственных PostgreSQL и nginx не выдерживаются: они остаются SPOF. Проверен только отказ одного API-процесса.
- Nginx разрешает имена
api1/api2при старте. После восстановления остановленной реплики надёжный способ вернуть её в балансировку —docker compose start apiNиdocker compose restart lb; в проверенных прогонах Docker переиспользовал IP, но на это не следует опираться. Следующий шаг — динамический resolver/resolveв upstream. - После восстановления реплика возвращается в балансировку не мгновенно: если первый запрос к ней попал в момент старта, nginx держит её вне пула до
fail_timeout=5s. Это наблюдалось один раз сразу послеrestart lb; в рабочий период оба экземпляра получают запросы. Поэтомуstudent-tests/session_across_replicas.pyсначала ждёт появления обоих экземпляров, а затем проверяет одну сессию. - Сессии и идемпотентные ключи хранятся в PostgreSQL; Redis/Valkey не используется. Это соответствует контракту lab3, но увеличивает нагрузку на БД.
- Просроченные идемпотентные ключи удаляются лениво — при повторном использовании ключа; фоновой очистки нет.
- Не реализованы TLS, rate limiting, вложения, фоновая обработка, телеметрия — это следующие лабораторные, для оценки 3 они не требуются.
- Уровень 4 (поочерёдная остановка всех реплик с метриками RPS/ошибок, rolling update под нагрузкой, CPU/RAM-лимиты как проверяемый критерий) и трек 5 не заявляются. Лимиты ресурсов в compose заданы, но измерение saturation и сравнение 1/2/4 реплик не проводилось.
- На Windows-хосте отсутствует
make, поэтому публичные цели запускались эквивалентными командами; на Linux/macOS команды Makefile применимы без изменений.