29 KiB
Отчёт — лабораторная 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, без выхода наружу. 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 |
Все прогоны 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 вне транзакции.
Ограничения и следующие шаги
- Выдерживается: плановая остановка, падение или зависание одной 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 нет.