forked from mtusi2026/mtusi2026lab3
Исходная точка lab3: код из solution/bvt2302-bodanyuk лабы 2, коммит ef44e48 (PR mtusi2026/mtusi2026lab2#42 принят). README, COURSE, contracts/ и tests/ преподавателя не тронуты; к Makefile дописан студенческий раздел lab2, .env.example — версия lab2. Исследование трека 2 lab2 (bench/track2) не переносилось. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
135 lines
8.3 KiB
Markdown
135 lines
8.3 KiB
Markdown
# Запуск на ноутбуке с Windows и сценарий защиты
|
||
|
||
Все команды — в **PowerShell**, из папки проекта. Внутри одного окна PowerShell переменные `$env:...` действуют до его закрытия.
|
||
|
||
## 1. Что установить один раз
|
||
|
||
| Программа | Зачем | Важно |
|
||
| --- | --- | --- |
|
||
| [Git for Windows](https://git-scm.com/download/win) | clone и Git Bash | ставить в путь по умолчанию `C:\Program Files\Git`: оттуда `scripts\restart.cmd` запускает `restart.sh` |
|
||
| [Docker Desktop](https://www.docker.com/products/docker-desktop/) | PostgreSQL, Valkey, API | backend WSL 2; в BIOS включена виртуализация; после установки перезагрузка |
|
||
| [Python 3.12+](https://www.python.org/downloads/windows/) | secrets, публичные тесты, свои тесты | галочка **Add python.exe to PATH**. Если `python` открывает Microsoft Store — отключить «Псевдонимы выполнения приложений» для python в настройках Windows |
|
||
|
||
Проверка:
|
||
|
||
```powershell
|
||
git --version; docker version --format '{{.Server.Version}}'; docker compose version; python --version
|
||
```
|
||
|
||
Docker Desktop должен быть **запущен** (кит в трее не мигает).
|
||
|
||
## 2. Развернуть проект (дома, заранее — нужен интернет)
|
||
|
||
```powershell
|
||
git clone https://gitea.privcloud.tech/wfa/mtusi2026lab2 mtusi2026lab2
|
||
cd mtusi2026lab2
|
||
git checkout solution/bvt2302-bodanyuk
|
||
python scripts\init_secrets.py
|
||
Copy-Item .env.example .env
|
||
docker compose --env-file .env up -d --build --wait
|
||
```
|
||
|
||
Первый запуск скачивает образы (~700 МБ) и собирает API — 3–10 минут. Сделайте это **дома**: в аудитории сеть может быть медленной. Последняя команда завершается, когда все сервисы `healthy`.
|
||
|
||
Проверка в браузере: http://127.0.0.1:8080/health/ready → `{"status":"ok"}`, Swagger — http://127.0.0.1:8080/docs.
|
||
|
||
Окружение для своих тестов (один раз):
|
||
|
||
```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
|
||
```
|
||
|
||
Активировать venv не нужно: везде вызывается `.venv\Scripts\python` напрямую, поэтому политика выполнения PowerShell не мешает.
|
||
|
||
## 3. Перед защитой (в аудитории)
|
||
|
||
```powershell
|
||
cd mtusi2026lab2
|
||
docker compose up -d --wait # если стенд был остановлен
|
||
$env:PYTHONUTF8 = "1" # публичные тесты читают UTF-8 JSON
|
||
python tests\smoke.py # PASS: lab2 public API scenario
|
||
```
|
||
|
||
## 4. Сценарий защиты из README — команды по шагам
|
||
|
||
**Шаг 1. Миграции к пустому volume, пользователи, вход, сообщение.**
|
||
|
||
```powershell
|
||
docker compose down -v # стереть учебные данные (volumes)
|
||
docker compose up -d --wait # postgres и valkey пустые -> migrate применяет схему
|
||
docker compose logs migrate # "0001_init: applied"
|
||
docker compose run --rm migrate # повтор: "already applied, skipped"
|
||
```
|
||
|
||
Дальше в Swagger (http://127.0.0.1:8080/docs):
|
||
1. `POST /api/v1/users` — создать двух пользователей (пароль 12+ символов).
|
||
2. **Authorize → basicAuth**: логин и пароль первого; `POST /api/v1/auth/sessions` — скопировать `token`.
|
||
3. **Authorize → bearerAuth**: вставить токен.
|
||
4. `POST /api/v1/chats` (в `member_ids` — оба id) → `POST /api/v1/chats/{chat_id}/messages` → `GET` истории.
|
||
|
||
**Шаги 2–3. Перезапуск API и хранилищ с сохранением volumes, тот же токен; logout → 401; короткий TTL.**
|
||
|
||
```powershell
|
||
python tests\resilience.py --mode persistence --action-script scripts\restart.cmd # PASS
|
||
docker compose ps # у api, postgres, valkey свежее время запуска
|
||
```
|
||
|
||
В Swagger тот же токен по-прежнему работает. `DELETE /api/v1/auth/sessions/current` → 204, затем любой запрос → 401.
|
||
|
||
Короткий TTL:
|
||
|
||
```powershell
|
||
$env:SESSION_TTL_SECONDS = "2"; docker compose up -d --wait api
|
||
docker compose exec api printenv SESSION_TTL_SECONDS # 2
|
||
# в Swagger: войти, сразу GET /users/me -> 200, через 3 секунды -> 401
|
||
Remove-Item Env:SESSION_TTL_SECONDS; docker compose up -d --wait api # вернуть 3600
|
||
```
|
||
|
||
**Шаг 4. Роль Valkey, план SQL, ошибка зависимости.**
|
||
|
||
```powershell
|
||
# Сессии лежат только в Valkey: ключи session:<sha256 токена>, самих токенов там нет
|
||
# (без двойных кавычек внутри: PowerShell 5.1 ломает их при передаче в docker)
|
||
docker compose exec valkey sh -c 'REDISCLI_AUTH=$(cat /run/secrets/valkey_password) valkey-cli --scan --pattern ''session:*'''
|
||
|
||
# План: поздняя страница по индексу (Index Cond) против IS NULL OR и OFFSET, 20 000 сообщений
|
||
.venv\Scripts\python scripts\explain_history.py
|
||
|
||
# Ошибка зависимости: с действующим токеном -> 503, без токена -> 401, после старта всё работает
|
||
docker compose stop valkey # или: docker compose pause postgres
|
||
# в Swagger: GET /users/me -> 503 unavailable; GET /health/ready -> 503
|
||
docker compose start valkey # или: docker compose unpause postgres
|
||
```
|
||
|
||
Всё то же автоматически, с восстановлением в `finally`, около 1 минуты:
|
||
|
||
```powershell
|
||
.venv\Scripts\python -m pytest student-tests\test_failures.py -v
|
||
```
|
||
|
||
**Трек 2 вживую.**
|
||
|
||
```powershell
|
||
.venv\Scripts\python bench\track2\backup_restore.py --repeats 1 # ~1 мин: dump во время записи -> restore в новый контейнер -> сверка
|
||
```
|
||
|
||
Скрипт печатает время дампа и восстановления, `reconciled: true` и сколько сообщений записано после снимка (RPO). Полный замер планов идёт ~25 минут, поэтому на защите показывайте готовые результаты: `evidence\track2\summary.md` и `evidence\track2\plans.png`. При желании можно запустить `.venv\Scripts\python bench\track2\index_sizes.py` (~2 мин).
|
||
|
||
**Все свои тесты** (~3,5 мин): `.venv\Scripts\python -m pytest student-tests -v`.
|
||
|
||
## 5. Если что-то пошло не так
|
||
|
||
| Симптом | Что сделать |
|
||
| --- | --- |
|
||
| `error during connect … dockerDesktopLinuxEngine` | Docker Desktop не запущен — запустить и подождать минуту |
|
||
| `port is already allocated` на 8080 | в `.env` поставить `APP_PUBLISH_PORT=8081`; дальше тесты с `--base-url http://127.0.0.1:8081` (smoke и resilience), для pytest — `$env:BASE_URL="http://127.0.0.1:8081"` |
|
||
| `secrets/... not found` при `up` | не выполнен `python scripts\init_secrets.py` |
|
||
| `UnicodeDecodeError` в `tests\*.py` | не задан `$env:PYTHONUTF8 = "1"` |
|
||
| `restart.cmd`: «не удаётся найти путь» | Git установлен не в `C:\Program Files\Git` — поправить путь в `scripts\restart.cmd` |
|
||
| api `unhealthy` после сна ноутбука | `docker compose restart` и подождать `docker compose ps` |
|
||
| нужно начать с чистого листа | `docker compose down -v` (удаляет учебные данные) → `docker compose up -d --wait` |
|
||
|
||
Остановить стенд после защиты: `docker compose down` (данные сохранятся) или `docker compose down -v` (данные удаляются).
|