forked from mtusi2026/mtusi2026lab3
135 lines
9.6 KiB
Markdown
135 lines
9.6 KiB
Markdown
# Отчёт — лабораторная 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 секунды. Подтверждены сохранность данных, сессий и реальный перезапуск инфраструктуры. |