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

117 lines
6.6 KiB
Markdown
Raw 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.
# Работа со стендом lab3
## Подготовка и запуск
Команды выполняются в корне проекта в Linux/macOS или WSL2. Нужны Docker Engine,
Compose v2.24+ и Python 3.9+ на хосте. Python-зависимости API устанавливаются в образе.
```sh
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 автоматически.
## Проверки
```sh
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
После запуска стенда:
```sh
make lab3-evidence
```
Сценарий создаёт синтетические данные, выполняет smoke, 12 одновременных повторов
одного ключа через LB, останавливает **каждую** реплику и восстанавливает её перед
проверкой следующей. Затем выполняет публичный failover, заменяет по очереди обе
API под нагрузкой, перезапускает весь стенд с прежними токенами и запускает pytest.
Результаты — `evidence/lab3/`. По умолчанию каждая нагрузочная фаза длится не менее
20 секунд, 2 closed-loop клиента выполняют POST+GET. Нет обещания универсального RPS.
```sh
python3 scripts/lab3_evidence.py --duration 30 --output evidence/lab3-run2
```
Не запускайте параллельно несколько сборщиков или rolling/failover: они управляют
одними контейнерами. Сохраните `evidence/lab3/` после успешного прогона и перенесите
реальные числа в REPORT.md. Если возникла ошибка, сборщик пишет FAIL и пытается
восстановить обе API; проверьте `make replicas` и выполните `make restore`.
## Поочерёдное обновление
Для новой версии с обратно совместимым изменением схемы:
```sh
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.
## Диагностика и остановка
```sh
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
```sh
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`.