forked from mtusi2026/mtusi2026lab5
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
115 lines
7.7 KiB
Markdown
115 lines
7.7 KiB
Markdown
# Запуск на ноутбуке с Windows и сценарий защиты ЛР 5
|
||
|
||
Команды — в **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, SeaweedFS (S3), RabbitMQ, HAProxy, API, relay, worker | backend WSL 2; в Settings → Resources ≥ 4 CPU и ≥ 8 ГБ RAM (сумма лимитов контейнеров ~6,5 ГБ) |
|
||
| [Python 3.12+](https://www.python.org/downloads/windows/) | secrets, публичные и свои тесты, сценарии | галочка **Add python.exe to PATH** |
|
||
| GNU make (необязательно) | `make check/test/...` | `winget install ezwinports.make`, затем **новое** окно; в каждом окне `$env:Path += ";C:\Program Files\Git\usr\bin"` (рецептам нужен `sh`) |
|
||
|
||
## 2. Развернуть проект (заранее, нужен интернет)
|
||
|
||
```powershell
|
||
git clone https://gitea.privcloud.tech/wfa/mtusi2026lab5 mtusi2026lab5
|
||
cd mtusi2026lab5
|
||
git checkout solution/bvt2302-bodanyuk
|
||
python scripts\init_secrets.py # пароли БД/Valkey, 4 пары ключей S3, пользователи RabbitMQ -> .\secrets
|
||
Copy-Item .env.example .env
|
||
docker compose --env-file .env config --quiet
|
||
docker compose --env-file .env up -d --build --wait
|
||
```
|
||
|
||
Первый запуск качает образы (~1,2 ГБ) и собирает образ приложения — 3–10 минут. Команда завершается, когда postgres, valkey, s3, broker, обе реплики api, lb, relay и worker в `healthy`, а `migrate` и `s3-init` вышли с кодом 0. Проверки прав S3: `docker compose logs s3-init`.
|
||
|
||
Окружение для своих тестов (один раз):
|
||
|
||
```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
|
||
```
|
||
|
||
Стенды ЛР 3/4 занимают порт 8080 — остановить: `docker compose -p mtusi-lab4 stop` (данные сохранятся).
|
||
|
||
## 3. Перед защитой
|
||
|
||
```powershell
|
||
$env:PYTHONUTF8 = "1"; $env:Path += ";C:\Program Files\Git\usr\bin"
|
||
docker compose up -d --wait
|
||
make check test PYTHON=python # 202 -> ready, настоящий JPEG 256x160
|
||
make jobs # задания по состояниям, хвост outbox
|
||
```
|
||
|
||
## 4. Сценарий защиты README — по шагам
|
||
|
||
**Шаг 1. `make test`**: API возвращает 202, GET доходит до ready, оригинал и настоящий JPEG thumbnail проверяются (см. раздел 3).
|
||
|
||
**Шаги 2–3. Worker остановлен → 202 → content 409 → рестарт API и брокера с volumes → worker → ready.** Скрипт печатает каждый шаг, ID вложения и сообщения, код ответа; токены не печатает:
|
||
|
||
```powershell
|
||
.venv\Scripts\python scripts\demo_pipeline.py
|
||
```
|
||
|
||
Что он делает:
|
||
1. `docker compose stop worker`;
|
||
2. upload → **202 queued**; `GET /content` и `?variant=thumbnail` → **409**; обычное сообщение → 201; сообщение с этим вложением → 201;
|
||
3. показывает строку outbox (`published_at` заполнен — relay получил confirm) и глубину очереди `messenger.attachment-jobs` (1);
|
||
4. `docker compose restart api broker` (volumes не трогаются), ждёт готовности; очередь снова показывает 1, вложение по-прежнему `queued`;
|
||
5. `docker compose start worker` → **ready**, скачивает thumbnail (JPEG 256×160), сверяет SHA-256 и размеры;
|
||
6. печатает журнал задания (`jobctl show`): `created → claimed → succeeded`, одна попытка.
|
||
|
||
То же автоматически: `.venv\Scripts\python -m pytest student-tests\test_pipeline_flow.py -k worker_stopped -v`.
|
||
|
||
**Шаг 4. Уровень 4 вживую.**
|
||
|
||
```powershell
|
||
# crash после записи в S3 до ack/COMMIT; разрыв COMMIT/publish; publish/confirm:
|
||
.venv\Scripts\python -m pytest student-tests\test_pipeline_flow.py -k "crash or broker_down or relay" -v
|
||
# retry с backoff, retry_exhausted -> реестр failed -> replay; replay готового -> отказ:
|
||
.venv\Scripts\python -m pytest student-tests\test_pipeline_flow.py -k "retry or permanent" -v
|
||
make failed # реестр failed
|
||
docker compose run --rm --no-deps jobctl replay <attachment_id> --operator alice --reason "причина устранена"
|
||
docker compose run --rm --no-deps jobctl show <attachment_id> # задания, попытки, аудит
|
||
# зависший worker (docker pause) теряет lease, второй worker публикует, первый не может:
|
||
.venv\Scripts\python -m pytest student-tests\test_pipeline_flow.py -k hung -v -s
|
||
```
|
||
|
||
**Трек 2 вживую.**
|
||
|
||
```powershell
|
||
make audit # инварианты I1-I7 по всей БД и обоим bucket (read-only)
|
||
.venv\Scripts\python bench\pipeline_faults.py --output evidence\track2-demo --uploads 3 # ~15 мин
|
||
```
|
||
|
||
Готовые результаты: [evidence/track2/summary.txt](../evidence/track2/summary.txt).
|
||
|
||
**Публичные проверки сохранности и failover.**
|
||
|
||
```powershell
|
||
make test-persistence ACTION_SCRIPT=scripts/restart.cmd PYTHON=python # restart всего стенда с volumes
|
||
make test-failover ACTION_SCRIPT=scripts/stop-one.cmd PYTHON=python
|
||
make restore PYTHON=python
|
||
```
|
||
|
||
**Все свои тесты** (~40 мин): `.venv\Scripts\python -m pytest student-tests -v`.
|
||
|
||
## 5. Если что-то пошло не так
|
||
|
||
| Симптом | Что сделать |
|
||
| --- | --- |
|
||
| `error during connect … dockerDesktopLinuxEngine` | Docker Desktop не запущен — запустить и подождать минуту |
|
||
| `port is already allocated` на 8080/8404 | стенд lab3/lab4 (`docker compose -p mtusi-lab4 stop`) или в `.env` `APP_PUBLISH_PORT=8081`, `LB_STATS_PORT=8405` |
|
||
| `secrets/... not found` | не выполнен `python scripts\init_secrets.py` |
|
||
| `s3-init` exit 1 | `docker compose logs s3-init`: какая проверка доступа не прошла |
|
||
| broker долго `starting` | первый старт RabbitMQ ~20 с; `docker compose logs broker` |
|
||
| вложение висит в `queued` | `make jobs`: если `outbox_due > 0` — смотреть `docker compose logs relay`; если очередь не пуста — `docker compose logs worker` |
|
||
| `UnicodeDecodeError` в `tests\*.py` | не задан `$env:PYTHONUTF8 = "1"` |
|
||
| локальный `.env` устарел | сравнить с `.env.example`: значения `.env` перекрывают умолчания compose |
|
||
| начать с чистого листа | `docker compose down -v` (удаляет учебные данные: БД, bucket, очередь) → `up -d --build --wait` |
|
||
|
||
Остановить после защиты: `docker compose down` (данные сохранятся).
|