Files
mtusi2026lab3/REPORT.md
T
2026-11-05 17:42:55 +03:00

30 KiB
Raw Blame History

Отчёт — лабораторная 3

  • Автор, группа: Запорожец Михаил, БВТ2304
  • Целевая оценка: 4 (трек 5 не заявлен)
  • Commit/PR: #99 (ветка solution/bvt2304-zaporozhets, коммит 9555684)
  • Использованные источники, библиотеки и помощь ИИ: документация HAProxy 3.2 (server-template/resolvers, http-check, retry-on, observe), Docker Compose (deploy.replicas/resources, healthcheck), PostgreSQL (INSERT … ON CONFLICT, deferrable constraints, READ COMMITTED); библиотеки FastAPI 0.115, uvicorn 0.34, asyncpg 0.30, argon2-cffi 23.1, redis-py 5.2. Код, конфигурации и тесты написаны с помощью ИИ-ассистента (Claude); решения разобраны и проверены автором.

Запуск из чистого clone

Нужно: Docker Engine/Desktop с Compose v2.20+ (проверено: Docker 29.8.2, Compose 5.6.0, Windows 11 + Docker Desktop, WSL2) и POSIX-shell (Linux/macOS или Git Bash). Для публичных проверок Python/make на хосте не нужны — они запускаются в сервисе tester. Python 3.9+ на хосте нужен только для серий отказов под нагрузкой (student-tests/failover_series.py), потому что rolling update создаёт контейнеры через compose с bind-путями хоста.

Роль Сервис Образ Health/readiness Volume Сеть / порт Credentials
Балансировщик lb haproxy:3.2.8-alpine wget /stats; сам проверяет API по /health/ready — edge; единственная публикация 127.0.0.1:8080 (+ 127.0.0.1:8404 статистика) не нужны
API × N api (deploy.replicas: ${API_REPLICAS:-2}) сборка Dockerfile (python:3.12.12-slim-bookworm) HEALTHCHECK /health/ready нет; root fs read-only, /tmp tmpfs edge + data; порты не публикуются secrets database_url, cache_url
Миграции migrate (one-shot) тот же образ exit 0 — data secret database_url
PostgreSQL postgres postgres:17.7-bookworm pg_isready pgdata data (internal) POSTGRES_PASSWORD_FILE
Кэш сессий valkey valkey/valkey:8.1.4 valkey-cli ping нет (кэш, persistence выключена намеренно) data (internal) requirepass в secret valkey_conf
API с TTL=2 с api-ttl (profile test) тот же образ как у api — edge + data, без публикации как у api
Тестовый стенд tester (profile tools) python:3.12.12-alpine3.22 + make + curl + docker-cli — bind . edge docker.sock
git clone <repo> && cd <repo>
sh scripts/init-secrets.sh                 # ./secrets/* со случайными паролями и .env из .env.example; значения не печатает
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --wait
#   postgres, valkey -> migrate (однократно применяет миграции) -> api x2 (healthy) -> lb

# Публичные проверки (Linux-контейнер tester; на Linux-хосте можно просто `make ...`)
docker compose --env-file .env --profile tools run --rm tester make check
docker compose --env-file .env --profile tools run --rm tester make test
docker compose --env-file .env --profile tools run --rm tester make test-failover ACTION_SCRIPT=scripts/stop-one.sh
docker compose --env-file .env --profile tools run --rm tester sh scripts/restore.sh       # вернуть реплику
docker compose --env-file .env --profile tools run --rm tester make test-persistence ACTION_SCRIPT=scripts/restart.sh

