Files
mtusi2026lab4-fork/REPORT.md
T
2026-11-12 23:09:48 +03:00

12 KiB
Raw Blame History

Отчёт — лабораторная 4

  • Автор, группа: Гадяцкий Л. Е., БПИ2302
  • Целевая оценка: 3
  • Commit/PR: solution/BPI2302-Gadiatskiy MR #121
  • Использованные источники и библиотеки:
    • контракт и семантика: contracts/openapi.json, contracts/README.md, README.md, COURSE.md
    • перенос из lab3: FastAPI, PostgreSQL/сессии, SQLAlchemy, миграции, Nginx LB, идемпотентность
    • runtime: FastAPI 0.115.6, Uvicorn 0.34.0, Pydantic 2.10.4, SQLAlchemy 2.0.36, psycopg 3.2.4, argon2-cffi 23.1.0, boto3 1.35.76, Pillow 11.0.0
    • PostgreSQL: postgres:16-alpine; LB: nginx:1.27-alpine; S3/MinIO: alpine/minio:RELEASE.2025-10-15T17-29-55Z
  • Помощь ИИ использована при переносе lab3, частично для вложений/S3 и при заполнении отчёта.

Запуск из чистого clone

Prerequisites: Docker и Docker Compose. Python 3.9+ нужен только для публичных проверок (make check / make test / tests/resilience.py). Runtime приложения — внутри образа.

Версии:

  • API: базовый образ python:3.12.8-slim-bookworm → локальный mtusi-messenger:lab4
  • PostgreSQL: postgres:16-alpine
  • Nginx: nginx:1.27-alpine
  • MinIO: alpine/minio:RELEASE.2025-10-15T17-29-55Z (community image; официальный minio/minio с Docker Hub недоступен)
  • зависимости: requirements.txt

Конфигурация: секретов в Git нет. Локальный .env создаётся из примера и не коммитится:

cp .env.example .env

Соответствие .env.example:

  • APP_HOST / APP_PORT — bind uvicorn внутри контейнеров API
  • HOST_PORT — порт LB на host (по умолчанию 8080; если занят — например 8081)
  • APP_ENV — среда запуска (lab)
  • SESSION_TTL_SECONDS — TTL сессии (по умолчанию 3600; для обычного smoke ≥ 300)
  • SESSION_STORE=postgres — сессии в PostgreSQL (общие для всех реплик)
  • DATABASE_URL — строка подключения API/migrate к PostgreSQL в compose-сети
    (приложение также поддерживает DATABASE_URL_FILE)
  • IDEMPOTENCY_TTL_SECONDS — срок хранения идемпотентных записей (по умолчанию 86400)
  • API_REPLICAS=2 — в compose.yaml зафиксированы сервисы api1 и api2
  • S3_ENDPOINT / S3_REGION / S3_BUCKET — доступ API к MinIO в compose-сети
  • S3_ACCESS_KEY_ID / S3_SECRET_ACCESS_KEY — учебные credentials MinIO (также *_FILE)
  • MAX_UPLOAD_BYTES=10485760, MAX_IMAGE_PIXELS=40000000 — лимиты загрузки

Учебные credentials compose (messenger / messenger, MinIO minioadmin / minioadmin) только для локального синтетического стенда.

Сборка и запуск:

docker compose --env-file .env up -d --build

