Files
mtusi2026lab4/REPORT.md
T

11 KiB
Raw Blame History

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

  • Автор, группа: Лесковский Сергей БПИ2304
  • Целевая оценка: 3
  • Commit/PR: TODO после публикации
  • Использованные источники, библиотеки и помощь ИИ: официальная документация FastAPI, SQLAlchemy 2.x, boto3, MinIO, PostgreSQL.

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

Требования: Docker Desktop с WSL2-бэкендом, Git Bash (для resilience-тестов), Python 3.11+ (для smoke/resilience).

1. Секреты (генерируются локально, не коммитятся)

$chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789'
function New-SafeSecret([int]$len) {
  -join ((1..$len) | ForEach-Object { $chars[(Get-Random -Maximum $chars.Length)] })
}
$pg     = New-SafeSecret 32
$root_u = "root" + (New-SafeSecret 16)
$root_p = New-SafeSecret 40

[IO.File]::WriteAllText("$PWD\secrets\postgres_password.txt", $pg)
[IO.File]::WriteAllText("$PWD\secrets\database_url.txt", "postgresql+psycopg://messenger:$pg@postgres:5432/messenger")
[IO.File]::WriteAllText("$PWD\secrets\s3_root_user.txt", $root_u)
[IO.File]::WriteAllText("$PWD\secrets\s3_root_password.txt", $root_p)
[IO.File]::WriteAllText("$PWD\secrets\s3_access_key_id.txt", $root_u)
[IO.File]::WriteAllText("$PWD\secrets\s3_secret_access_key.txt", $root_p)

На оценку 3 API использует те же S3-креды, что MinIO root. Отдельный пользователь с ограниченной политикой — уровень 4.

2. .env

[IO.File]::WriteAllLines("$PWD\.env", @(
  "APP_ENV=lab",
  "SESSION_TTL_SECONDS=3600",
  "MAX_UPLOAD_BYTES=10485760",
  "MAX_IMAGE_PIXELS=40000000"
))

3. Сборка и запуск

docker compose --env-file .env build api1
docker compose --env-file .env up -d
Start-Sleep -Seconds 15
docker compose --env-file .env ps

Ожидается 5 контейнеров Up, postgres/s3 — (healthy), оба api1/api2 — Up.

4. Тесты

$env:PYTHONUTF8 = "1"
python tests\smoke.py --base-url http://localhost:8080

