36 KiB
Отчёт — лабораторная 3
- Автор, группа: Тимаева М.П., БПИ2302
- Целевая оценка; выбранный трек 5, если нужен: 5, трек 1 (цена масштабирования)
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: документация Docker Compose / HAProxy / asyncpg; ИИ использовалось для написания отчета и помощи с написанием скриптов, цифры с прогона
scripts/scale_cost.py2026-11-08.
Запуск из чистого clone
Вариант: Docker Compose + HAProxy. Нужны Docker Engine с Compose v2 (проверено на Docker 29.4, Compose 5.1) и Python 3.9+ для тестов. На Windows скрипты .sh выполняются через Git Bash (обёртки scripts/*.cmd).
Образы: postgres:16.10-alpine и haproxy:3.2.26-alpine (LTS), оба закреплены digest в compose.yaml. Приложение собирается из Dockerfile на python:3.14.8-slim-bookworm@sha256:… в образ messenger-lab3-app:${APP_VERSION}.
Одна последовательность запуска:
cp .env.example .env # задать свой POSTGRES_PASSWORD
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --wait
# postgres (healthy) -> migrate (один раз, exit 0) -> api x API_REPLICAS (healthy) -> lb (healthy)
make test # smoke через LB, http://localhost:8080
python scripts/show_instances.py # одна сессия, разные X-Instance-Id
make test-idempotency # один ключ параллельно через разные реплики
make test-failover ACTION_SCRIPT=scripts/stop-one.sh # Windows: scripts/stop-one.cmd
docker compose --env-file .env up -d --wait # вернуть остановленную реплику
make test-persistence ACTION_SCRIPT=scripts/restart.sh # Windows: scripts/restart.cmd
# уровень 4
sh scripts/lb-status.sh # пул HAProxy: реплика, IP, UP/DOWN
make failover-series # поочерёдная остановка каждой реплики под нагрузкой
python scripts/failover_series.py --kill --output evidence/failover-series-kill.json # то же, SIGKILL
docker compose --env-file .env build api migrate # с APP_VERSION=v3 в окружении
make rolling-update APP_VERSION=v3 # Windows: scripts/failover_series.py --mode action --action scripts/rolling-update.cmd
# после rolling update записать APP_VERSION=v3 в .env
# уровень 5, трек 1 (после прогона стенд возвращается к 2×1.0 CPU)
make scale-cost PYTHON=python # Windows; GNU Make: make scale-cost
Остановка без потери данных: docker compose --env-file .env down. Намеренное удаление учебных данных: docker compose --env-file .env down -v (удаляет volume pgdata).
Архитектура и решения
edge network data network (internal: true)
client -> lb (HAProxy :8080, loopback) -> api-1, api-2, … (порт не публикуется) -> postgres (volume pgdata)
migrate (one-shot) ------------^
| Роль | Compose service | Образ | Health/readiness | Сети | Volume / секреты | Лимит CPU / RAM (резерв) |
|---|---|---|---|---|---|---|
| LB | lb |
haproxy:3.2.26-alpine@… |
monitor-uri /lb/health; активные проверки API |
edge | только read-only конфиг, секретов нет | 0.5 / 128M (0.1 / 32M) |
| API × N | api |
messenger-lab3-app:<версия> |
/health/live, /health/ready (БД, миграции, drain) |
edge, data | /run/secrets/postgres_password (uid 10001, 0400) |
${API_CPUS:-1.0} / ${API_MEMORY:-256M} (0.25 / 128M); пул ${DB_POOL_MAX:-10} |
| Миграции | migrate |
тот же образ | one-shot, service_completed_successfully |
data | тот же секрет | 0.5 / 128M |
| БД | postgres |
postgres:16.10-alpine@… |
pg_isready каждые 2 с |
data | pgdata, POSTGRES_PASSWORD_FILE |
${POSTGRES_CPUS:-1.0} / ${POSTGRES_MEMORY:-512M} (0.25 / 256M) |
- Источник истины — PostgreSQL: пользователи, чаты, сообщения, сессии (
sessions, токен хранится как SHA-256) и результаты идемпотентности (idempotency_keys). В API нет локального состояния, от которого зависит корректность. Redis из lab2 убран: он был только кэшем, а для общего хранилища сессий достаточно PostgreSQL. - Изоляция: наружу публикуется только
lbи только на loopback. У API нетports,docker portпуст. LB находится только в сетиedgeи не резолвитpostgres. Сетьdataобъявленаinternal, без выхода наружу. Volumepgdataсмонтирован только вpostgres.container_nameнигде нет, поэтому--scale api=Nработает (evidence/limits.txt). - Секреты: пароль БД лежит только в незакоммиченном
.envи попадает в контейнеры как Compose secretpostgres_password(environment: POSTGRES_PASSWORD). В env контейнеров есть только путь*_PASSWORD_FILE. API и мигратор собираютDATABASE_URLизDB_HOST/DB_USER/DB_NAMEи файла (app/config.py). У LB секретов нет. - Миграции выполняет отдельный сервис
migrate(python -m app.migrate) до старта реплик, а при rolling update — один раз черезdocker compose run --rm migrate. Реплики схему не меняют./health/readyвозвращает 503, пока вschema_migrationsнет всех миграций этой сборки. Параллельный запуск мигратора сериализуетсяpg_advisory_lock. - X-Instance-Id = hostname контейнера (короткий Docker ID). X-App-Version =
APP_VERSIONобраза. По нему видна смена версии при rolling update. - Балансировщик: HAProxy, round robin без sticky.
server-template api 1-10 api:8080сresolvers docker(Docker DNS127.0.0.11,hold valid 1s), поэтому реплики, добавленные через--scaleили rolling update и остановленные, входят в пул и выходят из него без перезапуска LB. - Повтор на другой реплике:
retries 2,option redispatch,retry-on conn-failure empty-response response-timeout. Для POST, кроме/api/v1/chats/{id}/messages, стоитhttp-request disable-l7-retry, то есть они повторяются только если соединение с репликой не было установлено. POST сообщений можно повторять, потому чтоIdempotency-Keyобязателен. - Идемпотентность: в одной транзакции удаляется истёкший ключ, затем
INSERT … ON CONFLICT DO NOTHINGвidempotency_keys(PK: пользователь + метод + путь + ключ) вместе с готовым ответом и SHA-256 тела, затем вставка сообщения. Конкурентный дубль на другой реплике ждёт на уникальном индексе до COMMIT первой транзакции и получает сохранённый ответ (тот же 201) либо 409 при другом теле. При ошибке ключ не фиксируется, и повтор безопасен.
Health, timeouts и SIGTERM: согласованные тайминги
SIGTERM -> readiness 503 сразу; запросы ещё обслуживаются
-> HAProxy: 2 неудачные проверки (inter 1s, timeout 1s) -> DOWN, не более 3 с
-> через DRAIN_SECONDS=4 uvicorn перестаёт принимать соединения, дорабатывает текущие за SHUTDOWN_TIMEOUT_SECONDS=3
-> exit 0 примерно через 5 с; stop_grace_period 10 s (stop-one: docker stop --time 9), SIGKILL не нужен
| Параметр | Значение | Где |
|---|---|---|
Период активной проверки LB /health/ready |
1 с, timeout check 1s, fall 2, rise 2 |
infra/haproxy/haproxy.cfg |
| Обновление DNS реплик | 1 с (hold valid 1s, hold obsolete 0s) |
там же |
timeout connect / server / client / http-request |
1 с / 10 с / 30 с / 10 с | там же |
| Drain после SIGTERM / завершение текущих запросов | 4 с / 3 с | DRAIN_SECONDS, SHUTDOWN_TIMEOUT_SECONDS |
stop_grace_period |
10 с (> 4 + 3) | compose.yaml |
| Keep-alive uvicorn | 10 с (> pool-purge-delay HAProxy 5 с) |
KEEPALIVE_TIMEOUT_SECONDS |
| Docker healthcheck API | каждые 3 с, 3 попытки; только порядок старта и rolling update, LB его не использует | compose.yaml |
Максимальное время обнаружения отказа:
- Плановая остановка (SIGTERM): реплика выводится заранее, не более (2 \cdot 1 + 1 = 3) с, и раньше, чем закрывается сокет. Замер: последний запрос на останавливаемую реплику пришёл через 1,76–2,05 с после SIGTERM, ошибок 0.
- Падение процесса (SIGKILL): запрос к мёртвому IP завершается по
timeout connect 1sи уходит на другую реплику (redispatch). Пул очищается по DNS примерно за 1 с или по проверкам не более чем за 3 с. Замер: максимальная пауза без успешного ответа 0,96–0,98 с, ошибок 0. - Зависшая реплика, принимающая соединения: проверки дают DOWN не более чем через 3 с. Запросы, уже отправленные на неё, ждут до
timeout server 10sи затем повторяются (response-timeout) для GET и POST сообщений. Экспериментально не проверялось. - Возврат в пул:
rise 2, то есть около 2 с после готовности. Замер отdocker startдо первого ответа реплики: 4,5–5,2 с, включая старт приложения.
Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|---|---|---|---|
| Стенд в compose.yaml, ≥2 API, одна точка входа, общая БД и сессии | down -v, config --quiet, up -d --build --wait |
config OK; api-1, api-2, lb, postgres healthy; migrate применил 001–003 и Exited (0); в HAProxy 2 реплики UP |
evidence/smoke.txt |
| Одна сессия обслуживается разными репликами | python scripts/show_instances.py |
6 запросов с одним токеном: по 3 на каждую из 2 реплик | evidence/instances.txt |
| Остановка любой одной API-реплики | make test-failover ACTION_SCRIPT=scripts/stop-one.cmd ×2, между прогонами up -d --wait |
2 PASS: остановлены api-2, затем api-1, Exited (0); 121 и 115 записей, 0 ошибок; HAProxy убрал реплику из пула |
evidence/failover.txt |
| Повтор POST с тем же Idempotency-Key | make test-idempotency |
5 ключей × 20 параллельных POST: по 10 ответов с каждой реплики, один Message на ключ, другое тело → 409 | evidence/idempotency.txt |
| make check, make test, persistence | make check, make test, make test-persistence ACTION_SCRIPT=scripts/restart.cmd |
PASS; после рестарта lb, api, postgres те же ID, volume на месте, прежний токен работает | evidence/smoke.txt, evidence/persistence.txt |
| 4: health/readiness, timeouts, SIGTERM согласованы; LB исключает недоступный backend | HAProxy active checks + drain; scripts/lb-status.sh |
см. таблицу таймингов; останавливаемая реплика получает последний запрос через ≤2,05 с после SIGTERM; после выхода её нет в пуле | infra/haproxy/haproxy.cfg, evidence/failover-series.json |
| 4: поочерёдная остановка каждой реплики: RPS, ошибки, время восстановления | make failover-series; failover_series.py --kill |
по 2 реплики в каждом режиме, 0 ошибок, все подтверждённые записи на месте, дублей нет (таблица ниже) | evidence/failover-series*.{txt,json} |
4: лимиты, нет портов API, секреты и хранилища только где нужно, нет container_name |
docker inspect, docker stats, docker port, nslookup из lb |
лимиты у всех 5 сервисов; порт только у lb (127.0.0.1/::1); пароль только файлом 0400; lb без секретов и без доступа к БД; container_name: 0 |
evidence/limits.txt |
| 4: rolling update под нагрузкой, миграции однократно и совместимо | make rolling-update APP_VERSION=v3; ранее dev → v2 с миграцией 003 |
0 ошибок, максимальная пауза 0,07 с; v2 → v3 без снижения числа реплик ниже 2; при dev → v2 миграция 003 применена один раз, и старые реплики dev продолжали работать |
evidence/rolling-update.{txt,json}, evidence/rolling-update-migration.txt |
| 5 трек 1: 1/2/4 реплики при бюджете 2.0 CPU/512M, рост CPU, saturation, одно улучшение | make scale-cost PYTHON=python |
187.5 / 249.5 / 185.8 RPS; 4×0.5 → 2×1.0 даёт +34% RPS и p95 465→197; пул 20 отвергнут; LB не насыщен | evidence/scale-cost.{json,txt,svg} |
Все прогоны 2026-11-07 на commit 124c83e + рабочее дерево (до коммита уровня 4), Docker 29.4.3, Windows 11, один хост. make test-failover/test-persistence под Windows запускались той же командой из Makefile напрямую (python tests/resilience.py ...), потому что GNU Make под cmd не находит test в guard-строке.
Цель make test-failover выбирает тест: это реплика, обслужившая первое сообщение. Для второго прогона через LB отправлен один GET /health/ready, чтобы сдвинуть round robin, и тест остановил другую реплику.
Эксперименты и отказы
Профиль нагрузки scripts/failover_series.py: 4 потока в закрытом цикле, каждый делает POST сообщения (с Idempotency-Key; неопределённый результат повторяется с тем же ключом) и GET 20 последних сообщений. Счёт идёт по секундам. Для каждой реплики по очереди: 10 с baseline, затем остановка, 15 с наблюдения, затем docker start того же контейнера, ожидание его ответов и 5 с паузы. В конце вся история чата читается заново: каждая подтверждённая запись должна быть ровно один раз.
Поочерёдная остановка реплик под нагрузкой
| Воздействие | Реплика | RPS baseline → во время → после | Ошибки | Макс. пауза без успеха | Последний запрос на реплику после сигнала | Выход контейнера | RPS ≥90% baseline после выхода | Возврат в пул после docker start |
|---|---|---|---|---|---|---|---|---|
docker stop (SIGTERM + drain) |
api-1 | 129,0 → 114,8 → 113,1 | 0 | 0,09 с | 2,05 с | 5,06 с, exit 0 | 2,8 с | 5,2 с |
docker stop (SIGTERM + drain) |
api-2 | 131,5 → 145,2 → 165,4 | 0 | 0,09 с | 1,76 с | 4,88 с, exit 0 | 1,6 с | 4,9 с |
docker kill (SIGKILL) |
api-1 | 174,4 → 145,3 → 158,4 | 0 | 0,96 с | 0,12 с | 0,66 с, exit 137 | 2,3 с | 4,5 с |
docker kill (SIGKILL) |
api-2 | 177,9 → 146,5 → 139,0 | 0 | 0,98 с | 0,12 с | 0,63 с, exit 137 | 2,1 с | 5,2 с |
Итог серий: SIGTERM — 80,5 с, 5312 записей и 5312 чтений, p95 73 мс; SIGKILL — 71,2 с, 5520 записей и 5520 чтений, p95 66 мс. В обоих случаях 0 ошибок, 0 дублей, 0 потерянных подтверждённых записей. В предварительном прогоне --kill (не сохранён) была 1 ошибка на 12 890 запросов: запрос, оборванный в момент SIGKILL. Это допустимый переходный эффект, клиент повторяет его с тем же ключом.
RPS — это пропускная способность закрытого цикла на одном хосте, где рядом работали посторонние контейнеры. Между сериями она колеблется на 30–40 %, а внутри серии падение во время отказа составляет 10–20 %. Иногда RPS с одной репликой выше baseline: узкое место — клиент и общий CPU хоста, а не число реплик. Это не измерение ёмкости.
make test-failover и rolling update
| Воздействие | Что ожидаем | Что наблюдали | Восстановление / потеря данных |
|---|---|---|---|
make test-failover, stop-one → api-2 |
запись продолжается ≤10 с, дублей нет | PASS, 121 запись, 0 ошибок | first_recovery_seconds 6,42 / нет |
то же после восстановления → api-1 |
то же | PASS, 115 записей, 0 ошибок | 6,44 / нет |
restart.cmd: lb, api, postgres |
данные и старый токен сохранены | PASS, volume сохранён | нет потерь |
| rolling update v2 → v3 под нагрузкой (2 реплики) | нет ошибок, ёмкость ≥2 реплик, версия сменилась | 42,7 с; 0 ошибок; пауза 0,07 с; RPS 181 → 146 → 186; ответы: до v2 1833; во время v2 3941 / v3 2279; после v3 2787 | 5423 записи, 0 дублей, 0 потерь |
| rolling update dev → v2 с миграцией 003 | старая версия работает на расширенной схеме | 45,7 с; 0 ошибок; пауза 0,10 с; миграция применена один раз в начале, реплики dev обслуживали запросы до своей замены |
4458 записей, 0 дублей, 0 потерь |
first_recovery_seconds в tests/resilience.py считается до первой успешной записи после завершения hook. Hook теперь длится около 6 с: это docker stop, который ждёт 4 с drain. Записи при этом не прерывались (0 ошибок), поэтому значение отражает длительность hook, а не простой. Оно укладывается в лимит 10 с, как и сам hook.
Rolling update (scripts/rolling-update.sh):
- Собрать
messenger-lab3-app:$APP_VERSION. - Один раз выполнить
docker compose run --rm migrate. - Для каждой старой реплики запустить
up -d --no-deps --no-recreate --wait --scale api=N+1. Новая реплика стартует из нового образа, скрипт ждёт healthy и UP в HAProxy. Затем старая реплика получаетdocker stop(drain) иdocker rm.
Ёмкость не опускается ниже N, LB не перезапускается. После обновления версию нужно записать в .env (APP_VERSION), иначе следующий docker compose up пересоздаст реплики в версии из .env.
Политика миграций (expand/contract). Миграция выполняется до замены реплик и должна быть совместима с работающей версией: только новые таблицы, индексы и nullable-колонки. Пример — 003_session_indexes.sql. Readiness старой сборки проверяет только свои миграции, поэтому расширенная схема её не ломает. Удаление и переименование колонок допустимы только отдельным релизом после ухода старых реплик. Ограничение: CREATE INDEX без CONCURRENTLY (мигратор работает в транзакции) коротко блокирует запись в индексируемую таблицу. Для sessions учебного размера это незаметно, для большой таблицы понадобится CONCURRENTLY вне транзакции.
Трек 1. Цена масштабирования
Гипотеза. При фиксированном суммарном бюджете API 2.0 CPU / 512M рост числа реплик 1 → 2 → 4 не увеличивает RPS пропорционально: один uvicorn-процесс не утилизирует 2.0 CPU, а четыре процесса по 0.5 CPU режут квант каждого воркера. Узкое место после двух реплик — не HAProxy, а общая PostgreSQL (лимит 1.0 CPU) плюс пул соединений. Подтверждённое улучшение: тот же бюджет отдать двум репликам по 1.0 CPU, а не четырём по 0.5.
Методика. Хост: Windows 11, Docker 29.4, 12 CPU, ≈11.6 GiB RAM, один Docker Engine. Профиль один на все точки: 24 потока, закрытый цикл POST /api/v1/chats/{id}/messages через LB (http://localhost:8080), прогрев 5 с, замер 20 с. Между точками Compose пересоздаёт только API (лимиты API_CPUS / API_MEMORY / DB_POOL_MAX); PostgreSQL остаётся 1.0 CPU / 512M. Раз в секунду снимаются docker stats и pg_stat_activity. Утилизация CPU считается как (сумма % docker stats) / лимит контейнера: 100% stats ≈ 1 host CPU. Повтор: make scale-cost PYTHON=python. Исходные JSON/таблица/графики: evidence/scale-cost.{json,txt,svg}. Дата прогона: 2026-11-08.
Серии:
- Фиксированный бюджет API 2.0 CPU / 512M: 1×2.0/512M, 2×1.0/256M, 4×0.5/128M; пул 10 на реплику.
- Рост ресурсов, 2 реплики: 0.25 → 0.50 → 1.0 CPU на процесс (postgres 1.0 не меняется).
- Одна попытка улучшения, отвергнутая: 2×1.0,
DB_POOL_MAX10 → 20.
Результаты. Ошибок 0 во всех точках. Лимиты совпали с docker inspect (NanoCpus / Memory).
| id | N | CPU/RAM реплики | пул | RPS | p95, мс | API util | PG util | LB util | backends / ёмкость пула |
|---|---|---|---|---|---|---|---|---|---|
| fixed-1 | 1 | 2.0 / 512M | 10 | 187.5 | 204 | 49% | 47% | 40% | 11 / 10 |
| fixed-2 | 2 | 1.0 / 256M | 10 | 249.5 | 197 | 85% | 66% | 47% | 21 / 20 |
| fixed-4 | 4 | 0.5 / 128M | 10 | 185.8 | 465 | 83% | 62% | 38% | 39 / 40 |
| grow-0.25 | 2 | 0.25 / 256M | 10 | 25.1 | 1916 | 96% | 26% | 12% | 21 / 20 |
| grow-0.50 | 2 | 0.50 / 256M | 10 | 93.8 | 593 | 97% | 38% | 24% | 21 / 20 |
| improve-pool20 | 2 | 1.0 / 256M | 20 | 140.7 | 397 | 89% | 63% | 45% | 35 / 40 |
График: evidence/scale-cost.svg (верх — фиксированный бюджет, низ — рост CPU).
Saturation.
- API CPU — saturation при срезе 0.25 и 0.50 (util 96–97%, p95 0.6–1.9 с). На 1×2.0 util только 49%: один процесс uvicorn ≈ один core, второй CPU бюджета не используется. На 4×0.5 каждый воркер упирается в квоту 0.5, как grow-0.50, только процессов больше.
- Пул.
backendsпочти равныN × DB_POOL_MAX(плюс соединение sampler). Это занятость слотов, не очередь в PostgreSQL:pg_active≈ 1–2,waiting≈ 0. На N=1 слотов 10 при 24 клиентах, часть потоков ждётpool.acquire(). На N=4 слотов 40 > 24 клиентов, пул уже не ограничивает. - PostgreSQL — максимум 66% своего 1.0 CPU, saturation нет.
- LB — максимум 47% своего 0.5 CPU, saturation нет.
timeout queue 2sне срабатывал (0 ошибок).
Поэтому рост реплик при фиксированном бюджете перестаёт помогать на N=4: суммарные 2.0 CPU режутся на кванты по 0.5, p95 растёт в 2.4 раза, а лишние соединения (40 вместо 20) бьют в ту же одноядерную БД и RPS падает ниже N=2.
Подтверждённое улучшение. Тот же бюджет 2.0 CPU / 512M: 4×0.5 → 2×1.0. RPS 185.8 → 249.5 (+34%), p95 465 → 197 мс. Это и есть рабочая топология стенда (API_REPLICAS=2, API_CPUS=1.0). Увеличение пула 10 → 20 на тех же 2×1.0 отвергнуто: 249.5 → 140.7 RPS (больше сессий на 1 CPU Postgres, p95 197 → 397).
Ограничения трека. Один прогон по 20 с, закрытый цикл на том же хосте (coordinated omission, общий CPU с Docker). pool_util считает idle-слоты asyncpg, не wait. WAL/диск не снимались. Open-loop / wrk не использовались: для минимума трека достаточно сравнить одинаковый профиль.
Ограничения и следующие шаги
- Выдерживается: плановая остановка, падение или зависание одной API-реплики, пока работает хотя бы одна другая; поочерёдная замена всех реплик; полный перезапуск стенда с сохранением volume.
- Не выдерживается: отказ PostgreSQL и HAProxy. Это единственные точки отказа: БД не реплицирована, LB один. При их остановке API недоступен до перезапуска, подтверждённые данные сохраняются в volume.
- Один хост: отказ узла или Docker Engine останавливает весь стенд. Проверен отказ процесса или контейнера, а не узла.
- Зависание реплики экспериментально не воспроизводилось. Оценка «не более 3 с до DOWN» следует из конфигурации, а уже отправленные на зависшую реплику запросы ждут до 10 с.
- Rolling update в Compose реализован скриптом, а не
deploy.update_config: Compose его не исполняет. Откат — тот же скрипт с прежнейAPP_VERSION, если схема не прошла contract-фазу. - Нагрузка — закрытый цикл одного клиента на том же хосте (coordinated omission, общий CPU). Цифры RPS сравнимы только внутри одной серии. В треке 1 сравнивались только точки той же матрицы
scale_cost.py. - Порядок сообщений между репликами зависит от общих часов хоста:
created_atназначает приложение. - Повтор LB: POST пользователей, чатов и сессий повторяется только при неустановленном соединении. После обрыва уже отправленного запроса клиент должен проверить результат сам: ключа идемпотентности у этих POST нет.