20 KiB
Отчёт — лабораторная 3
- Автор, группа: Васюкова Наталья, БВТ2303
- Целевая оценка: 4
- Commit/PR: solution/BVT2303-Vasyukova
- Использованные источники, библиотеки и помощь ИИ:
- Контракт: contracts/openapi.json, contracts/README.md
- Инструкции: README.md, COURSE.md, CONTRIBUTING.md
- Библиотеки: fastapi==0.115.0, uvicorn[standard]==0.32.0, psycopg[binary]==3.2.3, psycopg_pool==3.2.3, redis==5.2.0, pydantic (из fastapi)
- ИИ: DeepSeek — помощь в структурировании кода и отчёта. Весь код проверен, отредактирован и запущен разработчиком.
Запуск из чистого clone
Версии runtime/образов:
- Python: 3.12 (образ
python:3.12-slim) - FastAPI 0.115.0, uvicorn[standard] 0.32.0, psycopg[binary] 3.2.3, psycopg_pool 3.2.3, redis 5.2.0
- PostgreSQL 18.6-alpine, Redis 7.4.1-alpine, nginx 1.27.3-alpine (в Compose)
- Docker Desktop (Windows)
Запуск стека
- Клонировать репозиторий и переключиться на ветку решения:
git clone https://gitflic.ru/project/vasyukova-nat/mtusi2026lab3.git git checkout solution/BVT2303-Vasyukova - Создать
.envиз шаблона:copy .env.example .env - Собрать и поднять (LB + 2 реплики API + PostgreSQL + Redis):
docker compose --env-file .env up -d --build - Проверить готовность:
Ожидается:
curl.exe -s http://localhost:8080/health/ready{"status":"ok"}.
Все проверки ниже выполнялись с PYTHONUTF8=1 (Windows по умолчанию использует cp1251 и падает на чтении UTF-8 JSON):
$env:PYTHONUTF8="1"
Проверки
make в среде автора недоступен (Windows без GNU Make), поэтому использованы эквивалентные прямые вызовы скриптов. Для Linux/CI рядом указаны команды make.
| Makefile-команда | Прямой вызов |
|---|---|
make check |
python scripts/check_contract.py |
make validate |
python scripts/validate_openapi.py |
make test |
python tests/smoke.py --base-url http://localhost:8080 |
make test-student |
python student-tests/lab3_test_level4.py --base-url http://localhost:8080 |
make test-persistence ACTION_SCRIPT=scripts/restart.sh |
python tests/resilience.py --mode persistence --action-script scripts/restart.bat --base-url http://localhost:8080 |
make test-failover ACTION_SCRIPT=scripts/stop-one.sh |
python tests/resilience.py --mode failover --action-script scripts/stop-one.bat --base-url http://localhost:8080 |
Остановка и удаление учебных данных
docker compose stop # данные PostgreSQL и Redis сохраняются (volumes)
docker compose down # volumes сохраняются
docker compose down -v # ТОЛЬКО если осознанно стираем данные БД и Redis
Архитектура и решения
Схема процессов и хранилищ:
┌─ api-1 (uvicorn:8080, INSTANCE_ID=…)
HTTP-клиент → lb:80 ──┤ ↘
(nginx) └─ api-2 (uvicorn:8080, INSTANCE_ID=…) PostgreSQL 18.6 (postgres:5432)
Redis 7.4.1 (redis:6379)
Все сервисы — в одной compose-сети mtuci2026lab3_default. Публично опубликован только порт LB 127.0.0.1:8080:80. Реплики api не имеют ports — трафик к ним идёт исключительно через LB. PostgreSQL и Redis доступны только по внутренним именам postgres и redis.
Источники истины:
- PostgreSQL — данные (пользователи, чаты, членство, сообщения) и ключи идемпотентности.
- Redis — серверные сессии (общие для всех реплик).
Схема БД (подробнее — src/app/storage/db.py, константа SCHEMA_SQL):
users(id UUID PK, username TEXT UNIQUE, display_name TEXT, password_hash TEXT, created_at TIMESTAMPTZ)
chats(id UUID PK, title TEXT, created_at TIMESTAMPTZ)
chat_members(chat_id FK→chats, user_id FK→users, PK(chat_id,user_id))
messages(id UUID PK, chat_id FK→chats, sender_id FK→users, text TEXT, created_at TIMESTAMPTZ)
+ INDEX idx_messages_chat_created(chat_id, created_at, id)
sessions(token TEXT PK, user_id FK→users, expires_at TIMESTAMPTZ) -- fallback SESSION_STORE=postgres
idempotency_keys(user_id FK→users, method TEXT, path TEXT, key TEXT,
body_hash TEXT, response_status INT, response_body JSONB, created_at TIMESTAMPTZ,
PRIMARY KEY (user_id, method, path, key))
+ INDEX idx_idempotency_created(created_at)
Применяется идемпотентно через init_schema() на старте. Все временные метки — TIMESTAMPTZ.
Транзакционные границы:
create_user— SELECT-проверка username и INSERT в одной транзакции; при гонкеUniqueViolation→ 409.create_chat— INSERTchats+ INSERTchat_membersв одной транзакции, откат целиком.add_message— один INSERT, отдельная транзакция.- Создание/отзыв сессии — одна операция.
Дерево проекта (изменения относительно lab2 отмечены *)
mtuci2026lab3/
├── compose.yaml * # + lb, api без container_name/ports, deploy.replicas
├── Dockerfile * # убран ARG INSTANCE_ID, добавлен docker-entrypoint.sh
├── docker-entrypoint.sh * # генерирует INSTANCE_ID, пишет /tmp/instance_id
├── infra/nginx.conf * # vhost LB
├── Makefile
├── src/app/
│ ├── main.py * # X-Instance-Id в middleware
│ ├── api/
│ │ └── messages.py * # обязательный Idempotency-Key, атомарный reserve/complete
│ └── storage/
│ ├── db.py * # + таблица idempotency_keys
│ └── postgres.py * # + reserve_idempotency / complete_idempotency
├── scripts/
│ ├── restart.sh / .bat * # + lb, обе реплики api
│ └── stop-one.sh / .bat * # останавливает ту реплику, чей INSTANCE_ID == TARGET_INSTANCE_ID
└── student-tests/
└── lab3_test_level4.py * # два X-Instance-Id, идемпотентность через реплики, отказ реплики
Что нового в lab3 относительно lab2
Горизонтальное масштабирование. Сервис api больше не имеет container_name и ports; в deploy.replicas стоит 2. Compose запускает mtuci2026lab3-api-1 и mtuci2026lab3-api-2. Публичной точкой входа служит lb.
Балансировщик. nginx:1.27.3-alpine, конфиг infra/nginx.conf монтируется в /etc/nginx/conf.d/default.conf. Upstream api_backend резолвит Docker-DNS api:8080 во все реплики сервиса. max_fails=1 fail_timeout=5s — после первой ошибки реплика исключается из ротации на 5 секунд. proxy_next_upstream error timeout http_502 http_503 http_504 переводит неудавшийся запрос на следующую реплику. Keepalive к upstream намеренно отключён: с ним одна клиентская сессия уходит на одну реплику, и проверить балансировку на малом числе запросов нельзя.
X-Instance-Id. Каждая реплика при старте генерирует случайный alias в docker-entrypoint.sh и экспортирует как INSTANCE_ID; middleware в src/app/main.py добавляет его в каждый ответ, включая ошибки. Значение не содержит hostname/IP.
Идемпотентность (общая для реплик). POST /api/v1/chats/{chat_id}/messages требует Idempotency-Key (ASCII [A-Za-z0-9._:-]{1,128}). Scope: user_id + method + path + key. body_hash — sha256 канонизированного JSON (сортировка ключей, отсутствующий attachment_ids приравнен к []). Реализовано атомарно:
reserve_idempotencyделаетINSERT … ON CONFLICT DO NOTHING RETURNING keyвidempotency_keys. Ровно один параллельный запрос (в т.ч. через разные реплики) получает строку обратно — он и создаёт сообщение. Остальные видятreplay.- Победитель создаёт сообщение и вызывает
complete_idempotency—UPDATEсо реальнымresponse_status/response_body. replayс тем жеbody_hashвозвращает сохранённый 201 и то же Message. С другимbody_hash— 409. Если победитель ещё не записал ответ (response_status = 0), повторы коротко ждут.
Graceful shutdown. SIGTERM: main._handle_sigterm выставляет server.should_exit=True; uvicorn закрывает слушающий сокет, текущие запросы дожидаются завершения.
Ресурсные лимиты. В compose.yaml у api — deploy.resources.limits.cpus: "1.0", memory: 512M.
Соответствие .env.example реальной конфигурации (без изменений с lab2):
APP_HOST,APP_PORT— используются uvicorn/CMD в Dockerfile.APP_ENV— пишется в стартовый логevent=startup app_env=..., в остальном на логику не влияет.SESSION_TTL_SECONDS— TTL серверных сессий в Redis (или в таблицеsessionsприSESSION_STORE=postgres), по умолчанию 3600. Для теста expiry временно ставится 5 и возвращается обратно.DATABASE_URL— строка подключения к PostgreSQL. В Docker используетсяpostgresql://user:password@postgres:5432/high_load_messenger.REDIS_URL— адрес Redis в compose-сети (redis://redis:6379/0), не секрет.SESSION_STORE—redis(уровень 4) илиpostgres(fallback).CACHE_URL_FILE— резервная переменная из скелета, не используется.
Доказательства критериев
Уровень 3
| Критерий | Команда | Наблюдаемый результат |
|---|---|---|
| Стенд описан в compose.yaml, запускается командой | docker compose --env-file .env up -d --build |
mtuci-lb Up, mtuci2026lab3-api-1/-2 Up (healthy), mtuci-postgres Up (healthy), mtuci-redis Up (healthy) |
| ≥2 API-реплики, одна публичная точка входа, общая БД, общее хранилище сессий | docker compose --env-file .env ps |
2 контейнера api, порт 8080 публикует только lb |
| Разные запросы одного пользователя обслуживают разные реплики без повторного входа | python student-tests/lab3_test_level4.py → test_two_instances |
observed instances: ['00c1651b90c9', 'f8f94301bb06'], PASS |
| Остановка одной реплики: не позднее 10 с продолжаются новые чтения/записи, подтверждённые сообщения доступны | python tests/resilience.py --mode failover --action-script scripts/stop-one.bat … |
first_recovery_seconds: 5.189, PASS |
Повтор POST с тем же Idempotency-Key не создаёт дубль |
python student-tests/lab3_test_level4.py → test_idempotency_across_replicas |
10 параллельных POST с одним ключом → ровно 1 сообщение; PASS |
make test, persistence, failover проходят |
все команды ниже | PASS |
Уровень 4
| Критерий | Команда | Наблюдаемый результат |
|---|---|---|
| Health/readiness, timeouts, graceful shutdown; LB исключает недоступный backend | см. infra/nginx.conf (max_fails=1 fail_timeout=5s, proxy_next_upstream), main.py (_handle_sigterm) |
При docker stop реплики LB перестаёт её использовать; SIGTERM логируется, процесс завершается корректно |
| Последовательная остановка каждой реплики; RPS/ошибки/время восстановления | python tests/resilience.py --mode failover … для разных реплик (пользователь запускает дважды, восстанавливая предыдущую) |
successful_writes: 7, failed_attempts: 0, first_recovery_seconds: 5.189 |
| Общая идемпотентность проверена параллельными запросами | test_idempotency_across_replicas |
201 instances: {два разных alias}, ровно 1 сообщение в истории |
| CPU/RAM-лимиты, API не публикуют порты наружу, нет container_name у масштабируемого сервиса | compose.yaml |
deploy.resources.limits у api; api без ports; без container_name |
| Rolling update или эквивалентная поочерёдная замена под нагрузкой | docker compose --env-file .env up -d --force-recreate api (при поднятом LB) |
LB продолжает обслуживать на живой реплике; новых пользователей не требуется |
Выводы тестов
(venv) PS ...> python scripts/check_contract.py
PASS: offline skeleton structure, local refs and Python syntax; application NOT tested.
(venv) PS ...> python scripts/validate_openapi.py
PASS: full OpenAPI 3.1 and JSON Schema validation; application NOT tested.
(venv) PS ...> python tests/smoke.py --base-url http://localhost:8080
PASS: lab3 public API scenario; infrastructure and grading evidence remain separate.
(venv) PS ...> python student-tests/lab3_test_level4.py --base-url http://localhost:8080
=== test_two_instances ===
observed instances: ['00c1651b90c9', 'f8f94301bb06']
PASS: >=2 X-Instance-Id через LB
=== test_idempotency_across_replicas ===
201 instances: {'00c1651b90c9', 'f8f94301bb06'} 409 instances: set()
PASS: idempotency OK, ровно одно сообщение создано
PASS: идемпотентность на общих ключах
=== test_stop_one_replica ===
останавливаем replica container: c416ffa7ec4b
after-fail instances: {'f8f94301bb06'}
PASS: стенд пережил отказ одной реплики
PASS: отказ одной API-реплики обработан
PASS: all lab3 level-4 checks passed
(venv) PS ...> python tests/resilience.py --mode persistence --action-script scripts/restart.bat --base-url http://localhost:8080
Executing explicit persistence hook; hook output suppressed to avoid leaking secrets.
PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence.
(venv) PS ...> python tests/resilience.py --mode failover --action-script scripts/stop-one.bat --base-url http://localhost:8080
Executing explicit failover hook; hook output suppressed to avoid leaking secrets.
{"observed_instances_before": 2, "successful_writes": 7, "failed_attempts": 0, "first_recovery_seconds": 5.189}
PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence.
Эксперименты и отказы
Стенд: Windows 11, Docker Desktop (WSL2). Лимиты api — 1 CPU / 512 MiB на реплику. Данные синтетические, объём небольшой — этого достаточно для проверки балансировки и отказов.
| Воздействие | Что ожидаем | Что наблюдали |
|---|---|---|
docker compose --env-file .env restart lb api postgres redis (persistence hook) |
Все реплики и хранилища перезапускаются, volumes сохраняются, сессия и сообщения живы | PASS: токен прежний, подтверждённое сообщение найдено |
docker stop одной реплики API (failover hook) |
LB переключает трафик на живую реплику, новые POST/GET идут без потерь, подтверждённое сообщение доступно | first_recovery_seconds: 5.189, successful_writes: 7, failed_attempts: 0, PASS |
Параллельный POST с одним Idempotency-Key через LB (10 потоков) |
Ровно один INSERT в messages; все остальные — replay/409 |
ровно 1 сообщение в истории, PASS |
| SIGTERM одной реплике | Graceful shutdown uvicorn, без падения процессов | В логах event=shutdown_complete, контейнер завершается за секунды |
Дополнительно docker compose ps подтверждает, что во время failover-теста публичный порт 8080 обслуживает только LB; после docker stop одного контейнера api второй продолжает отвечать, что видно по его уникальному X-Instance-Id в ответах (в выводе: after-fail instances: {'f8f94301bb06'}).
Ограничения и следующие шаги
- Один Docker-host. Отказ узла не проверялся; LB, PostgreSQL и Redis — единичные экземпляры (SPOF). HA БД/LB не заявляется.
- Обнаружение отказа — реактивное. LB узнаёт о мёртвой реплике по первой ошибке (
max_fails=1 fail_timeout=5s), поэтому возможна короткая задержка ~5 с до исключения из ротации. Это допустимо по методичке (восстановление ≤10 с). - Идемпотентность только на POST сообщения.
POST /usersиPOST /chatsбезIdempotency-Key— повтор создаёт новый объект/409, что соответствует контракту. - Часы. Порядок
(created_at, id)требует монотонностиcreated_atв пределах сервера; для учебного стенда с одной БД это выполняется. - Миграции.
init_schema()идемпотентен, но запускается на старте каждой реплики. Гонки нет благодаряCREATE TABLE IF NOT EXISTS/CREATE INDEX IF NOT EXISTS. Отдельный миграционный job не выделен — это упрощение учебного уровня. - Нагрузка. Полноценных замеров RPS/p50/p95/p99 при фиксированных ресурсах не проводилось — для целевой оценки 4 это не требуется. Трек 5 (цена масштабирования) не заявлен.