13 KiB
Отчёт — лабораторная 5
- Автор, группа: Гадяцкий Л. Е., БПИ2302
- Целевая оценка: 3
- Commit/PR: solution/BPI2302-Gadiatskiy
- Использованные источники и библиотеки:
- контракт и семантика:
contracts/openapi.json,contracts/README.md,contracts/attachment-states.md,README.md,COURSE.md - перенос из lab4: FastAPI, PostgreSQL/сессии, SQLAlchemy, миграции, Nginx LB, идемпотентность, MinIO/S3, вложения
- 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, pika 1.3.2
- PostgreSQL:
postgres:16-alpine; LB:nginx:1.27-alpine; S3/MinIO:alpine/minio:RELEASE.2025-10-15T17-29-55Z; broker:rabbitmq:3.13.7-alpine
- контракт и семантика:
- Помощь ИИ использована при переносе lab4, частичной реализации брокера/worker-а и при заполнении отчёта. Результаты подтверждаются сохранёнными запусками.
Запуск из чистого clone
Prerequisites: Docker и Docker Compose. Python 3.9+ нужен только для публичных проверок (make check / make test / tests/resilience.py). Runtime приложения — внутри образа.
Версии:
- API/worker: базовый образ
python:3.12.8-slim-bookworm→ локальныйmtusi-messenger:lab5 - PostgreSQL:
postgres:16-alpine - Nginx:
nginx:1.27-alpine - MinIO:
alpine/minio:RELEASE.2025-10-15T17-29-55Z(community image; официальныйminio/minioс Docker Hub недоступен) - RabbitMQ:
rabbitmq:3.13.7-alpine - зависимости:
requirements.txt
Конфигурация: секретов в Git нет. Локальный .env создаётся из примера и не коммитится:
cp .env.example .env
Соответствие .env.example:
APP_HOST/APP_PORT— bind uvicorn внутри контейнеров APIHOST_PORT— порт LB на host (по умолчанию 8080; если занят — например 8085)APP_ENV— среда запуска (lab)SESSION_TTL_SECONDS— TTL сессии (по умолчанию 3600; для обычного smoke ≥ 300)SESSION_STORE=postgres— сессии в PostgreSQL (общие для всех реплик)DATABASE_URL— строка подключения API/migrate/worker к PostgreSQL в compose-сети
(приложение также поддерживаетDATABASE_URL_FILE)IDEMPOTENCY_TTL_SECONDS— срок хранения идемпотентных записей (по умолчанию 86400)API_REPLICAS=2— вcompose.yamlзафиксированы сервисыapi1иapi2S3_ENDPOINT/S3_REGION/S3_BUCKET— доступ API/worker к MinIO в compose-сетиS3_ACCESS_KEY_ID/S3_SECRET_ACCESS_KEY— учебные credentials MinIO (также*_FILE)MAX_UPLOAD_BYTES=10485760,MAX_IMAGE_PIXELS=40000000— лимиты загрузки/декодированияBROKER_URL— AMQP URL RabbitMQ (такжеBROKER_URL_FILE)WORKER_CONCURRENCY— prefetch consumer worker (по умолчанию 2)JOB_MAX_ATTEMPTS=5— лимит управляемых попыток обработкиJOB_TIMEOUT_SECONDS,STAGING_RETENTION_SECONDS— параметры эксплуатации (зафиксированы в.env)
Учебные credentials compose (messenger / messenger, MinIO minioadmin / minioadmin, RabbitMQ messenger / messenger) только для локального синтетического стенда.
Сборка и запуск:
docker compose --env-file .env up -d --build
Миграции migrations/*.sql применяет one-shot сервис migrate до старта api1/api2/worker (учёт в schema_migrations). Приватный bucket S3_BUCKET идемпотентно создают API и worker при старте (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) и RabbitMQ.
Публичный 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, broker, api1, api2, worker, lb без удаления volumes (down -v не используется).
Проверка отказа одной API-реплики:
# 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). Для защиты повторить на второй реплике после восстановления первой.
Демо остановки worker (уровень 3):
docker compose --env-file .env stop worker
# upload → 202 queued; GET /content → 409; сообщение с attachment_ids допускается
docker compose --env-file .env restart api1 api2
docker compose --env-file .env start worker
# опросить GET /attachments/{id} до ready; thumbnail доступен
Остановка:
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 (+ staging_object_key), attachment_jobs,
attachment_variants, sessions, idempotency_records
→ MinIO (S3)
staging/{chat_id}/{attachment_id}
attachments/{chat_id}/{attachment_id}/original
attachments/{chat_id}/{attachment_id}/variants/thumbnail.jpg
→ RabbitMQ (durable queue attachment.process)
→ worker (отдельный процесс)
читает staging → пишет final original + thumbnail → status=ready → ack
- Источник истины для метаданных — PostgreSQL; байты — только в S3. В сообщениях брокера только ID/служебные поля по
jobs.schema.json, без bytes и credentials. - До
202: оригинал в durable staging (S3), записьattachmentsсоstatus=queued, записьattachment_jobs, затем publish с publisher confirm. Остановка API после ответа не удаляет принятую работу. - Worker отделён от API: переносит оригинал в конечный S3-prefix, строит JPEG thumbnail (вписан в 256×256, без увеличения; EXIF orientation; alpha на белый). Fixture 320×200 → 256×160.
- Состояния
queued/processing/ready/failedвидны в API.GET .../contentдля queued/processing/failed →409; отсутствующий variant у ready →404. - Сообщение может ссылаться на queued/processing вложение;
failed→409. - Retry ограничен
JOB_MAX_ATTEMPTS(по умолчанию 5); исчерпание →failed/retry_exhausted. Повтор уже ready-задачи — no-op с ack; variantthumbnailне размножается. - Ack — после устойчивой записи результата; delivery at-least-once (persistent messages, durable queue, manual ack).
- Сессии в PostgreSQL;
X-Instance-Idстабилен на жизнь процесса;Idempotency-Keyна POST сообщений сохранён из lab3/lab4. - Compose:
lb+api1+api2+worker+postgres+s3+broker+migrate, volumespgdata,miniodata,brokerdata.
Перенесено из lab4: auth Basic→Bearer, Argon2id, чаты/сообщения, LB, две реплики, идемпотентность, MinIO, upload/download.
Изменено в lab5: upload 201/ready → 202/queued; staging + jobs; RabbitMQ; worker; thumbnail variant; link queued вложений.
Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|---|---|---|---|
| Публичный smoke (202 → ready, thumbnail 256×160) | python tests/smoke.py --base-url http://127.0.0.1:8085 |
PASS: lab5 public API scenario... |
evidence/smoke.txt |
| Стенд: ≥2 API, LB, Postgres, MinIO, broker, worker | docker compose --env-file .env ps |
lb, api1, api2, postgres, s3, broker, worker; 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:8085 |
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:8085 |
failover PASS; first_recovery_seconds≈2.89 |
evidence/failover.txt |
| Worker stop → upload 202 → restart API → start worker → ready | python evidence/worker_stop_demo.py |
upload queued; content 409; после старта worker — ready + thumbnail 256×160 | evidence/worker-stop.txt |
Эксперименты и отказы
Для оценки 3 отдельный нагрузочный трек не выполнялся. Проверены сохранность (БД+S3+broker), отказ API-реплики и остановка worker:
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|---|---|---|---|
docker compose --env-file .env restart (postgres+s3+broker+api1+api2+worker+lb), volumes сохранены |
/health/ready ok; прежний Bearer; тот же оригинал по /content |
persistence PASS | в бюджете теста; потери данных нет |
docker compose stop одной API-реплики |
LB обслуживает живую реплику | failover PASS; first_recovery_seconds≈2.89 |
подтверждённые сообщения на месте |
docker compose stop worker → upload → restart API → start worker |
202 queued сохраняется; после worker — ready/thumbnail | demo PASS; attachment 49100060-... стал ready |
сообщение в durable queue пережило остановку worker; потери нет |
Локальная проверка автора выполнялась на HOST_PORT=8085. На Windows для публичных тестов задайте PYTHONUTF8=1 (иначе чтение contracts/openapi.json может упасть на cp1251).
Аппаратный профиль: локальный Docker Desktop на Windows; 2 API + worker + Nginx + PostgreSQL + MinIO + RabbitMQ без CPU/RAM limits.
Ограничения и следующие шаги
- transactional outbox, DLQ/replay, crop/optimized WebP, lease зависшего processing — не реализованы (уровень 4).
- Единственный PostgreSQL, MinIO, RabbitMQ и Nginx — SPOF; отказ host/узла не выдерживается.
- При сбое между COMMIT задания и publisher confirm возможна запись queued без сообщения в брокере до ручного вмешательства.
- Basic по HTTP допустим только на локальном учебном стенде с синтетическими данными.