30 KiB
Отчёт — лабораторная 3
- Автор, группа: Запорожец Михаил, БВТ2304
- Целевая оценка: 4 (трек 5 не заявлен)
- Commit/PR: mtusi2026/mtusi2026lab3#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(удаляет volumemtusi-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:
- 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 — некуда положить локальное состояние даже случайно. - Идемпотентность (
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 ч; просроченный ключ атомарно переиспользуется, фоновая очистка раз в час. - X-Instance-Id =
<hostname контейнера>-<6 hex случайных>: стабилен для жизни процесса, новый после рестарта; hostname = короткий ID контейнера, по немуstop-one.shнаходит контейнер (и проверяет labelcom.docker.compose.service=api). В lab7 заменить на непрозрачный alias. - Graceful shutdown (
app/__main__.py). SIGTERM → drainSHUTDOWN_DRAIN_MS=3000: процесс обслуживает запросы, но/health/ready= 503 и ответы сConnection: close; LB за это время выводит реплику из ротации. Затем штатный graceful shutdown uvicorn (новые соединения не принимаются, начатые запросы дообрабатываются до 10 с).stop_grace_period: 20s> 3 + 10. Код выхода 0. - Балансировщик (
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не проходит ни у одной реплики (недоступна БД), запросы идут в резервный backendapi_live(проверка/health/live): клиент получает честный 503 контракта от API (сX-Instance-Id), а/health/liveработает. Ответы, созданные самим LB (502/503/504), тоже в формате ошибки контракта сX-Request-Id.
- Обнаружение реплик:
- Критичные зависимости readiness: только PostgreSQL. Valkey не критичен (без него API медленнее, но корректен —
test_valkey_down). - Часы и порядок:
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 server15 с. - Следующие шаги: трек 5.1 (k6 open-loop, 1/2/4 реплики при фиксированном CPU, пул БД как кандидат в узкое место), реплицированная PostgreSQL и второй LB для заявления устойчивости к потере узла.