# Уровень 4
sh scripts/test-lab3.sh                                       # собственные тесты lab3 + регрессия уровня 4 из lab2
python student-tests/failover_series.py --scenario stop    --output evidence/failover-stop.json
python student-tests/failover_series.py --scenario kill    --output evidence/failover-kill.json
python student-tests/failover_series.py --scenario rolling --duration 70 --action-at 10 --output evidence/rolling-update.json
sh scripts/collect-evidence.sh                                # все текстовые доказательства evidence/*.txt одной командой
  • Bootstrap/миграции: python -m app.migrate (сервис migrate) применяет migrations/NNNN_*.sql по порядку, каждую в своей транзакции, под pg_advisory_lock; версия и SHA-256 пишутся в schema_migrations. Реплики API миграции не выполняют: api стартует только после migrate: service_completed_successfully, поэтому гонки реплик за схему нет. Повторный запуск печатает skip (evidence/fresh-start.txt).
  • Масштабирование: docker compose --env-file .env up -d --wait --no-recreate --scale api=4 api — HAProxy сам находит новые реплики через DNS Docker (до 8 слотов server-template), конфигурация LB не меняется (evidence/scale.txt).
  • Rolling update: sh scripts/rolling-update.sh (см. ниже).
  • Действий оператора, кроме init-secrets.sh, не требуется. Если на 8080 уже работает стенд lab2 — остановить его (docker compose -p mtusi-lab2 stop) или задать LB_PUBLISHED_PORT в .env.
  • Безопасная остановка (данные сохраняются): docker compose --env-file .env stop или ... down.
  • Намеренное удаление учебных данных: docker compose --env-file .env down -v (удаляет volume mtusi-lab3_pgdata); секреты — каталог secrets/.

Архитектура и решения

клиент ──HTTP──> lb: HAProxy 3.2 (127.0.0.1:8080)          сеть edge
                  │  roundrobin, без sticky; активная проверка /health/ready раз в 1 с;
                  │  реплики из DNS Docker (server-template api-1..8 -> имя "api")
          ┌───────┴────────┐
          ▼                ▼
        api-1  ...       api-N   (FastAPI/uvicorn, stateless, X-Instance-Id)
          │  asyncpg pool ≤10  │  redis-py, timeout 300 мс      сеть data (internal)
          ▼                    ▼
     PostgreSQL 17 (источник истины)      Valkey 8.1 (общий кэш копий сессий с TTL)
     users, chats, chat_members, messages, sessions, idempotency_keys, cache_state

Что перенесено из lab2: весь API (пользователи, Argon2id, Basic → Bearer-сессии, чаты, keyset-пагинация, единый формат ошибок), схема 0001_init.sql, раннер миграций, Valkey как read-through кэш сессий, тесты уровня 4 (как регрессия student-tests/test_lab2_regression.py). Объявленные переходы 2 → 3: обязательный Idempotency-Key для POST сообщения и X-Instance-Id во всех ответах API.

