17 KiB
Отчёт — лабораторная 4
Автор: Шурман А.Р., БПИ2302. Целевая оценка: 4. Исследовательские треки на 5 не выполнялись.
Статус проверки
Полный прогон выполнен 12 ноября 2026 года на macOS arm64 / Docker Desktop.
make check, полная валидация OpenAPI, 5 unit-тестов и весь scripts/verify.py
прошли. Реальные результаты находятся в evidence/: smoke, негативные сценарии,
приватность bucket, безопасная очистка, обрыв upload, отказ S3, повторный bootstrap,
persistence, failover и нагрузка. Контракт и публичные тесты не изменены.
Первоначальный evidence/offline.txt сохранён как историческая проверка до запуска Docker.
Запуск
Нужны Docker с Compose, Python 3.9+ на хосте (для memory/unit — Pillow).
API работает на Python 3.12.7. Новый стенд использует порт 8084, отдельные volumes
и Compose project mtusi-lab4, поэтому не занимает порт предыдущих работ.
cd mtusi2026lab4-fork
python3 -m venv .venv
.venv/bin/pip install -r requirements-dev.txt Pillow==11.1.0
python3 scripts/bootstrap.py
docker compose config --quiet
docker compose up -d --build --wait
BASE_URL=http://localhost:8084 .venv/bin/python scripts/verify.py
make validate PYTHON=.venv/bin/python
Команды выполняются из корня этой лабораторной. Если репозиторий склонирован отдельно,
первую команду замените на переход в его каталог. bootstrap.py генерирует локальные
секреты, не выводит и не перезаписывает их. Повторный запуск сохраняет данные.
Для локальных тестов при отсутствии Pillow: отдельное venv и pip install Pillow==11.1.0.
Полная проверка OpenAPI: pip install -r requirements-dev.txt, затем make validate.
API: http://localhost:8084; Swagger: http://localhost:8084/docs.
Остановка без потери данных: docker compose down (без -v).
Возобновление: docker compose up -d --wait.
Готовые образы minio/minio и minio/mc оказались недоступны при проверке
12 ноября 2026 года (Docker Hub: pull access denied; Quay: 401).
Поэтому infra/s3/Dockerfile собирает официальные исходники закреплённых релизов
MinIO RELEASE.2025-04-22T22-12-26Z
и mc RELEASE.2025-04-16T18-13-26Z
в Go 1.24.2. Лицензии включены в образы. Первый запуск требует интернет и время
на скачивание Go-зависимостей и компиляцию; следующие сборки используют Docker cache.
Архитектура
HAProxy → две FastAPI-реплики → общий PostgreSQL и приватный MinIO.
Valkey кэширует публичные профили; сессии проверяются в PostgreSQL при каждом запросе.
Исходная основа — собственная лабораторная 2: модели пользователей/чатов,
аутентификация, SQL-хранилище и мигратор. Возможности лабораторной 3 добавлены здесь:
балансировка, X-Instance-Id, общая таблица идемпотентности.
Контракт и публичные тесты skeleton не изменены.
Каждая реплика возвращает api1 или api2. HAProxy проверяет readiness каждую секунду,
исключает реплику после двух неудач. Он не повторяет POST автоматически. При потере ответа
клиент повторяет сообщение с тем же Idempotency-Key. Advisory lock в PostgreSQL
сериализует один ключ пользователя/чата, вставка сообщения и результата атомарны.
Повтор в течение 24 часов возвращает исходный объект; другой текст/список вложений — 409.
Отсутствующий список вложений и [] равны. Просроченная запись ключа заменяется при повторном использовании.
История читается из primary без кэша. Keyset cursor не обеспечивает snapshot между страницами.
Метаданные Attachment находятся в PostgreSQL, байты — только в S3. Временный файл API
существует исключительно во время приёма и проверки запроса и закрывается по выходу.
Имя пользователя не используется как S3 key. Ключ — originals/<UUID>.
Скачивание идёт через API после проверки членства, без redirect и публичных URL.
Валидация и ресурсы
Загрузка принимает сырые PNG/JPEG, максимум 10 MiB. Content-Length проверяется заранее, но фактические байты также считаются во время потока. Общий срок приёма — 30 секунд. Pillow проверяет формат, MIME, структуру и декодирование. Размер не выше 40 млн пикселей проверяется до загрузки пикселей. Анимированные PNG в этой реализации отклоняются. Оригинал сохраняется без преобразования; SHA-256 и размер вычисляются при чтении. Пустые/опасные filename, MIME-подмена и чужие вложения имеют ошибки контракта.
Одновременно каждая реплика обрабатывает максимум две загрузки. Ожидание слота до 0.5 s, затем явный 503. Две реплики ограничены по 768 MiB и 1 CPU. На диск пишется максимум 10 MiB на активную загрузку, декодирование занимает ограниченную память до размера изображения. S3: connect timeout 2 s, read timeout 10 s, автоматических повторов нет. Download читает S3 чанками по 64 KiB. Оригинал не загружается целиком в RAM при скачивании.
Согласованность S3 и БД
- API принимает и проверяет временный файл.
- Отдельная транзакция сохраняет
pendingи назначенный object key до S3 PUT. - Новая транзакция блокирует строку, выполняет PUT и переводит её в
ready. - Ответ 201 отправляется только после COMMIT.
pendingне показывается публично.
При обрыве передачи клиента до PUT остаётся только автоматически закрываемый временный
файл. При сбое PUT, падении процесса или неуспешном COMMIT остаётся учтённый pending.
Фоновый cleaner раз в минуту выбирает pending старше 1 часа, блокируя строку
FOR UPDATE SKIP LOCKED, удаляет соответствующий S3 key и затем запись БД. Активная
транзакция пропускается. При ошибке S3 строка сохраняется для следующего прохода.
При сбое COMMIT очистка повторит безопасный DELETE отсутствующего объекта.
ready никогда не выбирается. Часовой grace period значительно больше таймаутов загрузки.
Это не распределённая транзакция: некоторое время возможны pending-метаданные и лишние байты.
Объекты, вручную записанные администратором без intent, вне модели очистки.
Приватность и запуск хранилища
MinIO, PostgreSQL, Valkey и API не публикуют порты на хост. Только HAProxy доступен
на loopback. Консоль MinIO слушает 127.0.0.1 внутри его контейнера.
Идемпотентный s3-init создаёт bucket, запрещает anonymous и назначает отдельному API user
политику: ListBucket одного bucket и Get/Put/Delete исключительно в originals/*.
Root credentials доступны только MinIO и init, API их не получает.
Readiness зависит от PostgreSQL и MinIO. Valkey имеет fallback в PostgreSQL.
Секреты находятся в исключённом из Git каталоге secrets/.
| Роль / service | Версия | Готовность | Постоянные данные | Доступ / credentials |
|---|---|---|---|---|
LB / lb |
HAProxy 3.0.8-alpine | HTTP /health/ready обеих API |
нет | только 127.0.0.1:8084 |
API / api1, api2 |
Python 3.12.7; app/requirements.txt |
PostgreSQL + MinIO | нет | внутренняя сеть; DB/S3 через secrets |
БД / postgres |
PostgreSQL 16.6-bookworm | pg_isready |
postgres-data |
внутренняя сеть; password secret |
Кэш / valkey |
Valkey 8.0.2-alpine | некритичен, fallback в БД | valkey-data (AOF) |
внутренняя сеть |
S3 / s3 |
MinIO RELEASE.2025-04-22T22-12-26Z | /minio/health/live |
s3-data |
внутренняя сеть; root secrets |
Bootstrap / s3-init |
mc RELEASE.2025-04-16T18-13-26Z | успешное завершение | bucket/policy в S3 | root + API secrets |
Миграции / migrate |
образ API | успешное завершение | schema_migrations в БД |
secrets, advisory lock, checksum миграций |
Очистка / cleaner |
образ API | повтор каждые 60 s | pending в БД | ограниченные API S3 credentials |
Все сервисы находятся в отдельной Compose-сети mtusi-lab4_default.
Повторный bootstrap.py сохраняет секреты; повторные migrate и s3-init
не удаляют данные и выполняются при docker compose up.
Проверки и доказательства
| Критерий | Проверка | Результат 12.11.2026 |
|---|---|---|
| Структура и синтаксис | make check, AST всех новых Python-файлов |
выполнено |
| Конфигурация | docker compose config --quiet |
выполнено |
| Реальные PNG/JPEG, MIME, повреждение, пиксели | python3 student-tests/unit.py |
5 тестов пройдено |
| Обязательный API и checksum | make test BASE_URL=http://localhost:8084 |
PASS; вывод в evidence/ |
| Ошибки файлов и ACL, конкуренция ключа | BASE_URL=http://localhost:8084 python3 student-tests/verify.py |
PASS; вывод в evidence/ |
| Приватность bucket и безопасная очистка | student-tests/storage_checks.py внутри API через общий runner |
PASS; вывод в evidence/ |
| Обрыв загрузки и отказ S3 | student-tests/outage.py |
PASS; вывод в evidence/ |
| Повторный bootstrap | повтор docker compose run --rm s3-init |
PASS; вывод в evidence/ |
| Перезапуск всех сервисов | persistence + scripts/restart.sh |
PASS; вывод в evidence/ |
| Остановка обслужившей реплики | failover + scripts/stop-one.sh |
PASS; 89 записей, 3 неудачные попытки, восстановление 2.8 s |
| Остановка именно загрузившей реплики | student-tests/attachment_failover.py |
PASS; upload api1 → download api2; bytes совпадают |
| 10 одновременных загрузок и RSS | student-tests/memory.py |
8 × 201, 2 × 503; пик RSS 132796 / 133912 KiB |
.venv/bin/python scripts/verify.py выполняет проверки и сохраняет реальные результаты в evidence,
останавливаясь при первом провале. Тест очистки создаёт только синтетические строки и объекты,
моделирует rollback финализации после PUT, проверяет grace period и сохранность ready.
Он удаляет только свои синтетические данные. До запуска убедитесь, что это учебный стенд.
Memory-тест создаёт PNG примерно 9 MiB и одновременно запускает 10 запросов.
Он пишет коды ответов, длительность, выборки VmRSS процессов API и измеренный максимум.
Отказы 503 из-за ограничения слотов учитываются явно; они не записываются как успешные загрузки.
Последовательная выборка /proc/1/status может пропустить короткий пик, поэтому результат —
максимум наблюдений, а не гарантированный абсолютный пик. Фактический эксперимент: 10 одновременных запросов по 9 201 866 байт,
8 ответов 201 и 2 ответа 503; время ответа 0.427–0.680 s. Наблюдаемый пик RSS:
api1 — 132 796 KiB (129.7 MiB), api2 — 133 912 KiB (130.8 MiB), при лимите
768 MiB на реплику. Полные выборки сохранены в evidence/memory.json.
Это проверка ограниченности ресурсов, а не обещание принять любую конкуренцию без 503.
Ограничения
Один host, HAProxy, PostgreSQL и MinIO остаются точками отказа. Это отказоустойчивость к остановке одной API-реплики, не полноценная HA-система. При отказе S3 readiness становится 503; после восстановления новые обращения повторяются клиентом. Обрыв S3 посреди уже начатого download закрывает поток, поэтому клиент проверяет длину/checksum. Нет UI, обработки изображений в очереди, presigned URL и исследовательских треков. Проверка реальных контейнеров выполнена; при переносе на другую машину её нужно повторить.
Источники и использование ИИ
Основа — собственные предыдущие лабораторные и skeleton преподавателя;
API и критерии взяты из contracts/ и README.md. MinIO/mc собираются из официальных
исходников по ссылкам выше. При проверке и исправлении работы использован Codex:
анализ кода, исправление сборки S3, дополнительные тесты, запуск стенда и оформление
фактических результатов. Результаты получены запуском, а не сгенерированы.