16 KiB
Отчёт — лабораторная 3
- Автор, группа: Федоров Арсений, БПИ2302.
- Целевая оценка: 3. Трек 5: не заявлен.
- Репозиторий: https://gitea.privcloud.tech/Fedoroff/mtusi2026lab3
- Ветка:
solution/BPI2302-fedorov. - Подтверждённый опубликованный коммит до обновления отчёта:
35ae6f7(feat: implement lab3 load balancing and idempotency). Коммит с данным отчётом будет создан отдельно; его хеш и ссылку на PR можно добавить после публикации. - Источники: задание и README лабораторной №3, контракт
contracts/openapi.json, код и результаты лабораторной №2, официальная документация Go, Docker Compose, Nginx, PostgreSQL и Redis. - Библиотеки: зависимости Go перечислены в
go.mod/go.sum(в частности, pgx, go-redis и google/uuid); образы инфраструктуры определены вcompose.yaml. - Использование ИИ: ChatGPT использовался для подготовки и исправления кода, конфигурации Docker/Nginx, тестов и документации, а также для разбора ошибок Windows/Python. Команды и сценарии, перечисленные как успешные ниже, запускались локально пользователем. ИИ не заменяет фактическую проверку и оценивание преподавателем.
Запуск из чистого clone
Среда фактической проверки: Windows, PowerShell, Docker Desktop / Docker Compose, Python 3.10.5; тесты Go запускались в контейнере golang:1.25.0-alpine. В compose.yaml использовались PostgreSQL 16.10-alpine, Redis 7.4.6-alpine, Nginx 1.29-alpine. Для запуска требуются Git, Docker с Compose и свободный порт 127.0.0.1:8080. Для Python-тестов на Windows требуется установленный Python с командой py -3; make — для запуска целей Makefile.
# Получить исходники и перейти на ветку решения
git clone https://gitea.privcloud.tech/Fedoroff/mtusi2026lab3.git
cd mtusi2026lab3
git switch solution/BPI2302-fedorov
# Создать локальную конфигурацию; вручную заполнить требуемые значения
Copy-Item .env.example .env
notepad .env
# Собрать и запустить инфраструктуру и API
docker compose --env-file .env up -d --build
# Проверить контейнеры (в том числе завершившийся с кодом 0 migrate)
docker compose --env-file .env ps -a
Локальный оператор задаёт значения из .env.example в .env, включая пароль БД; не публикует .env и не вставляет секреты в отчёт. Миграции выполняет отдельный сервис migrate в составе Compose; успешное завершение подтверждается Exited (0). Два экземпляра API (api1, api2) должны быть healthy, как и PostgreSQL/Redis. Балансировщик доступен по http://localhost:8080.
Проверки в том же окне PowerShell:
# Python 3.10 на Windows: читать UTF-8-файлы как UTF-8
$env:PYTHONUTF8 = "1"
# Если в Makefile установлено PYTHON ?= python3,
# использовать переносимый вызов с переопределением:
make check PYTHON="py -3"
make test PYTHON="py -3"
# Проверка конкурентной идемпотентности
py -3 tests/idempotency_concurrent.py --base-url "http://localhost:8080"
# Go-тесты без локальной установки Go
docker run --rm -v "${PWD}:/app" -w /app golang:1.25.0-alpine go test ./...
Примечание по Makefile: во время локальной проверки команда make выводила py -3 ..., поскольку для Windows было настроено значение PYTHON=py -3. На Linux можно оставить стандартное python3. Перед сдачей следует убедиться, что текущая версия Makefile соответствует командам в репозитории.
Безопасная остановка с сохранением томов и данных:
docker compose --env-file .env down
Только для намеренного удаления учебных данных (удаляет тома Compose, включая данные БД):
docker compose --env-file .env down -v
Архитектура и решения
Клиент / публичные тесты
|
v
Nginx (lb, 127.0.0.1:8080)
|
+----+----+
| |
api1 api2 (Go HTTP API; X-Instance-Id)
| |
+----+----+
|
+-----+-----+
| |
PostgreSQL Redis
(данные, (кеш / сессии)
транзакции,
идемпотентность)
migrate --> PostgreSQL (отдельный одноразовый сервис миграций)
Перенесено из лабораторной №2: API пользователей, авторизации/сессий, чатов и сообщений; PostgreSQL, Redis, проверка JSON, обработка ошибок, публичный контракт и регрессионные тесты.
Изменения лабораторной №3: два экземпляра API за Nginx, общий доступ к хранилищам, заголовок X-Instance-Id, идемпотентная отправка сообщений с Idempotency-Key, отдельный процесс миграций и сценарии проверки конкурентных запросов/остановки одной реплики.
Источник истины: PostgreSQL для сохраняемых сущностей и фиксации результата создания сообщения; Redis используется как вспомогательное хранилище для работы с сессиями. Для идемпотентной записи используются ограничения/транзакции PostgreSQL (см. migrations/002_idempotency.up.sql и internal/storage/message_postgres.go). Запросы к двум API-репликам обращаются к общим хранилищам, а не к независимым базам данных.
Конфигурация: шаблон переменных окружения — .env.example, локальные значения — .env; способ запуска и сервисы — compose.yaml, настройки балансировщика — infra/nginx.conf. Пароли и токены в Git не добавляются.
Доказательства критериев
| Проверяемое требование | Команда / сценарий | Фактически наблюдаемый результат | Где воспроизвести / доказательство |
|---|---|---|---|
| Структура и синтаксис | make check с PYTHON=py -3, PYTHONUTF8=1 |
PASS: offline skeleton structure, local refs and Python syntax; application NOT tested. |
scripts/check_contract.py; вывод локальной проверки |
| Публичный сценарий API | make test с PYTHON=py -3, PYTHONUTF8=1 |
PASS: lab3 public API scenario; infrastructure and grading evidence remain separate. |
tests/smoke.py; вывод локальной проверки |
| Go-тесты | docker run --rm -v "${PWD}:/app" -w /app golang:1.25.0-alpine go test ./... |
Пакеты internal/handler и internal/storage: ok; остальные показали [no test files]; ошибок FAIL не было |
Go-тесты в internal/handler, internal/storage; вывод локальной проверки |
| Конкурентная идемпотентность | py -3 tests/idempotency_concurrent.py --base-url "http://localhost:8080" |
PASS: 16 concurrent retries, one message, replicas: api1, api2 |
tests/idempotency_concurrent.py; вывод локальной проверки |
| Балансировка двух реплик | 10 запросов GET /health/live через Nginx, чтение X-Instance-Id |
В ответах присутствовали api1 и api2 |
compose.yaml, infra/nginx.conf; вывод PowerShell |
| Доступность после отказа одной реплики | docker compose --env-file .env stop api1; затем 5 запросов GET /health/live |
Все пять ответов получены от api2 |
Вывод PowerShell и состояние контейнеров |
| Возврат реплики в строй | docker compose --env-file .env up -d --no-deps api1; затем docker compose --env-file .env ps |
api1 снова healthy; api2, PostgreSQL и Redis также healthy |
Вывод docker compose ps |
| Миграции | docker compose --env-file .env ps -a |
migrate завершился с Exited (0); API и хранилища запустились |
compose.yaml, migrations/; вывод ps -a |
| Уровень 4 | Не заявлен | Не проверялся как критерий сдачи | — |
| Трек 5 | Не заявлен | Не проверялся | — |
Фактические фрагменты вывода:
make check:
PASS: offline skeleton structure, local refs and Python syntax; application NOT tested.
make test:
PASS: lab3 public API scenario; infrastructure and grading evidence remain separate.
idempotency_concurrent.py:
PASS: 16 concurrent retries, one message, replicas: api1, api2
GET /health/live при остановленном api1:
api2
api2
api2
api2
api2
Эти результаты получены на локальной машине, но отдельные файлы с полными логами в evidence/ пока не приложены. Для независимого воспроизведения приведены команды и исходники тестов. Сами make check и make test не доказывают всех инфраструктурных критериев: они дополнены ручным сценарием отказа и конкурентным тестом.
Эксперименты и отказы
Гипотеза 1: Nginx направляет запросы к обоим экземплярам API. Метод: десять последовательных HTTP-запросов к /health/live с чтением заголовка X-Instance-Id. Наблюдение: ответы от api1 и api2; распределение в этом небольшом прогоне близко к чередованию. Это функциональная проверка маршрутизации, не измерение производительности.
Гипотеза 2: остановка одной реплики не приводит к полной недоступности API. Метод: docker compose ... stop api1, затем пять запросов через балансировщик. Наблюдение: пять успешных ответов с X-Instance-Id: api2. После up -d --no-deps api1 реплика вновь стала healthy.
Гипотеза 3: конкурентные повторы одного запроса не создают дубликаты сообщения. Метод: tests/idempotency_concurrent.py, 16 одновременных повторов. Наблюдение: one message, запросы обработаны через обе реплики.
| Воздействие | Ожидание | Фактическое наблюдение | Восстановление / данные |
|---|---|---|---|
| Запросы через Nginx при двух работающих API | Обе реплики получают запросы | Наблюдались api1 и api2 |
Не применимо |
Остановка api1 |
Доступность через api2 |
Пять ответов api2 |
Время переключения не измерялось; потеря данных отдельно не проверялась |
Повторный запуск api1 |
Возврат к двум здоровым репликам | api1 и api2 в состоянии healthy |
Время до healthy не замерялось |
| 16 конкурентных повторов с одним ключом | Одна логическая запись сообщения | Тест сообщил one message |
Дубликаты в этом сценарии не обнаружены |
Условия и пределы измерения: локальная Windows-машина с Docker Desktop; точные характеристики CPU/RAM, выделенные лимиты контейнеров, продолжительность прогрева, arrival rate, успешные RPS, число ошибок под длительной нагрузкой, p50/p95/p99 и потребление ресурсов не фиксировались. Проведены функциональные сценарии, а не полноценный нагрузочный бенчмарк. Утверждений об улучшении производительности или гарантированном времени восстановления не делается.
Ограничения и следующие шаги
- При остановке одного Go API работа через оставшуюся реплику подтверждена; одновременная потеря обоих API не выдерживается.
- Nginx — один экземпляр и потенциальная единая точка отказа; отказоустойчивый кластер балансировщиков не реализован.
- PostgreSQL и Redis запущены без подтверждённого автоматического переключения на резервный узел; их отказоустойчивость не заявляется.
- Проверена конкурентная идемпотентность в одном сценарии на 16 запросов; исчерпывающие испытания при сбоях БД и во всех сетевых условиях не проводились.
- Нет измеренных RPS, p50/p95/p99, CPU/RAM и времени восстановления. Следующий шаг — выполнить повторяемый нагрузочный тест и сохранить сырые результаты без секретов.
- Локальная совместимость Python 3.10/Windows потребовала включения UTF-8 и корректного разбора дробных секунд RFC3339 в тестовом клиенте. Эти исправления должны быть включены в ветку вместе с отчётом.
- Решение ориентировано на учебную среду Docker Compose, не на промышленное развёртывание.