Что изменено в lab3:

  1. Stateless-реплики. Сессии — в PostgreSQL (источник истины) + общий Valkey; локальной памяти, от которой зависит корректность, нет. Единственное такое место из lab2 нашёл перенесённый тест test_revoke_during_cache_partition: «окно недоверия к кэшу» после ошибки Valkey жило в памяти одного процесса, и другая реплика, не видевшая сбоя, отдавала копию отозванной сессии (тест падал: expected 401, received 200). Исправлено миграцией 0003_cache_state.sql: реплика, получившая ошибку Valkey, публикует окно в PostgreSQL, а попадание в кэш принимается только если общий признак проверен не более 0,5 с назад (≤ 2 лёгких SELECT/с на реплику). Root fs контейнеров API read-only — некуда положить локальное состояние даже случайно.
  2. Идемпотентность (migrations/0002_idempotency.sql, create_message в app/main.py). Таблица idempotency_keys, PK (user_id, chat_id, key) = область контракта «пользователь + метод + путь + ключ» (метод один). В одной транзакции: проверка членства → INSERT ключа ON CONFLICT DO UPDATE … WHERE created_at < now − TTL RETURNING message_id → INSERT сообщения с этим id. Конкурентный INSERT того же PK с другой реплики ждёт COMMIT/ROLLBACK первой транзакции (уникальный индекс работает как замок), затем видит строку и возвращает сохранённое сообщение (READ COMMITTED: каждый оператор видит свежий снимок). FK ключа на сообщение DEFERRABLE INITIALLY DEFERRED — ключ вставляется раньше сообщения. Сравнение тела — SHA-256 канонического JSON (порядок ключей/пробелы/\u-экранирование не важны); другое тело — 409, сохранённый результат не меняется. Транзиентная 5xx откатывает и ключ, и сообщение — повтор с тем же ключом создаёт запись ровно один раз. Повтор заново проверяет сессию и членство (после logout — 401, посторонний — 404). TTL ключа IDEMPOTENCY_TTL_SECONDS = 24 ч; просроченный ключ атомарно переиспользуется, фоновая очистка раз в час.
  3. X-Instance-Id = <hostname контейнера>-<6 hex случайных>: стабилен для жизни процесса, новый после рестарта; hostname = короткий ID контейнера, по нему stop-one.sh находит контейнер (и проверяет label com.docker.compose.service=api). В lab7 заменить на непрозрачный alias.
  4. Graceful shutdown (app/__main__.py). SIGTERM → drain SHUTDOWN_DRAIN_MS=3000: процесс обслуживает запросы, но /health/ready = 503 и ответы с Connection: close; LB за это время выводит реплику из ротации. Затем штатный graceful shutdown uvicorn (новые соединения не принимаются, начатые запросы дообрабатываются до 10 с). stop_grace_period: 20s > 3 + 10. Код выхода 0.
  5. Балансировщик (infra/haproxy/haproxy.cfg). Почему не только depends_on/healthcheck: они управляют порядком старта и статусом контейнера, но не распределяют запросы и не убирают больной backend из маршрута — это делает LB.
    • Обнаружение реплик: resolvers docker (127.0.0.11), повторное разрешение раз в 1 с; остановленный контейнер исчезает из DNS → слот в MAINT.
    • Активная проверка: GET /health/ready, inter 1s, fastinter 500ms, fall 2, rise 2, timeout check 1s.
    • Пассивная: observe layer4 error-limit 2 on-error mark-down — 2 ошибки соединения на живом трафике сразу дают DOWN.
    • Повторы: retries 2 + option redispatch 1 (на другую реплику). L7-повторы retry-on conn-failure empty-response response-timeout разрешены только для GET и POST сообщения (защищён ключом); для POST /users, /chats, /auth/sessions и DELETE — disable-l7-retry: повтор только если запрос ещё не был отправлен. Так контракт («не добавляйте прозрачные повторы этих POST») соблюдён.
    • Таймауты: connect 1 с, server 15 с (> statement_timeout 5 с), keep-alive к клиенту 10 с < keep-alive uvicorn 30 с.
    • Если /health/ready не проходит ни у одной реплики (недоступна БД), запросы идут в резервный backend api_live (проверка /health/live): клиент получает честный 503 контракта от API (с X-Instance-Id), а /health/live работает. Ответы, созданные самим LB (502/503/504), тоже в формате ошибки контракта с X-Request-Id.
  6. Критичные зависимости readiness: только PostgreSQL. Valkey не критичен (без него API медленнее, но корректен — test_valkey_down).
  7. Часы и порядок: created_at и сроки сессий/ключей назначает PostgreSQL (clock_timestamp()), а не реплика — расхождение часов реплик не влияет на порядок истории и TTL.

Транзакционные границы: создание чата + участники — одна транзакция; ключ идемпотентности + сообщение — одна транзакция; logout — COMMIT revoked_at, затем DEL из кэша (при ошибке — общее окно недоверия).

Соответствие .env.example конфигурации

