12 KiB
Отчёт — лабораторная 4
- Автор, группа: Гадяцкий Л. Е., БПИ2302
- Целевая оценка: 3
- Commit/PR: solution/BPI2302-Gadiatskiy MR#121: #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 внутри контейнеров APIHOST_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иapi2S3_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-shotmigrate; Alembic не используется. - Порты API и MinIO наружу не публикуются; публичная точка входа — LB (
infra/nginx.conf:client_max_body_size 11m,least_conn). - Compose:
lb+api1+api2+postgres+s3+migrate, volumespgdataи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 допустим только на локальном учебном стенде с синтетическими данными.