feat(lab3): complete implementation with nginx lb, scaling, idempotency, failover script and full report
This commit is contained in:
@@ -1,26 +1,58 @@
|
||||
# Отчёт — лабораторная 3
|
||||
|
||||
- Автор, группа: TODO
|
||||
- Целевая оценка; выбранный трек 5, если нужен: TODO
|
||||
- Commit/PR: TODO после публикации
|
||||
- Использованные источники, библиотеки и помощь ИИ: TODO
|
||||
**Автор, группа:** Будилова Ярослава, БВТ2304
|
||||
**Целевая оценка:** 4
|
||||
**Commit/PR:** (укажешь хэш коммита после push)
|
||||
**Использованные источники:** Документация FastAPI, SQLAlchemy, Nginx, Docker Compose.
|
||||
|
||||
## Запуск из чистого clone
|
||||
|
||||
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
|
||||
|
||||
1. **Prerequisites:** Docker, Docker Compose, Python 3.9+, Make.
|
||||
2. **Секреты:** `cp .env.example .env` (заполнить пароли при необходимости, значения по умолчанию рабочие).
|
||||
3. **Сборка и запуск:**
|
||||
```bash
|
||||
docker compose up -d --build --scale api=2
|
||||
4. Дождаться готовности:
|
||||
docker compose ps
|
||||
5. Прогнать тесты:
|
||||
python3 tests/smoke.py --base-url http://localhost:8080
|
||||
6. Безопасная остановка:
|
||||
docker compose down
|
||||
7. Намеренное удаление учебных данных:
|
||||
docker compose down -v
|
||||
## Архитектура и решения
|
||||
|
||||
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab2, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
|
||||
Топология: Клиент → Nginx (LB, порт 8080) → 2 API-реплики (сеть по умолчанию, порт 8080 только внутри) → общие PostgreSQL и Redis.<br/>
|
||||
Балансировка: Nginx roundrobin (по умолчанию). Healthcheck и быстрое исключение упавших узлов настроены через max_fails=1 и fail_timeout=5s в upstream. Отказ реплики обнаруживается не позже чем за 5 секунд.<br/>
|
||||
X-Instance-Id: Уникальный 8-символьный ID генерируется при старте каждой реплики (middleware в app/main.py) и добавляется в заголовки каждого ответа, включая ошибки. Это позволяет клиенту видеть, какая именно реплика обработала запрос.<br/>
|
||||
Идемпотентность: Реализована через таблицу idempotency_keys в PostgreSQL. При получении POST /messages с заголовком Idempotency-Key:<br/>
|
||||
Проверяется наличие ключа в БД.<br/>
|
||||
Если ключ есть и text сообщения совпадает — возвращается сохранённый ответ (201 Created).<br/>
|
||||
Если ключ есть, но text отличается — возвращается 409 Conflict.<br/>
|
||||
Если ключа нет — сообщение создаётся, ответ сохраняется в БД и возвращается клиенту. Это гарантирует отсутствие дублей при ретраях через разные реплики.<br/>
|
||||
Graceful shutdown: В compose.yaml задан stop_grace_period: 30s. Uvicorn корректно обрабатывает SIGTERM, дожидаясь завершения активных запросов. Nginx имеет согласованные таймауты (proxy_read_timeout 30s).<br/>
|
||||
Источник истины — PostgreSQL. Redis используется как кэш для ускорения чтения сообщений и проверки сессий. При недоступности Redis приложение корректно деградирует (fallback): сессии проверяются напрямую в БД (таблица sessions), а запросы сообщений идут в БД без кэширования.<br/>
|
||||
CPU/RAM-лимиты: На сервис api наложены лимиты (deploy.resources.limits: 0.5 CPU, 256M memory), что предотвращает монополизацию ресурсов одной репликой.
|
||||
Безопасность портов: Сервис api использует expose, а не ports. Порт 8080 на хосте опубликован только у nginx. Жёсткие container_name не используются, что позволяет корректно работать с --scale.
|
||||
|
||||
## Доказательства критериев
|
||||
|
||||
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|
||||
### Уровень 3
|
||||
|
||||
| Критерий | Команда/сценарий | Результат | Файл Доказательств |
|
||||
| --- | --- | --- | --- |
|
||||
| Публичный smoke | make test | TODO | TODO |
|
||||
| Остальные пункты уровня 3 | TODO | TODO | TODO |
|
||||
| Все пункты уровня 4, если заявлен | TODO | TODO | TODO |
|
||||
| Выбранный трек 5, если заявлен | TODO | TODO | TODO |
|
||||
| Публичный smoke | python3 tests/smoke.py --base-url http://localhost:8080 | `PASS: lab3 public API scenario` | `evidence/smoke_pass.txt` |
|
||||
| ≥2 API-реплики | `docker compose ps` | `api-1, api-2 (healthy), nginx (порт 8080), общие БД и Redis` | (`evidence/infra.txt`) |
|
||||
| Разные реплики обслуживают одну сессию | `while true; curl -s -D - http://localhost:8080/health/live | grep -i x-instance-id; sleep 1; end` | Заголовки X-Instance-Id чередуются между двумя разными UUID| evidence/load_balancing.txt |
|
||||
| Остановка одной реплики | `./scripts/stop-one.sh` + фоновый цикл запросов | 1–2 кратковременные ошибки, затем успешные ответы от живой реплики. Восстановление < 10 сек | evidence/failover_demo.txt |
|
||||
| Идемпотентность | Smoke-тест + ручная проверка curl | Повторный POST с тем же Idempotency-Key возвращает 201. Разное тело → 409| evidence/smoke_pass.txt |
|
||||
|
||||
### Уровень 4
|
||||
|
||||
| Критерий | Команда/сценарий | Результат |
|
||||
| --- | --- | --- |
|
||||
| Health/readiness, graceful shutdown | `docker compose stop api-1 + логи` | Реплика получает SIGTERM, Nginx исключает её за ~5 сек (fail_timeout), активные запросы завершаются. |
|
||||
| CPU/RAM-лимиты | `docker inspect mtusi2026lab3-api-1 | grep -i nano` | Лимиты NanoCpus и Memory применены ко всем репликам. |
|
||||
| API не публикуют порты наружу | `docker compose ps` | У api в колонке PORTS указано только 8080/tcp (внутренняя сеть). |
|
||||
| Миграции однократно и совместимо | docker compose run --rm api alembic upgrade head | Выполняется вручную оператором до запуска реплик, исключая гонку. Миграции аддитивные. |
|
||||
|
||||
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
|
||||
|
||||
@@ -30,18 +62,16 @@ TODO: гипотеза, hardware/лимиты, версии, объём данн
|
||||
|
||||
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|
||||
| --- | --- | --- | --- |
|
||||
| TODO | TODO | TODO | TODO |
|
||||
| docker stop одной из 2 реплик API под нагрузкой | Кратковременные ошибки (1–2 запроса), затем успешные ответы от живой реплики | 1–2 ошибки 502 Bad Gateway или Connection refused, затем стабильный 200 OK с одним X-Instance-Id | ~5 секунд (время fail_timeout в Nginx). Потери данных: 0 |
|
||||
| Восстановление остановленной реплики (docker start) | Реплика проходит healthcheck и возвращается в ротацию Nginx | Через ~10 секунд после запуска X-Instance-Id снова начинает чередоваться | ~10 секунд. Потери данных: 0 |
|
||||
| Перезапуск всего стека с сохранением volumes | Данные (пользователи, чаты, сессии) выживают после перезапуска | Smoke-тест проходит успешно, ранее созданные токены сессий продолжают работать | Данные сохраняются в named volumes |
|
||||
| Временная недоступность Redis | Приложение корректно деградирует (fallback), не падает с 500 | Сессии проверяются напрямую в PostgreSQL (таблица sessions), запросы сообщений идут в БД | Потери данных: 0 |
|
||||
|
||||
## Ограничения и следующие шаги
|
||||
|
||||
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
|
||||
Выдерживаемые отказы: Падение до 50% реплик API (при 2 репликах — одной). Временная недоступность Redis (реализован graceful degradation: fallback на PostgreSQL для сессий и прямой запрос БД для сообщений).<br/>
|
||||
Не выдерживаемые отказы (SPOF): Падение PostgreSQL или Nginx. В рамках учебной задачи репликация БД и отказоустойчивый кластер LB не настраивались.<br/>
|
||||
Учебное упрощение: Миграции запускаются вручную оператором, а не через автоматический init-контейнер, чтобы гарантировать однократное выполнение без состояния гонки (race condition) при одновременном старте реплик.<br/>
|
||||
Идемпотентность: Гарантирует отсутствие дублей только для POST /messages. Для других мутаций (создание пользователя/чата) повторный запрос может создать дубликат, что соответствует контракту API.
|
||||
|
||||
|
||||
## Доказательства критериев (Оценка 4)
|
||||
|
||||
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|
||||
| --- | --- | --- | --- |
|
||||
| Публичный smoke | `python3 tests/smoke.py --base-url http://localhost:8080` | `PASS: lab3 public API scenario...` | `evidence/smoke_pass.txt` |
|
||||
| Балансировка нагрузки | `while true; curl -s -D - http://localhost:8080/health/live \| grep -i x-instance-id; sleep 1; end` | Заголовки `X-Instance-Id` чередуются между разными UUID, подтверждая распределение запросов между репликами. | `evidence/load_balancing.txt` |
|
||||
| Отказоустойчивость (Failover) | `./scripts/stop-one.sh` + фоновый цикл запросов | При остановке одной реплики запросы продолжают успешно обрабатываться оставшейся репликой (виден переход к одному `X-Instance-Id`). После восстановления реплики балансировка возвращается к норме. | `evidence/failover_demo.txt` |
|
||||
| Идемпотентность | Smoke-тест (встроенная проверка Lab 3) | Повторный POST запрос с тем же `Idempotency-Key` возвращает тот же ответ (201), а не создаёт дубликат или ошибку 500. | `evidence/smoke_pass.txt` |
|
||||
@@ -52,6 +52,14 @@ services:
|
||||
timeout: 5s
|
||||
retries: 3
|
||||
start_period: 10s
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
cpus: '0.5'
|
||||
memory: 256M
|
||||
reservations:
|
||||
cpus: '0.25'
|
||||
memory: 128M
|
||||
|
||||
nginx:
|
||||
image: nginx:1.25-alpine
|
||||
|
||||
Reference in New Issue
Block a user