14 KiB
Отчёт — лабораторная 5
- Автор, группа: Васюкова Наталья, БВТ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, 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
- PostgreSQL 18.6-alpine, Redis 7.4.1-alpine, nginx 1.27.3-alpine
- MinIO:
netvark/minio:20260213(зеркало официального образа; оригинальныеminio/minioудалены с Docker Hub). CLImc:netvark/mc:20260920. - Docker Desktop (Windows)
Запуск стека
- Клонировать репозиторий и переключиться на ветку решения:
git clone https://gitflic.ru/project/vasyukova-nat/mtusi2026lab4.git git checkout solution/BVT2303-Vasyukova - Создать
.envиз шаблона:copy .env.example .env - Собрать и поднять (LB + 2 реплики API + PostgreSQL + Redis + MinIO + minio-init + s3_cleanup):
docker compose --env-file .env up -d --build - Проверить готовность:
Ожидается:
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/lab4_test_level4.py --base-url http://localhost:8080 |
Остановка и удаление учебных данных
docker compose stop # данные PostgreSQL, Redis и MinIO сохраняются (volumes)
docker compose down # volumes сохраняются
docker compose down -v # ТОЛЬКО если осознанно стираем данные
Архитектура и решения
Схема процессов и хранилищ:
┌─ api-1 (uvicorn:8080, INSTANCE_ID=…)
HTTP-клиент → lb:80 ──┤ ↘
(nginx) └─ api-2 (uvicorn:8080, INSTANCE_ID=…) PostgreSQL 18.6 (метаданные)
Redis 7.4.1 (сессии)
MinIO (S3-байты, приватный bucket)
s3_cleanup (сверка S3↔БД)
Все сервисы — в одной compose-сети mtuci2026lab4_default. Публично опубликован только порт LB 127.0.0.1:8080:80. Реплики api не имеют ports — трафик к ним идёт исключительно через LB. PostgreSQL, Redis и MinIO доступны только по внутренним именам (postgres, redis, minio). Административная консоль MinIO (:9001) и S3 API (:9000) не публикуются наружу.
Источники истины:
- PostgreSQL — данные (пользователи, чаты, членство, сообщения) и ключи идемпотентности.
- Redis — серверные сессии (общие для всех реплик).
- MinIO (S3) — байты вложений (приватный bucket
messenger-attachments).
Схема БД (подробнее — 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,
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))
+ INDEX idx_msg_att_message(message_id, position)
Применяется идемпотентно через init_schema() в отдельном one-shot сервисе migrate (python -m app.storage.db). Все временные метки — TIMESTAMPTZ.
Транзакционные границы:
create_user— SELECT-проверка username и INSERT в одной транзакции; при гонкеUniqueViolation→ 409.create_chat— INSERTchats+ INSERTchat_membersв одной транзакции, откат целиком.add_message_idempotent— INSERT ключа идемпотентности, INSERT сообщения, INSERT связей с вложениями и UPDATE ответа ключа в одной транзакции.- Создание/отзыв сессии — одна операция.
Дерево проекта (изменения относительно lab3 отмечены *)
mtuci2026lab4/
├── compose.yaml * # + minio, minio-init, s3_cleanup; lab4-network
├── Dockerfile
├── docker-entrypoint.sh # генерирует INSTANCE_ID, пишет /tmp/instance_id
├── infra/nginx.conf
├── Makefile
├── requirements.txt * # + boto3, Pillow
├── src/app/
│ ├── main.py * # + attachments router, версия 1.4.0
│ ├── api/
│ │ ├── attachments.py * # новый: upload/get/download вложений
│ │ ├── messages.py * # CreateMessage c attachment_ids, проверка принадлежности чату
│ │ └── health.py * # + проверка S3
│ ├── models/
│ │ └── schemas.py * # + Attachment, Variant, Message.attachment_ids
│ └── storage/
│ ├── db.py * # + attachments, message_attachments
│ ├── postgres.py * # + методы для вложений, идемпотентность с attachments
│ └── s3.py * # новый: boto3-клиент, keyspace
│ └── s3_cleanup.py * # новый: фоновая сверка S3↔БД
├── scripts/
│ ├── restart.sh / .bat * # + minio, s3_cleanup
│ └── stop-one.sh / .bat # без изменений
└── student-tests/
└── lab4_test_level4.py * # новый: негативные тесты, компенсация, параллельные загрузки
Что нового в lab5 относительно lab4
TODO
Соответствие .env.example реальной конфигурации:
APP_HOST,APP_PORT— используются uvicorn/CMD в Dockerfile.APP_ENV— пишется в стартовый лог, на логику не влияет.SESSION_TTL_SECONDS— TTL серверных сессий в Redis (или в таблицеsessionsприSESSION_STORE=postgres), по умолчанию 3600.DATABASE_URL— строка подключения к PostgreSQL.REDIS_URL— адрес Redis в compose-сети.SESSION_STORE—redis(уровень 4) илиpostgres(fallback).S3_ENDPOINT— внутренний адрес MinIO (http://minio:9000).S3_REGION— регион (для MinIO фиктивныйus-east-1).S3_BUCKET— имя приватного bucket.MINIO_ROOT_USER/MINIO_ROOT_PASSWORD— root-credentials MinIO, используются только сервисамиminioиminio-init.S3_APP_KEY_ID/S3_APP_SECRET_KEY— прикладные S3-credentials, используются API иs3_cleanup.MAX_UPLOAD_BYTES,MAX_IMAGE_PIXELS— лимиты вложений.CLEANUP_INTERVAL_SECONDS— период сверки S3↔БД.ORPHAN_GRACE_SECONDS— grace period для удаления orphan-объектов.CACHE_URL_FILE— резервная переменная из скелета, не используется.
Доказательства критериев
| Критерий | Команда | Наблюдаемый результат | Уровень |
|---|---|---|---|
| Публичный smoke | python tests/smoke.py |
PASS: lab4 public API scenario | 3 |
| S3-сервер в общем стенде, приватный bucket | docker compose ps; minio-init |
minio/minio-init/s3_cleanup Up; bucket messenger-attachments создан |
3 |
| Остальные пункты уровня 3 | TODO | TODO | TODO |
| Все пункты уровня 4, если заявлен | TODO | TODO | TODO |
Выводы тестов
(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: lab4 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
PASS: persistence preserved confirmed data and existing session.
(venv) PS ...> python tests/resilience.py --mode failover --action-script scripts/stop-one.bat --base-url http://localhost:8080
{"observed_instances_before": 2, "successful_writes": 8, "failed_attempts": 0, "first_recovery_seconds": 4.146}
PASS: failover preserved confirmed data and existing session.
(venv) PS ...> python student-tests/lab4_test_level4.py --base-url http://localhost:8080
=== oversize ===
PASS: oversize -> 413
=== corrupted image ===
PASS: corrupted -> 415
=== spoofed MIME ===
PASS: spoofed MIME -> 415
=== bad filename ===
PASS: bad filename -> 400
=== foreign attachment / cross-chat ===
PASS: foreign -> 404, cross-chat -> 404
=== attachment belongs to chat ===
PASS: attachment from another chat -> 404
=== compensation on DB failure ===
upload при мёртвой БД вернул 503
компенсация: bucket не вырос (before=10 after=10)
PASS: компенсация orphan-объектов при отказе БД
=== parallel uploads memory ===
10 параллельных загрузок, пик RSS=88.94 MiB
PASS: 10 параллельных загрузок в пределах лимита памяти
PASS: all lab4 level-4 checks passed
Эксперименты и отказы
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|---|---|---|---|
| TODO | TODO | TODO | TODO |
Ограничения и следующие шаги
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.