19 KiB
Отчёт по лабораторной работе 3 — балансировка реплик мессенджера
- Автор / группа: Бадрадин Али / БВТ2302
- Целевая оценка: 4 (выполнены требования на оценки 3 и 4)
- Исследовательский трек на оценку 5: не заявлен
- Исходный проект ЛР 2: Badradine/mtusi2026lab2, ветка master, коммит 39277c14677fe8b3f362022af069d4e7a68f8158
- Источники и помощь: спецификация Docker Compose Deploy; документация NGINX по upstream и proxy; требования и публичные тесты ЛР 3; помощь OpenAI Codex при реализации и проверке. Студент должен понимать и уметь защитить принятые решения.
Клонирование и запуск с нуля
Требования: Git, Docker Desktop с Linux-контейнерами и Compose v2, PowerShell для создания локальных файлов секретов, WSL/Ubuntu с Python 3.12 и GNU Make для команд тестирования. Используйте только синтетические тестовые данные.
В PowerShell:
git clone https://gitea.privcloud.tech/Badradine/mtusi2026lab3.git
Set-Location .\mtusi2026lab3
Copy-Item .env.example .env
.\scripts\create-secrets.ps1
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --scale api=2
docker compose --env-file .env ps
Одноразовый сервис migrate применяет версионированные миграции, удерживая блокировку транзакции PostgreSQL. Реплики API запускаются только после успешного завершения миграции. Публичная точка входа: http://localhost:8080. Порт на хост публикует только NGINX и привязывает его к 127.0.0.1.
В WSL, находясь в каталоге репозитория, сначала разрешите запуск служебных скриптов: chmod +x scripts/*.sh. Затем выполните:
--sh make check make validate make test BASE_URL=http://localhost:8080 make test-idempotency BASE_URL=http://localhost:8080 make test-persistence ACTION_SCRIPT=scripts/restart.sh BASE_URL=http://localhost:8080
Для полной проверки OpenAPI установите dev-зависимости в WSL и укажите Python из виртуального окружения:
---sh python3 -m venv .venv .venv/bin/python -m pip install -r requirements-dev.txt make validate PYTHON=.venv/bin/python
Чтобы проверить переключение при параллельной записи, выполните проверку дважды, восстанавливая остановленную реплику между запусками. Учитывайте оба запуска только если в evidence/stopped-replicas.txt указаны два разных ID экземпляров:
--sh make test-failover ACTION_SCRIPT=scripts/stop-one.sh BASE_URL=http://localhost:8080 bash scripts/recover-api.sh make test-failover ACTION_SCRIPT=scripts/stop-one.sh BASE_URL=http://localhost:8080
Для одновременного сбора 40-секундных метрик нагрузки и проверки отказа использовалась оболочка:
--sh bash scripts/verify-failover.sh replica-run-2 bash scripts/verify-failover.sh replica-run-3
Каждый запуск verify-failover.sh сначала восстанавливает две API-реплики, затем запускает 40-секундную нагрузку и проверку отказа. Между зачтёнными запусками были остановлены разные экземпляры; их ID сверены с evidence/stopped-replicas.txt.
Чтобы проверить последовательную замену реплик во время генерации нагрузки:
--sh make test-rolling
Служебные скрипты сохраняют тома. Команда docker compose down останавливает стек, не удаляя данные. Удаляйте тома только если намеренно хотите стереть локальные данные лабораторной работы.
Архитектура и принятые решения
--text Клиент -> NGINX :8080 -> 2 реплики API -> общие PostgreSQL и Redis
В проект перенесена реализация ЛР 2 из актуальной ветки Gitea: хеши паролей Argon2id, вход Basic, непрозрачные Bearer-сессии в Redis, пользователи/чаты/участники/сообщения в PostgreSQL, постраничная навигация по ключу, ограниченные пулы и тайм-ауты, версионированные миграции. В ЛР 3 добавлена общая таблица результатов идемпотентности без изменения прежних таблиц и конечных точек API.
NGINX распределяет запросы по алгоритму round-robin без закрепления клиента за одной репликой. DNS Docker обновляется раз в секунду; отказавший upstream после первой ошибки исключается на две секунды. Тайм-аут подключения — одна секунда. Ожидаемое время исключения отказавшей реплики составляет примерно до трёх секунд (одно обновление DNS и одна попытка подключения); измеренные значения обнаружения отказа и восстановления приведены ниже.
Каждый процесс API возвращает имя контейнера как постоянный X-Instance-Id. Проверка готовности API проверяет PostgreSQL и Redis; проверка работоспособности API выполняется каждые три секунды с тайм-аутом две секунды. NGINX обнаруживает отказ upstream пассивно. При получении SIGTERM Uvicorn перестаёт принимать соединения и ждёт до пяти секунд завершения активных запросов; Compose предоставляет восемь секунд до принудительного завершения. Тайм-ауты отправки и чтения NGINX — пять секунд.
Область действия идемпотентности: (аутентифицированный пользователь, POST, путь сообщения чата, ключ). Допустимы ASCII-ключи [A-Za-z0-9._:-]{1,128}. Проверенный JSON-запрос приводится к каноническому виду и хешируется SHA-256. Уникальное ограничение PostgreSQL разрешает гонку параллельных вставок между репликами. Сообщение и запись JSON-ответа фиксируются одной транзакцией; при ошибке транзакции не сохраняется ни то ни другое. Точный повтор в течение 24 часов возвращает тот же ответ 201 и то же сообщение; запрос с изменённым телом получает 409. После окончания срока хранения ключ можно использовать повторно при следующем запросе с этим ключом.
В памяти API не хранится состояние, от которого зависит корректность сессий, сообщений или идемпотентности. В Compose не задан container_name; сервис API запущен в двух репликах. Тома PostgreSQL и Redis используются только соответствующими хранилищами. Для каждого сервиса заданы ограничения CPU и памяти. Порты PostgreSQL и Redis не публикуются на хост.
Миграция развёртывается один раз и только добавляет новое. Миграция ЛР 3 создаёт таблицу идемпотентности и индекс; предыдущая версия API может продолжать обслуживать запросы во время добавления новой версии. Для более сложных изменений схемы потребуется миграция expand/contract и отдельно измеренное окно совместимости.
Подтверждения выполнения требований на оценку 4
Результаты ниже получены на запущенном стеке. Полный вывод команд и агрегаты нагрузки находятся в каталоге evidence/. Цели Make следует запускать в WSL/Ubuntu: Makefile использует python3 и команды POSIX shell.
| Критерий | Команда / сценарий | Полученный результат | Подтверждение |
|---|---|---|---|
| Публичный контракт API, включая конечные точки ЛР 2 | python tests/smoke.py --base-url http://localhost:8080 | PASS после последнего перезапуска с проверкой сохранности данных; все сервисы работоспособны | evidence/smoke.txt |
| Две реплики и параллельные POST одного сообщения с одинаковым ключом | python tests/idempotency_concurrency.py --base-url http://localhost:8080 | PASS: 24 запроса, 12 рабочих потоков, обнаружены 2 реплики, один ID сообщения и одна сохранённая копия | evidence/idempotency.txt |
| Сохранность данных после перезапуска API, Redis и PostgreSQL | python3 tests/resilience.py --mode persistence --action-script scripts/restart.sh --base-url http://localhost:8080 | PASS: подтверждённое сообщение и существующая сессия остались доступны; ручной перезапуск записан в журнал | evidence/persistence.txt, evidence/persistence-hook.log |
Переключение с реплики 46c9e552d0a0 |
bash scripts/verify-failover.sh replica-run-2 |
PASS: 51 подтверждённая запись в сценарии, 0 неудачных попыток, первое восстановление за 1,897 с. Параллельная нагрузка: 1 123 успешных / 0 неудачных запросов, 27,902 успешного запроса/с, p50 109,335 мс, p95 380,847 мс, p99 509,395 мс | evidence/failover-replica-run-2.log, evidence/failover-replica-run-2-load.json, evidence/stopped-replicas.txt |
Переключение с другой реплики 3375d99fba8b |
bash scripts/verify-failover.sh replica-run-3 |
PASS: 50 подтверждённых записей в сценарии, 0 неудачных попыток, первое восстановление за 1,955 с. Параллельная нагрузка: 1 162 успешных / 0 неудачных запросов, 28,919 успешного запроса/с, p50 107,255 мс, p95 352,709 мс, p99 439,816 мс | evidence/failover-distinct-3375.log, evidence/failover-distinct-3375-load.json, evidence/stopped-replicas.txt |
| Последовательная замена реплик под нагрузкой | bash scripts/verify-rolling.sh (последний запуск) | PASS: старые контейнеры API заменены по одному; 2 новые реплики работоспособны (revision=roll-20261110095038). Нагрузка 60,079 с: 2 881 успешный / 2 неудачных запроса, 0,0694% ошибок, 47,953 успешного запроса/с, p50 83,439 мс, p95 198,871 мс, p99 289,461 мс | evidence/rolling-update.log, evidence/rolling-update-load.json |
| Внутренние порты API, локальная точка входа и ограничения ресурсов | docker compose config и проверка запущенных сервисов | PASS: только LB публикует 127.0.0.1:8080; порты API доступны только внутри сети; для каждого сервиса заданы ограничения CPU и памяти | evidence/runtime-config.txt |
| Структура, публичный smoke-тест, OpenAPI и конфигурация Compose | make check; make test BASE_URL=http://localhost:8080; make validate PYTHON=.venv/bin/python; docker compose --env-file .env config --quiet |
PASS в WSL/Ubuntu и PowerShell | evidence/make-check.log, evidence/make-test.log, evidence/implementation-checks.txt |
Два измеряемых запуска, зачтённых в таблице, остановили разные экземпляры: 46c9e552d0a0 (2026-11-06T21:35:34Z) и 3375d99fba8b (2026-11-06T21:38:58Z). В более поздних записях evidence/stopped-replicas.txt также есть дополнительные остановки с ID 2f298bdf21b0, 3895110fa377 и 80747c6466aa; они не подменяют измерения, связанные с двумя подробными наборами нагрузки выше. Повторные запуски, где остановился один и тот же ID 74e4faa7a0f1, не засчитываются как проверка обеих реплик.
Одна предварительная попытка, evidence/failover-failover-2.log, завершилась до проверки отказа: тест не увидел две реплики. Она не засчитана. После пересоздания NGINX были проверены две реплики за балансировщиком; успешный дополнительный запуск сохранён в evidence/failover-rr-after-lb-recreate.log и evidence/failover-rr-after-lb-recreate-load.json.
Дополнительно позднее был выполнен официальный target make test-failover ACTION_SCRIPT=scripts/stop-one.sh BASE_URL=http://localhost:8080: PASS, 101 подтверждённая запись, 0 неудачных попыток, первое восстановление за 2,295 с. Сразу после hook команда docker compose --env-file .env ps -a показала остановленную реплику api-10 и оставшуюся healthy api-9; после bash scripts/recover-api.sh обе реплики снова были healthy. Этот запуск подтверждает сам сценарий Make, но не используется для RPS в таблице, так как отдельная нагрузка вместе с ним не сохранялась.
Последняя проверка последовательной замены завершилась с двумя работоспособными репликами; параллельная нагрузка зафиксировала 2 881 успешный и два неудачных запроса. Результат приведён без исключений. Генератор нагрузки работает по замкнутому циклу с параллелизмом 4; это небольшая демонстрация, а не проверка производительности для промышленной эксплуатации. Процентили рассчитаны только по успешным запросам.
Во время этих запусков не записывались выделенные Docker Desktop ресурсы CPU/ОЗУ и характеристики компьютера. Ограничения сервисов Compose указаны в compose.yaml. Не следует использовать результаты этого ноутбука как оценку производительности в промышленной среде.
Эксперименты и сбои
Нагрузка при проверке переключения длилась 40 секунд с параллелизмом 4; последняя проверка последовательной замены длилась 60,079 секунды с параллелизмом 4. Точные успешные запросы в секунду, число и доля ошибок, задержки p50/p95/p99 и время первого восстановления приведены в таблице и JSON-файлах. Ограничения сервисов: PostgreSQL — 1 CPU / 1 ГиБ; Redis — 0,25 CPU / 256 МиБ; миграция — 0,25 CPU / 256 МиБ; каждая реплика API — 0,50 CPU / 512 МиБ; NGINX — 0,25 CPU / 128 МиБ.
Ограничения
Решение демонстрирует восстановление после отказа одного процесса/контейнера API на одном Docker-хосте. Оно не обеспечивает устойчивость при отказе хоста, NGINX, PostgreSQL, Redis, сети или диска. NGINX обнаруживает недоступность upstream пассивно, поэтому первая попытка обращения к только что отказавшему узлу может завершиться ошибкой до его исключения из пула. AOF Redis с appendfsync everysec поддерживает обычные перезапуски с томом, но не гарантирует отсутствие потери данных при внезапном отказе хоста или диска. Нагрузочный тест — небольшой замкнутый сценарий, а не гарантия пропускной способности. Просроченные записи идемпотентности для ключей, которые больше не использовались, остаются в базе до запуска будущей задачи очистки.