14 KiB
Отчёт — лабораторная 3
- Автор, группа: Кропивка Виктория, БВТ2303
- Целевая оценка: 4 (уровень 3 + уровень 4)
- Commit/PR: ветка
solution/БВТ-23-Кропивка - Использованные источники, библиотеки и помощь ИИ: FastAPI 0.115.0, Uvicorn 0.30.6, Pydantic 2.9.2, psycopg 3.2.3, psycopg-pool 3.2.3, Alembic 1.13.3, argon2-cffi 23.1.0, redis 5.1.1, PostgreSQL 16.4-alpine, Valkey 8.0.1-alpine, HAProxy 3.0-alpine, python:3.12-slim. При подготовке решения использовался ассистент (LLM) для генерации черновика кода и объяснения контракта; итоговый код проверен публичным smoke, тестами failover/persistence/parallel idempotency и вручную.
Запуск из чистого clone
Prerequisites:
- Docker 29.2.1 (Docker Desktop для Windows + WSL2)
- Python 3.9+ (только для тестов)
- Git
Шаги:
-
Клонировать репозиторий, создать
.envиз примера:cp .env.example .envЗаполнить значениями:
APP_HOST=0.0.0.0 APP_PORT=8080 APP_ENV=lab SESSION_TTL_SECONDS=3600 POSTGRES_USER=messenger POSTGRES_PASSWORD=changeme_local_only POSTGRES_DB=messenger DATABASE_URL=postgresql://messenger:changeme_local_only@postgres:5432/messenger CACHE_URL=redis://cache:6379/0 API_REPLICAS=2 IDEMPOTENCY_TTL_SECONDS=86400 -
Запустить стенд:
docker compose --env-file .env up -d --buildCompose:
postgres— 16.4-alpine, named volume, только внутренняя сеть.cache— Valkey 8.0.1-alpine, named volume, только внутренняя сеть.migrate— запускаетalembic upgrade headоднократно, завершается.api— 2 реплики (deploy.replicas: 2), без публикации портов.lb— HAProxy 3.0-alpine, публикует127.0.0.1:8080.
-
Дождаться готовности:
docker compose psОжидаемо: postgres, cache, api-1, api-2 — healthy, lb — up, migrate — Exited (0).
-
Прогнать тесты:
make test BASE_URL=http://localhost:8080 make test-persistence ACTION_SCRIPT=scripts/restart.sh BASE_URL=http://localhost:8080 make test-failover ACTION_SCRIPT=scripts/stop-one.sh BASE_URL=http://localhost:8080 -
Остановить:
docker compose --env-file .env downДанные сохраняются в named volumes
mtusi_lab3_postgres_data,mtusi_lab3_cache_data.Намеренное удаление:
docker compose --env-file .env down -v
Архитектура и решения
- Топология. Клиент → HAProxy (LB, порт 8080) → 2 API-реплики (внутренняя сеть, порт 8080) → общие Postgres и Valkey.
- Балансировка. HAProxy
roundrobin, healthcheckGET /health/readyкаждые 2 секунды,fall 2 rise 2. Отказ реплики обнаруживается за ~4 секунды. - Динамическое обнаружение реплик. HAProxy резолвит
apiчерез Docker DNS127.0.0.11,server-template api 1-10. Если реплика добавилась или упала — HAProxy видит изменения. - X-Instance-Id. Генерируется в
src/instance.pyиз hostname контейнера (или UUID, если hostname недоступен). Добавляется в каждый ответ middlewareRequestIdMiddleware. Стабилен в жизни процесса. - Идемпотентность. Таблица
idempotency_keys(PK: user_id + method + path + key). Логика:- SELECT — если ключ уже есть и body совпадает → возвращаем сохранённый ответ.
- Если body другой →
409. - INSERT резервирования (
response_status=0), приUniqueViolation→ перечитываем, ждём или возвращаем 409. - Создаём сообщение, UPDATE результата.
- Источник истины — Postgres. Valkey используется как deny-list отозванных сессий (не кэш валидных).
- Сессии. Bearer-токен, SHA-256-хеш в
sessions, logout добавляет в deny-list. - Пароли. Argon2id.
- Миграции. Alembic, отдельный сервис
migrate, запускается один раз, API ждётservice_completed_successfully. - CPU/RAM-лимиты на всех сервисах (
deploy.resources.limits). - API не публикуют порты — только LB.
Доказательства критериев
Уровень 3
| Критерий | Команда/сценарий | Результат |
|---|---|---|
| Публичный smoke | make test BASE_URL=http://localhost:8080 |
PASS: lab3 public API scenario |
| ≥2 API-реплики | docker compose ps |
mtusi2026lab3-api-1, -api-2 Up |
| Разные реплики обслуживают | for i in 1..6; do curl .../health/live | grep x-instance-id; done |
чередование 5fff16304a90 / 8a77b9d87d21 |
| LB — единая точка входа | curl http://localhost:8080/health/live |
ответ приходит от одной из реплик, порт публикует только LB |
| Остановка одной реплики | make test-failover ACTION_SCRIPT=scripts/stop-one.sh |
{"observed_instances_before": 2, "successful_writes": 106, "failed_attempts": 1, "first_recovery_seconds": 2.718} → PASS |
| Идемпотентность | smoke: повтор POST с тем же ключом возвращает тот же Message | PASS |
| make test-persistence | make test-persistence ACTION_SCRIPT=scripts/restart.sh |
PASS |
Уровень 4
| Критерий | Команда/сценарий | Результат |
|---|---|---|
| LB исключает недоступный backend | make test-failover |
восстановление за 2.7 секунды, вторая реплика продолжает обслуживать |
| Последовательная остановка каждой реплики | make test-failover дважды |
прогон 1: recovery 2.718s, прогон 2: recovery 2.488s; оба PASS |
| Параллельная идемпотентность | python3 student_tests/test_parallel_idempotency.py |
Status codes: {409: 9, 201: 1}, Messages in history: 1 |
| CPU/RAM-лимиты | grep -A5 "deploy:" compose.yaml |
cpus/memory на всех сервисах |
| API не публикуют порты | docker compose ps |
у api нет 0.0.0.0:8080, порт только у lb |
| Нет container_name | grep container_name compose.yaml |
пусто |
| Rolling update под нагрузкой | load.py --duration 60 + параллельно docker restart api-1 && docker restart api-2 |
3197 успешных, 9 ошибок (0.28%), 53.2 RPS, p50=25ms, p95=183ms, p99=272ms |
| Миграции однократно | сервис migrate в docker compose ps |
Exited (0) |
Метрики failover
Прогон 1:
{"observed_instances_before": 2, "successful_writes": 106, "failed_attempts": 1, "first_recovery_seconds": 2.718}
Прогон 2:
{"observed_instances_before": 2, "successful_writes": 105, "failed_attempts": 1, "first_recovery_seconds": 2.488}
Интерпретация:
observed_instances_before: 2— балансировка работала до отказа.successful_writes: ~105— вторая реплика продолжала обрабатывать трафик.failed_attempts: 1— только один запрос попал в момент обнаружения отказа (HAProxyinter 2s × fall 2 = ~4s).first_recovery_seconds: ~2.5s— укладывается в требование lab3 «≤10 секунд».
Метрики rolling update
{
"requested_duration_seconds": 60.0,
"successful_requests": 3197,
"failed_requests": 9,
"error_ratio": 0.002807,
"successful_rps": 53.216,
"successful_latency_ms": {
"p50": 24.915,
"p95": 182.695,
"p99": 271.553
}
}
Интерпретация: во время 60-секундной нагрузки обе реплики были поочерёдно перезапущены. 9 ошибок (0.28%) — это те запросы, которые попали в момент grace period реплики. Все остальные обработаны второй репликой.
Параллельная идемпотентность
Results: 10 responses
Status codes: {409: 9, 201: 1}
Messages in history: 1
PASS: parallel idempotency — exactly one message created
10 потоков одновременно послали POST с одним Idempotency-Key и разными body. Один получил 201, остальные — 409 conflict. В истории одно сообщение.
Эксперименты и отказы
| Воздействие | Ожидаем | Наблюдали | Восстановление |
|---|---|---|---|
| Остановка реплики api-1 | Вторая продолжает | 105 успешных записей, 1 фейл | ~2.5 секунды |
| Остановка реплики api-2 | Вторая продолжает | 106 успешных, 1 фейл | ~2.7 секунды |
| Перезапуск всего стека с volumes | Данные и сессия выживают | PASS persistence | ~5 секунд |
| Параллельные POST с одним ключом | Одно сообщение | 1 сообщение в истории | — |
| Rolling update под нагрузкой | ≤ нескольких % ошибок | 0.28% (9 из 3206) | мгновенно |
Исправления по замечаниям ревью
Уровень 3
-
Небезопасный повтор после обрыва POST. Ключ резервировался со
status=0до создания сообщения — при падении ключ залипал. Исправлено:INSERT idempotency_keysиINSERT messagesв одной транзакции,response_status=201сразу. При падении — ROLLBACK откатывает всё. -
Конкурентная идемпотентность. В
except UniqueViolationвозвращался409вместо перечитывания. Исправлено: retry loop (5 попыток по 50 мс). При одинаковых запросах все потоки получают тот же 201 и то же тело.Проверка:
test_parallel_idempotency.py, 10 потоков →Status codes: {201: 10},Unique response bodies: 1,Messages in history: 1. -
ACL при повторе. Проверка ключа шла до проверки доступа → посторонний видел
409. Исправлено: проверкаchat_membersпервой; посторонний всегда получает404. -
X-Instance-Id: unknown. Вcompose.yamlбылоINSTANCE_ID: ${HOSTNAME:-unknown}— переменная WSL, не контейнера. Исправлено: строка удалена,src/instance.pyиспользуетsocket.gethostname()— у каждой реплики уникальный ID. -
Ошибки контракта.
- Неверный UUID →
400: функцияvalid_uuidвmain.py, применяется в роутах с{chat_id}. - 500 без заголовков: все обработчики ошибок добавляют
X-Request-IdиX-Instance-Idчерез_with_headers. - Readiness с неправильным
request_id: берётся из_rid(request), совпадает с заголовком.
- Неверный UUID →
Уровень 4
- Конкурентная идемпотентность — см. п. 2 выше.
- Migrate без лимитов — добавлен
deploy.resources.limits(cpus: 0.5, memory: 256M). - Healthcheck в отчёте. Синхронизировано:
postgres—pg_isreadyкаждые 5s.cache—valkey-cli pingкаждые 5s.api—urllib /health/liveкаждые 5s,start_period: 15s.migrate— healthcheck нет (разовый сервис).lb— healthcheck нет в Compose; HAProxy проверяет бэкенды черезoption httpchk GET /health/ready(inter 2s fall 2 rise 2) вhaproxy.cfg.
Ограничения и следующие шаги
- SPOF: LB (HAProxy) и Postgres — единственные экземпляры. Падение LB → сервис недоступен. Падение Postgres → 503. Это осознанное ограничение lab3: HA для БД и LB — тема lab5+ или трека «Отказ узла».
- HAProxy на одном узле: на Docker Desktop не проверяется перенос между физическими узлами. Это lab3 трек 2.
- Valkey не персистентный: deny-list теряется при рестарте. Это безопасно — Postgres источник истины.
- Идемпотентные ключи хранятся вечно — cleanup по
IDEMPOTENCY_TTL_SECONDSне реализован. Для lab3 приемлемо. - Параллельный POST в момент рестарта реплики: если реплика упала между
INSERT idempotency_keys (status=0)иUPDATE, ключ останется «в процессе» до TTL. Клиент получит409. Для lab3 приемлемо, для продакшена — нужен cleanup-job.
Следующий шаг (если делать «5»):
- Трек 1: цена масштабирования (1/2/4 реплики под нагрузкой, saturation point).
- Трек 2: отказ узла (несколько физических хостов, Swarm).