From ec8e0e7c4206c38830f79bffc907687dbda2bec3 Mon Sep 17 00:00:00 2001 From: vasyukova Date: Wed, 4 Nov 2026 22:46:17 +0300 Subject: [PATCH] =?UTF-8?q?=D0=9D=D0=B0=D0=BF=D0=B8=D1=81=D0=B0=D0=BB?= =?UTF-8?q?=D0=B0=20=D1=87=D0=B5=D1=80=D0=BD=D0=BE=D0=B2=D0=B8=D0=BA=20?= =?UTF-8?q?=D0=BE=D1=82=D1=87=D0=B5=D1=82=D0=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- REPORT.md | 209 +++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 200 insertions(+), 9 deletions(-) diff --git a/REPORT.md b/REPORT.md index 9801db4..92d1d24 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,29 +1,220 @@ # Отчёт — лабораторная 7 -- Автор, группа: TODO -- Целевая оценка; выбранный трек 5, если нужен: TODO -- Commit/PR: TODO после публикации -- Использованные источники, библиотеки и помощь ИИ: TODO +- Автор, группа: Васюкова Наталья, БВТ2303 +- Целевая оценка: 4 +- Commit/PR: solution/BVT2303-Vasyukova +- Использованные источники, библиотеки и помощь ИИ: + - Контракт: contracts/openapi.json, contracts/README.md, contracts/observability.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, opentelemetry-api==1.28.2, opentelemetry-sdk==1.28.2, opentelemetry-exporter-otlp-proto-http==1.28.2, opentelemetry-instrumentation-fastapi==0.49b2, opentelemetry-instrumentation-requests==0.49b2 + - ИИ: DeepSeek — помощь в структурировании кода и отчёта. Весь код проверен, отредактирован и запущен разработчиком. ## Запуск из чистого clone -TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных. +Версии 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 +- OTel SDK 1.28.2, FastAPI instrumentation 0.49b2 +- 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`. +- OTel Collector: `otel/opentelemetry-collector-contrib:0.108.0` +- Prometheus: `prom/prometheus:v2.54.1`, Loki: `grafana/loki:3.1.1`, Tempo: `grafana/tempo:2.5.0`, Grafana: `grafana/grafana:11.2.0` +- 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 + OTel Collector + Prometheus + Loki + Tempo + Grafana): + ``` + docker compose --env-file .env up -d --build + ``` +4. Проверить готовность: + ``` + curl.exe -s http://localhost:8080/health/ready + ``` + Ожидается: `{"status":"ok"}`. +5. Grafana доступна на `http://localhost:3000` (admin/admin). Дашборд `messenger-lab6` и datasources импортируются автоматически. + +Все проверки ниже выполнялись с `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/lab6_test_level4.py --base-url http://localhost:8080` | + +### Остановка и удаление учебных данных + +``` +docker compose stop # данные PostgreSQL, Redis, MinIO, RabbitMQ, Prometheus, Loki, Tempo, Grafana сохраняются (volumes) +docker compose down # volumes сохраняются +docker compose down -v # ТОЛЬКО если осознанно стираем данные +``` ## Архитектура и решения -TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab6, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации. +Схема процессов и хранилищ: + +``` + ┌─ 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 + +API/worker/outbox → OTLP/HTTP → otel-collector → ┬→ Tempo (traces) + ├→ Loki (logs) + └→ Prometheus (metrics) + → Grafana (дашборд, алерты) +``` + +Все сервисы — в одной compose-сети `mtuci2026lab6_default`. Публично опубликован только порт LB `127.0.0.1:8080:80` и Grafana `127.0.0.1:3000:3000`. Реплики `api` **не имеют `ports`** — трафик к ним идёт исключительно через LB. PostgreSQL, Redis, MinIO, RabbitMQ, OTel Collector (4317/4318/8888/8889), Prometheus (9090), Loki (3100), Tempo (3200) доступны только по внутренним именам. + +Источники истины: +- PostgreSQL — данные (пользователи, чаты, членство, сообщения, метаданные вложений, варианты, outbox, ключи идемпотентности). +- Redis — серверные сессии (общие для всех реплик). +- MinIO (S3) — байты вложений: staging (`staging/…`) и финальный `attachments/…` (приватный bucket). +- RabbitMQ — durable очередь job'ов. Сама по себе не источник истины: намерение сохраняется в `outbox` до публикации. +- Tempo/Loki/Prometheus — telemetry storage. Их падение не останавливает API. + +Схема БД (подробнее — `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, + 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)) +outbox(id BIGSERIAL PK, job_id UUID UNIQUE, payload JSONB, created_at TIMESTAMPTZ, + published_at TIMESTAMPTZ) + + 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` — 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` в **одной** транзакции. Идемпотентно к повторной доставке. + +### Дерево проекта (изменения относительно lab5 отмечены `*`) + +``` +mtuci2026lab6/ +├── compose.yaml * # + otel-collector, prometheus, loki, tempo, grafana; tag lab6 +├── Dockerfile +├── docker-entrypoint.sh # генерирует INSTANCE_ID, пишет /tmp/instance_id +├── infra/ +│ ├── nginx.conf +│ ├── otel/collector.yaml * # OTLP receivers, memory_limiter, batch, exporters +│ ├── prometheus/ +│ │ ├── prometheus.yaml * # scrape otel-collector:8889 +│ │ └── rules/alerts.yaml * +│ ├── loki/loki.yaml * +│ ├── tempo/tempo.yaml * +│ ├── grafana/provisioning/ +│ │ ├── datasources/datasources.yaml * # Prometheus/Loki/Tempo +│ │ ├── dashboards/provider.yaml * +│ │ ├── dashboards/json/messenger.json * +│ │ └── alerting/{contactpoints,policies,rules}.yaml * +│ └── runbooks/ * # high-error-rate.md, queue-lag.md, slow-upload.md +├── Makefile +├── requirements.txt * # + opentelemetry-* +├── src/app/ +│ ├── main.py * # OTel init, HTTP-метрики, X-Request-Id/X-Instance-Id +│ ├── telemetry.py * # новый: единая точка init OTel + лог-формат +│ ├── outbox_worker.py * # trace context из outbox payload → job.publish span +│ ├── worker.py * # consumer span job.consume, метрики jobs_* +│ ├── api/attachments.py * # inject traceparent в outbox payload +│ ├── api/... # без изменений с lab5 +│ ├── models/schemas.py +│ └── storage/ # без изменений с lab5 +├── scripts/ +│ ├── restart.sh / .bat +│ ├── stop-one.sh / .bat +│ └── rolling-update.sh +└── student-tests/ + └── lab6_test_level4.py * # новый: traces, metrics, logs, dashboard, alerts, telemetry down +``` + +### Что нового в lab6 относительно lab5 + +TODO ## Доказательства критериев -| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | +| Критерий README | Команда/сценарий | Наблюдаемый результат | Уровень | | --- | --- | --- | --- | -| Публичный smoke | make test | TODO | TODO | +| Публичный smoke | `python tests/smoke.py` | PASS: lab6 public API scenario | 3 | | Остальные пункты уровня 3 | TODO | TODO | TODO | | Все пункты уровня 4, если заявлен | TODO | TODO | TODO | -| Выбранный трек 5, если заявлен | TODO | TODO | TODO | TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены. +### Выводы тестов + +``` +(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: lab6 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. +``` + ## Эксперименты и отказы TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.