Files
mtusi2026lab3/REPORT.md
T

29 KiB
Raw Blame History

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

  • Автор, группа: Тимаева М.П., БПИ2302
  • Целевая оценка; выбранный трек 5, если нужен: TODO
  • Commit/PR: TODO после публикации
  • Использованные источники, библиотеки и помощь ИИ: TODO

Запуск из чистого 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

Остановка без потери данных: 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) 1.0 / 256M (0.25 / 128M)
Миграции migrate тот же образ one-shot, service_completed_successfully data тот же секрет 0.5 / 128M
БД postgres postgres:16.10-alpine@… pg_isready каждые 2 с data pgdata, POSTGRES_PASSWORD_FILE 1.0 / 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, без выхода наружу. Volume pgdata смонтирован только в postgres. container_name нигде нет, поэтому --scale api=N работает (evidence/limits.txt).
  • Секреты: пароль БД лежит только в незакоммиченном .env и попадает в контейнеры как Compose secret postgres_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 DNS 127.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

Все прогоны 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):

  1. Собрать messenger-lab3-app:$APP_VERSION.
  2. Один раз выполнить docker compose run --rm migrate.
  3. Для каждой старой реплики запустить 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 вне транзакции.

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

  • Выдерживается: плановая остановка, падение или зависание одной 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 сравнимы только внутри одной серии.
  • Порядок сообщений между репликами зависит от общих часов хоста: created_at назначает приложение.
  • Повтор LB: POST пользователей, чатов и сессий повторяется только при неустановленном соединении. После обрыва уже отправленного запроса клиент должен проверить результат сам: ключа идемпотентности у этих POST нет.