Переменная Где используется Значение по умолчанию
APP_HOST, APP_PORT uvicorn в контейнере API (APP_PORT в compose зафиксирован 8080) 0.0.0.0, 8080
APP_ENV метка окружения lab
SESSION_TTL_SECONDS срок сессии в PostgreSQL 3600
DATABASE_URL_FILE, CACHE_URL_FILE пути к Compose secrets внутри контейнера /run/secrets/...
SESSION_STORE postgres или postgres+valkey postgres+valkey
API_REPLICAS deploy.replicas сервиса api 2
IDEMPOTENCY_TTL_SECONDS срок жизни ключа (не меньше 24 ч, проверяется при старте) 86400
SESSION_CACHE_TTL_SECONDS TTL копии сессии в Valkey и длина окна недоверия 60
SHUTDOWN_DRAIN_MS drain при SIGTERM 3000
DB_POOL_MAX, DB_STATEMENT_TIMEOUT_MS, DB_ACQUIRE_TIMEOUT_MS, CACHE_TIMEOUT_MS пул и таймауты на реплику 10, 5000, 2000, 300
PASSWORD_HASH_WORKERS параллельные Argon2id на реплику (по 64 MiB) 2
API_CPUS, API_MEMORY, PG_CPUS лимиты контейнеров 1.0, 384M, 2.0
LB_PUBLISHED_PORT, LB_STATS_PORT порты LB на 127.0.0.1 8080, 8404

Лимиты ресурсов (deploy.resources.limits, проверяет test_infrastructure_rules): api 1 CPU / 384 MiB на реплику, postgres 2 CPU / 768 MiB, valkey 0.5 CPU / 96 MiB, lb 1 CPU / 128 MiB, migrate 0.5 CPU / 128 MiB. Нет container_name; порты публикует только lb и только на 127.0.0.1; сеть data — internal: true, LB в неё не входит; secret БД получают только api/migrate/postgres, secret Valkey — только valkey и api.

Доказательства критериев

Все файлы — evidence/, дата прогона 2026-11-05, хост: Intel i5-1135G7 (8 потоков), 7.8 GB RAM; Docker Desktop VM: 8 CPU, 3.7 GiB.

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Публичный smoke make check, make validate, make test (в tester, через LB) 3 × PASS public-tests.txt
3: стенд в compose.yaml, ≥2 API, один вход, общие БД и store сессий docker compose up -d --build --wait; compose ps 2 api + lb + postgres + valkey healthy, порт только у lb instances.txt
3: разные запросы одной сессии — разные реплики student-tests/show_instances.py (1 вход, 10 запросов через LB) 2 разных X-Instance-Id по 5 раз, без повторного входа instances.txt
3: остановка любой одной реплики, ≤10 с make test-failover ACTION_SCRIPT=scripts/stop-one.sh × 2 (по очереди api-6 и api-5, restore между ними) PASS, failed_attempts: 0; запись не прерывалась (first_recovery_seconds ≈ 4 с = длительность самого hook: drain 3 с + shutdown) failover-hook.txt, stop-one.log
3: какой контейнер реально остановлен evidence/stop-one.log пишет hook container=mtusi-lab3-api-6 … exited exit=0, затем api-5 failover-hook.txt
3: идемпотентность, повтор не создаёт дубль smoke (replay/409/400); test_same_key_concurrent_across_replicas 24 параллельных POST с одним ключом напрямую в обе реплики → 24 × 201, одно тело, 1 строка в messages student-tests.txt
3: persistence, прежний токен make test-persistence ACTION_SCRIPT=scripts/restart.sh PASS; StartedAt lb, api ×2, postgres, valkey изменились, volume сохранён persistence.txt
3: запуск с пустого volume отдельный проект -p mtusi-lab3-fresh, smoke, повтор migrate apply 0001..0003, smoke PASS, повтор — skip fresh-start.txt
4: health/readiness, timeouts, SIGTERM согласованы; LB исключает backend test_sigterm_drain; серия stop после SIGTERM ready=503, live=200, запросы ещё обслуживаются с Connection: close; через 2 с LB на неё не шлёт; exit 0. LB пометил DOWN через 1,34–1,52 с, последний ответ от цели 1,2–1,3 с student-tests.txt, failover-stop.json
4: период проверок и макс. время обнаружения конфигурация + измерение см. таблицу «Обнаружение отказа» ниже haproxy.cfg, failover-*.json
4: каждая реплика по очереди под нагрузкой: RPS, ошибки, восстановление failover_series.py --scenario stop и --scenario kill 4 прогона, 0 ошибок клиента, 0 потерь/дублей; таблица ниже failover-stop.json, failover-kill.json
4: общая идемпотентность параллельными запросами test_same_key_concurrent_* один ключ: 24/24 одинаковых 201; два тела под одним ключом: 10 × 201 (одно тело) + 10 × 409, 1 сообщение student-tests.txt
4: retry после транзиентной ошибки test_transient_failure_not_recorded при остановленной БД POST → 503 от API; после восстановления тот же ключ → 201, повтор → тот же ответ, 1 сообщение student-tests.txt
4: CPU/RAM-лимиты, нет обхода LB, нет container_name, общие только нужные секреты/хранилища test_infrastructure_rules (docker inspect) PASS: лимиты у всех, у api нет PortBindings, read-only root fs, монтируются только 2 secret student-tests.txt
4: rolling update под нагрузкой; миграции однократно и совместимы failover_series.py --scenario rolling (scripts/rolling-update.sh разворачивал исправление кэша + миграцию 0003) 0 ошибок за 70 с; apply 0003_cache_state один раз до замены; новые реплики с label сборки 0ab3a34-1793888112; RPS до/во время/после 283/243/280 rolling-update.json
4: возможности lab2 сохранены test_lab2_regression.py через LB 10/10 (TTL, logout, гонка регистрации, откат чата, курсоры, кэш, отказ Valkey/БД, разрыв с Valkey) student-tests.txt
4: масштабирование без правки LB --scale api=4, затем =2 4 слота UP в HAProxy, одна сессия обслужена 4 репликами scale.txt