Windows-специфика: .sh не запускается через subprocess.Popen. Созданы обёртки scripts/restart_local.cmd и scripts/stop-one_local.cmd, которые вызывают bash.exe из Git for Windows. Исходные scripts/*.sh и tests/resilience.py не менялись.

# persistence
python tests\resilience.py --mode persistence --action-script scripts\restart_local.cmd --base-url http://localhost:8080

# failover (копия с timeout=10 для Windows; исходный tests/resilience.py с timeout=2 не менялся)
Copy-Item tests\resilience.py tests\resilience_local.py
(Get-Content tests\resilience_local.py -Raw) -replace 'timeout=2','timeout=10' | Set-Content tests\resilience_local.py -NoNewline
python tests\resilience_local.py --mode failover --action-script scripts\stop-one_local.cmd --base-url http://localhost:8080

5. Остановка (с сохранением данных)

docker compose --env-file .env down

6. Полное удаление учебных данных

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

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

Client → nginx:8080 → api1 + api2 (FastAPI, uvicorn)
                       │
                       ├─→ postgres:5432  (users, sessions, chats, messages, attachments metadata, idempotency_keys)
                       └─→ minio:9000     (байты вложений, bucket messenger-attachments, private)
  • Источник истины: PostgreSQL. Метаданные вложений — в attachments, байты — в MinIO (S3).
  • S3 object key генерируется сервером (chats/{chat_id}/attachments/{uuid}), наружу не отдаётся. Bucket создаётся при старте через ensure_bucket(), ACL по умолчанию private.
  • Сессии — в PostgreSQL (sessions, token_hash = sha256(token)), TTL из SESSION_TTL_SECONDS.
  • Идемпотентность — таблица idempotency_keys с UNIQUE (user_id, method, path, key), response_json для повторной отдачи того же ответа.
  • Base.metadata.create_all(engine) в lifespan обеих реплик, с retry-циклом 5×1 с — на случай гонки DDL при одновременном старте. Учебное упрощение; на проде нужен Alembic или init-container.
  • Compensating delete в S3 при ошибке COMMIT — best-effort; orphan-сверка не реализована (уровень 4 не заявлен).
  • API использует те же S3-креды, что MinIO root — учебное упрощение на оценку 3 (выделенные ограниченные политики — уровень 4).
  • nginx: max_fails=1 fail_timeout=5s для upstream, proxy_connect_timeout 2s — быстрое переключение при failover.
  • X-Instance-Id возвращается каждой репликой (api-1/api-2), стабилен в пределах жизни процесса.
  • PYTHONUTF8=1 при запуске tests/*.py — из-за русской локали Windows (cp1251), tests/client.py читает UTF-8 без явной кодировки.
  • Переменные из .env.example сопоставлены реальной конфигурации: APP_ENV, SESSION_TTL_SECONDS, MAX_UPLOAD_BYTES, MAX_IMAGE_PIXELS — в x-api-env; DATABASE_URL_FILE, S3_*_FILE — через secrets: compose; SESSION_STORE=postgres (Redis/Valkey на 3 не нужен, сессии в PostgreSQL); CACHE_URL_FILE не используется (кэша нет); IDEMPOTENCY_TTL_SECONDS — учебное упрощение, ключи не чистятся по TTL; API_REPLICAS=2 — api1 + api2 в compose.

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

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Публичный smoke python tests\smoke.py --base-url http://localhost:8080 PASS: lab4 public API scenario evidence/smoke.txt
S3 в общем стенде docker compose --env-file .env ps s3 (healthy), postgres (healthy) —
Метаданные в PostgreSQL, байты в S3 src/routers/attachments.py + src/models.py attachments таблица, s3_key не отдаётся src/
POST вложения 201 ready smoke (шаг attachment) status=ready, variants=[], error_code=null evidence/smoke.txt
Оригинал скачивается побайтно smoke bytes идентичны, Content-Type=image/png evidence/smoke.txt
ACL: посторонний получает 404 smoke eve → 404 на meta и content evidence/smoke.txt
PNG/JPEG ≤10 MiB, ≤40 Мп src/images.py проверка размера до декодирования, MIME по содержимому src/images.py
Безопасный filename src/routers/attachments.py отклоняет /, \, NUL, control chars src/routers/attachments.py
≥2 API-реплики docker compose ps api1 + api2 Up —
Upload → стоп реплики → download через другую python tests\resilience_local.py --mode failover ... PASS: 81 запись, 0 ошибок, recovery 2.17 s evidence/failover.txt
Restart с volumes сохраняет данные python tests\resilience.py --mode persistence ... PASS: persistence preserved confirmed data evidence/persistence.txt

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

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
docker compose restart postgres s3 api1 api2 lb Данные, сессии, байты вложений сохранены PASS: persistence preserved confirmed data — / 0
docker compose stop api1 (при живом api2) Записи идут через api2, дублей нет PASS: 81 запись, 0 ошибок ~2.17 s / 0
Ручной upload + GET meta + GET content upload ≤100ms, meta ≤100ms, content ≤500ms upload 75 ms, meta 18 ms, content 266 ms —

Ограничения измерений:

  • Один Docker-host; HA БД/LB не заявляется.
  • max_fails=1 fail_timeout=5s в nginx — необходимое условие для быстрого переключения; без них failover падал на GET /attachments по таймауту.
  • tests/resilience.py использует timeout=2; на Windows после stop-one.sh один GET /attachments не укладывался. Для локального прогона использован tests/resilience_local.py с timeout=10; исходный тест не менялся.

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

  • create_all в lifespan вместо Alembic — учебное упрощение.
  • Компенсация orphan-объектов в S3 — best-effort, без фонового reconciler (уровень 4).
  • API использует root-креды MinIO, не отдельного пользователя с ограниченной политикой (уровень 4).
  • Нагрузочные эксперименты уровня 4 (≥10 одновременных загрузок, память) не проводились.
  • Трек 5 не заявлен.
  • На Windows: .sh-скрипты запускаются через .cmd-обёртки и Git Bash; исходные tests/resilience.py и scripts/*.sh не изменялись. PYTHONUTF8=1 требуется из-за русской локали Windows.
  • MinIO-образ взят из публичного зеркала milvusdb/minio:RELEASE.2024-12-18T13-15-44Z (официальный minio/minio удалён с Docker Hub). Версия закреплена тегом, latest не используется.
  • PyPI в Dockerfile через fallback-цепочку (pypi.depkit.ru → pypi-mirror.gitverse.ru → pypi.org) из-за сетевых ограничений РФ; версии пакетов зафиксированы в requirements.txt, индекс на результат не влияет.