forked from mtusi2026/mtusi2026lab4
Исходники, Dockerfile, compose.yaml, скрипты и собственные тесты скопированы из mtusi2026lab3 (ветка solution/bvt2302-bodanyuk, b6847e2) как есть; изменения lab4 — отдельными коммитами. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
139 lines
10 KiB
Markdown
139 lines
10 KiB
Markdown
# Запуск на ноутбуке с Windows и сценарий защиты ЛР 3
|
||
|
||
Команды — в **PowerShell** из папки проекта (где лежит `compose.yaml`). Переменные `$env:...` действуют до закрытия окна.
|
||
|
||
## 1. Что установить один раз
|
||
|
||
| Программа | Зачем | Важно |
|
||
| --- | --- | --- |
|
||
| [Git for Windows](https://git-scm.com/download/win) | clone и Git Bash | путь по умолчанию `C:\Program Files\Git`: оттуда `scripts\*.cmd` запускают `.sh`-хуки |
|
||
| [Docker Desktop](https://www.docker.com/products/docker-desktop/) | PostgreSQL, Valkey, HAProxy, API | backend WSL 2, виртуализация в BIOS; для трека 1 в Settings → Resources дать **8 CPU** |
|
||
| [Python 3.12+](https://www.python.org/downloads/windows/) | secrets, публичные и свои тесты, скрипты замеров | галочка **Add python.exe to PATH** |
|
||
| GNU make (необязательно) | `make check/test/test-failover …` | `winget install ezwinports.make`, затем **новое** окно PowerShell. Рецептам Makefile нужен `sh`: в каждом окне PowerShell один раз `$env:Path += ";C:\Program Files\Git\usr\bin"` (или запускать make из Git Bash). Без make те же команды есть в таблице REPORT.md |
|
||
|
||
Проверка:
|
||
|
||
```powershell
|
||
git --version; docker version --format '{{.Server.Version}}'; docker compose version; python --version; make --version
|
||
```
|
||
|
||
## 2. Развернуть проект (дома, заранее — нужен интернет)
|
||
|
||
```powershell
|
||
git clone https://gitea.privcloud.tech/wfa/mtusi2026lab3 mtusi2026lab3
|
||
cd mtusi2026lab3
|
||
git checkout solution/bvt2302-bodanyuk
|
||
python scripts\init_secrets.py # случайные пароли в .\secrets (не в Git)
|
||
Copy-Item .env.example .env
|
||
docker compose --env-file .env config --quiet # конфигурация собирается без ошибок
|
||
docker compose --env-file .env up -d --build --wait
|
||
```
|
||
|
||
Первый запуск качает образы (~800 МБ) и собирает API — 3–10 минут. Команда завершается, когда postgres, valkey, обе реплики api и lb в состоянии `healthy`, а `migrate` завершился с кодом 0.
|
||
|
||
Окружение для своих тестов и скриптов (один раз):
|
||
|
||
```powershell
|
||
python -m venv .venv
|
||
.venv\Scripts\python -m pip install --require-hashes --no-deps -r requirements.txt
|
||
.venv\Scripts\python -m pip install -r requirements-test.txt -r requirements-dev.txt
|
||
$env:PYTHONUTF8 = "1" # публичные тесты читают UTF-8 JSON
|
||
```
|
||
|
||
Проверка в браузере: http://127.0.0.1:8080/health/ready → `{"status":"ok"}`; Swagger — http://127.0.0.1:8080/docs; состояние балансировщика (какие реплики UP/DOWN) — http://127.0.0.1:8404/.
|
||
|
||
## 3. Перед защитой (в аудитории)
|
||
|
||
```powershell
|
||
cd mtusi2026lab3
|
||
$env:PYTHONUTF8 = "1"
|
||
$env:Path += ";C:\Program Files\Git\usr\bin" # sh для рецептов Makefile
|
||
docker compose up -d --wait # если стенд был остановлен
|
||
make check test PYTHON=python # или: python scripts\check_contract.py; python tests\smoke.py
|
||
python scripts\lbctl.py status # обе реплики UP
|
||
```
|
||
|
||
## 4. Сценарий защиты из README — по шагам
|
||
|
||
**Шаг 1. ≥ 2 разных `X-Instance-Id` через LB с одной сессией.**
|
||
|
||
```powershell
|
||
python scripts\lbctl.py replicas # контейнеры api: имя, X-Instance-Id (= hostname), PID, IP
|
||
# Один пользователь, один токен, 6 запросов подряд через LB — номера реплик чередуются:
|
||
$u = "demo_" + (Get-Random); $p = "Demo-password-123"
|
||
Invoke-RestMethod -Method Post http://127.0.0.1:8080/api/v1/users -ContentType 'application/json' -Body (@{username=$u; display_name='Демо'; password=$p} | ConvertTo-Json)
|
||
$basic = [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes("${u}:${p}"))
|
||
$t = (Invoke-RestMethod -Method Post http://127.0.0.1:8080/api/v1/auth/sessions -Headers @{Authorization="Basic $basic"}).token
|
||
1..6 | ForEach-Object { (Invoke-WebRequest http://127.0.0.1:8080/api/v1/users/me -Headers @{Authorization="Bearer $t"} -UseBasicParsing).Headers['X-Instance-Id'] }
|
||
```
|
||
|
||
Повторный вход не нужен: сессия лежит в общем Valkey. То же автоматически: `.venv\Scripts\python -m pytest student-tests\test_balancing.py -k one_session -v`.
|
||
|
||
**Шаг 2. Отказ реплики публичным тестом.**
|
||
|
||
```powershell
|
||
make test-failover ACTION_SCRIPT=scripts/stop-one.cmd PYTHON=python
|
||
# без make: python tests\resilience.py --mode failover --action-script scripts\stop-one.cmd
|
||
```
|
||
|
||
Тест сам выбирает реплику, обслужившую его первое сообщение, и передаёт её `X-Instance-Id` хуку. Хук останавливает именно этот контейнер и оставляет его остановленным. Вариант «падение процесса» — `$env:STOP_MODE = "kill"` перед командой (SIGKILL), вернуть — `Remove-Item Env:STOP_MODE`.
|
||
|
||
**Шаг 3. Показать, какой контейнер действительно остановлен, и повторить для второй.**
|
||
|
||
```powershell
|
||
python scripts\lbctl.py replicas # у остановленной: exited, exit_code 0 (stop) или 137 (kill)
|
||
python scripts\lbctl.py status # её слот в HAProxy — MAINT/DOWN, вторая UP
|
||
docker compose logs --tail 20 api # drain_started -> shutdown_requested -> stopped у остановленной
|
||
make restore PYTHON=python # или: & "C:\Program Files\Git\bin\bash.exe" scripts/restore-api.sh; python scripts\lbctl.py wait-up 2
|
||
make test-failover ACTION_SCRIPT=scripts/stop-one.cmd PYTHON=python
|
||
```
|
||
|
||
Тест останавливает ту реплику, которая обслужила его первое сообщение, поэтому для второй он может снова выбрать прежнюю. Детерминированно по очереди каждую реплику останавливает серия уровня 4 (~5 мин): `python bench\failover_series.py --output evidence\failover` (stop, kill и pause для каждой реплики, с восстановлением предыдущей).
|
||
|
||
**Шаг 4. Restart всего стенда с сохранением volumes и прежним токеном.**
|
||
|
||
```powershell
|
||
make test-persistence ACTION_SCRIPT=scripts/restart.cmd PYTHON=python
|
||
python scripts\lbctl.py replicas # у всех api свежий started и новый PID; LB снова видит обе реплики
|
||
docker compose ps # postgres, valkey, lb — тоже «Up N seconds»
|
||
```
|
||
|
||
**Уровень 4 вживую.**
|
||
|
||
```powershell
|
||
# Неготовая, но живая реплика исключается из LB (pg_hba reject и docker network disconnect), ~1 мин:
|
||
.venv\Scripts\python -m pytest student-tests\test_balancing.py -k not_ready -v -s
|
||
# Rolling update под нагрузкой (~1,5 мин): новая ревизия на обеих репликах, 0 ошибок
|
||
python bench\rolling_under_load.py --output evidence\rolling-update
|
||
# Одновременные повторы с одним ключом через разные реплики:
|
||
.venv\Scripts\python -m pytest student-tests\test_idempotency.py -k concurrent -v
|
||
```
|
||
|
||
**Трек 1.** Полная серия идёт часы, поэтому на защите — готовые результаты: [evidence/track1/summary.md](../evidence/track1/summary.md) и графики `evidence/track1/*/*/throughput.svg`. Вживую можно показать профиль одной реплики (~2 мин) и одну короткую серию (~6 мин):
|
||
|
||
```powershell
|
||
docker compose stop # основной стенд не должен мешать замеру
|
||
python bench\track1\profile.py --label demo --rate 240
|
||
python bench\track1\run.py --series demo --label now --rates 150,250,350 --repeats 1 --config replicas=2,MESSAGE_WRITE_PATH=multi --config replicas=2,MESSAGE_WRITE_PATH=function
|
||
docker compose up -d --wait # вернуть основной стенд
|
||
```
|
||
|
||
**Все свои тесты** (~8 мин): `.venv\Scripts\python -m pytest student-tests -v`.
|
||
|
||
## 5. Если что-то пошло не так
|
||
|
||
| Симптом | Что сделать |
|
||
| --- | --- |
|
||
| `error during connect … dockerDesktopLinuxEngine` | Docker Desktop не запущен — запустить и подождать минуту |
|
||
| `port is already allocated` на 8080/8404 | занято другим стендом (lab2: `docker compose -p mtusi-lab2 stop`) или в `.env` поставить `APP_PUBLISH_PORT=8081`, `LB_STATS_PORT=8405`; тестам — `--base-url http://127.0.0.1:8081` / `$env:BASE_URL` |
|
||
| `secrets/... not found` при `up` | не выполнен `python scripts\init_secrets.py` |
|
||
| `UnicodeDecodeError` в `tests\*.py` | не задан `$env:PYTHONUTF8 = "1"` |
|
||
| `*.cmd`: «не удаётся найти путь» | Git установлен не в `C:\Program Files\Git` — поправить путь в `scripts\*.cmd` |
|
||
| `make: command not found` | новое окно PowerShell после установки make или команды без make из REPORT.md |
|
||
| make: `'test' is not recognized` | в этом окне не добавлен `C:\Program Files\Git\usr\bin` в `$env:Path` (рецептам нужен `sh`) |
|
||
| после `stop-one` в LB одна реплика | так и задумано; вернуть: `make restore PYTHON=python` |
|
||
| api `unhealthy` после сна ноутбука | `docker compose restart` и `python scripts\lbctl.py wait-up 2` |
|
||
| нужно начать с чистого листа | `docker compose down -v` (удаляет учебные данные) → `docker compose up -d --build --wait` |
|
||
|
||
Остановить стенд после защиты: `docker compose down` (данные сохранятся) или `docker compose down -v` (данные удаляются).
|