add report.md

This commit is contained in:
2026-10-29 01:39:56 +03:00
parent 55072c04c4
commit 620537e9a9
+62 -15
View File
@@ -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`).