Files
mtusi2026lab3/REPORT.md
T

25 KiB
Raw Blame History

Отчёт — лабораторная 3

  • Автор, группа: Орлова В. / БПИ2301
  • Целевая оценка; выбранный трек 5: 5, трек 1 (цена масштабирования). Трек 2 не брала: на одном Docker-хосте нельзя честно показать потерю узла.
  • Commit/PR: не публиковала
  • Использованные источники, библиотеки и помощь ИИ: код lab2 (FastAPI, Postgres, Redis, Argon2id, cursor, Basic/Bearer). Новое: HAProxy 2.8, общая идемпотентность в Postgres, отдельный контейнер миграций. Образы и документация: PostgreSQL 16, Redis AOF, HAProxy server-template и health checks, RFC 7617. Реализацию и текст отчёта готовила с помощью Cursor; команды и измерения ниже прогнала локально и могу объяснить.

Запуск из чистого clone

Нужны Docker и Python 3.11+ на хосте (тесты). Секретов в репозитории нет. На Windows официальные hook — это shell-скрипты, их запускала из WSL, где есть python3 и docker. На Linux достаточно chmod +x и python3. У меня консоль Windows в cp1251, поэтому локально к python добавляла -X utf8. На Linux это не нужно.

python scripts/bootstrap.py
docker compose --env-file .env up -d --build --scale api=2
python scripts/wait_ready.py
python tests/smoke.py --base-url http://127.0.0.1:8080

bootstrap.py один раз пишет .env и secrets/ (пароль Postgres и URL Redis/Postgres). В консоль пароль не печатает и повторно файлы не перезаписывает: volume уже инициализирован этим паролем.

Дальше:

chmod +x scripts/restart.sh scripts/stop-one.sh scripts/rolling-restart.sh
python tests/resilience.py --mode persistence --action-script scripts/restart.sh --base-url http://127.0.0.1:8080
python tests/resilience.py --mode failover --action-script scripts/stop-one.sh --base-url http://127.0.0.1:8080
# hook оставляет реплику остановленной. Вернуть:
docker compose --env-file .env start api
python tests/load.py --base-url http://127.0.0.1:8080 --duration 20 --concurrency 8 --output evidence/load.json
python student-tests/run.py
python student-tests/run_grade4.py
python student-tests/run_track1.py
python student-tests/run_track1_db.py

Остановка без удаления данных: docker compose --env-file .env stop. Снести учебные данные: docker compose --env-file .env down -v. Пароль в secrets/ после этого подходит к новому пустому volume. Новый пароль — удалить secrets/ и снова запустить bootstrap.

Образы, не latest:

Образ Digest
python:3.12.10-slim-bookworm sha256:fd95fa221297a88e1cf49c55ec1828edd7c5a428187e67b5d1805692d11588db
postgres:16.10-bookworm sha256:38471f330eb885e04de130b768d6db4e10469e2311879c7e5c699f6d2d8a1c74
redis:7.4.2-bookworm sha256:fbdbaea47b9ae4ecc2082ecdb4e1cea81e32176ffb1dcf643d422ad07427e5d9
haproxy:2.8.14 sha256:2344d1efbf7a932c7a3d49b60748c28af81c70fd11fcadd983e2be1f0376a69d

Свой API собирается в mtusi-lab3-api:local. Процесс внутри — пользователь 10001. Снаружи опубликован только 127.0.0.1:8080 у HAProxy. У реплик API PortBindings пустой.

Архитектура и решения

Из lab2 перенесены пользователи, чаты, keyset-история, Argon2id, сессии в Redis и атомарное создание чата. In-memory состояния по-прежнему нет. Канонический UUID для участников чата тоже остался: один и тот же id в разном регистре — это один участник, ответ 400, строка чата не создаётся.

Клиент ходит только в HAProxy. Дальше round-robin по репликам API. Sticky cookie нет: иначе разные X-Instance-Id одной сессии были бы случайностью, а не свойством стенда. Сессия лежит в общем Redis, поэтому второй процесс принимает тот же Bearer.

X-Instance-Id — hostname контейнера. Docker ставит его равным id контейнера и не меняет, пока контейнер жив. scripts/stop-one.sh ищет API этого проекта с таким hostname и делает docker stop --time 5. Это учебный alias lab3. Для lab7 он слишком говорящий, там понадобится отдельное случайное имя.

Postgres — источник истины для пользователей, чатов, сообщений и результатов идемпотентности. Redis хранит только сессии (appendonly yes, appendfsync everysec, volume /data). Историю в Redis не клала.