Эксперименты и отказы

Профиль серий (student-tests/failover_series.py): closed-loop, 4 писателя (POST сообщения; при неопределённом результате — повтор с тем же ключом и телом) + 2 читателя (GET истории limit=20), таймаут клиента 3 с, 25 с на прогон, воздействие на 8-й секунде, клиент — Python на хосте Windows через проброс порта Docker Desktop. Параллельно раз в 200 мс опрашивается /stats;csv HAProxy — оттуда время, когда слот цели перестал быть UP. Окна: «до» = [1 с; воздействие), «во время» = [воздействие; конец hook + 5 с), «после» = остаток.

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
docker stop api-5 (SIGTERM, drain) LB выводит реплику до закрытия сокета, ошибок нет 0 ошибок; DOWN в LB через 1,34 с; последний ответ цели 1,22 с; RPS 341 → 303 → 279; p99 63 → 78 мс ошибок не было; 4766/4766 подтверждённых записей в истории, дублей 0
docker stop api-6 то же 0 ошибок; DOWN через 1,52 с; RPS 349 → 258 → 259; max 188 мс 0; 4461/4461, дублей 0
docker kill api-5 (SIGKILL, без drain) краткие ошибки допустимы, повтор с ключом не дублирует 0 ошибок клиента; DOWN через 0,31 с; HAProxy: 3 retry, 5 redispatch; max задержка 1015 мс (= timeout connect 1 с + повтор на другой реплике) 0; 4225/4225, дублей 0
docker kill api-6 то же 0 ошибок; DOWN через 0,16 с; 1 retry, 3 redispatch; max 1031 мс 0; 4240/4240, дублей 0
rolling-update.sh (сборка, migrate 0003, surge ×2, поочерёдный stop старых) 0 ошибок, обе реплики заменены 0 ошибок за 36 с операции; 4 redispatch; RPS 283 → 243 → 280; p99 78 → 94 → 78 мс 0; 11433/11433, дублей 0
public test-failover × 2 (по очереди обе реплики) ≥2 реплики до, восстановление ≤10 с failed_attempts 0, 135–136 записей за 15 с запись не прерывалась
restart.sh (всё, кроме volume) данные и токен переживают PASS ≈ 20 с до готовности; потерь нет
остановка PostgreSQL честный 503, без 500 и без пропуска 503 unavailable от API через api_live, live = 200; после старта — та же сессия ≈ 5–10 с после старта БД

