Files
mtusi2026lab3/REPORT.md
T
2026-10-15 00:18:02 +03:00

212 lines
12 KiB
Markdown
Raw 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
- Целевая оценка: 5, выполнение по этапам 3 → 4 → 5
- Выбранный трек оценки 5: цена масштабирования
- Commit/PR: будет указан после публикации
- Использованные источники: документация Docker Compose, FastAPI, SQLAlchemy, Alembic, PostgreSQL, Redis, Nginx; материалы лабораторной работы
- Помощь ИИ: ChatGPT использовался для обсуждения архитектуры, разработки, отладки и подготовки документации
## Запуск из чистого clone
Для запуска необходимы Docker Engine с поддержкой Docker Compose, Git и Python 3.9 или новее.
Приложение работает в контейнерах. Локальная установка PostgreSQL и Redis не требуется.
Используемые образы:
- Python 3.13.15-slim
- PostgreSQL 17.6
- Redis 8.2.2
- Nginx 1.29-alpine
Из корневого каталога проекта выполнить:
```bash
./scripts/bootstrap.sh
docker compose config --quiet
docker compose up -d --build
docker compose ps -a
```
Скрипт `bootstrap.sh` создаёт локальные файлы секретов, если они отсутствуют, и проверяет конфигурацию Compose. Значения существующих секретов не перезаписываются.
Используются файлы:
- `secrets/postgres_password` — пароль PostgreSQL
- `secrets/database_url` — строка подключения к PostgreSQL
- `secrets/cache_url` — строка подключения к Redis
Секреты не должны попадать в Git.
Миграции Alembic выполняются отдельным сервисом `migrate` перед запуском API. Успешное завершение этого контейнера отображается как `Exited (0)`.
После запуска обе API-реплики должны иметь статус `healthy`, PostgreSQL и Redis — `healthy`, Nginx — `Up`.
Единая точка входа:
`http://localhost:8080`
Проверки:
```bash
make check
make validate
make test
make test-persistence ACTION_SCRIPT=./scripts/restart.sh
make test-failover ACTION_SCRIPT=./scripts/stop-one.sh
python3 tests/test_concurrent_idempotency.py
```
Для локальных Python-проверок требуется установить зависимости из `requirements-dev.txt`, если они ещё не установлены.
После failover-теста восстановить реплики:
```bash
docker compose start api-1 api-2
```
Безопасная остановка стенда с сохранением данных:
```bash
docker compose down
```
Повторный запуск:
```bash
docker compose up -d --build
```
Для намеренного удаления учебных данных и постоянных Docker volumes используется:
```bash
docker compose down -v
```
Последняя команда удаляет данные PostgreSQL и Redis и не применяется при обычном перезапуске.
## Архитектура и решения
Используется Docker Compose со следующими компонентами:
```text
Client
|
v
Nginx :8080
|
+---- API-1 :8080
|
+---- API-2 :8080
|
+---- PostgreSQL
|
+---- Redis
```
Nginx является единой публичной точкой входа. API-реплики не публикуют порты на хосте и доступны через внутреннюю сеть Compose.
Обе реплики используют одну PostgreSQL и один Redis.
PostgreSQL хранит постоянные данные приложения и информацию, необходимую для общей идемпотентности отправки сообщений. Redis хранит пользовательские сессии с TTL 3600 секунд.
В API не используются локальные пользовательские сессии, поэтому запросы одного пользователя могут обслуживаться разными репликами без повторной авторизации.
Каждая реплика возвращает заголовок `X-Instance-Id`, позволяющий определить обработавший запрос экземпляр.
Для отправки сообщений используется обязательный `Idempotency-Key`. Повторная отправка с тем же ключом не должна создавать второе сообщение. Согласованность между репликами обеспечивается общим PostgreSQL и транзакционным механизмом идемпотентности.
Миграции выполняются отдельным контейнером, что исключает одновременный запуск Alembic несколькими API-репликами.
В Nginx настроены два backend-сервера, таймауты подключения и обработки запросов, а также повторная попытка при отдельных ошибках upstream.
Из лабораторной 2 перенесены основная реализация API, PostgreSQL, миграции, авторизация и работа с сообщениями. В лабораторной 3 добавлены балансировка, две API-реплики, идентификация экземпляров и общая идемпотентность.
Файл `.env.example` является шаблоном задания. Фактическая конфигурация контейнеров задаётся в `compose.yaml`; подключения к PostgreSQL и Redis передаются через файлы секретов.
## Доказательства критериев
| Критерий | Команда или сценарий | Наблюдаемый результат | Доказательство |
| --- | --- | --- | --- |
| Публичный smoke | `make test` | PASS | `evidence/smoke.txt` |
| Структура проекта | `make check` | PASS | Вывод проверки |
| OpenAPI | `make validate` | PASS | Вывод проверки |
| Две API-реплики | `docker compose ps -a` | Обе реплики healthy | `evidence/compose-status.txt` |
| Общая сессия | `make test-failover` | Сессия сохраняется после отказа реплики | `evidence/failover.txt` |
| Отказ одной реплики | `make test-failover ACTION_SCRIPT=./scripts/stop-one.sh` | 55 успешных записей, 4 неудачные попытки, первое восстановление за 1,327 с | `evidence/failover.txt` |
| Сохранность данных | `make test-persistence ACTION_SCRIPT=./scripts/restart.sh` | PASS, подтверждённые данные и сессия сохранились | `evidence/persistence.txt` |
| Конкурентная идемпотентность | `python3 tests/test_concurrent_idempotency.py` | 20 запросов, 1 уникальный ID, 1 сообщение в истории | `evidence/idempotency.txt` |
| Запросы через разные реплики | Конкурентный тест | Обнаружены `api-1` и `api-2` | `evidence/idempotency.txt` |
| Остановка каждой реплики | Ручная последовательная проверка | При остановке одной реплики оставшаяся продолжала отвечать HTTP 200 | Результаты ручной проверки |
## Эксперименты и отказы
На этапе оценки 3 выполнены функциональные проверки отказоустойчивости, сохранности данных и идемпотентности.
### Отказ API-реплики
Команда:
```bash
make test-failover ACTION_SCRIPT=./scripts/stop-one.sh
```
Полученные результаты:
- Наблюдаемых реплик до отказа: 2
- Успешных записей: 55
- Неудачных попыток: 4
- Время до первого успешного восстановления: 1,327 с
- Подтверждённые данные: сохранены
- Существующая сессия: сохранена
Дополнительно вручную проверена остановка каждой реплики с восстановлением предыдущей. В обоих случаях оставшаяся реплика продолжала обслуживать запросы через Nginx.
### Сохранность данных
Команда:
```bash
make test-persistence ACTION_SCRIPT=./scripts/restart.sh
```
Результат: PASS. После перезапуска PostgreSQL, Redis и API подтверждённые данные и существующая сессия остались доступными.
### Конкурентная идемпотентность
Команда:
```bash
python3 tests/test_concurrent_idempotency.py
```
Результаты:
- Параллельных запросов: 20
- Уникальных идентификаторов сообщений: 1
- Наблюдаемые реплики: `api-1`, `api-2`
- Совпадающих сообщений в истории: 1
- Итог: PASS
Таким образом, конкурентные запросы с одинаковым ключом не создали дублирующих сообщений.
### Дальнейшие измерения
Для оценки 4 планируется собрать RPS, количество ошибок, время восстановления, задержки и потребление ресурсов при последовательной остановке каждой реплики и поочерёдном обновлении контейнеров.
Для оценки 5 выбран трек исследования цены масштабирования. Планируется сравнить 1, 2 и 4 API-реплики при фиксированном общем бюджете CPU/RAM, затем повторить эксперимент с увеличением ресурсов.
## Ограничения и следующие шаги
Реализована устойчивость к остановке одной API-реплики при сохранении доступности второй.
PostgreSQL, Redis и Nginx представлены одиночными экземплярами и остаются едиными точками отказа. Отказ этих компонентов не покрывается механизмом переключения API-реплик.
Проверка повторного запуска выполнена на существующих Docker volumes. Полностью независимый запуск из чистого клона пока не проверялся.
Время 1,327 с характеризует восстановление, наблюдаемое тестом, а не отдельное измерение времени обнаружения отказа балансировщиком.
В текущем локальном варианте файловые секреты имеют права чтения, допускающие доступ других локальных пользователей. Для следующего этапа необходимо ограничить доступ к ним без нарушения работы непривилегированных контейнеров.
Количественные эксперименты с производительностью, rolling update и масштабированием будут проведены при выполнении критериев оценок 4 и 5.