Идемпотентность — таблица idempotency_keys. Область: пользователь + POST + путь чата + ключ. Каноническое тело — JSON с отсортированными ключами, где пропущенный attachment_ids равен []. Непустой список вложений в этой лабе отклоняется: файлов ещё нет. В одной транзакции с INSERT сообщения берётся pg_advisory_xact_lock по хешу области. Повтор того же тела читает уже записанное сообщение и возвращает тот же 201. Другое тело — 409, второй строки нет. Откат транзакции не оставляет ключ занятым, поэтому 5xx можно повторить тем же ключом. Срок — IDEMPOTENCY_TTL_SECONDS, по умолчанию 86400, сравнение делает Postgres. Чужой пользователь или другой чат с тем же ключом — отдельная область. Повтор всё равно начинается с проверки сессии и членства.

Миграции выполняет одноразовый сервис migrate и выходит. Реплики API схему не накатывают: они ждут строку 002_idempotency в schema_migrations. Повторный запуск migrate пишет already applied. Добавляется только новая таблица, старые таблицы lab2 не меняются.

/health/live смотрит только процесс. /health/ready — 200, если не идёт остановка, в базе есть версия 002_idempotency и Redis отвечает на ping. Иначе 503 без имени хранилища. HAProxy опрашивает именно ready.

Проверки LB, из infra/haproxy.cfg:

  • период inter 500ms, fall 2, rise 2, timeout check 800ms, timeout connect 500ms
  • верхняя оценка обнаружения мёртвого backend: один интервал + ещё одна неудача + timeout проверки, около 1.8 с, плюс время самого docker stop
  • DNS Docker 127.0.0.11, server-template на 8 слотов, hold valid 1s
  • POST буферизуется и при обрыве соединения повторяется на другой живой backend. Это безопасно, потому что ключ идемпотентности общий. Наблюдение: в официальном failover из ~90–95 записей сорвалась одна

depends_on и healthcheck контейнера только выстраивают старт. Они не выбирают живый backend на каждый запрос и не убирают умерший процесс из публичного адреса. Это делает HAProxy.

При SIGTERM uvicorn перестаёт принимать соединения (timeout_graceful_shutdown=5, в compose init: true, чтобы сигнал дошёл до процесса). docker stop в hook ждёт до 5 с. Оба официальных отказа закончились кодом 143, это SIGTERM. Политика restart: unless-stopped: явная остановка не поднимает реплику обратно.

Лимиты обычного стенда: API 0.50 CPU и 256 МиБ на реплику, Postgres 1.00 CPU и 512 МиБ, Redis 0.25 CPU и 128 МиБ, HAProxy 0.25 CPU и 128 МиБ. container_name нет, сервис api масштабируется --scale. Пул psycopg по умолчанию 10 на реплику, statement_timeout 5 с. Postgres: fsync=on, synchronous_commit=on, full_page_writes=on, max_connections=80.

Соответствие .env: APP_PORT — порт HAProxy на localhost, внутри API всегда 8080. SESSION_TTL_SECONDS — абсолютный срок сессии. SESSION_STORE=redis, другое значение процесс не принимает. IDEMPOTENCY_TTL_SECONDS — срок ключа. POOL_MAX — размер пула. API_REPLICAS — подсказка для --scale, в compose ещё записано deploy.replicas: 2. Секреты читаются из файлов, не из переменных с паролем.

Отказ процесса и отказ узла — разные вещи. stop-one.sh убивает один контейнер API. Второй API, HAProxy, Postgres и Redis остаются на том же хосте. Потеря хоста уносит все эти процессы сразу. Этот стенд такое не переживает, и я это не заявляю.

Если бы сессии жили в памяти процесса, второй API отвечал бы 401 на тот же токен. Sticky session спрятала бы это, пока жива «своя» реплика, и сломалась бы ровно в момент её остановки. Поэтому сессия в Redis, а балансировка без прилипания.

Повторять после timeout можно POST сообщения с тем же Idempotency-Key и тем же телом: либо вернётся исходное сообщение, либо, если транзакция откатилась, создастся одно. Другое тело с тем же ключом — 409, не вторая запись. Регистрация, логин и создание чата таким ключом не защищены: повтор может создать ещё один объект. Их я автоматически не повторяю.

Доказательства критериев

