Files
mtusi2026lab3/REPORT.md

135 lines
9.6 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Отчёт — лабораторная 3
- **Автор, группа:** Матвиенко, БПИ2304
- **Целевая оценка:** 3
- **Commit/PR:** добавить после публикации
- **Использованные источники, библиотеки:** материалы и контракт лабораторной, Python 3.12, FastAPI, Uvicorn, PostgreSQL 16, Nginx 1.29, Docker Compose.
## Запуск из чистого clone
Для запуска необходимы Docker Desktop с Docker Compose, Git и WSL Ubuntu с установленным Make.
Создать файл `.env` в корне проекта, указав локальный пароль:
```env
POSTGRES_PASSWORD=<локальный_пароль>
SESSION_TTL_SECONDS=3600
```
Сборка и запуск:
```bash
docker compose up -d --build
docker compose ps -a
curl http://127.0.0.1:8080/health/ready
```
Миграции выполняются отдельным сервисом `migrate` перед запуском API. Проверить повторный запуск миграций:
```bash
docker compose run --rm --no-deps migrate
```
Проверки:
```bash
make test
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
```
После тестирования восстановить две реплики:
```bash
docker compose up -d --wait api1 api2
```
Безопасная остановка с сохранением данных:
```bash
docker compose down
```
Намеренное удаление учебной базы и контейнеров:
```bash
docker compose down -v
```
Последняя команда удаляет также именованные тома с данными PostgreSQL. Секреты из `.env` в репозиторий не добавляются.
## Архитектура и решения
Архитектура приложения:
**Клиент → Nginx → API1 / API2 → PostgreSQL**
Единая публичная точка входа — `http://localhost:8080`. Nginx распределяет запросы между двумя независимыми процессами FastAPI.
В общей PostgreSQL хранятся пользователи, чаты, сообщения, сессии и ключи идемпотентности. PostgreSQL является источником истины, а именованный Docker volume обеспечивает сохранность данных при перезапуске контейнеров.
Из второй лабораторной перенесены REST API, аутентификация, работа с PostgreSQL и SQL-миграции. В третьей лабораторной добавлены:
- Две API-реплики и балансировка через Nginx.
- Заголовок `X-Instance-Id`, уникальный для каждого процесса.
- Общая идемпотентность отправки сообщений с `Idempotency-Key`.
- Транзакционная защита от одновременного создания дубликатов сообщений.
- Отдельный сервис миграций и healthcheck контейнеров.
- Скрипты перезапуска инфраструктуры и остановки выбранной реплики.
Для повторного запроса с тем же ключом и содержимым возвращается ранее созданное сообщение. При изменении содержимого с тем же ключом возвращается HTTP 409. Запись сообщения и ключа выполняется в одной транзакции PostgreSQL.
Переменные `.env`: `POSTGRES_PASSWORD` задаёт пароль базы данных, `SESSION_TTL_SECONDS` — время жизни пользовательской сессии. Адрес `DATABASE_URL` формируется в Docker Compose.
## Доказательства критериев
| Критерий | Команда или сценарий | Наблюдаемый результат | Доказательство |
|---|---|---|---|
| Публичный smoke | `make test` | PASS | `evidence/smoke.txt` |
| Две API-реплики | Получение `X-Instance-Id` от `api1` и `api2` | Два различных UUID | `evidence/instances.txt` |
| Проверка сохранности | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | PASS, данные и сессия сохранены | `evidence/persistence.txt` |
| Отказ одной реплики | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` | PASS, 122 успешные записи, 0 ошибок | `evidence/failover.txt` |
| Восстановление записи | Сценарий failover | 0,909 секунды | `evidence/failover.txt` |
| Повторные миграции | `docker compose run --rm --no-deps migrate` | Обе миграции уже применены | `evidence/migrations.txt` |
| Состояние контейнеров | `docker compose ps -a` | Обе API-реплики и PostgreSQL healthy | `evidence/containers.txt` |
| Реальный перезапуск | `bash scripts/restart.sh` и `docker inspect` | Изменилось время запуска PostgreSQL и двух API | `evidence/restart-before.txt`, `evidence/restart-action.txt`, `evidence/restart-after.txt` |
Уровень 4 и трек 5 не заявлены.
## Эксперименты и отказы
**Гипотеза:** после остановки одной API-реплики запросы продолжат обрабатываться оставшимся экземпляром, подтверждённые сообщения не потеряются, пользовательская сессия сохранится.
**Испытательная среда:** Windows, WSL Ubuntu, Docker Desktop, два процесса FastAPI, PostgreSQL 16 и Nginx 1.29. Проверки проведены 16 ноября 2026 года на локальном стенде.
Результаты теста отказа:
```text
observed_instances_before: 2
successful_writes: 122
failed_attempts: 0
first_recovery_seconds: 0.909
PASS: failover preserved confirmed data and existing session.
```
| Воздействие | Ожидание | Наблюдаемый результат | Восстановление / данные |
|---|---|---|---|
| Остановка одной API-реплики | Работа через оставшуюся реплику | PASS, 122 записи, 0 ошибок | 0,909 с, потерь подтверждённых данных не выявлено |
| Перезапуск API и PostgreSQL | Сохранение записей и сессий | Persistence PASS | Данные и сессия сохранены |
| Повторное применение миграций | Отсутствие повторных изменений схемы | `Already applied` для двух миграций | Успешное завершение |
Дополнительно подтверждён фактический перезапуск инфраструктуры. Время запуска PostgreSQL изменилось с `19:31:02 UTC` на `19:31:47 UTC`, а API-реплик — примерно с `19:31:09 UTC` на `19:31:53 UTC`.
После перезапуска оба API-контейнера перешли в состояние `healthy`. Проверка readiness возвращала HTTP 200, а заголовки `X-Instance-Id` двух реплик различались.
Результаты 122 успешных записей и 0 ошибок относятся к автоматическому failover-сценарию, а не к отдельному нагрузочному тесту. Отдельные измерения RPS, p50/p95/p99, CPU/RAM, длительности прогрева и серии повторов не проводились.
## Ограничения и следующие шаги
Реализация выдерживает остановку одной API-реплики. Однако PostgreSQL и Nginx остаются едиными точками отказа. Резервирование базы данных и балансировщика не реализовано.
Идемпотентность использует транзакции и блокировки PostgreSQL, поэтому дополнительный Redis не требуется, но производительность такого решения под высокой нагрузкой отдельно не измерялась.
В дальнейшем возможны резервирование PostgreSQL, мониторинг, автоматизированные нагрузочные испытания и независимое масштабирование API.
**Вывод:** реализована работа двух API-реплик через единый балансировщик. Публичный smoke, persistence и failover завершились успешно. При отказе одной реплики тест выполнил 122 записи без ошибок, восстановление записи заняло 0,909 секунды. Подтверждены сохранность данных, сессий и реальный перезапуск инфраструктуры.