Files
2026-11-13 00:45:56 +03:00

120 lines
19 KiB
Markdown
Raw Permalink 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 — балансировка реплик мессенджера
- Автор / группа: Бадрадин Али / БВТ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:
~~~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 поддерживает обычные перезапуски с томом, но не гарантирует отсутствие потери данных при внезапном отказе хоста или диска. Нагрузочный тест — небольшой замкнутый сценарий, а не гарантия пропускной способности. Просроченные записи идемпотентности для ключей, которые больше не использовались, остаются в базе до запуска будущей задачи очистки.