forked from mtusi2026/mtusi2026lab2
docs: адрес форка и инструкция для Windows
This commit is contained in:
@@ -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
@@ -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` (данные удаляются).
|
||||
Reference in New Issue
Block a user