Стенд измерений: Docker Engine 26.1.4, Intel Core i5-10300H, 8 логических CPU, 17008717824 байт RAM. Дата прогонов 2026-11-06. В docker stats 100% — это одно ядро: лимит 0.35 CPU виден как потолок около 35%.

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Offline check python -X utf8 scripts/check_contract.py PASS: offline skeleton structure вывод команды
Публичный smoke python -X utf8 tests/smoke.py --base-url http://127.0.0.1:8080 PASS: lab3 public API scenario evidence/smoke.txt
Две реплики, одна сессия, разные X-Instance-Id student-tests/run.py, 30 GET /users/me instances 2 evidence/student_checks.txt
API без наружных портов, CPU/RAM лимиты тот же прогон, docker inspect PortBindings пустой, NanoCpus>0, Memory>0; после трека снова 0.50 CPU и 256 МиБ, портов нет evidence/student_checks.txt
Общий Redis, не локальная память failover без повторного логина старый токен пишет через оставшуюся реплику evidence/failover.txt
Идемпотентность: то же тело, другой JSON-порядок и attachment_ids: [], другой регистр UUID в пути run.py второй ответ равен первому evidence/student_checks.txt
Другое тело — 409, без второй строки run.py 409, в таблице одно сообщение с этим id evidence/student_checks.txt
8 параллельных POST с одним ключом run.py 8x201, 1 row evidence/student_checks.txt
Тот же ключ у другого пользователя отдельная проверка двух участников одного чата два разных id сообщений вывод команды, в отчёт не клала токены
Ключ старше 24 ч можно занять снова UPDATE created_at на −25 ч, тот же ключ и текст новый id evidence/student_checks.txt
Нет ключа, ключ с пробелом, пробельный текст run.py три раза 400 код run.py, прогон дошёл до PASS
Cursor другого чата отдельная проверка 400 invalid_request вместе с проверкой двух пользователей
Один UUID участника в двух регистрах run.py 400, число чатов не выросло прогон PASS
Миграции один раз и не из реплик лог migrate, schema_migrations сначала applied, повторно already applied; версии 001_init, 002_idempotency evidence/persistence.txt, evidence/student_checks.txt
Persistence: API и оба хранилища, volume цел, старый токен tests/resilience.py --mode persistence PASS; StartedAt сменился у postgres, redis и api, у lb нет evidence/persistence.txt
Официальный failover, две разные реплики два прогона tests/resilience.py --mode failover 95 и 91 успешных записей, по 1 ошибке, восстановление 1.99 с и 1.371 с, оба PASS, остановленный контейнер Exited (143) evidence/failover.txt
Каждая реплика по очереди, RPS и ошибки student-tests/run_grade4.py первая: 498/499 ok, 33.2 RPS; вторая: 623/624 ok, 41.6 RPS; обе реально stopped evidence/grade4.txt
Rolling под нагрузкой тот же скрипт, docker restart по одной 1189/1190 ok, 42.5 RPS, restarted: 2, после этого снова 2 instance id evidence/grade4.txt
LB снимает мёртвый backend официальный тест: после возврата hook остановленного id нет в последних ответах период проверки 500 мс, fall 2 evidence/failover.txt, infra/haproxy.cfg
Публичная нагрузка tests/load.py --duration 20 --concurrency 8 326 успехов, 0 ошибок, 14.787 RPS, p50 312 мс, p95 1422 мс, p99 1656 мс evidence/load.json
Трек 1 серии ниже см. следующий раздел evidence/track1_*

docker compose start api заодно снова стартует migrate, потому что это зависимость. На данных это no-op: в логе already applied.

Эксперименты и отказы

Гипотеза трека: при фиксированном суммарном CPU/RAM API рост числа реплик перестаёт поднимать RPS, когда упираемся не в число процессов, а в общий бюджет CPU либо в единственный Postgres. Отдельно проверяла, маленький ли пул соединений сам режет успехи.

Методика одна для всех точек, генератор student-tests/run_track1.py: closed-loop POST с новым ключом на каждый запрос, новый чат на повтор, прогрев 4 с выбрасывается, измерение 12 с, два повтора. Ошибки не входят в latency. Это не открытый поток и не пик стенда: клиент ждёт ответ, прежде чем послать следующий. docker stats снимала раз в 2 с только в окне измерения.

Серия A. Суммарно 1.0 CPU и 1024 МиБ на все API, Postgres 1.0 CPU, пул 10, concurrency 8.

Реплики CPU на реплику Средний успешный RPS p50, мс CPU API, % CPU Postgres, %
1 1.00 23.1 328–344 104 16–18
2 0.50 17.0 219 39–41 18–19
4 0.25 23.7 94–110 18–22 16–26

Ошибок не было. Одна реплика уже сидит на своём лимите (около 100% = одно ядро). Postgres при этом занят примерно на пятую часть ядра. Четыре реплики дают тот же порядок RPS, что и одна, медиана лучше, хвост p95 остаётся 1.2–1.5 с. Две реплики в этом бюджете оказались медленнее обеих крайних точек. Рост числа процессов при том же суммарном CPU пропускную способность не поднимает: делить уже занятое ядро неоткуда, а база ещё свободна.

