12 KiB
Отчёт — лабораторная 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
Из корневого каталога проекта выполнить:
./scripts/bootstrap.sh
docker compose config --quiet
docker compose up -d --build
docker compose ps -a
Скрипт bootstrap.sh создаёт локальные файлы секретов, если они отсутствуют, и проверяет конфигурацию Compose. Значения существующих секретов не перезаписываются.
Используются файлы:
secrets/postgres_password— пароль PostgreSQLsecrets/database_url— строка подключения к PostgreSQLsecrets/cache_url— строка подключения к Redis
Секреты не должны попадать в Git.
Миграции Alembic выполняются отдельным сервисом migrate перед запуском API. Успешное завершение этого контейнера отображается как Exited (0).
После запуска обе API-реплики должны иметь статус healthy, PostgreSQL и Redis — healthy, Nginx — Up.
Единая точка входа:
http://localhost:8080
Проверки:
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-теста восстановить реплики:
docker compose start api-1 api-2
Безопасная остановка стенда с сохранением данных:
docker compose down
Повторный запуск:
docker compose up -d --build
Для намеренного удаления учебных данных и постоянных Docker volumes используется:
docker compose down -v
Последняя команда удаляет данные PostgreSQL и Redis и не применяется при обычном перезапуске.
Архитектура и решения
Используется Docker Compose со следующими компонентами:
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-реплики
Команда:
make test-failover ACTION_SCRIPT=./scripts/stop-one.sh
Полученные результаты:
- Наблюдаемых реплик до отказа: 2
- Успешных записей: 55
- Неудачных попыток: 4
- Время до первого успешного восстановления: 1,327 с
- Подтверждённые данные: сохранены
- Существующая сессия: сохранена
Дополнительно вручную проверена остановка каждой реплики с восстановлением предыдущей. В обоих случаях оставшаяся реплика продолжала обслуживать запросы через Nginx.
Сохранность данных
Команда:
make test-persistence ACTION_SCRIPT=./scripts/restart.sh
Результат: PASS. После перезапуска PostgreSQL, Redis и API подтверждённые данные и существующая сессия остались доступными.
Конкурентная идемпотентность
Команда:
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.