Обнаружение отказа (конфигурация → верхняя граница → измерено):

Тип отказа Механизм Граница Измерено
Остановка процесса (SIGTERM) ready = 503 → активная проверка: ≤ 1 с до проверки + 1 × fastinter 0,5 с (fall 2) ≈ 1,5 с (+ время ответа проверки); drain 3 с её перекрывает 1,34–1,52 с, 0 ошибок
Внезапная смерть процесса / контейнера пассивно: 2 ошибки соединения → DOWN; DNS: запись исчезает, разрешение раз в 1 с; активно: ≤ 1 с + 2 × (timeout check 1 с) + 0,5 с пассивно — сразу; DNS ≤ ~2 с; активно ≤ ~3,5 с 0,16–0,31 с; запросы в полёте повторены на другой реплике (≤ 1 с задержки)
Зависание без закрытия сокета timeout check 1 с × fall 2; запрос клиента — timeout server 15 с, затем L7-повтор для GET/POST сообщения ≈ 3,5 с для новых запросов не измерялось (см. ограничения)

Нагрузка на стенд (tests/load.py --duration 30 --concurrency 8 из tester, только POST): 460 успешных RPS, 0 ошибок, p50/p95/p99 = 14/43/80 мс (load.json). docker stats в середине (load-stats.txt): api 91–92 % от лимита 1 CPU каждая, postgres 55 %, lb 29 %, клиент 77 %; RAM api ≈ 40 MiB из 384. Узкое место этого профиля — CPU API-реплик (Python), а не БД или LB. Сравнение 1/2/4 реплик при фиксированном CPU и поиск saturation point — это трек 5.1, здесь не заявляется.

Ограничения измерений. Closed-loop клиент страдает coordinated omission; на Windows-хосте клиент идёт через проброс портов Docker Desktop, поэтому абсолютные RPS серий (≈ 250–350) ниже, чем из контейнера (460) и не являются оценкой ёмкости. RPS «после» отказа ниже, потому что остаётся одна реплика с 1 CPU. Каждый сценарий прогнан по одному разу на реплику — разброс не оценён. Время обнаружения измерено с дискретностью опроса статистики 200 мс.

Ограничения и следующие шаги

  • Выдерживается: остановка или внезапная смерть любой одной API-реплики (в том числе поочерёдно каждой), rolling update, перезапуск всего стенда с volume, недоступность Valkey, разрыв API ↔ Valkey при logout.
  • Не выдерживается (честно): отказ Docker-host (все контейнеры на одном узле), отказ lb (единственный HAProxy — SPOF), отказ PostgreSQL (одна БД без реплики: на время простоя — 503, данные сохраняются на volume). Отказ процесса ≠ отказ узла: при потере узла пропали бы и LB, и БД.
  • POST /users, /chats, /auth/sessions не защищены ключом: если реплика умрёт после получения такого запроса, клиент может получить 502, а самостоятельный повтор может создать второй объект (это разрешено контрактом; L7-повтор LB для них намеренно выключен).
  • Окно согласованности кэша сессий при частичном разрыве с Valkey — не более 0,5 с (время до проверки общего признака другой репликой), вместо 60 с, которые были бы без общего признака. Полностью строгий вариант — отказаться от кэша.
  • Миграции — только expand (добавление): версия N−1 работает на схеме N, поэтому migrate выполняется один раз перед заменой реплик. Удаляющие изменения (contract) потребовали бы отдельного шага после того, как старые реплики выведены, — в этой работе их нет.
  • X-Instance-Id содержит hostname контейнера (= его ID) — допустимо для lab3, для lab7 нужен непрозрачный alias.
  • Зависание реплики (живой сокет, нет ответа) отдельно не моделировалось; ожидаемое поведение — вывод по timeout check, первые запросы ждут до timeout server 15 с.
  • Следующие шаги: трек 5.1 (k6 open-loop, 1/2/4 реплики при фиксированном CPU, пул БД как кандидат в узкое место), реплицированная PostgreSQL и второй LB для заявления устойчивости к потере узла.