16 KiB
Отчёт — лабораторная 3
- Автор / группа: Авзалов Артур Марсович, БПИ2301
- Целевая оценка: 4; трек 5 не заявлен
- Статус: локальная реализация проверена на двух Windows-компьютерах с Docker Desktop 06.11.2026; публичный API, persistence, идемпотентность, остановка обеих реплик и поочерёдное пересоздание под нагрузкой проверены.
- Инструменты: Python 3.12, FastAPI/Pydantic, PostgreSQL 16, psycopg3 pool, Redis 7.4 с AOF, HAProxy 3.1, Docker Compose.
- Помощь ИИ: ChatGPT использовался для генерации кода, SQL-миграций, конфигурации инфраструктуры, тестов и пояснений. Результаты ниже получены на локальном стенде и зафиксированы по фактическому выводу команд.
Запуск из чистого clone
Нужны Docker Desktop (Compose v2), Python 3.9+ и make (или запуск тестов напрямую). PowerShell:
Copy-Item .env.example .env
# В .env заменить POSTGRES_PASSWORD на свой локальный случайный ASCII-пароль без URI-спецсимволов.
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
docker compose --env-file .env ps
make check PYTHON=python
make test PYTHON=python
python tests/idempotency_parallel.py
Все API-запросы идут только через http://localhost:8080 (HAProxy). PostgreSQL, Redis и API-реплики не публикуют портов на хост. Не коммитить .env и результаты с секретами. Безопасная остановка: docker compose --env-file .env down; без -v. Удаление учебных данных только намеренно: down -v.
Запуск миграций: одноразовый сервис migrate выполняется до старта API; версионные скрипты db/migrations/001_initial.sql и 002_idempotency.sql. Отдельная повторная проверка: docker compose --env-file .env run --rm migrate.
Проба сохранности на Windows:
python tests/resilience.py --mode persistence --action-script scripts/restart.cmd
На Linux: chmod +x scripts/*.sh, затем make test-persistence ACTION_SCRIPT=scripts/restart.sh.
Архитектура
Client localhost:8080 -> HAProxy roundrobin + readiness check (1 s interval, fall=2)
| |
api1 api2
\ /
PostgreSQL (users, chats, messages, idempotency receipts)
Redis AOF (session:<SHA256(bearer)> => user UUID, EX TTL)
Между API-репликами нет общих файлов и локального авторизационного состояния. API_INSTANCE_ID назначается для каждой реплики, отражается в X-Instance-Id, а X-Request-Id генерируется для каждого запроса. Basic используется только на login; пользователь и членство проверяются через Bearer + Redis + PostgreSQL. Argon2id применяется для паролей.
Тексты сообщений, названия чатов и display names — UTF-8 в PostgreSQL bytea, чтобы API поддерживал U+0000, запрещённый в PostgreSQL text/varchar. Транзакция защищает создание чата и участников. Пагинация истории — keyset по (created_at, id), индекс (chat_id, created_at, id).
Идемпотентность POST сообщений
Ключ (actor_id, chat_id, method, Idempotency-Key) уникален в PostgreSQL. Body fingerprint — SHA-256 канонического JSON с полем text; lab3 ещё не содержит вложений. В транзакции после проверки доступа вызывается pg_advisory_xact_lock(hashtextextended(scope, 0)), затем либо читается результат предыдущего сообщения, либо атомарно вставляются сообщение и receipt. Повтор возвращает тот же 201 Message, другое тело с тем же ключом — 409. Блокировка работает между процессами и освобождается с завершением транзакции.
Результаты сохраняются бессрочно: требование не менее 24 часов выполняется, но БД будет расти; политику очистки следует добавить при длительной эксплуатации. Внешний отказ после COMMIT безопасен: повтор возвращает исходное сообщение. Нет автоматических повторов POST на уровне HAProxy.
Отказы и ограничения
Остановка одной API-реплики переносится на другую. HAProxy проверяет GET /health/ready с интервалом 1 с и fall=2; в двух прогонах с остановкой api1 восстановление записи заняло 6.281 и 8.282 с. При повторной автоматической проверке на втором компьютере восстановление заняло 8.328 с; имя остановленной реплики в сохранённом выводе не указано. Все три значения меньше 10 с. При ручной остановке api2 на первом компьютере LB вернул 200 от api1; на втором компьютере первый запрос к LB получил переходный 503, после чего публичный smoke успешно прошёл через оставшуюся реплику. Мгновенное переключение или точное время восстановления для api2 не заявляются. Graceful shutdown Uvicorn ограничен 8 с, Docker stop grace period 12 с. HAProxy использует Docker DNS резолвер для смены адреса пересозданной реплики. На каждом API контейнере CPU limit 0.75 и RAM limit 384 MiB, LB 0.5/128 MiB, PG 1.0/512 MiB, Redis 0.5/256 MiB.
Остановка PostgreSQL или Redis делает обязательные операции недоступными (503); /health/live не зависит от внешних сервисов, /health/ready проверяет оба. Хранилища не реплицированы. Потеря узла Docker, LB, диска или volumes не покрыта. HTTP Basic/Bearer в локальном стенде допускается только на loopback; для удалённого доступа требуется TLS.
Миграции вынесены в отдельный one-shot сервис и координируются PG advisory lock. Текущие миграции предназначены для чистого стенда Lab3; автоматический импорт уже существующей чужой схемы/volume Lab2 не заявлен. Rolling update рассчитан на совместимость неизменной текущей схемы с обеими API-репликами; миграции с несовместимыми ALTER TABLE потребуют расширения стратегии.
Фактические проверки (Windows PowerShell + Docker Desktop, 06.11.2026)
| Критерий | Команда / способ | Наблюдение |
|---|---|---|
| Подъём стенда | docker compose --env-file .env up -d --build, docker compose --env-file .env ps |
PASS: api1, api2, lb, postgres, redis — healthy; наружу опубликован только LB на 127.0.0.1:8080 |
| Проверка структуры | make check PYTHON=python |
PASS: offline skeleton structure, local refs and Python syntax; application NOT tested. |
| Публичный API | make test PYTHON=python |
PASS: lab3 public API scenario; также PASS после rolling update и при остановленной api2 на обоих компьютерах |
| Конкурентная идемпотентность | python tests/idempotency_parallel.py |
PASS: две реплики, одно сообщение, повтор 201, изменённое тело 409 |
| Persistence | python tests/resilience.py --mode persistence --action-script scripts/restart.cmd |
PASS: подтверждённые данные и прежняя сессия сохранились после restart; тест требует дополнительно показать scope hook |
| Автоматический failover | python tests/resilience.py --mode failover --action-script scripts/stop-one.cmd |
PASS трижды (6.281, 8.282 и 8.328 с); на первом компьютере после тестов в docker compose ps отсутствовала api1, api2 оставалась healthy. На втором выбор остановленной реплики в логе не зафиксирован |
| Отказ api2 | docker compose --env-file .env stop --timeout 1 api2 + curl.exe -i http://localhost:8080/health/ready + make test PYTHON=python |
PASS для функциональной доступности: на первом ПК 200 OK, X-Instance-Id: api1 и smoke PASS. На втором ПК первый curl вернул от HAProxy 503 No server is available, но следующий smoke PASS при остановленной api2. Срок восстановления именно для api2 не замерен |
| Повторное применение миграций на втором ПК | docker compose --env-file .env run --rm migrate |
PASS: Migrations up to date |
| Возврат обеих реплик | docker compose --env-file .env up -d --no-deps --wait api1 api2 |
PASS: обе реплики healthy |
| Rolling update под нагрузкой | Фоновый 90-секундный tests/load.py + поочерёдное --force-recreate --wait api1, затем api2 |
PASS: нагрузка была Running до замены; обе реплики вернулись в healthy; первый ПК — 171 успешная запись, 0 ошибок; второй ПК — 168 успешных записей, 0 ошибок; оба раза job Completed |
Linux persistence отдельно не прогонялся. Локальный дополнительный unit-тест tests/own_unit.py не заявляется как выполненный; публичный smoke, check и конкурентная идемпотентность проверены.
Измерения нагрузки
| Сценарий | Успешные запросы | Ошибки | RPS | p50 | p95 | p99 |
|---|---|---|---|---|---|---|
| Базовая нагрузка, concurrency=4, 30 с | 60 | 0 | 1.863 | 2063 мс | 2344 мс | 2703 мс |
| 90 с без подтверждённого перекрытия с update | 176 | 0 | 1.914 | 2063 мс | 2203 мс | 2469 мс |
| Rolling update под нагрузкой, первый ПК, concurrency=4, 90 с | 171 | 0 | 1.838 | 2063 мс | 2828 мс | 4047 мс |
| Базовая нагрузка, второй ПК, concurrency=4, 30 с | 60 | 0 | 1.882 | 2093 мс | 2125 мс | 2329 мс |
| Rolling update, второй ПК, concurrency=4, 90 с | 168 | 0 | 1.861 | 2094 мс | 2156 мс | 6172 мс |
Rolling update запускался в PowerShell Start-Job; после 15 секунд тест был Running, затем по очереди выполнялось пересоздание реплик. На первом ПК api1 восстановилась за 7.6 с, api2 за 6.9 с; на втором — за 7.1 с и 7.5 с соответственно. Wait-Job оба раза вернул JSON с нулём ошибок и состоянием Completed. Эти результаты подтверждают замену контейнеров под нагрузкой, но не являются тестом обновления на новую версию кода или несовместимой схемы БД.
Фактические значения failover в автоматических прогонах:
| Остановленная реплика | Успешные записи | Неуспешные попытки | Первое восстановление записи |
|---|---|---|---|
| api1, прогон 1 | 8 | 0 | 6.281 с |
| api1, прогон 2 | 6 | 1 | 8.282 с |
| выбранная тестом реплика, второй ПК | 6 | 1 | 8.328 с |
| api2, ручной сценарий (первый ПК) | Smoke: PASS | Не измерено | Проверка readiness дала HTTP 200, время failover не измерялось |
| api2, ручной сценарий (второй ПК) | Smoke: PASS | Первый curl: 503 | После 503 smoke прошёл; время восстановления не измерялось |
На первом ПК остановку именно api2 подтвердил docker compose ps, а обработчик ответа имел X-Instance-Id: api1. На втором ПК остановка api2 подтверждена выводом docker compose stop, первый readiness-запрос вернул 503 от HAProxy, последующий smoke прошёл. Ручной сценарий не даёт количественной оценки RPS или задержки восстановления для api2.
tests/load.py использует closed-loop нагрузку без автоматических повторов: измерение включает клиентские задержки и может страдать coordinated omission. p50/p95/p99 относятся только к успешным HTTP-ответам. На обоих компьютерах медиана осталась около 2.1 с; это делает нехватку RAM первого ПК менее убедительной единственной причиной. Задержку не профилировали, узкое место не установлено.
Ограничения результатов
- PostgreSQL, Redis и балансировщик представлены одним экземпляром; отказ всего хоста и потеря volumes не покрываются.
- При остановке api2 проверены работоспособность и публичный smoke, но отдельное инструментальное время восстановления и RPS этой реплики не фиксировались. На втором ПК первый readiness после остановки вернул 503, поэтому непрерывную безошибочную доступность в этом сценарии не заявляем.
- Приведены результаты двух Windows-хостов при конкретном closed-loop профиле нагрузки; Linux-испытание не проводилось.