Серия B. Две реплики по 0.50 CPU, concurrency 8, лимит Postgres 0.30 / 0.60 / 1.20. Средний RPS: 20.9, 18.0, 22.3. CPU Postgres 13–21%, то есть даже лимит 0.30 не выбран. Колена нет. В этом профиле база не насыщена, и я не утверждаю, что добавка CPU Postgres здесь что-то ускорила.

Серия C. Те же две реплики по 0.50 CPU, concurrency 16.

POOL_MAX Повторы, RPS Среднее p95, мс Ошибки
2 48.0, 36.7 42.4 922–1312 0
10 20.4, 17.7 19.0 1718–2312 0

Диапазоны не пересекаются. Это подтверждённое улучшение для независимых вставок: пул 2 при concurrency 16 дал примерно вдвое больше успешных RPS, чем пул 10, на тех же CPU. Объяснение, которое сходится с цифрами: реплика и так упёрта в 0.50 CPU (в обоих вариантах stats около 45% на контейнер). Десять одновременных соединений только увеличивают очередь и хвост. Два соединения держат работу короче.

Пул 2 я не сделала значением по умолчанию. Восемь параллельных запросов с одним ключом ждут advisory lock, каждый держит соединение. При пуле 2 часть из них получит 503, хотя сообщение по-прежнему будет одно. Для контракта оставлен POOL_MAX=10. Улучшение измерено как настройка под этот профиль, не как новая константа стенда.

Серия D, run_track1_db.py. API больше не режу: 1.0 CPU на реплику, concurrency 16, пул 10.

Точка Средний RPS CPU Postgres, %
2 API, Postgres 0.35 62.5 22–25
4 API, Postgres 0.35 48.8 35–38
2 API, Postgres 1.50 59.3 26–32

На двух репликах лимит 0.35 не выбран, и подъём до 1.50 RPS не увеличил (62.5 и 59.3 — один разброс). На четырёх репликах Postgres встал в свой потолок около 35–38%, а успешный RPS упал. Здесь saturation point — CPU единственного Postgres: дополнительные API его добивают и сами становятся лишними. Отдельный прогон «4 API и Postgres 1.50» я не делала, поэтому не пишу, что снятие лимита базы вернуло бы RPS. Это следующая проверка, не результат.

Графики средних: evidence/track1_replicas.svg, evidence/track1_postgres.svg, evidence/track1_pool.svg, evidence/track1_db.svg. Сырые повторы: evidence/track1_runs.csv, evidence/track1_runs.json, evidence/track1_db.json.

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
scripts/restart.sh старый токен и сообщение на месте, volume цел, базы реально перезапущены persistence PASS; StartedAt обновлён у postgres, redis и api, lb остался прежним данные целы, повтор миграции ничего не дописал
scripts/stop-one.sh, официальный тест, дважды через ≤10 с снова можно писать, остановленной реплики в последних ответах нет, дублей нет 1.99 с и 1.371 с, по одной ошибке, PASS, контейнер Exited (143) подтверждённые сообщения на месте
Остановка каждой реплики под записью короткая ошибка, потом RPS с оставшейся 1 ошибка из 499 и 1 из 624 обе реплики после docker start снова видны
Поочерёдный docker restart под записью сервис не встаёт целиком 1 ошибка из 1190, 42.5 RPS, оба контейнера сменили старт дубли не считала: у нагрузки уникальные ключи

Ограничения и следующие шаги

Выдерживается: смерть одного контейнера API, рестарт API вместе с Postgres и Redis при живых volume, общая сессия, конкурентный одинаковый ключ, поочерёдная замена реплик. Не выдерживается: смерть хоста, смерть HAProxy, смерть Postgres или Redis. Один балансировщик и одна база — SPOF. Несколько API-процессов этого не лечат.

Подтверждено измерением: при фиксированном 1.0 CPU на все API число реплик 1/2/4 не поднимает RPS выше одиночного процесса, потому что этот процесс уже занимает ядро, а Postgres свободен. Когда API получают по целому ядру, четыре реплики упирают Postgres в лимит 0.35 CPU и RPS падает. На concurrency 16 уменьшение пула с 10 до 2 подняло RPS с 19.0 до 42.4.

Не подтверждено: что в слабом профиле (две реплики по 0.50 CPU, concurrency 8) Postgres или его лимит вообще участвуют. Серия 0.30/0.60/1.20 лежит в шуме. Не подтверждено и то, что пул 2 лучше для пачки одинаковых ключей: там он как раз тесный.

Учебные упрощения: Redis без пароля и только во внутренней сети; X-Instance-Id равен id контейнера; HAProxy может повторить POST при обрыве; миграция аддитивная, две версии API одновременно я не гоняла; closed-loop занижает хвост и не является пиковой мощностью.