18 KiB
Отчёт — лабораторная 3
- Автор, группа: Койчакаев Багавдин, БВТ2301.
- Целевая оценка: 5; законченный трек: 1 — цена масштабирования.
- Состав реализации: API ЛР2, HAProxy, минимум две API-реплики, общие PostgreSQL и Valkey, конкурентная идемпотентность в PostgreSQL.
- Внешние источники: контракт и материалы курса. Использованы Python 3.12.8, psycopg 3.2.3, argon2-cffi 23.1.0, redis-py 5.2.1; при подготовке использовался Codex.
Запуск
cp .env.example .env
# задайте POSTGRES_PASSWORD и CURSOR_SECRET (случайный ключ минимум 32 байта)
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --scale api=2 --wait --wait-timeout 180
make check
make validate
make test BASE_URL=http://127.0.0.1:8080
make test-idempotency BASE_URL=http://127.0.0.1:8080
make test-persistence ACTION_SCRIPT=scripts/restart.sh BASE_URL=http://127.0.0.1:8080
make test-failover ACTION_SCRIPT=scripts/stop-one.sh BASE_URL=http://127.0.0.1:8080
Приложение слушает только внутреннюю сеть Compose. Единственный опубликованный порт — loopback порт HAProxy 8080. Миграции запускает одноразовый сервис migrate перед API, под advisory lock PostgreSQL. Первая схема сохраняется совместимой с базой ЛР2; миграция 002_idempotency добавляет таблицу ключей и индекс срока хранения.
Архитектура и решения
HTTP client → HAProxy :8080 → API × 2+ → PostgreSQL (messages, sessions, idempotency)
↘ общий Valkey (TTL lookup hint; PostgreSQL остаётся источником истины)
HAProxy round-robin балансирует запросы между адресами DNS api, повторно разрешая адрес каждые 2 секунды. Проверка GET /health/ready выполняется раз в секунду; две ошибки исключают backend, два успеха возвращают его. Connect timeout — 1 секунда, timeout ожидания/ответа — 10 секунд. API слушает 0.0.0.0:8080 внутри сети и на SIGTERM прекращает serve_forever; Compose ждёт до 10 секунд для штатного завершения.
Сессия проверяется PostgreSQL на каждом запросе; значение Valkey лишь ускоряет lookup и не авторизует пользователя без живой строки в PostgreSQL. Общий CURSOR_SECRET нужен, чтобы cursor истории, созданный одной репликой, принимался другой. Секрет и пароль БД находятся только в локальном .env, игнорируемом Git и Docker build context.
Для каждого POST сообщения обязателен ключ [A-Za-z0-9._:-]{1,128}. Уникальная область — пользователь, метод, путь чата и ключ; body хешируется после нормализации JSON, а пропущенный attachment_ids равен []. pg_advisory_xact_lock сериализует одновременные запросы одной области во всех API-процессах; PostgreSQL хранит отпечаток body и точный JSON результата вместе с сообщением в одной транзакции. Совпавший запрос возвращает тот же 201 и Message; отличающийся body — 409; запись можно использовать заново спустя 24 часа. Ошибка/откат транзакции не оставляет частично зарегистрированный ключ. Каждый API-ответ включая ошибку содержит непустой X-Request-Id и идентификатор процесса в X-Instance-Id.
Роли и версии
| Роль | Service | Версия | Health/volume/порты |
|---|---|---|---|
| API | api (Compose scale) |
Python 3.12.8 slim Bookworm, pinned digest в Dockerfile | /health/ready, без host-порта, без локального состояния |
| Балансировщик | haproxy |
3.0.8 Alpine | HAProxy backend checks, единственный порт 127.0.0.1:8080 |
| База | postgres |
16.4 Bookworm | pg_isready, общий volume postgres_data, внутренний порт 5432 |
| Кэш сессий | valkey |
8.0.1 Alpine | PING, volume valkey_data, AOF everysec, внутренний порт 6379 |
| Миграции | migrate |
тот же образ API | одноразовый контейнер; выполняется до запуска реплик |
CPU/RAM limits заданы в compose для API, HAProxy, PostgreSQL и Valkey. api не имеет container_name, поэтому штатное горизонтальное масштабирование поддерживается.
Проверки уровня 3 и 4
Публичный smoke проверяет обязательный API через HAProxy. Дополнительный параллельный тест запускает 32 запроса с одним ключом и одним body одновременно; все ответы вернули один ID сообщения, наблюдались две реплики. Persistence-сценарий перезапустил API, HAProxy, PostgreSQL и Valkey без удаления volumes; тот же Bearer-токен прочитал те же данные. Три failover-прогона остановили API-реплику по очереди и повторили сценарий после восстановления. Каждый наблюдал две реплики до отказа; новые записи восстановились за 2,902 с, 1,543 с и 1,447 с; ошибок было 0 во всех трёх прогонах (113, 125 и 114 успешных записей); сообщение до отказа и все подтверждённые записи остались доступны, дубли отсутствовали. В конце теста остановленная реплика оставалась остановленной; Compose восстановил её перед следующим прогоном и после финальной проверки.
Rolling replacement под нагрузкой выполняется скриптом scripts/rolling-update.sh: пул сначала увеличивается до трёх, затем контейнеры заменяются по одному с сохранением активного backend. Под нагрузкой 60 секунд, concurrency 16: 50 291 успешная запись (836,949 RPS), 24 ошибки из 50 315 запросов (0,048%), p50/p95/p99 = 6,118/55,938/85,729 мс. После завершения пул восстановлен до двух здоровых реплик. Метрики сохранены в evidence/rolling-update-load.json; успешность запросов при замене не абсолютная, что отражено в ограничениях.
Трек 1 — цена масштабирования
Гипотеза. При равном суммарном CPU/RAM перенос ресурса с одного API на несколько реплик улучшит RPS только до насыщения общей PostgreSQL или пула соединений. При фиксированной мощности на реплику добавление API в какой-то момент перестанет повышать throughput; увеличение пула сверх полезного уровня добавит конкуренцию за БД, а не пропускную способность.
Методика. scripts/track1_experiment.py пересоздаёт API при каждом профиле, ждёт readiness и 5 секунд стабилизации, затем трижды измеряет закрытый цикл POST-сообщений по 30 секунд с concurrency 16. Перед каждым sample очищаются только учебные таблицы messages и idempotency_keys, затем выполняется ANALYZE; порядок вариантов перемешивается детерминированным seed. Сессии/пользователи остаются в PostgreSQL. Фиксированный бюджет: 2 vCPU и 1 GiB RAM суммарно для API, разделённые между 1/2/4 репликами. Серия роста: 0,5 vCPU и 256 MiB на реплику для 1/2/4/8 реплик. Отдельное сравнение при четырёх репликах меняет DB_POOL_MAX 5/10/20. PostgreSQL ограничен 2 CPU и 1 GiB; HAProxy — 0,25 CPU и 128 MiB. Записываются успешные RPS, ошибки, p50/p95/p99, CPU/RAM компонентов и число сообщений. Сводки и исходные данные — evidence/track1-results.json, график — evidence/track1-rps.svg.
Чтобы определить точку насыщения, scripts/track1_offered_load.py подаёт фиксированный поток 250/500/750/1000 POST RPS на восемь API-реплик (0,5 CPU / 256 MiB каждая) по три раза в перемешанном порядке; HTTP-клиент переиспользуется в потоках, число in-flight ограничено, Docker stats во время нагрузочного окна не опрашивается. Throughput рассчитан по фактическому времени вместе с drain. Затем scripts/track1_offered_scale.py делает три парных прогона 8/12 реплик при предложенных 1000 RPS. Между повторами масштабирование возвращается к восьми репликам, чтобы освободить DB-соединения до очистки синтетических таблиц. Все исходные измерения лежат в evidence/offered-load-results.json и evidence/offered-scale-results.json; график rate sweep — evidence/offered-load.svg.
| Профиль | Реплики | Пул/реплика | медиана RPS (min–max) | медиана ошибок | p50/p95/p99, ms | API CPU mean/peak, % | API RAM peak, MiB |
|---|---|---|---|---|---|---|---|
| fixed-1 | 1 | 10 | 418,5 (389,7–456,3) | 0,017% | 32,3/53,0/82,4 | 174,3/190,2 | 61,9 |
| fixed-2 | 2 | 10 | 698,6 (653,6–749,2) | 0% | 8,0/62,4/92,9 | 74,0/109,5 | 60,9 |
| fixed-4 | 4 | 10 | 837,7 (590,7–900,3) | 0,007% | 5,2/57,5/101,9 | 38,2/53,3 | 62,4 |
| scaled-1 | 1 | 10 | 103,7 (102,1–108,8) | 0,064% | 111,1/313,3/484,9 | 47,8/53,3 | 83,5 |
| scaled-2 | 2 | 10 | 274,6 (244,8–276,3) | 0,048% | 22,9/183,7/290,4 | 37,6/52,9 | 140,0 |
| scaled-4 | 4 | 10 | 680,7 (635,3–875,7) | 0% | 6,0/71,0/123,1 | 40,8/53,2 | 79,2 |
| scaled-8 | 8 | 10 | 764,2 (655,4–787,6) | 0% | 9,5/70,6/111,2 | 29,0/50,1 | 82,0 |
| pool-5 | 4 | 5 | 921,2 (837,9–1061,3) | 0,003% | 5,3/49,2/89,8 | 40,4/53,3 | 62,6 |
| pool-10 | 4 | 10 | 808,9 (611,5–969,2) | 0,020% | 5,5/66,7/108,3 | 38,9/51,9 | 99,5 |
| pool-20 | 4 | 20 | 951,3 (573,5–1044,2) | 0,003% | 5,4/45,3/89,2 | 41,7/52,5 | 63,1 |
Среда: macOS 26.5.1 arm64, 8 host CPU; Docker Engine 29.8.2; Docker VM 8 CPU / 4 106 605 444 байта RAM (~3 918 MiB); Python клиента 3.14.6; Python API 3.12.8; PostgreSQL 16.4. Закрытая серия длилась 30 секунд, rate-controlled серия — 15 секунд на sample. Во всех замерах JSON фиксирует размер синтетических таблиц; перед sample messages и idempotency_keys очищались, остальные пользовательские данные сохранялись. Closed-loop percentiles подвержены coordinated omission; rate-controlled серия имеет короткие окна и оценивает только эту среду. Все результаты ограничены одним Docker-host; потеря узла одновременно затрагивает API, HAProxy, PostgreSQL и локальные volumes.
| Предложено, RPS | Медиана успешных RPS (min–max) | Медиана ошибок | Медиана p95, ms |
|---|---|---|---|
| 250 | 249,6 (249,6–250,0) | 0% | 9,9 |
| 500 | 499,6 (419,6–499,9) | 0% | 41,6 |
| 750 | 745,9 (693,2–748,7) | 0,018% | 100,9 |
| 1000 | 810,1 (553,2–879,3) | 2,753% | 1 611,3 |
Парное сравнение при 1000 предложенных RPS:
| API-реплик | Успешные RPS, медиана (min–max) | p95, медиана, ms | Ошибки POST за 3 повтора | Диагностика PostgreSQL |
|---|---|---|---|---|
| 8 | 727,0 (584,4–851,5) | 1 504,7 | 874 / 45 000 | SELECT прошёл |
| 12 | 555,8 (546,0–774,9) | 1 986,4 | 12 / 45 000 | Все 3 запроса отклонены: too many clients already |
Поиск насыщения и улучшение. В rate-controlled серии 250 и 500 предложенных RPS полностью принимались без ошибок (медианный p95 9,9 и 41,6 мс). При 750 RPS медиана успешной пропускной способности составила 745,9 RPS, p95 — 100,9 мс. При 1000 RPS throughput вырос лишь до 810,1 RPS, медианная доля ошибок достигла 2,75%, а p95 — 1 611 мс. Это показывает knee общей цепочки между 750 и 1000 RPS; повторяемость ограничена тремя короткими прогонами, поэтому это не универсальная производственная ёмкость.
Компонентное ограничение установлено отдельной проверкой DB-пула. При DB_POOL_MAX=10 восемь реплик могут открыть до 80 соединений, а двенадцать — до 120. Фактический max_connections PostgreSQL равен 100. В трёх прогонах с 12 репликами и нагрузкой 1000 RPS, помимо роста задержки, PostgreSQL трижды отказал даже в диагностическом SELECT с FATAL: sorry, too many clients already; после возврата к восьми репликам запросы к БД снова проходили. Наблюдение сохранено в evidence/db-saturation-observation.txt, а метрики сравнения — evidence/offered-scale-results.json. Таким образом, насыщение пула/БД возникает между восемью и двенадцатью репликами при текущем лимите пула; дальнейшее увеличение API без снижения размера пула или повышения DB connection budget ухудшает доступность общих соединений. 8→12 RPS-диапазоны перекрываются, поэтому причинный вывод основан на подтверждённом исчерпании connection slots, а не только на падении медианного throughput.
Подтверждённое улучшение при фиксированном суммарном бюджете 2 vCPU / 1 GiB: переход fixed-1→fixed-2 поднял медиану с 418,5 до 698,6 RPS (+66,9%); диапазоны трёх повторов не пересекаются (389,7–456,3 и 653,6–749,2 RPS). p50 снизился с 32,3 до 8,0 мс, p95 изменился с 53,0 до 62,4 мс. Серии DB_POOL_MAX=5/10/20 при низкой конкуренции и HAProxy 0,25/0,5 CPU имеют перекрывающиеся диапазоны; их эффект не заявляется как отдельное улучшение. Все измерения ограничены одной Docker VM и конкретным синтетическим профилем.
Результаты и ограничения
Офлайн структурная проверка, API smoke, гонка идемпотентности, перезапуск и failover пройдены; подробный stdout сохранён в evidence/lab3-checks.txt. Полная OpenAPI/JSON Schema проверка требует openapi-spec-validator==0.7.2 из requirements-dev.txt; установить зависимость в этой среде не удалось из-за недоступного DNS PyPI. HTTP используется только на loopback для синтетических данных. Эта схема выдерживает отказ одного API-процесса при работающих HAProxy, host, PostgreSQL и Valkey; она не выдерживает потерю Docker-host, HAProxy или PostgreSQL. При отказе Valkey действующие сессии проверяются по PostgreSQL. Отдельной HA базы данных и второго узла нет. Под нагрузкой при rolling replacement замерены 24 ошибки на 50 315 запросов (0,048%); для повторения именно операции создания сообщения клиент должен повторить запрос с тем же Idempotency-Key. Другие POST-операции не обещают прозрачную идемпотентность.