120 lines
18 KiB
Markdown
120 lines
18 KiB
Markdown
# Лабораторная 4 — файлы в S3
|
||
|
||
Автор: Саламатин, БПИ-2304. Целевая оценка: **4**, включая весь минимум на 3. Треки на 5 не выполнялись.
|
||
|
||
## Как запустить
|
||
|
||
Нужны Docker Desktop с Linux containers и Compose. Из корня репозитория в PowerShell:
|
||
|
||
```powershell
|
||
./start.ps1
|
||
```
|
||
|
||
Или вручную, если установлен Python 3.9+:
|
||
|
||
```powershell
|
||
python scripts/init_local.py
|
||
docker compose build api checks minio
|
||
docker compose up -d --no-build --wait --wait-timeout 180
|
||
curl.exe --noproxy "*" http://127.0.0.1:8084/health/ready
|
||
```
|
||
|
||
Каждый образ собираем один раз: сервисы migrate, api и cleanup используют общий образ. Первая сборка MinIO занимает несколько минут: готовые образы из реестров оказались недоступны, поэтому Dockerfile собирает официальный исходный релиз MinIO `RELEASE.2025-09-07T16-13-09Z` и mc `RELEASE.2025-08-13T08-35-41Z`. Версии Go и базовых образов зафиксированы в Dockerfile. Python и зависимости приложения закреплены в requirements.txt и Dockerfile. После успешной сборки Compose использует локальный образ `mtusi-minio:2025-09-07`.
|
||
|
||
init_local.py один раз создаёт случайные секреты и .env. Повторный запуск сохраняет значения. Секреты не добавляются в Git. Не менять пароли при сохранённых volumes без отдельной процедуры смены пароля хранилища.
|
||
|
||
По умолчанию доступен только балансировщик на `127.0.0.1:8084`. Порт выбран отдельно от lab3. API_PORT меняет внешний порт, API_REPLICAS задаёт число API, SESSION_TTL_SECONDS — срок сессий, APP_VERSION — метку версии, APP_ENV — метку окружения. API внутри контейнера слушает 8080. Остальные настройки и пути secrets находятся в compose.yaml.
|
||
|
||
Остановить без потери данных: `docker compose stop` или `docker compose down`. Команда намеренного удаления учебных данных: `docker compose down --volumes`; в проверках она не используется.
|
||
|
||
## Что сделано и зачем
|
||
|
||
Перенесена собственная реализация lab3: FastAPI, PostgreSQL, сессии Redis с TTL и AOF, scrypt, проверка членства в чате, история с cursor, идемпотентная отправка сообщений, HAProxy и две API-реплики. Публичные contracts и tests lab4 сохранены.
|
||
|
||
Клиент обращается к HAProxy, тот выбирает API. PostgreSQL хранит пользователей, чаты, сообщения и сведения о вложениях. Оригиналы находятся в приватном bucket MinIO. Redis хранит сессии. Все три хранилища используют отдельные именованные volumes. API не хранит подтверждённые оригиналы у себя.
|
||
|
||
Миграция 003 добавляет attachments и attachment_ids сообщения. Вложение заранее связано с чатом. object_key — случайный UUID с префиксом original/, имя клиента используется только в метаданных. Доступ к метаданным и байтам проверяется по членству в чате. Для чужого объекта возвращается 404. Один участник может прикрепить файл, загруженный другим участником того же чата.
|
||
|
||
POST вложения принимает сырое тело PNG/JPEG. Лимит — 10 MiB и 40 млн пикселей. Сначала проверяем заголовки, имя и доступ, затем читаем тело по частям во временный файл с подсчётом размера и SHA-256. Временный файл — только staging на время запроса, после него закрывается. Размеры проверяем до декодирования, MIME — по фактическому формату Pillow. verify проверяет структуру, load ловит ошибки декодирования. Оригинал не перекодируется.
|
||
|
||
Одна реплика одновременно декодирует один файл. Ожидание слота ограничено 10 s, чтение тела — 20 s, общий бюджет до формирования ответа — 35 s. S3 connect/read timeout — 2/3 s, автоматических повторов PUT нет. HAProxy даёт 40 s. При отмене запроса ждём завершения уже начатой операции в потоке, прежде чем закрыть временный файл и освободить SQL-блокировку. Контейнер API ограничен 512 MiB. Это ограничивает память, но не обещает постоянную задержку под любой нагрузкой.
|
||
|
||
201 ready возвращается после S3 PUT и SQL COMMIT. GET content сначала проверяет сессию и чат, затем читает оригинал из S3 кусками по 64 KiB, без redirect. variant=original — единственный вариант. Сбой во время уже начатого скачивания может оборвать ответ: заменить его JSON-ошибкой после отправки заголовков невозможно.
|
||
|
||
Отпечаток идемпотентности сообщения теперь учитывает attachment_ids; отсутствие поля и [] равны. Пустой текст допустим с вложениями. Чужие, неизвестные и принадлежащие другому чату ID отклоняются до вставки сообщения.
|
||
|
||
## Если запись оборвалась
|
||
|
||
Общей транзакции PostgreSQL и S3 нет. Перед PUT отдельно фиксируем строку pending со случайным ключом. Затем блокируем эту строку, записываем S3 и меняем статус на ready одной SQL-транзакцией. Если процесс погибнет после PUT или SQL COMMIT завершится ошибкой, останется учтённая строка pending. Её нельзя прикрепить к сообщению или скачать через API.
|
||
|
||
Сервис cleanup раз в минуту берёт до 100 pending старше часа через FOR UPDATE SKIP LOCKED, удаляет объект S3 и затем строку БД. При ошибке S3 строка остаётся для следующего прохода. DELETE S3 повторяем, поэтому сбой между удалением объекта и COMMIT не мешает следующему запуску. Часовой grace period защищает свежие запросы, блокировка — выполняющуюся финализацию. Ready не очищаются, даже если ещё не прикреплены к сообщению: контракт разрешает прикрепить их позже.
|
||
|
||
Обрыв HTTP до завершения приёма тела не вызывает PUT. Используется одиночный PUT без multipart, незавершённые multipart-загрузки не создаются. Для всех PUT сначала существует запись в БД, поэтому полного обхода bucket для штатной очистки не нужно. Ручное изменение БД или загрузка объектов администратором вне приложения этим механизмом не покрывается.
|
||
|
||
## Приватный bucket и права
|
||
|
||
bucket-init ждёт готовности MinIO, создаёт bucket с --ignore-existing, выключает anonymous access, создаёт отдельного пользователя messenger-api и назначает ему политику. Повторный bootstrap безопасен для существующих файлов. У API есть только ListBucket для attachments и GetObject/PutObject/DeleteObject для original/*. Нет прав создавать bucket, менять политику или пользователей. У cleanup такие же ограниченные credentials. Корневой пароль доступен только MinIO и bootstrap.
|
||
|
||
MinIO не публикует порты на хост, административная консоль слушает только 127.0.0.1 внутри его контейнера. Проверка приватности выполняется напрямую по внутреннему адресу S3 без API и без подписи; проверяется и листинг bucket, и GET существующего объекта. Отдельно проверяется запрет административных операций с API credentials.
|
||
|
||
## Проверки
|
||
|
||
Полный прогон: `python scripts/verify.py`. На этом компьютере также можно использовать `../.tools/python/python.exe -X utf8 scripts/verify.py`.
|
||
|
||
```powershell
|
||
docker compose run --rm --no-deps checks make check test
|
||
docker compose run --rm --no-deps checks make test-student
|
||
docker compose run --rm --no-deps checks sh -ec 'chmod +x scripts/restart.sh; make test-persistence ACTION_SCRIPT=scripts/restart.sh'
|
||
docker compose run --rm --no-deps checks sh -ec 'chmod +x scripts/stop-one.sh; make test-failover ACTION_SCRIPT=scripts/stop-one.sh'
|
||
docker compose start api
|
||
```
|
||
|
||
Failover оставляет выбранную реплику остановленной; восстановление выполняется отдельно. verify.py делает это сам. Restart перезапускает API, PostgreSQL, Redis, MinIO и LB без удаления volumes; cleanup продолжает работу и переподключается к БД.
|
||
|
||
Проверки выполнены 17 ноября 2026 года. Ветка `solution/bpi-2304-salamatin`; исходный skeleton `ec540a1`. Проверенная реализация — commit `372471a`. Реализация находится в локальном репозитории; fork/PR ещё не публиковались.
|
||
|
||
| Требование | Проверка | Результат | Доказательство |
|
||
| --- | --- | --- | --- |
|
||
| Минимум lab3 и API lab4 | `make check test`, `make test-student` | Публичный smoke и 17 собственных тестов прошли | smoke.txt, student-tests.txt |
|
||
| Оригинал, checksum, сообщение с attachment_ids, доступ участника | Публичный smoke и test_validation_and_acl | Побайтовое совпадение, чужому пользователю 404 | smoke.txt, student-tests.txt |
|
||
| Ограничения bytes, pixels, MIME, filename | test_validation_and_acl | 413 / 415 / 400, без 500 | student-tests.txt |
|
||
| Чужой attachment_id и файл другого чата | test_validation_and_acl | 404, сообщение не создаётся | student-tests.txt |
|
||
| Обрыв тела и ошибка после S3 PUT | test_failed_commit_cleanup_and_abort | Обрыв не создаёт строку; PUT + ошибка SQL оставляют pending | student-tests.txt |
|
||
| Grace period и повторяемая очистка | Тот же тест | Свежий pending сохранён; старый удалён из S3 и БД; повтор безопасен | student-tests.txt |
|
||
| Недоступность S3 | test_s3_outage | live 200, ready/upload/download 503; после запуска прежний файл читается | student-tests.txt |
|
||
| Приватность и ограничение прав | test_private_bucket_and_bootstrap | Anonymous list/GET существующего объекта 403; create bucket и запись вне prefix 403 | student-tests.txt |
|
||
| Bootstrap можно повторять | Два запуска существующего bucket-init | Без ошибок, ранее загруженный файл сохранён | student-tests.txt |
|
||
| Сохранность после restart | `make test-persistence`, сравнение контейнеров | Прежняя сессия и оригинал сохранены; изменился StartedAt у API, PostgreSQL, Redis, MinIO и LB; volumes те же | persistence.txt, restart.json |
|
||
| Публичный failover | Два `make test-failover` | Обе проверки прошли, восстановление 2.309 и 2.320 s | failover-1.txt, failover-2.txt, stop-1.json, stop-2.json |
|
||
| Остановка именно загрузившей API | `python scripts/check_uploader_failover.py` в checks | Upload instance остановлен, download instance другой, SHA-256 совпал | uploader-failover.json |
|
||
| 10 одновременных загрузок и память | test_ten_parallel_uploads_memory | 10 из 10 загружены и скачаны; контрольные суммы совпали | uploads-memory.json |
|
||
|
||
Все файлы доказательств находятся в evidence/. Итоговый smoke после отказов — smoke-final.txt. Проверки инфраструктуры выполнялись с сохранением volumes.
|
||
|
||
### Условия опыта с памятью
|
||
|
||
Docker Desktop 28.5.1, x86_64, 16 доступных CPU, 7.47 GiB RAM виртуальной машины Docker. У каждой API-реплики лимит 1 CPU и 512 MiB. Две реплики, HAProxy round-robin. Один прогон без отдельного прогрева; до опыта выполнялись функциональные проверки. Barrier запускает 10 HTTP-загрузок одновременно. Каждый файл — PNG 1700×1600 со случайными RGB-пикселями, 8173157 байт. Каждый клиент после upload скачивает файл и проверяет SHA-256. Время всего опыта с загрузкой и скачиванием — 3.776 s.
|
||
|
||
Cgroup memory.current опрашивалась в отдельном потоке через docker exec последовательно для двух API, пауза между циклами 0.1 s; реальный интервал выше из-за накладных расходов команд. Выборочные пики — 248.3 MiB, 217.6 MiB. В JSON также сохранена memory.peak за всю жизнь контейнера: она включает предыдущие тесты и не выдается за чистый пик только этого опыта. CPU-потребление в этом опыте отдельно не измерялось. Это функциональная проверка ограниченной памяти при 10 клиентах, а не поиск максимального RPS.
|
||
|
||
Первые прогоны выявили ошибки проверочного окружения: запуск нового Compose-контейнера из checks разрешал bind mount относительно /checks, а restart.sh имел CRLF. Повторный bootstrap теперь запускает уже созданный init-контейнер; shell-скрипты сохранены с LF. Проверки повторены после исправлений. Бизнес-ошибки файлов не маскировались изменениями публичных tests.
|
||
|
||
MinIO собран через go install из закреплённого тега исходников; команда minio --version у такой сборки выводит DEVELOPMENT.GOGET. Версия исходного кода закреплена в infra/s3/Dockerfile, а фактический image ID сохранён в verification.json. Это не готовый upstream Docker-образ.
|
||
|
||
|
||
## Ограничения
|
||
|
||
Стенд учебный, на одном компьютере. Один PostgreSQL, Redis, MinIO и балансировщик остаются точками отказа. Проверяется отказ API, а не потеря всего хоста. Нет резервного копирования, HTTPS для удалённого доступа и обработки изображений в фоне. Эксперимент загрузок — один функциональный прогон на локальном Docker Desktop, не оценка предельной производительности. Измерение cgroup учитывает память процесса и файловый кэш; memory.peak относится ко всей жизни контейнера.
|
||
|
||
## Источники и инструменты
|
||
|
||
Задание и контракт: https://gitea.privcloud.tech/mtusi2026/mtusi2026lab4
|
||
|
||
Исходники S3: https://github.com/minio/minio и https://github.com/minio/mc
|
||
|
||
Проверка изображений: https://pillow.readthedocs.io/en/stable/reference/Image.html
|
||
|
||
S3 SDK: https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3.html
|
||
|
||
Использованы FastAPI, Pydantic, Uvicorn, Psycopg, redis-py, boto3, Pillow, HAProxy. Codex помог с реализацией, тестами и объяснением работы.
|