11 KiB
Лабораторная 4: S3-хранилище и вложения
Мессенджер на FastAPI с PostgreSQL, Redis и двумя API-репликами за HAProxy. Оригиналы PNG/JPEG хранятся в приватном MinIO, метаданные и связи с сообщениями — в PostgreSQL. Выполнены требования уровня 4 и трек 2 на 5: согласованность двух хранилищ, повторяемая сверка, безопасная очистка и эксперименты.
Автор: Каменский Андрей, БПИ2301.
Задание · Отчёт · Семантика API · OpenAPI · Алгоритм сверки · Проверка замечаний преподавателя
Запуск с нуля
Нужны Docker с Compose v2 и Python 3.13 для полного набора проверок. Публичный HTTP smoke использует только стандартную библиотеку Python 3.9+.
python3 scripts/setup-env.py
docker compose config --quiet
docker compose up -d --build --wait
python3 tests/smoke.py
setup-env.py создаёт .env с новыми случайными паролями и правами 0600,
не выводит значения и не перезаписывает существующий файл. Для существующего
стенда сохранить прежний .env и volumes. Логин стартового администратора —
ADMIN_USERNAME, пароль — ADMIN_PASSWORD из локального .env.
Первый build собирает MinIO community из закреплённого commit, поэтому требует интернет и может занять несколько минут. Это не зависит от наличия готового официального образа MinIO. При запуске автоматически выполняются миграции до 008, создание приватного bucket, пользователей и S3-политик. Все сервисы находятся в этом Compose; заранее установленная БД или S3 не нужны.
API: http://localhost:8080, Swagger: http://localhost:8080/docs. Наружу опубликован только LB на loopback. Консоль MinIO выключена.
В этой локальной копии после переноса выбран APP_PORT=8084: Swagger находится
на http://localhost:8084/docs. Верификатор читает порт
из локального .env. Для отдельных Make-target можно передать
BASE_URL=http://127.0.0.1:8084. Новый клон по умолчанию использует 8080.
docker compose down # остановить, сохранить данные
# Осознанно удалить все учебные данные текущего проекта:
# docker compose down --volumes
Архитектура
flowchart LR
C[Клиент] --> LB[HAProxy]
LB --> A1[API 1]
LB --> A2[API 2]
A1 --> PG[(PostgreSQL)]
A2 --> PG
A1 --> R[(Redis: сессии)]
A2 --> R
A1 --> S3[(Приватный MinIO)]
A2 --> S3
W[Reconciler] --> PG
W --> S3
PostgreSQL хранит пользователей, чаты, сообщения, вложения, идемпотентность и
журнал загрузок. Redis хранит сессии с TTL/AOF и кэш профилей. MinIO хранит
неизменённые оригиналы в volume minio_data. У API нет постоянного локального
состояния. У сообщения до 10 уникальных вложений; одно вложение можно повторно
использовать в том же чате. Связующая таблица сохраняет порядок и запрещает
связывать разные чаты составными внешними ключами.
Загрузка и чтение
- Создать пользователя и сессию, создать чат с явным списком участников.
POST /api/v1/chats/{chat_id}/attachments?filename=photo.png: Bearer-токен,Content-Type: image/pngилиimage/jpeg, в теле сырые байты одного файла.- После S3 PUT и COMMIT вернуть
201 Attachment,status=ready,variants=[]. - Создать сообщение с
Idempotency-Keyи телом{"text":"", "attachment_ids":["UUID"]}. Текст можно оставить пустым при наличии файла. GET /api/v1/attachments/{id}— метаданные;GET /api/v1/attachments/{id}/content— оригинал через API без redirect.
Доступ есть только у участников чата; посторонним — 404. Filename не используется как путь или S3 key. Размер — до 10 MiB, число пикселей — до 40 млн включительно. Формат определяется по содержимому и сравнивается с MIME; после ранней проверки размеров проверяются структура и декодирование. Оригинал не пересохраняется. Примеры для HTTP-клиента: examples/student-requests.http.
API использует отдельную S3-учётную запись без DeleteObject и административных прав. Reconciler может читать/удалять только в нашем префиксе, не может загружать объекты. Owner credentials передаются только MinIO и bootstrap.
Согласованность и отказы
Перед PUT отдельным COMMIT создаётся upload_intents.pending. Загрузчик удерживает
транзакционный advisory lock на ключ до публикации Attachment и перевода намерения
в committed. Reconciler пропускает занятые ключи; старые pending без Attachment
закрывает, бесхозные объекты удаляет. Запас для свежих объектов/попыток — 300 секунд,
настраивается через RECONCILE_GRACE_SECONDS.
Сверка проходит каждые 300 секунд, ограничена нашим bucket и originals/, читает
ListObjectsV2 постранично. Потеря оригинала отмечается без удаления сообщений;
его восстановление подтверждается размером и SHA-256. Ошибка удаления не закрывает
возможность повторной очистки. Полный алгоритм и ограничения —
LAB4_RECONCILIATION.md.
make -f student.mk reconcile # dry-run: только показать действия
make -f student.mk reconcile-apply # повторно проверить и применить
Readiness проверяет PostgreSQL, Redis и bucket с HTTP-бюджетом 2 секунды. Обычные бизнес-запросы ограничены 5 секундами до заголовков ответа, включая ожидание отмены SQL/rollback. Зависшие обработчики отменяются, но занимают свой лимит до завершения. После возобновления PostgreSQL API восстанавливается без перезапуска. Binary upload имеет отдельный бюджет приёма и завершающий deadline.
Проверки
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-student.txt
make -f student.mk check validate lint PYTHON=.venv/bin/python
make -f student.mk verify-lab4 PYTHON=.venv/bin/python
Полная проверка выполняет сценарии последовательно: публичный smoke, вложения,
конкурентную идемпотентность, замечания преподавателя, сверку со сбоями, память
при 10 загрузках, отказ загрузившей реплики, сохранность и сборку с пустыми volumes.
Она создаёт синтетические данные и временно останавливает/замораживает сервисы
учебного стенда; восстановление включено в сценарии. Отдельный clean-start
использует UUID-проект, новый порт и новые volumes; текущие данные не удаляются.
Итог: evidence/lab4-final-summary.json, детальный вывод — evidence/lab4-final-*.txt.
make -f student.mk test-attachments PYTHON=.venv/bin/python
make -f student.mk test-lab4-review PYTHON=.venv/bin/python
make -f student.mk test-reconciliation
make -f student.mk test-upload-memory PYTHON=.venv/bin/python
make -f student.mk test-attachment-failover PYTHON=.venv/bin/python
make -f student.mk test-persistence-proof ACTION_SCRIPT=scripts/restart.sh PYTHON=.venv/bin/python
make -f student.mk test-clean-lab4 PYTHON=.venv/bin/python
Параметры и локальные credentials описаны в student.env.example. Результаты, методика и ограничения находятся в REPORT.md.
Исходные материалы преподавателя
Все 34 файла skeleton сохранены побайтно, включая README.md, REPORT.md, Makefile,
.env.example, requirements-dev.txt, lab.json, тесты, контракт и исходный workflow.
Наши инструкции находятся в STUDENT_README.md, отчёт — в STUDENT_REPORT.md,
описание PR — в PULL_REQUEST.md. Наши команды — в student.mk, шаблон настроек —
student.env.example, полный набор зависимостей проверок — в requirements-student.txt.
Проверка неизменности: python3 scripts/check-course-files.py.