251 lines
17 KiB
Markdown
251 lines
17 KiB
Markdown
# Отчёт — лабораторная 6
|
||
|
||
- Автор, группа: Васюкова Наталья, БВТ2303
|
||
- Целевая оценка: 4
|
||
- Commit/PR: solution/BVT2303-Vasyukova
|
||
- Использованные источники, библиотеки и помощь ИИ:
|
||
- Контракт: contracts/openapi.json, contracts/README.md
|
||
- Инструкции: README.md, COURSE.md, CONTRIBUTING.md
|
||
- Библиотеки: fastapi==0.115.0, uvicorn[standard]==0.32.0, psycopg[binary]==3.2.3, psycopg_pool==3.2.3, redis==5.2.0, boto3==1.35.74, Pillow==11.0.0, pika==1.3.2, pydantic (из fastapi)
|
||
- ИИ: DeepSeek — помощь в структурировании кода и отчёта. Весь код проверен, отредактирован и запущен разработчиком.
|
||
|
||
## Запуск из чистого clone
|
||
|
||
Версии runtime/образов:
|
||
- Python: 3.12 (образ `python:3.12-slim`)
|
||
- FastAPI 0.115.0, uvicorn[standard] 0.32.0, psycopg[binary] 3.2.3, psycopg_pool 3.2.3, redis 5.2.0, boto3 1.35.74, Pillow 11.0.0, pika 1.3.2
|
||
- PostgreSQL 18.6-alpine, Redis 7.4.1-alpine, nginx 1.27.3-alpine
|
||
- RabbitMQ 3.13.7-management-alpine
|
||
- MinIO: `netvark/minio:20260213` (зеркало официального образа; оригинальные `minio/minio` удалены с Docker Hub). CLI `mc`: `netvark/mc:20260920`.
|
||
- Docker Desktop (Windows)
|
||
|
||
### Запуск стека
|
||
|
||
1. Клонировать репозиторий и переключиться на ветку решения:
|
||
```
|
||
git clone https://gitflic.ru/project/vasyukova-nat/mtusi2026lab5.git
|
||
git checkout solution/BVT2303-Vasyukova
|
||
```
|
||
2. Создать `.env` из шаблона:
|
||
```
|
||
copy .env.example .env
|
||
```
|
||
3. Собрать и поднять (LB + 2 реплики API + PostgreSQL + Redis + MinIO + minio-init + rabbitmq + worker + outbox + s3_cleanup):
|
||
```
|
||
docker compose --env-file .env up -d --build
|
||
```
|
||
4. Проверить готовность:
|
||
```
|
||
curl.exe -s http://localhost:8080/health/ready
|
||
```
|
||
Ожидается: `{"status":"ok"}`.
|
||
|
||
Все проверки ниже выполнялись с `PYTHONUTF8=1` (Windows по умолчанию использует cp1251 и падает на чтении UTF-8 JSON):
|
||
```
|
||
$env:PYTHONUTF8="1"
|
||
```
|
||
|
||
### Проверки
|
||
|
||
`make` в среде автора недоступен (Windows без GNU Make), поэтому использованы эквивалентные прямые вызовы скриптов. Для Linux/CI рядом указаны команды `make`.
|
||
|
||
| Makefile-команда | Прямой вызов |
|
||
| --- | --- |
|
||
| `make check` | `python scripts/check_contract.py` |
|
||
| `make validate` | `python scripts/validate_openapi.py` |
|
||
| `make test` | `python tests/smoke.py --base-url http://localhost:8080` |
|
||
| `make test-persistence` | `python tests/resilience.py --mode persistence --action-script scripts/restart.bat --base-url http://localhost:8080` |
|
||
| `make test-failover` | `python tests/resilience.py --mode failover --action-script scripts/stop-one.bat --base-url http://localhost:8080` |
|
||
| `make test-student` | `python student-tests/lab5_test_level4.py --base-url http://localhost:8080` |
|
||
|
||
### Остановка и удаление учебных данных
|
||
|
||
```
|
||
docker compose stop # данные PostgreSQL, Redis, MinIO, RabbitMQ сохраняются (volumes)
|
||
docker compose down # volumes сохраняются
|
||
docker compose down -v # ТОЛЬКО если осознанно стираем данные
|
||
```
|
||
|
||
### Операторский replay failed-задач
|
||
|
||
Причина ошибки устранена — вернуть задачи в обработку (failed → queued + новая строка outbox, готовые не трогаются):
|
||
|
||
```
|
||
docker compose --env-file .env exec -T worker python -m app.storage.replay_failed --all-failed
|
||
# или конкретные ID:
|
||
docker compose --env-file .env exec -T worker python -m app.storage.replay_failed <attachment_id> [...]
|
||
```
|
||
|
||
Публикацию делает существующий `outbox`, обработку — `worker`; оба должны быть запущены. Проверка: `status=queued`, затем `ready`.
|
||
|
||
## Архитектура и решения
|
||
|
||
Схема процессов и хранилищ:
|
||
|
||
```
|
||
┌─ api-1 (uvicorn:8080) ┐
|
||
HTTP-клиент → lb:80 ──┤ │
|
||
(nginx) └─ api-2 (uvicorn:8080) ├→ PostgreSQL 18.6 (метаданные, outbox)
|
||
├→ Redis 7.4.1 (сессии)
|
||
├→ MinIO (S3: staging + final байты)
|
||
└→ RabbitMQ (durable job queue)
|
||
|
||
outbox (publisher) → читает unpublished из PostgreSQL → публикует в RabbitMQ
|
||
worker (consumer) → забирает job из RabbitMQ → читает staging → пишет final+variants → status=ready
|
||
s3_cleanup → сверка S3↔БД, recover зависших processing
|
||
```
|
||
|
||
Все сервисы — в одной compose-сети `mtuci2026lab5_default`. Публично опубликован только порт LB `127.0.0.1:8080:80`. Реплики `api` **не имеют `ports`** — трафик к ним идёт исключительно через LB. PostgreSQL, Redis, MinIO и RabbitMQ доступны только по внутренним именам. Административная консоль MinIO (`:9001`), S3 API (`:9000`) и RabbitMQ management (`:15672`) **не публикуются** наружу.
|
||
|
||
Источники истины:
|
||
- PostgreSQL — данные (пользователи, чаты, членство, сообщения, метаданные вложений, варианты, outbox, ключи идемпотентности).
|
||
- Redis — серверные сессии (общие для всех реплик).
|
||
- MinIO (S3) — байты вложений: staging (`staging/…`) и финальный `attachments/…` (приватный bucket).
|
||
- RabbitMQ — durable очередь job'ов. Сама по себе не источник истины: намерение сохраняется в `outbox` до публикации.
|
||
|
||
Схема БД (подробнее — `src/app/storage/db.py`, константа `SCHEMA_SQL`):
|
||
```
|
||
users(id UUID PK, username TEXT UNIQUE, display_name TEXT, password_hash TEXT, created_at TIMESTAMPTZ)
|
||
chats(id UUID PK, title TEXT, created_at TIMESTAMPTZ)
|
||
chat_members(chat_id FK→chats, user_id FK→users, PK(chat_id,user_id))
|
||
messages(id UUID PK, chat_id FK→chats, sender_id FK→users, text TEXT, created_at TIMESTAMPTZ)
|
||
+ INDEX idx_messages_chat_created(chat_id, created_at, id)
|
||
sessions(token TEXT PK, user_id FK→users, expires_at TIMESTAMPTZ) -- fallback SESSION_STORE=postgres
|
||
idempotency_keys(user_id FK→users, method TEXT, path TEXT, key TEXT,
|
||
body_hash TEXT, response_status INT, response_body JSONB, created_at TIMESTAMPTZ,
|
||
PRIMARY KEY (user_id, method, path, key))
|
||
+ INDEX idx_idempotency_created(created_at)
|
||
attachments(id UUID PK, chat_id FK→chats, owner_id FK→users,
|
||
filename TEXT, content_type TEXT, size_bytes BIGINT, sha256 TEXT,
|
||
object_key TEXT UNIQUE, status TEXT, error_code TEXT,
|
||
processing_until TIMESTAMPTZ, -- lab5: lease для worker
|
||
created_at TIMESTAMPTZ, updated_at TIMESTAMPTZ)
|
||
+ INDEX idx_attachments_chat(chat_id)
|
||
message_attachments(message_id FK→messages, attachment_id FK→attachments, position INT,
|
||
PRIMARY KEY (message_id, attachment_id))
|
||
attachment_variants(attachment_id FK→attachments, pipeline_version INT, variant TEXT,
|
||
object_key TEXT, content_type TEXT, size_bytes BIGINT,
|
||
width INT, height INT, sha256 TEXT, created_at TIMESTAMPTZ,
|
||
PRIMARY KEY (attachment_id, pipeline_version, variant)) -- lab5
|
||
outbox(id BIGSERIAL PK, job_id UUID UNIQUE, payload JSONB, created_at TIMESTAMPTZ,
|
||
published_at TIMESTAMPTZ) -- lab5 level 4
|
||
+ PARTIAL INDEX idx_outbox_unpublished(id) WHERE published_at IS NULL
|
||
```
|
||
|
||
Применяется идемпотентно через `init_schema()` в отдельном one-shot сервисе `migrate` (`python -m app.storage.db`). Все временные метки — `TIMESTAMPTZ`.
|
||
|
||
Транзакционные границы:
|
||
- `create_user` — SELECT-проверка username и INSERT в одной транзакции; при гонке `UniqueViolation` → 409.
|
||
- `create_chat` — INSERT `chats` + INSERT `chat_members` в одной транзакции, откат целиком.
|
||
- `add_message_idempotent` — INSERT ключа идемпотентности, INSERT сообщения, INSERT связей с вложениями и UPDATE ответа ключа в **одной** транзакции.
|
||
- `create_attachment_queued` (lab5) — INSERT `attachments` (status=`queued`) + INSERT `outbox` в **одной** транзакции. Это durable handoff: если API упадёт сразу после ответа 202, outbox гарантирует публикацию job'а.
|
||
- `finalize_ready` — UPDATE `attachments` (status=`ready`, `object_key`=final) + INSERT `attachment_variants` с `ON CONFLICT (attachment_id, pipeline_version, variant) DO NOTHING` в **одной** транзакции. Идемпотентно к повторной доставке.
|
||
|
||
### Дерево проекта (изменения относительно lab4 отмечены `*`)
|
||
|
||
```
|
||
mtuci2026lab5/
|
||
├── compose.yaml * # + rabbitmq, worker, outbox; tag lab5 для всех сервисов
|
||
├── Dockerfile
|
||
├── docker-entrypoint.sh # генерирует INSTANCE_ID, пишет /tmp/instance_id
|
||
├── infra/nginx.conf
|
||
├── Makefile
|
||
├── requirements.txt * # + pika
|
||
├── src/app/
|
||
│ ├── main.py * # версия 1.5.0, title lab5
|
||
│ ├── api/
|
||
│ │ ├── attachments.py * # upload → 202 queued; download variant
|
||
│ │ ├── messages.py # без изменений с lab4
|
||
│ │ └── health.py # без изменений с lab4
|
||
│ ├── models/
|
||
│ │ └── schemas.py # без изменений с lab4
|
||
│ ├── storage/
|
||
│ │ ├── db.py * # + attachment_variants, outbox, processing_until
|
||
│ │ ├── postgres.py * # + lab5 методы (queued, variants, outbox, lease, recover)
|
||
│ │ ├── s3.py * # + staging_key, variant_key
|
||
│ │ ├── rabbit.py * # новый: topology, publish с confirm, retry, DLQ
|
||
│ │ └── s3_cleanup.py * # + cleanup staging, recover processing
|
||
│ ├── worker.py * # новый: consumer, обработка изображений
|
||
│ └── outbox_worker.py * # новый: outbox publisher (level 4)
|
||
├── scripts/
|
||
│ ├── restart.sh / .bat * # + rabbitmq, worker, outbox
|
||
│ └── stop-one.sh / .bat # без изменений
|
||
└── student-tests/
|
||
└── lab5_test_level4.py * # новый: variants, outbox, DLQ, lease, retry
|
||
```
|
||
|
||
### Что нового в lab5 относительно lab4
|
||
|
||
TODO
|
||
|
||
## Доказательства критериев
|
||
|
||
| Критерий | Команда | Наблюдаемый результат | Уровень |
|
||
| --- | --- | --- | --- |
|
||
| Публичный smoke | `python tests/smoke.py` | PASS: lab5 public API scenario | 3 |
|
||
| Broker + worker в общем стенде, at-least-once | `docker compose ps`; `rabbitmqctl list_queues` | rabbitmq/worker/outbox Up; consumer на `attachment.process.v1` | 3 |
|
||
| Upload возвращает 202 queued, работа переживает остановку worker | `lab5_test_level4.py::test_worker_stopped` | 202 queued → content 409 → старт worker → ready | 3 |
|
||
| Сохранение метаданных и сессии при рестарте | `resilience.py --mode persistence` | PASS: тот же токен и SHA-256 файла | 3 |
|
||
| Отказ одной API-реплики | `resilience.py --mode failover` | observed_instances_before=2, successful_writes=7, failed_attempts=0, first_recovery=4.245 s | 3 |
|
||
| Worker сохраняет original + один thumbnail по контракту | `lab5_test_level4.py::test_variants` | thumbnail JPEG 256×160, sha256/size совпадают | 3 |
|
||
| Ограниченный retry, финальный failed с error_code | `lab5_test_level4.py::test_broken_staging_dlq` | failed `retry_exhausted` + DLQ | 3 |
|
||
| Повтор job не создаёт второго набора вариантов | `lab5_test_level4.py::test_duplicate_delivery_no_duplicates` | variants не выросли, status=ready | 3 |
|
||
| Original неизменен, download побайтно | smoke + `test_variants` | SHA-256 совпадает; при скачивании — те же байты | 3 |
|
||
| Crop 128×128 (JPEG) | `lab5_test_level4.py::test_variants` | jpeg_size(crop) == (128,128) | 4 |
|
||
| Optimized WebP (≤1280×1280) | `lab5_test_level4.py::test_variants` | Content-Type image/webp, RIFF/WEBP | 4 |
|
||
| Outbox закрывает разрыв COMMIT → publish | `lab5_test_level4.py::test_outbox_crash` | stop outbox → upload 202 + outbox unpublished → start outbox → ready | 4 |
|
||
| Retry с backoff, DLQ, безопасный replay | `lab5_test_level4.py::test_broken_staging_dlq` | 4 попытки, `retry_exhausted`, DLQ +1 | 4 |
|
||
| Ограниченная конкуренция, prefetch=1, очистка staging | `worker.py`, `s3_cleanup.py` | prefetch_count=1; staging удаляется после finalize | 4 |
|
||
| Lease: зависший processing возвращается в queued | `lab5_test_level4.py::test_stuck_processing_recovered` | processing (lease истёк) → queued → ready | 4 |
|
||
| Лимиты времени/памяти worker | `Pillow`, `MAX_IMAGE_PIXELS`, threadpool | Pillow в threadpool, лимит до `load()` | 4 |
|
||
| Гарантия, что в очереди ID, а не байты/креды | `rabbit.py`, `outbox_worker.py` | payload = {job_id, attachment_id, pipeline_version, created_at}; staging/финальные байты — в S3 | 4 |
|
||
|
||
### Выводы тестов
|
||
|
||
```
|
||
(venv) PS ...> python scripts/check_contract.py
|
||
PASS: offline skeleton structure, local refs and Python syntax; application NOT tested.
|
||
|
||
(venv) PS ...> python scripts/validate_openapi.py
|
||
PASS: full OpenAPI 3.1 and JSON Schema validation; application NOT tested.
|
||
|
||
(venv) PS ...> python tests/smoke.py --base-url http://localhost:8080
|
||
PASS: lab5 public API scenario; infrastructure and grading evidence remain separate.
|
||
|
||
(venv) PS ...> python tests/resilience.py --mode persistence --action-script scripts/restart.bat --base-url http://localhost:8080
|
||
Executing explicit persistence hook; hook output suppressed to avoid leaking secrets.
|
||
PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence.
|
||
|
||
(venv) PS ...> python tests/resilience.py --mode failover --action-script scripts/stop-one.bat --base-url http://localhost:8080
|
||
Executing explicit failover hook; hook output suppressed to avoid leaking secrets.
|
||
{"observed_instances_before": 2, "successful_writes": 7, "failed_attempts": 0, "first_recovery_seconds": 4.245}
|
||
PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence.
|
||
|
||
(venv) PS ...> python student-tests/lab5_test_level4.py --base-url http://localhost:8080
|
||
=== variants (thumbnail/crop/optimized) ===
|
||
PASS: original, thumbnail 256×160, crop 128×128, optimized WebP
|
||
=== outbox crash between COMMIT and publish ===
|
||
PASS: outbox recovers job after stop/start without manual intervention
|
||
=== duplicate delivery does not create duplicates ===
|
||
PASS: re-delivery of the same job is a no-op
|
||
=== worker stopped: 202 → content 409 → ready ===
|
||
PASS: accepted work survives worker restart
|
||
=== broken staging → retry_exhausted → failed + DLQ ===
|
||
PASS: bounded retry, failed with safe error_code, message in DLQ
|
||
=== stuck processing (lease) → queued → ready ===
|
||
PASS: expired lease is recovered, same attachment becomes ready
|
||
PASS: all lab5 level-4 checks passed
|
||
```
|
||
|
||
## Эксперименты и отказы
|
||
|
||
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
|
||
|
||
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|
||
| --- | --- | --- | --- |
|
||
| TODO | TODO | TODO | TODO |
|
||
|
||
## Ограничения и следующие шаги
|
||
|
||
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
|