10 KiB
Отчёт — лабораторная 3
- Автор, группа: TODO
- Целевая оценка: 4 (трек 5 не заявлен)
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: FastAPI, SQLAlchemy 2, Alembic, argon2-cffi, Nginx, PostgreSQL 16; документация Docker Compose и Nginx; помощь ИИ при генерации кода и текста отчёта.
Запуск из чистого clone
Prerequisites: Docker Engine 24+, Docker Compose v2.20+, curl, make, Python 3.9+ (для публичных тестов).
Версии образов закреплены: postgres:16.4-alpine, nginx:1.27.3-alpine, python:3.12-slim (базовый образ приложения).
cp .env.example .env
# отредактируйте .env: задайте POSTGRES_PASSWORD (не коммитить!)
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
# дождитесь готовности через LB:
until curl -fsS http://localhost:8080/health/ready >/dev/null; do sleep 1; done
make test BASE_URL=http://localhost:8080
Миграции выполняются one-shot сервисом migrate (Alembic upgrade head) до старта API; API ждёт service_completed_successfully. Повторный up безопасен: Alembic идемпотентен.
Безопасная остановка (сохраняет данные):
docker compose --env-file .env stop
Намеренное удаление учебных данных (необратимо):
docker compose --env-file .env down -v
Архитектура и решения
Клиент → Nginx (lb:8080) → api-1 / api-2 (FastAPI, uvicorn) → PostgreSQL 16
- Источник истины: PostgreSQL. Пользователи, сессии, чаты, участники, сообщения и ключи идемпотентности хранятся в одной БД. Локального состояния в API нет — реплики взаимозаменяемы.
- Сессии: таблица
sessions(SHA-256 от токена,expires_at). TTL задаётсяSESSION_TTL_SECONDS(по умолчанию 3600). Переживают рестарт API и БД. - Идемпотентность: таблица
idempotency_keysс PK(user_id, method, path, key)иbody_hash. Создание сообщения и запись ключа — в одной транзакции. Конкурентный повтор через разные реплики разрешается уникальным PK: проигравший получаетIntegrityError, откатывается и читает уже сохранённый результат. Другой body при том же ключе → 409. - X-Instance-Id: задаётся через env
INSTANCE_ID(api-1/api-2), стабилен в пределах жизни процесса. - X-Request-Id: генерируется middleware, если клиент не передал; возвращается во всех ответах, включая ошибки.
- LB: Nginx
upstreamс двумя явными backend-серверами,max_fails=2 fail_timeout=5s,proxy_next_upstream error timeout http_502 http_503 http_504,proxy_connect_timeout 2s. Обнаружение отказа ≤ 10 с. - Graceful shutdown: uvicorn по SIGTERM перестаёт принимать новые соединения и завершает текущие;
stop_grace_period: 15s. Nginx перенаправляет запросы на живую реплику. - Миграции: one-shot сервис
migrate(Alembic), запускается до API. Совместимы с работающей версией (только additive). - Лимиты: API — 0.5 CPU / 256 MiB, PostgreSQL — 1 CPU / 512 MiB, Nginx — 0.5 CPU / 128 MiB.
- Порты: наружу публикуется только
lb:8080. Порты API не публикуются.
Соответствие .env.example:
| Переменная | Где используется |
|---|---|
POSTGRES_PASSWORD |
compose.yaml (postgres, migrate, api-*) |
SESSION_TTL_SECONDS |
app/config.py |
IDEMPOTENCY_TTL_SECONDS |
app/config.py (зарезервировано для очистки) |
APP_HOST, APP_PORT |
app/config.py |
DATABASE_URL_FILE |
не используется в текущей реализации (см. ограничения) |
Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|---|---|---|---|
| Публичный smoke | make test |
PASS: lab3 public API scenario |
evidence/smoke.txt |
| ≥2 API-реплики, одна точка входа | for i in 1 2 3 4; do curl -sI http://localhost:8080/health/live | grep X-Instance-Id; done |
чередуются api-1 и api-2 |
evidence/instances.txt |
| Разные запросы одного пользователя на разных репликах | make test + X-Instance-Id в ответах |
smoke проходит, X-Instance-Id меняется |
evidence/smoke.txt |
| Остановка одной реплики, продолжение работы | make test-failover ACTION_SCRIPT=scripts/stop-one.sh |
PASS: failover preserved confirmed data |
evidence/failover.txt |
| Идемпотентность (в т.ч. конкурентная) | make test (LAB≥3) + параллельный повтор |
повтор возвращает тот же Message, дублей нет | evidence/smoke.txt |
| Persistence (рестарт с сохранением volumes) | make test-persistence ACTION_SCRIPT=scripts/restart.sh |
PASS: persistence preserved confirmed data |
evidence/persistence.txt |
| Health/readiness, SIGTERM, LB исключает backend | docker compose stop api-1 + curl /health/ready |
200 через api-2, api-1 исключён из upstream | evidence/health.txt |
| Последовательная остановка каждой реплики под нагрузкой | make load + scripts/stop-one.sh для api-1, затем api-2 |
RPS/ошибки/время восстановления | evidence/load-*.json |
| CPU/RAM-лимиты, API не публикует порты | docker compose config |
deploy.resources.limits заданы, у api-* нет ports: |
evidence/compose-config.txt |
| Rolling update под нагрузкой | docker compose up -d --no-deps api-1 при работающем make load |
ошибок нет, RPS не падает до нуля | evidence/rolling.txt |
| Миграции однократно | docker compose logs migrate |
один прогон upgrade head, повторный up не падает |
evidence/migrate.txt |
Эксперименты и отказы
Гипотеза: при остановке одной API-реплики Nginx исключает её из upstream за ≤ 10 с, а вторая реплика продолжает обслуживать чтение и запись без потери подтверждённых сообщений и без дублей при повторе с тем же Idempotency-Key.
Стенд: локальный Docker Desktop, 4 CPU / 8 GiB. Лимиты: API 0.5 CPU / 256 MiB × 2, PostgreSQL 1 CPU / 512 MiB, Nginx 0.5 CPU / 128 MiB. Версии: postgres:16.4-alpine, nginx:1.27.3-alpine, python:3.12-slim.
Профиль нагрузки: make load — closed-loop, 4 потока, 30 с, POST сообщений. Ограничения: клиент на Python, coordinated omission, latency только по успешным запросам.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|---|---|---|---|
scripts/stop-one.sh для api-1 |
Nginx исключает api-1, api-2 продолжает | ошибки в первые ~5 с, затем 200; X-Instance-Id = api-2 |
≤ 10 с; потерь нет |
scripts/stop-one.sh для api-2 (после восстановления api-1) |
симметрично | симметрично | ≤ 10 с; потерь нет |
scripts/restart.sh (postgres + api-*) |
данные и сессии сохранены | smoke с прежним токеном проходит | ~15 с; потерь нет |
Rolling update api-1 под нагрузкой |
без 5xx | кратковременный рост latency, 5xx нет | ~5 с |
Ограничения и следующие шаги
- Выдерживается: отказ одной API-реплики (процесса/контейнера), рестарт API и PostgreSQL с сохранением volumes.
- Не выдерживается: отказ узла (single-host Compose), отказ PostgreSQL (SPOF), отказ Nginx (SPOF). Для трека 2 потребовался бы Swarm/несколько узлов и репликация БД.
- Упрощения:
DATABASE_URL_FILEиз.env.exampleне используется — пароль передаётся черезPOSTGRES_PASSWORDв env (для локального синтетического стенда допустимо; для production нужен Docker secret). Очисткаidempotency_keysпо TTL не реализована (запись остаётся, но контракт требует хранения ≥ 24 ч — выполнено). Вложения (lab4+) не реализованы — целевая оценка 4 в рамках lab3. - Подтверждено: failover одной реплики, persistence, идемпотентность (включая конкурентный повтор), rolling update без 5xx.
- Гипотеза (не проверено): поведение при отказе PostgreSQL и при горизонтальном масштабировании на 4+ реплик.