Files
mtusi2026lab4/docs/WINDOWS.md
T
Alexey BodanyukandClaude Opus 5.5 4ea6924db1 lab4: память загрузок и S3 под лимитом, документация защиты
- тело загрузки: один буфер ровно Content-Length, без копий до S3 и djpeg;
- PNG: zlib получает вход кусками по 64 KiB (unconsumed_tail копировал остаток IDAT);
- djpeg, убитый OOM-killer'ом, -> 503 (ресурсы сервера), а не 415;
- api: memswap_limit = memory (жёсткий лимит без swap); S3: GOMEMLIMIT и лимиты
  одновременных загрузок SeaweedFS, память 1g;
- docs: CONSISTENCY.md, DEFENSE.md, WINDOWS.md, DATA_MODEL.md под lab4;
  scripts/demo_attachments.py для сценария защиты; CI и collect_evidence под lab4;
- bench/reconcile_faults.py: отчёты трека 2 (ошибки с обеих сторон, прерванный apply).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-25 14:21:43 +03:00

123 lines
8.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Запуск на ноутбуке с Windows и сценарий защиты ЛР 4
Команды — в **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), HAProxy, API | backend WSL 2, виртуализация в BIOS; в Settings → Resources ≥ 4 CPU и ≥ 6 ГБ RAM |
| [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`: в каждом окне один раз `$env:Path += ";C:\Program Files\Git\usr\bin"` |
## 2. Развернуть проект (дома, заранее — нужен интернет)
```powershell
git clone https://gitea.privcloud.tech/wfa/mtusi2026lab4 mtusi2026lab4
cd mtusi2026lab4
git checkout solution/bvt2302-bodanyuk
python scripts\init_secrets.py # случайные пароли и 3 пары ключей S3 в .\secrets (не в Git)
Copy-Item .env.example .env
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --wait
```
Первый запуск качает образы (~1 ГБ) и собирает API — 3–10 минут. Команда завершается, когда postgres, valkey, s3, обе реплики api и lb в состоянии `healthy`, а `migrate` и `s3-init` завершились с кодом 0. Вердикты bootstrap 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
$env:PYTHONUTF8 = "1"
```
Если запущен стенд lab3, он занимает порт 8080: `docker compose -p mtusi-lab3 stop` (данные lab3 сохранятся).
## 3. Перед защитой
```powershell
cd mtusi2026lab4
$env:PYTHONUTF8 = "1"; $env:Path += ";C:\Program Files\Git\usr\bin"
docker compose up -d --wait
make check test PYTHON=python # или: python tests\smoke.py
python scripts\lbctl.py status # обе реплики UP
```
## 4. Сценарий защиты из README — по шагам
**Шаг 1. Загрузить fixture, отправить сообщение, скачать вторым участником, сравнить SHA-256.**
```powershell
.venv\Scripts\python scripts\demo_attachments.py
```
Скрипт печатает каждый запрос и ответ: регистрирует alice, bob и eve, создаёт чат alice+bob, загружает `tests/fixtures/sample.png` (201 ready, sha256), отправляет сообщение с `attachment_ids` и `text=""`. Затем bob скачивает файл, SHA-256 совпадает. Для eve (посторонний) — 404 на метаданные и на байты. Отдельно показано, что ключ объекта в S3 случайный и в API не раскрывается.
**Шаг 2. Прямой неаутентифицированный GET к S3 не отдаёт объект.** Скрипт из шага 1 в конце делает изнутри сети `storage` (снаружи S3 не опубликован) анонимный GET того же объекта и анонимный листинг bucket — оба 403. Тот же GET, подписанный ключом API, — 200. Вручную:
```powershell
docker compose logs s3-init # anonymous GET/LIST -> 403, права ключей api/reconciler
.venv\Scripts\python -m pytest student-tests\test_storage_failures.py -k private -v
```
**Шаг 3. Persistence и failover: общий тест сохраняет и заново читает оригинал через API.**
```powershell
make test-persistence ACTION_SCRIPT=scripts/restart.cmd PYTHON=python # restart lb, api, postgres, valkey, s3
docker compose ps # у всех «Up N seconds»
make test-failover ACTION_SCRIPT=scripts/stop-one.cmd PYTHON=python
python scripts\lbctl.py replicas # остановленная — exited
make restore PYTHON=python
```
Для второй реплики: сдвинуть round-robin одним запросом (`Invoke-WebRequest http://127.0.0.1:8080/health/live -UseBasicParsing | Out-Null`) и повторить `make test-failover`. Загрузка → kill обслужившей реплики → скачивание через другую: `.venv\Scripts\python -m pytest student-tests\test_storage_failures.py -k failover -v`.
**Шаг 4. На API нет локального файла оригинала.**
```powershell
.venv\Scripts\python -m pytest student-tests\test_attachments.py -k not_stored -v # find по ФС реплик
docker compose config --format json | Select-String '"volumes"' # у api нет volume
```
**Уровень 4 вживую.**
```powershell
# Отказ S3 (stop и pause): readiness 503, загрузка 503 за < 8 с, текст работает (деградированный режим LB):
.venv\Scripts\python -m pytest student-tests\test_storage_failures.py -k outage -v
# Сбой между PUT и COMMIT убирает janitor; потерянный ответ после COMMIT ничего не удаляет:
.venv\Scripts\python -m pytest student-tests\test_consistency.py -v
# Все негативные кейсы файлов (413/415/400, чужой чат, MIME):
.venv\Scripts\python -m pytest student-tests\test_attachments.py -v
```
**Трек 2 вживую.**
```powershell
docker compose run --rm reconciler # dry-run: отчёт JSON, ничего не меняет
.venv\Scripts\python -m pytest student-tests\test_reconcile.py -k both_sides -v -s # ошибки на обеих сторонах, ~1,5 мин
docker compose run --rm reconciler --apply # исправить (на чистом стенде — 0 действий)
```
Готовые отчёты прогонов — [evidence/reconcile/](../evidence/reconcile/), стоимость обхода — [evidence/reconcile/cost.json](../evidence/reconcile/cost.json).
**Все свои тесты** (~25 мин): `.venv\Scripts\python -m pytest student-tests -v`.
## 5. Если что-то пошло не так
| Симптом | Что сделать |
| --- | --- |
| `error during connect … dockerDesktopLinuxEngine` | Docker Desktop не запущен — запустить и подождать минуту |
| `port is already allocated` на 8080/8404 | занято стендом lab3 (`docker compose -p mtusi-lab3 stop`) или в `.env` поставить `APP_PUBLISH_PORT=8081`, `LB_STATS_PORT=8405` |
| `secrets/... not found` при `up` | не выполнен `python scripts\init_secrets.py` |
| `s3-init` exit 1 | `docker compose logs s3-init`: какая проверка доступа не прошла |
| `UnicodeDecodeError` в `tests\*.py` | не задан `$env:PYTHONUTF8 = "1"` |
| `*.cmd`: «не удаётся найти путь» | Git установлен не в `C:\Program Files\Git` — поправить путь в `scripts\*.cmd` |
| после `stop-one` в LB одна реплика | так и задумано; вернуть: `make restore PYTHON=python` |
| api `unhealthy` после сна ноутбука | `docker compose restart` и `python scripts\lbctl.py wait-up 2` |
| нужно начать с чистого листа | `docker compose down -v` (удаляет учебные данные, включая bucket) → `docker compose up -d --build --wait` |
Остановить стенд после защиты: `docker compose down` (данные сохранятся) или `docker compose down -v` (данные удаляются).