docs: адрес форка и инструкция для Windows

This commit is contained in:
Alexey Bodanyuk
2026-10-13 10:32:58 +03:00
parent f469b8efcc
commit ef44e48464
2 changed files with 137 additions and 3 deletions
+3 -3
View File
@@ -2,17 +2,17 @@
- Автор, группа: Боданюк Алексей, БВТ2302
- Целевая оценка: **5**, трек 2 «План запроса и восстановление»
- Ветка: `solution/bvt2302-bodanyuk`. Форк: `<URL форка>`. PR: «ЛР 2 — БВТ2302 — Боданюк — на 5» в mtusi2026/mtusi2026lab2
- Ветка: `solution/bvt2302-bodanyuk`. Форк: `https://gitea.privcloud.tech/wfa/mtusi2026lab2`. PR: «ЛР 2 — БВТ2302 — Боданюк — на 5» в mtusi2026/mtusi2026lab2
- Стек: Python 3.13.16, Starlette 1.7.0, uvicorn 0.54.0, psycopg 3.3.6 + psycopg-pool 3.3.3, redis-py 8.1.0 (протокол Valkey), argon2-cffi 25.1.0; PostgreSQL 18.6, Valkey 8.1.3. Все образы закреплены по тегу и digest, все Python-пакеты — по хешам ([requirements.txt](requirements.txt))
- Источники: README, COURSE, контракт ([openapi.json](contracts/openapi.json), [семантика](contracts/README.md)), документация PostgreSQL (transactions, EXPLAIN, pg_dump/pg_restore, pgbench), Valkey persistence, RFC 7617, OWASP Password Storage Cheat Sheet (параметры Argon2id). Учтены замечания преподавателя к PR других студентов этого репозитория (см. раздел «Проверки, на которых ловили другие работы»)
- Помощь ИИ: код, тесты, скрипты эксперимента и черновик отчёта написаны с помощью ИИ-ассистента Claude Code (Anthropic). Все команды и замеры реально выполнены на стенде ниже, их вывод лежит в [evidence/](evidence/). Пояснения для защиты — [docs/DEFENSE.md](docs/DEFENSE.md)
- Помощь ИИ: код, тесты, скрипты эксперимента и черновик отчёта написаны с помощью ИИ-ассистента Claude Code (Anthropic). Все команды и замеры реально выполнены на стенде ниже, их вывод лежит в [evidence/](evidence/). Пояснения для защиты — [docs/DEFENSE.md](docs/DEFENSE.md), запуск на Windows и сценарий защиты по шагам — [docs/WINDOWS.md](docs/WINDOWS.md)
## Запуск из чистого clone
Нужны Git, Docker с Compose v2 (проверено: Docker 29.8.0, Compose 5.5.1) и Python 3.9+ (secrets, публичные тесты). Для своих тестов нужен venv. Учётные данные не хранятся в Git: их создаёт скрипт.
```sh
git clone <URL форка> mtusi2026lab2 && cd mtusi2026lab2 && git checkout solution/bvt2302-bodanyuk
git clone https://gitea.privcloud.tech/wfa/mtusi2026lab2 mtusi2026lab2 && cd mtusi2026lab2 && git checkout solution/bvt2302-bodanyuk
python3 scripts/init_secrets.py # случайные локальные пароли -> ./secrets (git-ignored), идемпотентно
cp .env.example .env # необязательно: значения по умолчанию заданы в compose.yaml
docker compose --env-file .env config --quiet
+134
View File
@@ -0,0 +1,134 @@
# Запуск на ноутбуке с 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` (данные удаляются).