# Отчёт — лабораторная 3 - Автор, группа: [ФИО], [группа] - Целевая оценка; выбранный трек 5, если нужен: **5**, трек 1 «Цена масштабирования» - Commit/PR: локальный коммит ветки `solution/lab3`; PR — после публикации - Использованные источники, библиотеки и помощь ИИ: Python 3.12, uvicorn, asyncpg, redis-py, argon2-cffi; HAProxy 3.0; PostgreSQL 17; Valkey 8; aiohttp/matplotlib (только для экспериментов). Код lab2 перенесён с объявленными изменениями (`Idempotency-Key`, `X-Instance-Id`). Использование ИИ: [заполняется автором] ## Запуск из чистого clone Prerequisites: Docker Compose v2, bash (Git Bash на Windows), Python ≥ 3.9. На Windows перед `tests/*.py` установите `PYTHONUTF8=1`. Версии: `python:3.12.12-slim-bookworm@sha256:593bd06e…`, `postgres:17.11-alpine@sha256:b0f9560a…`, `valkey/valkey:8.1.10-alpine@sha256:081c2f5c…`, `haproxy:3.0-alpine@sha256:56b887da…` (3.0.29), зависимости — `requirements.txt` (закреплены). ```sh sh scripts/init-secrets.sh # secrets/postgres_password, secrets/database_url (в Git не попадают) cp .env.example .env # API_REPLICAS=2 и лимиты ресурсов docker compose --env-file .env config --quiet docker compose --env-file .env up -d --build # postgres, valkey -> migrate (1 раз) -> api x N -> lb curl http://127.0.0.1:8080/health/ready # единственная публичная точка входа (LB), только 127.0.0.1 python3 tests/smoke.py --base-url http://127.0.0.1:8080 # make test python3 tests/resilience.py --mode persistence --action-script scripts/restart.sh --base-url http://127.0.0.1:8080 python3 tests/resilience.py --mode failover --action-script scripts/stop-one.sh --base-url http://127.0.0.1:8080 sh scripts/restore-replicas.sh # вернуть остановленную реплику (удаляет exited-контейнеры api и поднимает N) ``` Windows: `scripts/restart.cmd`, `scripts/stop-one.cmd` — аналоги `.sh` (CreateProcess не запускает `.sh`). Масштабирование: `docker compose --env-file .env up -d --no-deps --scale api=4 api`. Rolling update: `sh scripts/rolling-update.sh [revision]`. Остановка с сохранением данных: `docker compose --env-file .env stop`. **Намеренное удаление учебных данных**: `docker compose --env-file .env down -v`. ## Архитектура и решения ``` Клиент ─▶ HAProxy (127.0.0.1:8080) ─▶ API ×N (stateless, без публикации портов) ─▶ PostgreSQL (истина, идемпотентность, сессии) └▶ Valkey (общий кэш сессий) ``` | Роль | Сервис | Версия / digest | Health | Volume | Сеть/порт | Credentials | | --- | --- | --- | --- | --- | --- | --- | | LB | `lb` | HAProxy 3.0.29 | `monitor-uri /healthz` | — | `127.0.0.1:8080` (единственный публичный) | — | | API | `api` (≥2 реплики, без `container_name`) | собирается из Dockerfile | `/health/ready` | — | только сеть `backend` | secret `database_url` | | БД | `postgres` | 17.11-alpine | `pg_isready` | `pgdata` | `backend` | secret `postgres_password` | | Сессии/кэш | `valkey` | 8.1.10-alpine, AOF | `valkey-cli ping` | `valkeydata` | `backend` | не опубликован | | Миграции | `migrate` (one-shot) | образ api | код выхода 0 | — | `backend` | secret `database_url` | - **Общее состояние**: пользователи, чаты, сообщения, сессии и ключи идемпотентности — в PostgreSQL; кэш сессий — в общем Valkey. В процессе API локального состояния нет, sticky-сессий в LB нет. Любой запрос любой реплики обслуживается одинаково; видно по `X-Instance-Id` (= имя хоста контейнера, 12 hex = короткий ID контейнера, поэтому его легко сопоставить с `docker ps` в `stop-one.sh`). - **Миграции** выполняются отдельным one-shot сервисом `migrate` до старта реплик (`depends_on: service_completed_successfully`), а не гонкой реплик; при ручном запуске защищены advisory lock. Новые миграции делаются обратно совместимыми (expand/contract): при rolling update старая версия работает со схемой новой. - **Идемпотентность `POST /chats/{id}/messages`** (`Idempotency-Key` обязателен, `[A-Za-z0-9._:-]{1,128}`): таблица `idempotency_keys (user_id, chat_id, idem_key)` с PK. Запись ключа и сообщение — **одна транзакция** (серверная функция `send_message`, миграция 0003). Одновременные повторы, в том числе через разные реплики, сериализуются уникальным индексом: второй `INSERT … ON CONFLICT DO NOTHING` ждёт COMMIT первого и возвращает сохранённое сообщение; другое тело при том же ключе → `409`; тело нормализуется (порядок ключей JSON, отсутствие `attachment_ids` == `[]`), хеш тела хранится. Повтор заново проверяет сессию и членство. Транзиентный сбой откатывает транзакцию целиком — ключ не фиксируется, повтор безопасен. TTL ключа 24 ч (просроченный ключ той же области считается свободным; фоновая очистка раз в час). - **Балансировщик (HAProxy)**: активная проверка `GET /health/ready` каждые **1 с**, `fall 2` / `rise 2` — максимальное время обнаружения отказа ≈ **2–3 с**; `retries 3` + `redispatch` — запросы с ошибкой соединения повторяются на другой реплике; адреса реплик обновляются через Docker DNS (`resolvers docker`, `server-template api 1-8`), поэтому scale/пересоздание не требует перезапуска LB. Ошибки, созданные самим LB (нет живых реплик), отдаются в контрактном формате `503` JSON + `Retry-After` (errorfile). - **Согласованное завершение**: SIGTERM → readiness сразу `503` → ещё 4 с (`DRAIN_SECONDS`) реплика обслуживает запросы, пока LB её исключает → uvicorn прекращает приём и дожидается текущих запросов (≤ 8 с). `stop_grace_period: 15s`. Измерено: реплика перестаёт получать трафик через 1.1–1.7 с, контейнер завершается за 4.6 с, ошибок клиента 0 (`evidence/drain_timing.json`). - **Ресурсы и порты**: у всех сервисов `cpus`/`mem_limit` (API 1 CPU/256 MiB, PostgreSQL 1 CPU/512 MiB, LB 1 CPU/128 MiB); API-порты не публикуются (проверяет `student-tests/test_topology.py`); `container_name` не используется. - Источник хранилища сессий — PostgreSQL + общий Valkey (как в lab2); readiness API зависит только от PostgreSQL. ## Доказательства критериев | Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | | --- | --- | --- | --- | | Весь стенд в compose.yaml, ≥2 реплики, единая точка входа, общие БД и сессии | `docker compose up -d`; `tests/smoke.py` | PASS; ответы через LB с ≥2 разными `X-Instance-Id` без повторного входа | `evidence/checks.txt` | | Разные запросы одного пользователя — разные реплики | `student-tests/test_idempotency.py::test_session_is_shared_between_replicas_without_relogin` | 30 запросов с одним токеном обслужены ≥2 репликами | `evidence/checks.txt` | | Остановка любой одной реплики: чтение/запись ≤10 с, данные целы | `tests/resilience.py --mode failover` для каждой реплики | обе: PASS; восстановление записи 2.4 с и 1.5 с, ошибочных попыток 0 | `evidence/checks.txt` | | Повтор POST с тем же ключом без дубля, в т. ч. конкурентный и через разные реплики | `test_idempotency.py` (9 тестов) | 24 параллельных запроса с одним ключом через ≥2 реплики → 1 сообщение, одинаковый ответ | `evidence/checks.txt` | | make test, persistence, failover | см. выше | PASS; при persistence `StartedAt` всех сервисов изменился | `evidence/checks.txt` | | Health/readiness/SIGTERM согласованы, период проверок и время обнаружения | `research/drain_timing.py` | SIGTERM: 1.1–1.7 с до исключения из ротации, 4.6 с до выхода, 0 ошибок | `evidence/drain_timing.json` | | Последовательная остановка каждой реплики: RPS, ошибки, время восстановления | `research/failover_sequence.py` (70 с нагрузки, 16 клиентов, restore между отказами) | см. таблицу ниже | `evidence/failover_sequence.json\|png` | | CPU/RAM-лимиты, порты API не опубликованы, нет `container_name` | `student-tests/test_topology.py` | 6 тестов OK | `evidence/checks.txt` | | Rolling update под нагрузкой, миграции однократно | `research/rolling_update.py` | обе реплики заменены, 0 ошибок, 0 повторов | `evidence/rolling_update.json` | | Трек 1 | `research/run_scaling_all.sh` | см. ниже | `evidence/scaling_*.json`, `scaling.png` | **Последовательная остановка (под нагрузкой 16 клиентов, записи повторяются клиентом с тем же ключом):** | Реплика | RPS до | RPS на одной реплике | RPS после восстановления | Ошибочных попыток за 10 с | Ошибки прекратились через | | --- | --- | --- | --- | --- | --- | | 1-я (t=10 с) | 1460 | 1411 | 1441 | 14 (`ServerDisconnectedError`) | 1.55 с | | 2-я (t=40 с) | 1436 | 1350 | 1376 | 16 | 1.57 с | Итого 91 677 запросов, ошибочных 30 (0.03 %), после повторов с тем же ключом **финальных отказов 0**, подтверждённых 91 647 = записано 91 647, **потерь 0, дублей 0** (сверка по тексту уникальных сообщений). Ограничение: один клиентский процесс упирается в ≈1.4 тыс. RPS, поэтому RPS одной и двух реплик здесь схожи; для оценки ёмкости см. трек 1. **Rolling update** (60 с нагрузки, обновление на t=10..45 с, `scripts/rolling-update.sh`): запросов 39 597 за время обновления, ошибок **0**, повторов 0, RPS до/во время/после 1263/1123/1268, обе реплики заменены (4 разных `X-Instance-Id` видны во время обновления). В первом прогоне с `on-marked-down shutdown-sessions` в HAProxy наблюдалось 9 ошибок соединения (разрыв активных сессий при исключении сервера); опция удалена, повтор дал 0 ошибок — конфигурация в Git — финальная. ## Эксперименты (трек 1): цена масштабирования **Гипотеза.** Масштабирование API репликами линейно увеличивает пропускную способность, пока не упрётся в общий компонент; при фиксированном суммарном CPU выгоднее меньше процессов лучшей загрузки, чем много «тонких». Узкое место — PostgreSQL (CPU), его можно снять и ресурсами, и сокращением числа обращений к БД на запрос. **Методика** (`research/scaling.py`, `research/run_scaling_all.sh`). Docker Desktop (WSL2), хост 24 логических CPU. Профиль: 64 одновременных клиента (8 процессов aiohttp, closed-loop, чтобы клиент не был узким местом), 90 % `POST` сообщения (с `Idempotency-Key`) + 10 % `GET` первой страницы истории, 40 пользователей/40 чатов, 5 с прогрева + 30 с замера, **2 повтора** на конфигурацию, ресурсы меняются на лету (`docker update`), загрузка CPU снимается `docker stats`. Лимиты по умолчанию: PostgreSQL 2.0 CPU, HAProxy 2.0 CPU, API по 256 MiB. **Серия A — фиксированный суммарный CPU API = 2.0** (RPS = среднее двух повторов; p95 POST): | Конфигурация | До: RPS | p95 | После: RPS | p95 | CPU PostgreSQL (из 200 %) | | --- | --- | --- | --- | --- | --- | | 1 × 2.0 CPU | 1353 | 82 мс | 2289 | 43 мс | 97 % → 115 % | | **2 × 1.0 CPU** | **2364** | 73 мс | **3280** | 37 мс | 163 % → 187 % | | 4 × 0.5 CPU | 2107 | 119 мс | 2575 | 81 мс | 142 % → 171 % | Вывод A: один процесс Python использует ≈1 ядро — лимит 2.0 CPU у единственной реплики не используется (CPU API ≈ 98 %); 2 × 1.0 лучшая конфигурация; 4 × 0.5 хуже из-за троттлинга CPU (каждая реплика упирается в 50 %) и большего числа соединений к БД. **Серия B — рост ресурсов (реплики по 1.0 CPU), RPS:** | Реплик | БД 2 CPU, до | БД 4 CPU, до | БД 2 CPU, после | | --- | --- | --- | --- | | 1 | 1352 | 1418 | 2153 | | 2 | 2453 | 2451 | 3313 | | 4 | 2741 | 3834 | 2995 | | 8 | 2593 | 4636 | 2381 | CPU PostgreSQL (до, лимит 200 %): 98 → 161 → **203 → 204 %** при 1/2/4/8 репликах; CPU одной реплики API падает 97 → 38 %, HAProxy 16 → 48 % (лимит 200 %). **Точка насыщения и почему рост реплик перестаёт помогать.** С 4 реплик PostgreSQL упирается в лимит 2.0 CPU (≈204 %), RPS выходит на плато ≈2.6–2.7 тыс.; дальнейшие реплики лишь ждут ответов БД (CPU API на реплику падает). Это подтверждено вторым прогоном с лимитом БД 4 CPU: RPS продолжает расти (3834 при 4 и 4636 при 8 репликах), т. е. причина плато именно CPU БД, а не LB (HAProxy 78 % из 200 %), пул или клиент. При 8 репликах БД с 4 CPU использует 395 %: ещё не насыщена. **Подтверждённое улучшение** — уменьшение числа обращений к БД на одну запись: вместо проверки членства + транзакции из 3 запросов (`DELETE` просроченного ключа, `INSERT` ключа, `INSERT` сообщения) — один вызов серверной функции `send_message` (миграция 0003; тот же код идемпотентности и атомарности, тесты `test_idempotency.py` проходят на обеих реализациях, переключатель `SEND_STRATEGY=multi|function`). При тех же лимитах (БД 2 CPU, реплики по 1.0 CPU): пик RPS **2741 → 3313 (+21 %)**, на 1 реплике 1352 → 2153 (**+59 %**), p95 при 2 репликах 74 → 40 мс (−45 %). Почему работает: на запись приходится в разы меньше сетевых round-trip и разборов запросов между приложением и БД — ограниченный CPU БД тратится на полезную работу. **Ограничение (честно):** при 4 и 8 репликах «после» ниже, чем при 2 (2995 и 2381): БД уже на пределе CPU, избыточные соединения дают конкуренцию и переключения контекста — оптимум смещается к 2 репликам; точку оптимума нужно определять под лимиты БД. Ограничения методики: один ноутбук, 2 повтора (разброс ≈±4 %), p95 включает задержку клиента; цифры RPS не переносимы между машинами, соотношения — переносимы. Данные: `evidence/scaling_A_base.json`, `scaling_A_improved.json`, `scaling_B_base.json`, `scaling_B_base_pg4.json`, `scaling_B_improved.json` (включая сырые прогоны и загрузку CPU компонентов); график `evidence/scaling.png`. ### Отказы | Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | | --- | --- | --- | --- | | Остановка одной реплики (мгновенно, `docker stop --time 0`) | чтение/запись продолжаются ≤ 10 с | см. таблицу выше | ≈1.5 с; потерь и дублей нет | | SIGTERM реплики | без ошибок клиента | 0 ошибок, исключение из LB за 1.1–1.7 с | — | | Остановка PostgreSQL | реплики исключаются (readiness 503), клиент получает 503 JSON | `test_dependencies.py` OK | после старта БД — автоматически | | Остановка Valkey | кэш обходится | OK | мгновенно | | Рестарт всего стенда с volumes | токен и данные на месте | persistence PASS | < 90 с | ## Ограничения и следующие шаги - Не выдерживается: потеря PostgreSQL/LB/хоста Docker (единичные экземпляры, SPOF); отказ узла не исследовался (трек 2 не выбран). HAProxy — единственная точка входа. - Окно инвалидации кэша сессий (≤ 60 с) при недоступном Valkey в момент logout — как в lab2. - Идемпотентный ключ хранится 24 ч в PostgreSQL; очистка просроченных — фоновая задача каждой реплики. - Подтверждено экспериментами: масштабирование, насыщение БД, улучшение +21 %/+59 %; гипотеза без доказательства: поведение при >8 репликах и при нескольких хостах.