212 lines
12 KiB
Markdown
212 lines
12 KiB
Markdown
# Отчёт — лабораторная 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. |