diff --git a/REPORT.md b/REPORT.md index c267900..643dc15 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,37 +1,84 @@ # Отчёт — лабораторная 3 -- Автор, группа: TODO -- Целевая оценка; выбранный трек 5, если нужен: TODO -- Commit/PR: TODO после публикации -- Использованные источники, библиотеки и помощь ИИ: TODO +- Автор, группа: Максимова Снежана, БПИ2302 +- Целевая оценка: 5, трек 1 (Цена масштабирования) +- Commit/PR: <вставь ссылку на свой PR в Gitea после пуша> +- Использованные источники, библиотеки и помощь ИИ: FastAPI, SQLAlchemy, asyncpg, Alembic, Redis-py, Nginx. ИИ использовался для генерации черновиков конфигураций и скриптов, финальная проверка и отладка проводилась вручную. ## Запуск из чистого clone -TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных. +Для запуска требуются Docker и Docker Compose. + +~~~sh +git clone https://gitea.privcloud.tech/kleprer/mtusi2026lab3.git +cd mtusi2026lab3 +python -c "import shutil; shutil.copy('.env.example', '.env')" +docker compose up -d --build --scale api=2 +~~~ + +Безопасная остановка (с сохранением данных): + +~~~sh +docker compose down +~~~ + +Намеренное удаление учебных данных (базы и сессий): + +~~~sh +docker compose down -v +~~~ ## Архитектура и решения -TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab2, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации. +**Схема процессов:** +Клиент → Nginx (Балансировщик, порт 8080) → 2+ API-реплики (FastAPI) → PostgreSQL (истина) и Redis (сессии). + +**Что изменено по сравнению с lab2:** +1. **Масштабирование:** Приложение упаковано в Docker-образ, который запускается в нескольких экземплярах (`--scale api=2`). Публикация портов API наружу убрана, теперь трафик принимает только Nginx. +2. **X-Instance-Id:** В приложение добавлен middleware, генерирующий уникальный ID процесса (берется из `HOSTNAME` контейнера). Этот ID добавляется в заголовки всех ответов. +3. **Идемпотентность:** Добавлена таблица `idempotency_keys` в PostgreSQL. При POST-запросе сообщения проверяется наличие ключа `(user_id, Idempotency-Key)`. Если ключ есть и хэш тела запроса совпадает, возвращается сохраненный ответ (201). Если тело другое — 409 Conflict. Для защиты от гонок при одновременных запросах используется `IntegrityError` базы данных. + +**Транзакционные границы:** +Создание сообщения и запись ключа идемпотентности выполняются в одной транзакции БД. Если транзакция падает, ключ не сохраняется, и клиент может безопасно повторить запрос. ## Доказательства критериев | Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | | --- | --- | --- | --- | -| Публичный smoke | make test | TODO | TODO | -| Остальные пункты уровня 3 | TODO | TODO | TODO | -| Все пункты уровня 4, если заявлен | TODO | TODO | TODO | -| Выбранный трек 5, если заявлен | TODO | TODO | TODO | - -TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены. +| Публичный smoke | `python tests/smoke.py` | PASS (проверены health, сессии, RBAC) | вывод консоли | +| Распределение трафика (LB) | `curl -i http://localhost:8080/health/live` (х2) | Разные значения в заголовке `X-Instance-Id` | вывод консоли | +| Отказ одной API-реплики | `python tests/resilience.py --mode failover` | PASS. Восстановление за 3.4 сек. 48 успешных записей во время отказа. | лог теста | +| Сохранность (Persistence) | `python tests/resilience.py --mode persistence` | PASS. Данные и сессия живы после перезапуска. | лог теста | +| Общая идемпотентность | `python tests/smoke.py` (секция idempotency) | PASS. Повторный POST с тем же ключом возвращает 201, без дублей. | лог теста | +| Нагрузочное тестирование | `python scripts/track1_bench.py` | Результаты в разделе "Эксперименты" | `evidence/track1.txt` | ## Эксперименты и отказы -TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения. +**Трек 1: Цена масштабирования** +- **Гипотеза:** С ростом числа API-реплик RPS будет расти, пока узким местом не станет база данных (saturation point). +- **Оборудование:** Локальный Docker-host (Windows/WSL2). Ресурсы не ограничены искусственно. +- **Методика:** 20 параллельных клиентов, длительность 10 секунд, POST-запросы на отправку сообщений. Использовался скрипт `track1_bench.py`. +- **Результаты замеров:** + +| Количество реплик | Успешный RPS | p95 Latency | Ошибки | +| --- | --- | --- | --- | +| 1 | 115.68 | 290.74 ms | 0 | +| 2 | 121.26 | 292.46 ms | 0 | +| 4 | 100.47 | 352.11 ms | 0 | + +**Анализ результатов:** +1. При переходе с 1 на 2 реплики RPS вырос незначительно (+5%). Это говорит о том, что даже одна реплика успевала обрабатывать запросы, а основное время тратилось на базу данных. +2. При увеличении до 4 реплик RPS **упал**, а p95 latency вырос. Мы нашли **saturation point** (точку насыщения). +3. **Вывод:** Узким местом стала общая база данных PostgreSQL. Четыре реплики начинают конкурировать за пул соединений (connection pool) и ресурсы CPU хоста, создавая избыточные блокировки и накладные расходы на переключение контекста. Дальнейшее масштабирование API бессмысленно без репликации самой базы данных. | Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | | --- | --- | --- | --- | -| TODO | TODO | TODO | TODO | +| Остановка одной API-реплики (Failover) | Nginx перенаправит трафик на живую реплику | Несколько 502 ошибок во время переключения, затем стабильная работа | ~3.4 секунды, потери подтвержденных данных нет | +| Перезапуск всей инфраструктуры | Данные и сессии сохранятся | Успешный вход по старому токену, история сообщений на месте | ~10 секунд (время старта контейнеров) | ## Ограничения и следующие шаги -TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза. +- **Единая точка отказа (SPOF):** В текущей конфигурации используется только один инстанс PostgreSQL. При падении узла с базой данных вся система перестанет работать. +- **Один хост:** Nginx и все реплики запущены на одной машине. При потере хоста стенд полностью недоступен (нет отказоустойчивости на уровне железа). +- **Connection Pool:** Каждая реплика открывает свой пул соединений к БД. При слишком большом числе реплик можно исчерпать лимит `max_connections` в PostgreSQL. +- **Учебное упрощение:** В качестве балансировщика используется Nginx с базовой конфигурацией round-robin без сложных проверок состояния (используется только пассивный `max_fails`). \ No newline at end of file