Миграции migrations/*.sql применяет one-shot сервис migrate до старта api1/api2 (учёт в schema_migrations). Приватный bucket S3_BUCKET идемпотентно создаёт API при старте (ensure_bucket). Реплики API миграции SQL при старте не выполняют.

Готовность через LB (подставьте свой HOST_PORT):

curl -i http://127.0.0.1:8080/health/ready

Ожидается HTTP 200, тело {"status":"ok"}, заголовки X-Request-Id и X-Instance-Id (api1 или api2). /health/ready требует доступности PostgreSQL и S3 (MinIO).

Публичный smoke (при уже запущенном стенде):

python tests/smoke.py --base-url http://127.0.0.1:8080
# или: make test BASE_URL=http://127.0.0.1:8080

Проверка сохранности (включая исходный файл вложения):

# Unix:
chmod +x scripts/restart.sh
python tests/resilience.py --mode persistence --action-script scripts/restart.sh --base-url http://127.0.0.1:8080

# Windows:
python tests/resilience.py --mode persistence --action-script scripts/restart.cmd --base-url http://127.0.0.1:8080

Hook выполняет docker compose --env-file .env restart для postgres, s3, api1, api2, lb без удаления volumes (down -v не используется).

Проверка отказа одной API-реплики (upload → stop обслужившей → download через другую):

# Unix:
chmod +x scripts/stop-one.sh
python tests/resilience.py --mode failover --action-script scripts/stop-one.sh --base-url http://127.0.0.1:8080

# Windows:
python tests/resilience.py --mode failover --action-script scripts/stop-one.cmd --base-url http://127.0.0.1:8080

TARGET_INSTANCE_ID = X-Instance-Id (api1/api2); hook делает docker compose stop только этой реплики и оставляет её остановленной. После теста: docker compose --env-file .env start api1 (или api2). Для защиты повторить на второй реплике после восстановления первой.

Остановка:

docker compose --env-file .env down

Намеренное удаление учебных данных (volumes):

docker compose --env-file .env down -v

Архитектура и решения

HTTP-клиент
  → lb (Nginx)
      → api1 / api2 (uvicorn + FastAPI)
          → PostgreSQL
             users, chats, chat_members, messages, message_attachments,
             attachments (метаданные), sessions, idempotency_records
          → MinIO (S3, образ alpine/minio:RELEASE.2025-10-15T17-29-55Z)
             байты оригиналов в bucket messenger-attachments
  • Источник истины для метаданных — PostgreSQL; байты оригиналов — только в S3, не в БД и не на локальном диске API.
  • Object key назначает сервер (attachments/{chat_id}/{attachment_id}); filename только для отображения.
  • POST .../attachments читает тело с лимитом до MAX_UPLOAD_BYTES+ отказа, проверяет MIME по содержимому (PNG/JPEG), лимит пикселей через Pillow, затем PutObject и запись метаданных; ответ 201 со status=ready.
  • Download только через авторизованный API без redirect; посторонний участник получает 404.
  • Сессии в PostgreSQL: один Bearer работает через любую реплику без sticky sessions.
  • X-Instance-Id стабилен на жизнь процесса (INSTANCE_ID сервиса).
  • Idempotency-Key обязателен на POST .../messages; хеш тела учитывает text и attachment_ids.
  • ORM-модели: src/messenger/tables.py. Доступ к данным: src/messenger/store.py. S3: src/messenger/s3util.py.
  • Миграции: SQL в migrations/ (+ 003_attachments.sql) + one-shot migrate; Alembic не используется.
  • Порты API и MinIO наружу не публикуются; публичная точка входа — LB (infra/nginx.conf: client_max_body_size 11m, least_conn).
  • Compose: lb + api1 + api2 + postgres + s3 + migrate, volumes pgdata и miniodata; сервис s3 с user: "0:0", чтобы alpine/MinIO мог писать в named volume; .env в Git не коммитится.

Перенесено из lab3: auth Basic→Bearer, Argon2id, чаты/сообщения, LB, две реплики, идемпотентность, restart/stop-one.
Добавлено в lab4: MinIO, Attachment/message_attachments, upload/download, attachment_ids в сообщениях, готовность с проверкой S3.

Доказательства критериев

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Публичный smoke (lab3 + вложения/SHA-256/чужой 404) python tests/smoke.py --base-url http://127.0.0.1:8083 PASS: lab4 public API scenario... evidence/smoke.txt
Стенд: ≥2 API, LB, Postgres, MinIO docker compose --env-file .env ps lb, api1, api2, postgres, s3 (alpine/minio:RELEASE.2025-10-15T17-29-55Z); migrate Exited 0 evidence/compose-ps.txt
Persistence: рестарт без удаления volumes, прежний токен и тот же файл python tests/resilience.py --mode persistence --action-script scripts/restart.cmd --base-url http://127.0.0.1:8083 PASS: persistence preserved... evidence/restart.txt
Failover: остановка одной API-реплики; файл через другую python tests/resilience.py --mode failover --action-script scripts/stop-one.cmd --base-url http://127.0.0.1:8083 failover PASS; first_recovery_seconds≈2.64; attachment bytes совпали evidence/failover.txt

Эксперименты и отказы

Для оценки 3 отдельный нагрузочный трек не выполнялся. Проверены сохранность (БД+S3) и отказ API-реплики с повторным чтением вложения:

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
docker compose --env-file .env restart (postgres+s3+api1+api2+lb), volumes сохранены /health/ready ok; прежний Bearer; тот же оригинал по /content persistence PASS в бюджете теста; потери данных нет
docker compose stop одной API-реплики LB обслуживает живую; download оригинала через другую реплику failover PASS; first_recovery_seconds≈2.64 подтверждённые сообщения и файл на месте

Локальная проверка автора выполнялась на HOST_PORT=8083. На Windows для публичных тестов задайте PYTHONUTF8=1 (иначе чтение contracts/openapi.json может упасть на cp1251).

Аппаратный профиль: локальный Docker Desktop на Windows; 2 API + Nginx + PostgreSQL + MinIO без CPU/RAM limits.

Ограничения и следующие шаги

  • отдельные S3 credentials с минимальными правами, reconciler orphan-объектов, эксперимент ≥10 загрузок, presigned upload не выполнялись.
  • Единственный PostgreSQL, единственный MinIO и единственный Nginx — SPOF; отказ host/узла не выдерживается.
  • При сбое между PutObject и COMMIT возможны неучтённые объекты в bucket.
  • Basic по HTTP допустим только на локальном учебном стенде с синтетическими данными.