Files
mtusi2026lab3/REPORT.md
T

125 lines
20 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Отчёт — лабораторная 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 репликах и при нескольких хостах.