Files
mtusi2026lab3-fork/GUIDE.md
T
2026-11-02 20:05:33 +03:00

6.6 KiB

Работа со стендом lab3

Подготовка и запуск

Команды выполняются в корне проекта в Linux/macOS или WSL2. Нужны Docker Engine, Compose v2.24+ и Python 3.9+ на хосте. Python-зависимости API устанавливаются в образе.

cp env.lab3.template .env
# Откройте .env и смените POSTGRES_PASSWORD: случайные ASCII буквы и цифры.
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
python3 scripts/replicas.py restore
make replicas

db хранит данные в именованном томе pgdata; migrate должен завершиться с кодом 0. API начинают работу только после него. Команда restore ждёт готовности обеих API и появления обоих alias через LB. API, PostgreSQL и Redis не публикуют host-порты. В .env нет обязательных внешних сервисов. Redis можно отключить: CACHE_URL=.

Не запускайте lab2 и lab3 одновременно на одном порту 8080. У них разные имена Compose project и томов; lab3 с нуля не импортирует старый volume lab2 автоматически.

Проверки

make check
make test
make test-student
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
make replicas
make restore
make test-persistence ACTION_SCRIPT=scripts/restart.sh

make test и проверки отказа идут через Nginx. Собственные pytest-тесты используют отдельную БД messenger_test и Redis DB 15; проверка гонки запускает два приложения с отдельными engine и alias, использующими одну БД.

Hook отказа получает TARGET_INSTANCE_ID от публичного теста. Он опрашивает readiness внутри реальных контейнеров через docker compose exec, сопоставляет alias со службой и вызывает docker compose stop --timeout 6 только для неё. Нельзя заменять этот hook командой, которая лишь меняет заголовок или немедленно поднимает остановленную реплику.

Полный сбор доказательств уровня 4

После запуска стенда:

make lab3-evidence

Сценарий создаёт синтетические данные, выполняет smoke, 12 одновременных повторов одного ключа через LB, останавливает каждую реплику и восстанавливает её перед проверкой следующей. Затем выполняет публичный failover, заменяет по очереди обе API под нагрузкой, перезапускает весь стенд с прежними токенами и запускает pytest. Результаты — evidence/lab3/. По умолчанию каждая нагрузочная фаза длится не менее 20 секунд, 2 closed-loop клиента выполняют POST+GET. Нет обещания универсального RPS.

python3 scripts/lab3_evidence.py --duration 30 --output evidence/lab3-run2

Не запускайте параллельно несколько сборщиков или rolling/failover: они управляют одними контейнерами. Сохраните evidence/lab3/ после успешного прогона и перенесите реальные числа в REPORT.md. Если возникла ошибка, сборщик пишет FAIL и пытается восстановить обе API; проверьте make replicas и выполните make restore.

Поочерёдное обновление

Для новой версии с обратно совместимым изменением схемы:

docker compose --env-file .env build api-a migrate
docker compose --env-file .env run --rm --no-deps migrate
make rolling

Образ собирается один раз под API_IMAGE. Старые контейнеры продолжают работать со старым образом до пересоздания. Скрипт сначала проверяет вторую API, исключает обновляемую из upstream через marker в Nginx, ждёт применения конфига и завершения старых workers, пересоздаёт контейнер, ждёт readiness и возвращает backend в LB. Затем проверяет оба alias через LB и переходит ко второй реплике.

Это rolling эквивалент для двух Compose-services, не встроенный rolling update Compose и не обновление PostgreSQL/Nginx. make lab3-evidence проверяет такую же поочерёдную замену под нагрузкой, но без изменения бизнес-версии образа. Несовместимая миграция требует отдельного окна обслуживания; см. REPORT.md.

Диагностика и остановка

docker compose --env-file .env ps -a
make replicas
docker compose --env-file .env logs --tail 100 api-a api-b nginx migrate
docker compose --env-file .env exec nginx cat /tmp/backends.conf
make restore
docker compose --env-file .env stop

stop и down сохраняют pgdata. down -v удаляет данные и для доказательства persistence не используется. В логах нет токенов, паролей и текста сообщений.

Запуск unit-тестов без Docker

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt -r requirements-test.txt
.venv/bin/python -m pytest -q unit-tests

Эти тесты подменяют внешние зависимости. Они проверяют HTTP-валидацию, заголовки, ошибки, отзыв сессии и SIGTERM; они не доказывают конкурентность PostgreSQL и работу Nginx. Для повторного сохранения локальных результатов установите также requirements-dev.txt и выполните python scripts/local_evidence.py.