30 KiB
Отчёт — лабораторная 3
- Автор, группа: Бабиченко Максим, БВТ2303
- Целевая оценка; выбранный трек 5, если нужен: 4, трек 5 не выбран
- Commit/PR: <<ссылка на MR в Gitea после публикации>>
- Использованные источники, библиотеки и помощь ИИ: всё из lab2 (FastAPI, Uvicorn, Pydantic, psycopg 3 и psycopg-pool, argon2-cffi, redis-py; точные версии в requirements.txt); образы python:3.11.13-slim, postgres:17.11-alpine, redis:7.4.11-alpine и новый haproxy:3.2.25-alpine; документация HAProxy 3.2 (resolvers, server-template, http-check, retries, observe), документация Docker Compose (deploy.replicas и resources, depends_on с condition, healthcheck), документация PostgreSQL (INSERT ... ON CONFLICT, уникальные ограничения).
Запуск из чистого clone
Проверял на Windows 11, все команды в PowerShell. Версии Docker, Compose и ресурсы машины — в evidence/stack.txt. Python нужен только для тестов (стандартная библиотека). Перед запуском остановить стенд lab2 (docker compose down в его папке), иначе занят порт 8080.
git clone https://gitea.privcloud.tech/Kalibr/mtusi2026lab3.git
cd mtusi2026lab3
git checkout solution/bvt2303-babichenko
$env:PYTHONUTF8 = "1" # contracts/openapi.json в UTF-8, без этого тесты на Windows падают
Copy-Item .env.example .env
python scripts/init_secrets.py # случайные пароли в secrets/ (папка в .gitignore)
docker compose up -d --build --wait # migrate -> 2 реплики api -> lb; ждём healthy
docker compose ps
python student-tests/collect_evidence.py # все проверки по очереди (~10 мин), вывод в evidence/, таблицы в этот отчёт
Отдельные проверки (make на моём Windows нет, ниже то же самое без make):
| Команда из README | То же в PowerShell |
|---|---|
make check |
python scripts/check_contract.py |
make test |
python tests/smoke.py --base-url http://127.0.0.1:8080 |
make test-persistence ACTION_SCRIPT=... |
python tests/resilience.py --mode persistence --action-script scripts/restart.cmd --base-url http://127.0.0.1:8080 |
make test-failover ACTION_SCRIPT=... |
python tests/resilience.py --mode failover --action-script scripts/stop-one.cmd --base-url http://127.0.0.1:8080 |
После test-failover одна реплика остаётся остановленной (так требует тест). Вернуть её: docker start <ID из docker compose ps -a> или docker compose up -d --wait. На Linux/macOS вместо .cmd — scripts/restart.sh и scripts/stop-one.sh: тест запускает hook без shell, а Python на Windows не умеет запускать .sh (WinError 193).
Миграции применяет одноразовый сервис migrate при docker compose up, отдельной команды нет. Остановка без потери данных: docker compose down (volumes pgdata, redisdata остаются). Намеренное удаление учебных данных: docker compose down -v, затем удалить папку secrets и снова python scripts/init_secrets.py.
Архитектура и решения
Клиент --HTTP--> lb: HAProxy 3.2, 127.0.0.1:8080 (единственный опубликованный порт)
| round robin, без привязки клиента к реплике
+--> api-1 --+
+--> api-2 --+--> postgres: пользователи, чаты, сообщения, ключи идемпотентности (volume pgdata)
+--> redis: сессии (AOF, volume redisdata)
migrate (одноразовый): применяет migrations/*.sql до старта api и завершается
сети: edge (lb <-> api) и data (api, migrate <-> postgres, redis; internal, без выхода наружу)
| Роль | Сервис Compose | Версия | Health / готовность | Volume | Сеть / порт | Credentials |
|---|---|---|---|---|---|---|
| Балансировщик | lb |
haproxy:3.2.25-alpine | /lb-health на 8404 (есть куда отправить запрос) |
нет | edge; 127.0.0.1:8080, статистика 127.0.0.1:8404/stats |
не нужны |
| API ×2 | api (из Dockerfile, deploy.replicas: 2) |
python:3.11.13-slim | /health/ready (Docker раз в 5 с, HAProxy раз в 1 с) |
нет | edge + data; порт наружу не публикуется | /run/secrets/database_url, /run/secrets/cache_url |
| Миграции | migrate (тот же Dockerfile) |
python:3.11.13-slim | завершается с кодом 0 | нет | data | только /run/secrets/database_url |
| База данных | postgres |
postgres:17.11-alpine | pg_isready |
pgdata |
data, 5432 | POSTGRES_PASSWORD_FILE |
| Сессии | redis |
redis:7.4.11-alpine | redis-cli ping с паролем |
redisdata (AOF) |
data, 6379 | include /run/secrets/redis_auth |
Что перенесено из lab2: весь код API (main.py, db.py, auth.py, settings.py, errors.py), миграции 001–002, свои тесты, Dockerfile, compose.yaml, infra/redis.conf, scripts/init_secrets.py, restart-скрипты. Сессии и данные уже были в Redis и PostgreSQL, в памяти API ничего не хранится, поэтому реплики взаимозаменяемы.
Что изменено в lab3:
compose.yaml: две репликиapiбезportsиcontainer_name, балансировщикlb, сервисmigrate, лимиты CPU/RAM у всех контейнеров, две сети.infra/haproxy.cfg: список реплик HAProxy берёт из DNS Docker (имяapi-> IP всех реплик, перечитывается раз в 2 с), поэтому подхватывает остановленные и новые реплики без перезапуска.X-Instance-Idв каждом ответе (middleware вmain.py) — hostname контейнера, то есть его короткий ID. По заголовку сразу видно контейнер вdocker ps, аscripts/stop_one.pyостанавливает именно его.- Обязательный
Idempotency-Keyу POST сообщения (main.py,db.add_message,migrations/003_idempotency.sql). - Миграции больше не применяет API: это делает
migrate.py(сервисmigrate), а реплика при старте только проверяет, что все миграции её образа применены (db.wait_for_schema). - Остановка по SIGTERM в два шага (класс
Serverвmain.py).
Идемпотентность. Ключ и SHA-256 тела запроса хранятся прямо в строке сообщения. Уникальное ограничение (chat_id, sender_id, idempotency_key) — это область ключа из контракта: пользователь + чат (метод и путь у ключа всегда POST .../messages). Запись — один INSERT ... ON CONFLICT DO NOTHING, поэтому сообщение и «запомненный результат» сохраняются атомарно. Если ключ уже есть: то же тело (сравнивается хеш, порядок полей и пробелы в JSON не важны) -> тот же 201 и то же сообщение, другое тело -> 409. Если два запроса с одним ключом пришли одновременно на разные реплики, PostgreSQL заставляет второй INSERT ждать, пока завершится первая транзакция, после чего второй видит готовую строку. Повтор снова проверяет сессию (middleware) и членство в чате (404). Ответы 400/404/503 не сохраняются: после ошибки тот же ключ можно использовать снова. Ключ хранится столько же, сколько сообщение (удаления в API нет), то есть не меньше 24 ч из контракта.
Балансировщик и отказ реплики:
- Проверка готовности: HAProxy раз в 1 с запрашивает
/health/readyу каждой реплики (при смене состояния раз в 0,5 с,timeout check 1s). 2 неудачи подряд -> реплика выведена, 2 удачи -> возвращена. Худший случай для зависшей реплики: около 1 + 1 + 0,5 + 1 = 3,5 с. Кроме того,observe layer4выводит реплику сразу после первой ошибки соединения у живого запроса, а DNS Docker убирает остановленный контейнер (HAProxy замечает это за 2–4 с). - Повторы в HAProxy только при ошибке соединения (запрос ещё не отправлен) и на другую реплику (
retries 2,option redispatch). Уже отправленный POST HAProxy сам не повторяет: это делает клиент с тем жеIdempotency-Key. - Аварийный режим: если готовых реплик нет совсем (например, упал Redis или PostgreSQL), запросы всё равно идут в API через резервные записи
fallbackв HAProxy. Клиент получает ответ самого API (503 в формате контракта, сX-Request-Id),/health/liveотвечает 200, регистрация без Redis работает. Пока готова хоть одна реплика, резервные записи не используются. - SIGTERM:
/health/readyсразу отвечает 503, но запросы ещё обслуживаются 3 с (SHUTDOWN_DRAIN_SECONDS). За это время HAProxy выводит реплику, затем uvicorn закрывает приём и доделывает начатые запросы (не дольшеSHUTDOWN_TIMEOUT_SECONDS=10). Docker ждётstop_grace_period: 15s. Самый долгий запрос — 8 с (пул 3 с +statement_timeout5 с), поэтому у HAProxytimeout server 15s.
Миграции: сервис migrate применяет migrations/*.sql один раз (schema_migrations, pg_advisory_lock на случай двух запусков). api стартует только после его успешного завершения (depends_on: condition: service_completed_successfully). Реплика с кодом новее схемы не стартует. Миграция 003 только добавляет столбцы и ограничение, у старых сообщений ключ NULL, поэтому API из lab2 продолжает работать на новой схеме (проверено: старый API пишет без ключа и читает новые сообщения).
Соответствие .env.example:
| Переменная | Что делает в этом решении |
|---|---|
| APP_HOST, APP_PORT, APP_ENV | где слушает API (0.0.0.0:8080 внутри контейнера), APP_ENV пишется в лог |
| SESSION_TTL_SECONDS | срок жизни сессии, 3600 с |
| DATABASE_URL_FILE, CACHE_URL_FILE | пути к секретам с адресами PostgreSQL и Redis |
| SESSION_STORE=redis | сессии в Redis (как в lab2) |
| API_REPLICAS | число реплик api (deploy.replicas), по умолчанию 2 |
| IDEMPOTENCY_TTL_SECONDS | не используется: ключ хранится вместе с сообщением бессрочно (не меньше 24 ч) |
| SHUTDOWN_DRAIN_SECONDS, SHUTDOWN_TIMEOUT_SECONDS | остановка: 3 с на выход из балансировки, до 10 с на начатые запросы |
| DB_, REDIS_ | размеры пулов и таймауты (как в lab2) |
Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|---|---|---|---|
| Публичный smoke | python tests/smoke.py --base-url http://127.0.0.1:8080 |
PASS через балансировщик | evidence/smoke.txt |
| Skeleton и контракт не изменены | python scripts/check_contract.py |
PASS | evidence/check.txt |
| 3: весь стенд в compose.yaml, одна команда запуска | docker compose up -d --build --wait |
migrate Exited (0), api ×2 и lb healthy | evidence/stack.txt |
| 3: ≥2 API-реплики, одна точка входа, общая БД и общее хранилище сессий | python student-tests/check_stack.py |
2 реплики api без портов; наружу только lb на 127.0.0.1; один postgres, один redis | evidence/stack.txt |
| 3: запросы одного пользователя обслуживают разные реплики без повторного входа | test_balancing.py (test_requests_spread_over_replicas) |
20 запросов с одним токеном, ответы от 2 разных X-Instance-Id | evidence/balancing.txt |
| 3: состояние общее: запись на одной реплике сразу видна на другой, logout действует везде | test_balancing.py |
записано одной репликой, прочитано другой; после logout обе отвечают 401 | evidence/balancing.txt |
| 3: X-Instance-Id в каждом ответе, это реальный контейнер | test_balancing.py (test_instance_header_everywhere) |
200/201/400/401/404/409 с X-Instance-Id = ID контейнера api | evidence/balancing.txt |
| 3: доступ через LB — основной маршрут, без sticky session | все тесты идут на 127.0.0.1:8080; infra/haproxy.cfg (balance roundrobin, без cookie) |
ответы чередуются между репликами | evidence/balancing.txt, evidence/stack.txt |
| 3: остановка любой реплики: не позднее 10 с новые чтения/записи, подтверждённое на месте, ошибки измерены | python student-tests/run_failover.py (публичный failover для каждой реплики, scripts/stop-one.cmd) |
PASS для каждой реплики; видно, какой контейнер остановлен (docker compose ps до/после) |
evidence/failover.txt |
| 3: повтор POST с тем же ключом не создаёт дубль, в том числе одновременный и через другую реплику | test_idempotency.py, test_balancing.py (test_idempotent_retry_on_other_replica) |
повтор -> тот же 201 и то же сообщение; 20 одновременных запросов через 2 реплики -> 1 сообщение | evidence/idempotency.txt, evidence/balancing.txt |
| 3: неподтверждённую запись можно безопасно повторить | test_idempotency.py (test_lost_response_then_retry); публичный failover повторяет POST с тем же ключом |
ответ потерян -> повтор 201, сообщение одно; в failover дублей нет | evidence/idempotency.txt, evidence/failover.txt |
| 3: миграции отдельно и согласованно, не гонкой реплик | сервис migrate; test_db.py |
миграции применяет только migrate (Exited 0), в логах api — только проверка схемы; повторный запуск migrate ничего не применяет | evidence/db.txt |
| 3: make test, persistence и failover проходят | smoke, run_persistence.py, run_failover.py |
все PASS; в failover до отказа наблюдались 2 реплики | evidence/smoke.txt, evidence/persistence.txt, evidence/failover.txt |
| 3: hook перезапуска реально перезапускает процессы | python student-tests/run_persistence.py |
у postgres, redis, обеих api и lb тот же ID контейнера и новое время старта; данные и прежний токен на месте | evidence/persistence.txt |
| 3: Swarm | — | выбран Compose, пункт про сборку образа для узлов Swarm не нужен | — |
| 3: возможности lab1/lab2 сохранены | test_api.py, test_race.py, test_db.py, test_expiry.py, test_failures.py, redis_info.py, explain.py через балансировщик |
все PASS | evidence/student-tests.txt, race.txt, db.txt, expiry.txt, failures.txt, redis.txt, explain-history.txt |
| 4: health/readiness, таймауты и SIGTERM согласованы; LB исключает недоступную реплику; период проверок и время обнаружения | infra/haproxy.cfg, класс Server в main.py; failover_metrics.py |
проверка раз в 1 с (0,5 с при смене), 2 неудачи; худший случай ~3,5 с; измеренное время вывода — в таблице ниже | evidence/failover-metrics.txt |
| 4: остановлена каждая реплика по очереди с восстановлением предыдущей; RPS, ошибки, время восстановления | python student-tests/failover_metrics.py (docker stop и docker kill, нагрузка 4+1 потока) |
таблица ниже; потерь и дублей 0 | evidence/failover-metrics.txt, evidence/failover-metrics.json |
| 4: общая идемпотентность проверена параллельными запросами с одним ключом | test_idempotency.py (test_same_key_parallel_through_replicas, test_same_key_different_bodies_parallel) |
20 одновременных запросов: 1 сообщение, 20 одинаковых ответов; с разными телами: одно сохранено, другие 409 | evidence/idempotency.txt |
| 4: CPU/RAM-лимиты у контейнеров | check_stack.py |
лимиты у всех: api 1 CPU / 512 MiB, postgres 1 CPU / 512 MiB, redis и lb 0,5 CPU / 128 MiB | evidence/stack.txt |
| 4: API не публикует порты в обход LB | check_stack.py |
у api нет опубликованных портов, у postgres и redis тоже; lb только на 127.0.0.1 | evidence/stack.txt |
| 4: секреты и хранилища общие только где нужно | check_stack.py |
lb без секретов, migrate только database_url; postgres и redis только во внутренней сети data | evidence/stack.txt |
| 4: нет container_name | check_stack.py |
ни у одного сервиса нет container_name | evidence/stack.txt |
| 4: rolling update под нагрузкой | python student-tests/rolling_update.py |
реплики заменены новой версией по одной, ошибки и RPS — ниже | evidence/rolling-update.txt, evidence/rolling-update.json |
| 4: миграции однократные и совместимые с работающей версией | сервис migrate, migrations/003_idempotency.sql; test_db.py |
003 только добавляет, API из lab2 работает на новой схеме; ограничение см. ниже | evidence/db.txt |
| Выбранный трек 5 | — | не выбран | — |
Эксперименты и отказы
Гипотезы:
- Плановая остановка реплики (
docker stop) проходит без ошибок у клиента: по SIGTERM реплика сначала отвечает 503 на readiness и уходит из балансировки, а приём закрывает только через 3 с. - При аварии (
docker kill) ошибки получают только запросы, начатые на убитой реплике, а HAProxy выводит её быстрее, чем за 3,5 с. Клиент повторяет с тем же ключом, и дублей не появляется. - Rolling update (новая реплика -> готова -> старая уходит) проходит без ошибок при постоянной нагрузке.
Методика: стенд из compose.yaml с лимитами из таблицы выше; нагрузка — student-tests/loadgen.py: 4 потока пишут сообщения без пауз (closed loop), 1 поток читает историю, timeout клиента 2 с, неподтверждённый POST повторяется с тем же ключом. Отказ — через 3 с нагрузки, наблюдение 10 с. Состояние HAProxy читается со страницы статистики раз в 0,1 с. После каждого прогона реплика запускается (docker start) и ждём, пока HAProxy вернёт её. Это closed-loop генератор на той же машине, поэтому RPS ограничен и клиентом, и лимитами CPU; это не предельная пропускная способность.
Машина: Windows 10, AMD64 Family 26 Model 68 Stepping 0, AuthenticAMD; Docker VM: 16 CPU, 15.2 GiB RAM; клиент Python 3.11.1; дата прогона 2026-10-14, commit 0ab3a34 + uncommitted changes. Лимиты контейнеров: api 1 CPU / 512 MiB каждая, postgres 1 CPU / 512 MiB, redis и lb по 0,5 CPU / 128 MiB.
Публичный тест отказа (make test-failover, 15 с записи во время остановки реплики):
| Прогон | Остановлена реплика | Реплик до отказа | Успешных записей | Неудачных попыток (повторены с тем же ключом) | Первая запись после hook, с |
|---|---|---|---|---|---|
| 1 | 58542a53644c | 2 | 128 | 0 | 4.203 |
| 2 | 9737b915ff2f | 2 | 132 | 0 | 4.281 |
Остановка каждой реплики под нагрузкой (student-tests/failover_metrics.py: 4 потока записи без пауз + 1 поток чтения, timeout клиента 2 с, 3 с до и 10 с после отказа):
| Реплика | Как остановлена | Команда, с | HAProxy вывел из балансировки через, с | Ошибок (коды) | Ошибки прекратились через, с | Записей/с до | Записей/с после | p95 после, мс | Вернулась в балансировку после docker start, с |
|---|---|---|---|---|---|---|---|---|---|
| 58542a53644c | docker stop (SIGTERM) | 4.12 | 1.11 | 0 (-) | 0.0 | 304.7 | 202.2 | 47.0 | 3.25 |
| 58542a53644c | docker kill (SIGKILL) | 0.81 | 0.11 | 2 (502: 2) | 0.05 | 328.7 | 228.2 | 32.0 | 1.55 |
| 9737b915ff2f | docker stop (SIGTERM) | 4.12 | 1.5 | 0 (-) | 0.0 | 288.7 | 232.7 | 32.0 | 4.09 |
| 9737b915ff2f | docker kill (SIGKILL) | 0.83 | 0.11 | 2 (502: 2) | 0.05 | 266.7 | 219.9 | 32.0 | 4.14 |
Во всех прогонах: потерянных подтверждённых сообщений 0, дублей 0, остановленная реплика после остановки не ответила ни разу.
Rolling update (student-tests/rolling_update.py): версия rolling-20261014-201405 -> rolling-20261014-202804, 2 реплики заменены по одной за 13.48 с под той же нагрузкой. Записей/с до: 284.7, во время замены: 346.3; ошибок: 0 (-); p95 31.0 мс, максимум 78.0 мс; подтверждено 6527 сообщений, потерь и дублей нет.
Публичный генератор нагрузки (tests/load.py, closed loop, concurrency 4, 30 с, 2 реплики): 308.848 успешных POST/с, ошибок 0 (доля 0.0), задержка успешных p50 15.0 мс, p95 32.0 мс, p99 46.0 мс.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|---|---|---|---|
docker stop реплики (SIGTERM) под нагрузкой |
ошибок нет: реплика сначала уходит из балансировки (readiness 503), потом закрывает приём | ошибок: 0, 0 (по репликам); HAProxy вывел реплику через 1.11, 1.5 с | ошибки прекратились через 0.0 с; потерь 0, дублей 0; реплика вернулась через 4.09 с после docker start |
docker kill реплики (SIGKILL, авария) под нагрузкой |
единицы 502 на запросы, начатые на убитой реплике; клиент повторяет их с тем же ключом | ошибок: 2, 2 (по репликам); HAProxy вывел реплику через 0.11, 0.11 с | ошибки прекратились через 0.05 с; потерь 0, дублей 0; реплика вернулась через 4.14 с после docker start |
публичный make test-failover для каждой реплики |
запись продолжается не позже 10 с, подтверждённые сообщения на месте, дублей нет | PASS 2 раз(а), неудачных попыток: 0, 0 | первая запись после hook через 4.203, 4.281 с (hook ждёт остановки ~4 с); потерь нет |
| rolling update под нагрузкой | ошибок нет, реплик всё время не меньше 2 | ошибок: 0, замена заняла 13.48 с | потерь 0, дублей 0 |
перезапуск всего стенда (restart hook: postgres, redis, api, lb) |
данные и прежний токен живы | PASS, те же контейнеры с новым временем старта | 8.5 с до готовности; потерь нет |
Также проверено (как в lab2, теперь через балансировщик, evidence/failures.txt): остановка Redis -> /health/ready 503, запросы с токеном 503, без токена 401, регистрация 201; аварийная остановка Redis -> сессия на месте (AOF); остановка PostgreSQL -> 503 без подробностей, анонимов не пускаем; после запуска прежний токен и сообщения на месте.
Ограничения и следующие шаги
- Выдерживается отказ одной API-реплики (процесса или контейнера). Не выдерживается отказ единственных
lb,postgres,redisи всей машины: стенд на одном узле, это SPOF. Реплика БД и Redis, второй балансировщик — не в этой работе. - HAProxy на время проверок может послать запрос на реплику, которая только что умерла. Такой запрос получает 502 (если он уже был отправлен) или уходит на другую реплику (если упало соединение). 502 на POST сообщения клиент безопасно повторяет с тем же ключом; HAProxy сам POST не повторяет.
- Создание чата и регистрация не идемпотентны по контракту: их повтор после timeout может создать второй объект.
- Миграция 003 добавляет уникальное ограничение: на большой таблице построение индекса заблокировало бы запись в
messages. Для большой базы нуженCREATE UNIQUE INDEX CONCURRENTLYотдельным шагом; на учебной базе это доли секунды. - Rolling update сделан скриптом (Compose не умеет заменять реплики по одной сам). В Swarm это было бы
update_config: order: start-first. X-Instance-Idраскрывает ID контейнера; в lab7 его нужно заменить на случайный alias.- Ключи идемпотентности хранятся вместе с сообщениями бессрочно (место в индексе растёт вместе с числом сообщений).