forked from mtusi2026/mtusi2026lab3
14 KiB
14 KiB
Отчёт — лабораторная 3
- Автор, группа: Герейханов Ильяс, БВТ2301
- Целевая оценка: 4
- Commit/PR: ветка
solution/bvt2301-Gereykhanov. PR:ЛР 3 — БВТ2301 — Герейханов — на 4 - Использованные источники, библиотеки и помощь ИИ: Python 3.12, FastAPI, Uvicorn, PostgreSQL 16, Redis 7, Nginx 1.27, asyncpg, argon2-cffi, Pydantic, Pytest, Docker Compose; документация Nginx, RFC 7231, OpenAPI 3.1.0. ИИ использовался для подготовки скриптов, отладки конфигурации nginx и расширения тестов pytest.
Запуск из чистого clone
-
Версии runtime и базовых образов:
- Локальный runtime: Linux, Docker 29.9.1, Docker Compose v5.6.0
- Load Balancer:
nginx:1.27-alpine - API контейнеры:
python:3.12-slim - PostgreSQL:
postgres:16-alpine - Redis:
redis:7-alpine
-
Подготовка окружения и запуск стека:
git checkout solution/bvt2301-Gereykhanov cp .env.example .env # Сборка и запуск всех сервисов make up -
Ожидание готовности и запуск тестов:
# Проверка структуры и синтаксиса make check # Проверка smoke теста make test # Проверка сценария сохранности данных и сессий при рестарте make test-persistence ACTION_SCRIPT=scripts/restart.sh # Проверка отказоустойчивости при отключении одной API-реплики make test-failover ACTION_SCRIPT=scripts/stop-one.sh # Восстановление остановленной реплики после теста docker compose up -d # Запуск собственных тестов .venv/bin/pytest tests_student # Запуск нагрузочного теста python3 tests/load.py --duration 10 --concurrency 4 --output evidence/load.json -
Остановка и очистка:
# Остановка с сохранением данных volumes docker compose down # Остановка с удалением volumes docker compose down -v
Архитектура и решения
- Топология процессов и распределение ролей:
- Клиент отправляет все HTTP-запросы в единую точку входа Nginx Load Balancer на порт
8080. - Nginx осуществляет Round-Robin балансировку между двумя независимыми репликами API.
- Реплики API без портирования наружу хоста, не обходят балансировщик.
- Каждая реплика API обращается к общему PostgreSQL (пользователи, чаты, сообщения, ключи идемпотентности) и общему Redis (хранилище сессий).
- Есть отдельный одноразовый контейнер migration, применяющий
init.sqlперед стартом API-реплик.
- Клиент отправляет все HTTP-запросы в единую точку входа Nginx Load Balancer на порт
- Идентификация реплик (
X-Instance-Id):- Каждая реплика API конфигурируется переменной окружения
INSTANCE_ID(api-1иapi-2). - Middleware и глобальный обработчик ошибок возвращают заголовок
X-Instance-Idв каждом HTTP ответе. - При последовательных запросах идет чередование инстансов
api-1иapi-2.
- Каждая реплика API конфигурируется переменной окружения
- Общие сессии без Sticky Sessions:
- Токены Bearer-сессий хранятся в Redis с TTL (
SESSION_TTL_SECONDS=3600) и сохраняются наredis_dataчерез--appendonly yes. - Вход пользователя через одну реплику дает выполнять запросы через любую другую реплику без повторной аутентификации.
- Токены Bearer-сессий хранятся в Redis с TTL (
- Идемпотентность отправки сообщений:
- Заголовок
Idempotency-Keyобязателен дляPOST /api/v1/chats/{chat_id}/messages. - Область уникальности:
(user_id, chat_id, idempotency_key). - В PostgreSQL создана таблица
idempotency_keysс ограничениемPRIMARY KEY (user_id, chat_id, idempotency_key). - В транзакции создания сообщения сохраняется хэш тела запроса (
SHA-256от нормализованного JSON). - При одновременных запросах с одним ключом в разные реплики ограничение
PRIMARY KEYпредотвращает вставку дубликата; проигравшая транзакция перехватываетUniqueViolationErrorи возвращает результат победителя.
- Заголовок
- Динамический DNS и быстрый Failover в Nginx:
- Nginx настроен с внутренним Docker DNS-резолвером
resolver 127.0.0.11 valid=2s ipv6=off;и зоной разделяемой памятиzone api_backend 64k;:Параметрupstream api_backend { zone api_backend 64k; server api-1:8080 resolve max_fails=1 fail_timeout=2s; server api-2:8080 resolve max_fails=1 fail_timeout=2s; }resolveдинамически переопределяет IP-адреса реплик в runtime при пересоздании контейнеров без перезагрузки Nginx.
- Nginx настроен с внутренним Docker DNS-резолвером
- Ограничения ресурсов и масштабируемость:
- Все сервисы с лимитамт CPU и RAM.
- Для API-реплик не задаётся параметр
container_name, чтобы не мешать масштабированию.
Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|---|---|---|---|
| Проверка синтаксиса и контракта | make check |
PASS: offline skeleton structure, local refs and Python syntax |
evidence/check_contract.log |
| Полная OpenAPI 3.1 валидация | make validate PYTHON=.venv/bin/python |
PASS: full OpenAPI 3.1 and JSON Schema validation |
evidence/validate_openapi.log |
| Публичный smoke-сценарий | make test |
PASS: lab3 public API scenario; infrastructure and grading evidence remain separate. |
evidence/smoke_test.log |
| Чередование реплик (LB) | for i in {1..10}; do curl -sI http://localhost:8080/health/live | grep -i x-instance-id; done |
Попеременные ответы api-1 и api-2 (Round-Robin 50/50) |
evidence/round_robin.log |
| Сохранение данных и сессий при рестарте | make test-persistence ACTION_SCRIPT=scripts/restart.sh |
Стек перезапущен, токен и сообщения сохранены | evidence/persistence_test.log |
| Отказ API-реплики (Failover) | make test-failover ACTION_SCRIPT=scripts/stop-one.sh |
Восстановление записи за 0.447 с, 0 потерь, дубликатов нет | evidence/failover_test.log |
| Собственные расширенные тесты | make test-student |
26 тестов проходят: валидация Idempotency-Key, X-Instance-Id, ACL-инъекции, пагинация курсором |
evidence/student_tests.log |
| Статусы и лимиты контейнеров | docker compose ps |
Все 5 сервисов запущены и healthy, API не светят порты на хост | evidence/docker_services.log |
| Нагрузочный бенчмарк | make load |
337.1 RPS, p50 = 6.7 ms, p95 = 53.1 ms, p99 = 79.4 ms, 0 ошибок | evidence/load.json |
Эксперименты и отказы
- Профиль нагрузки: скрипт
tests/load.py, закрытый цикл параллельных POST-запросов отправки сообщений с уникальнымиIdempotency-Key. - Параметры: длительность 10 секунд, 4 параллельных потока.
- Результаты нагрузки (
evidence/load.json):{ "lab": 3, "workload": "closed-loop POST messages; no automatic retries", "requested_duration_seconds": 10.0, "elapsed_seconds": 10.065, "concurrency": 4, "successful_requests": 3393, "failed_requests": 0, "error_ratio": 0.0, "successful_rps": 337.112, "successful_latency_ms": { "p50": 6.724, "p95": 53.145, "p99": 79.35 } }
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления |
|---|---|---|---|
Остановка одной реплики API (scripts/stop-one.sh) под нагрузкой |
Nginx переключает трафик на живую реплику; продолжение записи \le 10 с; отсутствие дубликатов |
122 успешных записи во время остановки, 0 ошибок, переключение за 0.447 с | 0.447 сек, потерь данных нет |
Рестарт всего стека (scripts/restart.sh) при активной сессии |
Сохранение подтверждённых данных в Postgres и токенов сессий в Redis; восстановление API \le 90 с |
Контейнеры перезапущены, токен валиден, история сообщений сохранена | Восстановление за 2.1 сек, потеря подтверждённых данных: 0 |
Повтор отправки сообщения с тем же Idempotency-Key и телом |
Возврат кода 201 и сохранённого сообщения без создания дубликата в БД | 201 Created, ID и текст сообщения идентичны исходным | Мгновенно, извлечение из таблицы idempotency_keys |
Повтор сообщения с тем же Idempotency-Key, но изменённым текстом |
Отклонение запроса с конфликтом | 409 Conflict | Мгновенно, защита целостности данных |
| Повтор сообщения с тем же ключом после удаления пользователя из чата | Проверка прав доступа перед возвратом кэшированного ответа | 404 Not Found | Проверка ACL выполняется до чтения кэша идемпотентности |
Пересоздание контейнера с новым IP (docker compose up -d --force-recreate api-1) |
Nginx динамически обновляет IP в runtime без ручного reload | Nginx переопределяет IP через Docker DNS 127.0.0.11 за 2 с и продолжает балансировку |
До 2 секунд |
Ограничения
- Какие отказы выдерживаются и какие нет:
- Выдерживаются:
- Внезапная остановка любой одной API-реплики под нагрузкой: балансировщик Nginx переключает входящие запросы на оставшуюся работоспособную реплику за
<0.5секунды без потери данных и дубликатов. - Полный рестарт стека: все подтверждённые данные и активные Bearer-токены сохраняются благодаря volumes
pg_dataиredis_data - Конкурентная отправка сообщений с одинаковым
Idempotency-Keyв разные реплики: ограничение в базе гарантирует, что будет создана ровно одна запись, а проигравшая гонку реплика вернёт созданное сообщение. - Пересоздание контейнеров со сменой IP: встроенный Docker DNS-резолвер Nginx автоматически обновляет адреса в shared memory zone за 2 секунды.
- Внезапная остановка любой одной API-реплики под нагрузкой: балансировщик Nginx переключает входящие запросы на оставшуюся работоспособную реплику за
- Не выдерживаются:
- Одновременное падение обеих API-реплик (клиент получает HTTP 502 Bad Gateway от Nginx).
- Падение единственного экземпляра PostgreSQL или Redis.
- Удаление Docker volumes через
docker compose down -v.
- Выдерживаются:
- Учебные упрощения:
- Nginx, PostgreSQL и Redis запущены в единственном экземпляре без кластеризации и репликации.
- Ключи идемпотентности сохраняются в БД бессрочно.
- Следующий шаг (Лаба 4):
- Подключение S3-совместимого хранилища (MinIO) для бинарных вложений к сообщениям чата и разграничение доступа к файлам по presigned URLs.