8.4 KiB
Лабораторная работа №4 — S3-хранилище и вложения
Автор, группа: Магазейщикова Дарья, БПИ2304
Целевая оценка: 3
Стек: Python 3.12 / FastAPI, PostgreSQL 16.8, SeaweedFS 3.80 (S3 API), Nginx 1.27.5, Docker Compose.
1. Цель
Разделить хранение метаданных и бинарных файлов, добавить PNG/JPEG-вложения в сообщения и обеспечить скачивание оригиналов через любую из двух API-реплик после переключения балансировщика.
2. Архитектура
Клиент → Nginx (localhost:8080) → api1 / api2 → PostgreSQL (пользователи, сессии, чаты, сообщения, метаданные вложений) + SeaweedFS S3 (http://s3:8333, бинарное содержимое).
API-реплики не используют локальный каталог для обязательного хранения оригиналов. Имя файла предназначено для отображения, а S3 object key генерирует сервер. Для PostgreSQL и SeaweedFS используются именованные тома postgres_data и s3_data. Сервисы migrate и s3-init завершаются с кодом 0 после выполнения своих задач. Инициализация создаёт bucket messenger-attachments при его отсутствии.
В infra/seaweedfs-s3.json настроена S3-учётная запись. Конфигурация и .env должны содержать согласованные ключи; демонстрационные секреты допустимы только в изолированном учебном окружении и должны быть заменены перед публикацией/внешним развёртыванием. Порт S3 не опубликован на хост.
3. Запуск из чистого клона
Требуются Docker Desktop с Compose и Python 3.9+ для публичных тестов. Из корня репозитория:
Copy-Item .env.example .env
notepad .env
# Заполнить переменные PostgreSQL и S3 согласно compose.yaml и infra/seaweedfs-s3.json.
$env:PYTHONUTF8 = "1"
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
docker compose ps -a
curl.exe http://localhost:8080/health/ready
python tests/smoke.py
Для Linux/macOS предусмотрены аналогичные команды cp .env.example .env, docker compose ... и make test. Проверка make check работает отдельно от запущенного приложения. При запуске из чистого клона необходимо убедиться, что файл scripts/init_bucket.py доступен внутри контейнера s3-init по пути /app/scripts/init_bucket.py (в текущем стенде используется bind mount в compose.yaml).
Миграции из каталога migrations/ выполняются сервисом migrate, их учёт ведётся в schema_migrations. Инициализатор s3-init создаёт bucket через boto3 и может безопасно запускаться повторно.
4. Реализация вложений
При загрузке принимаются PNG/JPEG размером не более 10 MiB и не более 40 млн пикселей. MIME определяется по содержимому изображения, имя файла проверяется, размер ограничивается до неограниченного чтения/декодирования. Успешная синхронная загрузка возвращает 201 и состояние ready. Метаданные Attachment сохраняются в PostgreSQL, оригинальные байты — в приватном S3 bucket. Сообщение может ссылаться на attachment_ids; доступ к метаданным и скачиванию через API разрешён участникам чата.
Порядок операций: сначала загрузка объекта в S3, затем фиксация метаданных в БД. При ошибке БД предпринимается компенсирующее удаление объекта. При аварии между операциями возможен «осиротевший» объект; автоматическая фоновая очистка не реализована.
5. Фактические результаты проверок (Windows PowerShell, 12.11.2026)
| Проверка | Результат |
|---|---|
docker compose --env-file .env config --quiet |
PASS, без ошибок |
docker compose --env-file .env up -d --build |
PASS после исправления пути init_bucket.py |
docker compose ps -a |
PostgreSQL healthy, обе API healthy, Nginx и SeaweedFS running; migrate и s3-init exited (0) |
GET /health/ready |
{"status":"ok"} |
python tests/smoke.py с PYTHONUTF8=1 |
PASS: lab4 public API scenario; infrastructure and grading evidence remain separate. |
Persistence с scripts/restart.cmd |
PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence. |
| Failover, запуск №1 | PASS; 2 реплики до отказа; 97 успешных записей, 0 ошибок; восстановление 0,785 с |
| Failover, запуск №2 | PASS; 2 реплики до отказа; 97 успешных записей, 0 ошибок; восстановление 0,794 с |
s3-init |
Private S3 bucket ready: messenger-attachments |
Анонимный GET http://127.0.0.1:8333/messenger-attachments/test.png из S3-контейнера |
HTTP 403 Forbidden |
Команды проверки устойчивости:
$env:PYTHONUTF8 = "1"
python tests/resilience.py --mode persistence --action-script scripts/restart.cmd
python tests/resilience.py --mode failover --action-script scripts/stop-one.cmd
docker compose --env-file .env up -d api1 api2
Скрипт restart.cmd перезапускает PostgreSQL и S3, ожидает 12 секунд, затем перезапускает API и балансировщик и ожидает ещё 5 секунд; тома не удаляются. stop-one.cmd использует TARGET_INSTANCE_ID для остановки обслуживавшей реплики. После теста реплики восстановлены. Вывод тестов подтверждает сохранность данных и сессий, включая оригинал изображения для persistence в lab4.
Границы доказательств: два запуска failover прошли. Анонимный запрос вернул 403, но обращался к test.png, существование которого не доказано; для окончательного подтверждения приватности нужен анонимный GET реально загруженного object key. Также полезно приложить выводы docker compose ps до и после restart и остановки реплики. Публичный smoke не заменяет все негативные и инфраструктурные проверки.
6. Ограничения
- Единственный экземпляр PostgreSQL, SeaweedFS и Nginx остаётся точкой отказа; failover проверяет только API-реплики.
/health/readyне гарантирует мгновенную готовность S3 после его рестарта; для persistence используется ожидание в скрипте. В дальнейшем нужна зависимостная readiness-проверка.- Возможны orphan-объекты при аварийном завершении между записью в S3 и коммитом БД.