Files
mtusi2026lab4/REPORT.md
T

36 KiB
Raw Blame History

Лабораторная 4 — S3-хранилище и вложения

Автор: Майорова Софья, БВТ2301. Целевая оценка: 5. Выбран трек 2: согласованность двух хранилищ. Проверки выполнены 27 октября 2026 года. Окончательную оценку выставляет преподаватель.

Работа продолжает мою lab3, PR 55. Сохранены PostgreSQL, Redis-кэш профиля, сессии, keyset-пагинация, балансировка и транзакционная идемпотентность сообщений на 24 часа. Добавлены приватное S3, бинарные вложения, проверки изображений и повторяемая безопасная сверка S3/БД. Исходные README, COURSE, contracts и публичные tests этой лабораторной сохранены.

Запуск из чистого clone

Нужны Docker Engine с Compose v2 и Python 3.9+ на хосте. Сервер работает на Python 3.12.8 внутри образа; устанавливать серверные библиотеки на Mac не нужно. Для используемого Mac Docker запускается через отдельный профиль Colima:

colima start --profile mtusi-labs
export DOCKER_CONTEXT=colima-mtusi-labs
cd "/Users/ssmayorova/Documents/Учеба/Высоконагруженные приложения/lab4"
python3 scripts/bootstrap.py
docker compose build api
docker compose up -d --wait
export BASE_URL=http://127.0.0.1:18089
python3 scripts/wait_ready.py
make check test test-student BASE_URL=$BASE_URL

На другой машине вместо этого cd клонировать публичный форк и выбрать ветку solution/BVT2301-Mayorova. build api идёт перед up: одноразовые migrate/bootstrap используют тот же уже построенный образ. bootstrap.py создаёт только локальные .env и secrets/, не печатает значения и не перезаписывает существующие. Пароли случайные; путь секрета — не его значение. Каталог secrets имеет 0700, файлы читаются UID 10001 в контейнере. Секреты, .env, runtime/build и данные исключены из Git и Docker build context.

migrate один раз применяет версии 001–004 под advisory lock; API DDL не выполняет. Затем административный bucket-bootstrap создаёт bucket. Уже существующий bucket допустим, повторный bootstrap проверен. API стартуют после обоих jobs. Контейнер s3-store хранит и volume-файлы, и filer metadata под /data на одном persistent volume; PostgreSQL использует другой volume. Redis — восстанавливаемый кэш, сессии находятся в PostgreSQL.

Остановка с сохранением данных:

docker compose down

Только для намеренного удаления данных этого учебного проекта, когда они больше не нужны: docker compose down -v. Эта команда не используется в restart/failover. Закрытые тестовые volumes отдельного clean-clone стенда удаляются после окончания его проверки.

.env.example содержит реальные настройки моего решения: APP_PORT=18089 — только порт LB на localhost, API_REPLICAS=2, API_CPUS=1, API_MEMORY=512m, HTTP_WORKERS=16, DB_POOL_MAX=8, DB_ACCESS_MODE=optimized, POSTGRES_CPUS=1, SESSION_TTL_SECONDS=3600. Внутренний API слушает 8080. Endpoint/bucket/пути S3 credentials задаются в Compose; ограничения 10 MiB и 40 млн пикселей закреплены в коде по контракту и не увеличиваются переменной окружения.

Архитектура и данные

Клиент → 127.0.0.1:18089 → HAProxy → API × 2
                                      ├→ PostgreSQL (общие метаданные/сессии/идемпотентность)
                                      ├→ Redis (необязательный кэш профилей)
                                      └→ S3 gateway → отдельная сеть storage → SeaweedFS mini
                                                                                 └→ s3_data

Выбрана официальная SeaweedFS 4.51, digest sha256:f7a49e3f3972ebed5be2ed4befa4a0c68eb7bdddba6e692d42729ceb545134b8. Образ и реальные параметры проверены запуском. Шлюз weed s3 принимает только S3; IAM API, Iceberg/Lance отключены. Mini в s3-store запускает master/volume/filer, а его S3, WebDAV и административная консоль отключены. Из API недоступен filer: API не состоит в сети storage. Ни S3, ни PostgreSQL, ни Redis, ни отдельные API-порты на хост не публикуются. Только LB подключён к edge.

Образы Python 3.12.8, PostgreSQL 17.2-bookworm, Redis 7.4.1-bookworm, HAProxy 3.0.5-alpine также закреплены digest в Dockerfile/Compose. Pillow 13.0.0 проверяет изображения, boto3 1.40.61 обращается к S3; точные прямые и транзитивные Python-зависимости закреплены в requirements.txt. Их выбор — проверенная версия, не обещание постоянного отсутствия уязвимостей.

Роль CPU Память Устойчивые данные
API, каждая из двух реплик 1 512 MiB Нет
PostgreSQL 1 512 MiB postgres_data
SeaweedFS master/volume/filer 1 512 MiB s3_data
S3 gateway 0,5 512 MiB, GOMEMLIMIT=384MiB Нет
HAProxy 0,5 64 MiB Нет
Redis 0,25 64 MiB, maxmemory=32mb Нет

CPU-лимиты суммарно превышают 4 vCPU локальной VM; это допускаемый overcommit локального стенда, не выделенные физические ядра каждому сервису. Поэтому измерения не выдаются за максимальную производительность production.

Миграция 004 создаёт attachments: UUID, chat_id, owner_id, filename, случайный object_key, истинный MIME, размер, SHA-256, внутреннее состояние и timestamps. messages.attachment_ids сохраняет порядок ссылок; message_attachments с FK защищает целостность и запрещает удалить используемое вложение. Пустой текст допустим с вложениями; текст до 4000 Unicode code points, включая U+0000, по-прежнему сохраняется lossless в BYTEA.

POST /chats/{id}/attachments?filename=... принимает сырые PNG/JPEG, не multipart. Сервер создаёт ключ originals/<UUIDv4>, имя файла никогда не является путём. Ответ 201 содержит ready, variants=[], error_code=null, checksum оригинала. Участник другого чата/посторонний получает 404 для metadata/content и при попытке прикрепить чужое вложение. Отсутствие Bearer даёт 401. Download идёт через API без redirect; истинный Content-Type и nosniff, private, no-store, байты не перекодируются. Ключи S3 и адреса backend не входят в публичные модели. Любой участник своего чата может прикрепить доступное вложение.

Границы операции upload

  1. Аутентификация и проверка членства предшествуют приёму тела файла. Проверяются query/filename, один Content-Length, отсутствие Transfer-Encoding, лимит bytes и MIME.
  2. Файл читается кусками до 64 KiB в TemporaryFile внутри ограниченного tmpfs /tmp (128 MiB на API). Это только временный буфер незавершённой операции, не источник хранения подтверждённого файла. При исключении/обрыве контекст закрывает файл; при падении процесса tmpfs исчезает.
  3. Вычисляется SHA-256. Pillow открывает только PNG/JPEG, проверяет размеры до load, затем verify() и полное декодирование первого изображения. MIME сравнивается с форматом по содержимому. Ошибки дают 415, превышение pixels — 413. Управляющие символы, NUL, slash/backslash в filename — 400. Для защиты от сжатых PNG-текстов установлен дополнительный лимит декодированных текстовых метаданных 1 MiB.
  4. PostgreSQL фиксирует устойчивый intent со state=uploading до S3 PUT. Он уже содержит всю ожидаемую checksum/size и назначенный сервером key.
  5. В новой транзакции upload берёт row lock на intent, выполняет S3 PUT, затем обновляет ready. COMMIT завершён до возврата 201. Lock удерживается до COMMIT, поэтому reconciler не может собрать выполняющуюся операцию.
  6. Обрыв до intent не создаёт S3-объекта. Отказ после intent/PUT оставляет учтённое состояние uploading, которое безопасно убирается последующей сверкой. Ошибка записи в БД отдаёт 503 без SQL/credentials. Неопределённый результат HTTP upload нельзя прозрачно повторять: upload по контракту не идемпотентен. Сообщения с Idempotency-Key остаются идемпотентными через общую транзакцию PostgreSQL.

Не обещается распределённая ACID-транзакция между PostgreSQL и S3. Именно окно между двумя хранилищами исследуется в выбранном треке.

Ограничение ресурсов и таймауты

На API максимум 16 выполняющихся HTTP handlers и 32 принятых соединения; заполнение очереди даёт 503. Одновременно принимаются максимум 8 upload на реплику, декодируется один файл. Пиксельный буфер явно освобождается image.close() до освобождения decoder semaphore; duplicate file descriptor сохраняет исходный временный файл для S3. Это важно: один только выход из контекста Pillow не должен оставлять предыдущий декодированный объект живым, пока следующий запрос уже декодируется.

Content-Length >10 485 760 отклоняется до чтения файла; dimension check >40 000 000 — до распаковки. Приём тела имеет общий deadline 15 секунд и idle timeout ≤3 секунд; read1 позволяет пересчитывать общий deadline даже при постоянной подаче очень маленьких порций. Ожидание декодера ограничено 10 секундами. S3 connect timeout 1 секунда, socket read timeout 3 секунды, SDK total_max_attempts=1; автоматического retry upload нет. HTTP LB client/server timeouts 30 секунд. Download также идёт кусками 64 KiB, с ограничением времени, первый кусок читается до 200. Ошибка S3 посреди уже начатого ответа закрывает соединение; клиент обязан считать недополученное тело ошибкой.

Пул PostgreSQL ≤8 соединений на API, ожидание 2 секунды, statement_timeout=2s, lock_timeout=1,5s. SIGTERM прекращает приём новых соединений, drain ограничен 5 секундами. Readiness проверяет PostgreSQL и S3 bucket — зависимости обязательного синхронного пути; Redis не критичен. Liveness проверяет жизнь процесса. При недоступном S3 LB убирает API из ready backend; ответы самого LB о невозможности соединения могут отличаться от JSON-ошибки API.

Приватность bucket и права

bootstrap.py генерирует три разные S3 identities. Административная имеет Admin/Read/Write/List и доступна только bucket-bootstrap и явно запускаемому тестовому audit. API и reconciler получают отдельные пары с Read/Write/List только messenger-attachments, без Admin. Write включает удаление объектов этого bucket; API не использует этот метод в публичном endpoint, reconciler использует для компенсации. Это ограничение по bucket, не по одному пользовательскому чату: ACL чата обеспечивает приложение.

Нет anonymous identity/публичного policy. storage_checks.py вне API действительно получает 403 на прямой unauthenticated GET известного key и bucket listing. С реальными ключами API создание другого bucket, listing другого bucket и изменение policy дают 403. Внутренний filer и административный порт также недоступны из сети API. audit — только tools profile, не запускается обычным up; его административные секреты никогда не подключаются к API. Bucket bootstrap успешно повторён.

Трек 2: повторяемый reconciler

Гипотеза: устойчивый intent перед PUT, row lock и консервативная сверка позволят исправлять частичные записи без удаления свежего или используемого файла; цена полного прохода будет расти примерно линейно с числом метаданных/объектов.

Оператор сначала запускает dry-run, затем после просмотра — apply:

make reconcile
make reconcile-apply

Обе команды используют отдельные ограниченные credentials reconciler. По умолчанию grace 3600 секунд и dry-run; команда без --apply не меняет ни S3, ни строки БД. Значение grace <3600 отвергается, кроме явно отмеченного флага --allow-short-test-grace на синтетическом стенде. Для регулярного обслуживания оператор должен повторять эти команды; скрытого фонового удаления нет.

Сверка берёт общий advisory lock, чтобы два reconciler не работали одновременно. Cutoff фиксируется в начале прохода. PostgreSQL читается страницами по 100 UUID, S3 list — страницами по 100 ключей; findings ограничены 200 записями, счётчики полные. Внутри каждой операции берётся FOR UPDATE SKIP LOCKED: занятая живым upload строка пропускается, а свежая по updated_at защищена grace period.

Обнаруженное состояние Dry-run Apply и повторный запуск
Старый uploading, PUT не было stale_intent Удаляет intent, S3 delete идемпотентен
Старый uploading, PUT уже был, ready/COMMIT сорвался stale_intent Удаляет объект, затем intent; при сбое между delete и БД следующий проход завершит очистку
Старый объект originals/UUIDv4 без строки БД orphan Перед delete повторно проверяет отсутствие строки и свежесть HEAD; ключи никогда не переиспользуются
Ready-метаданные, S3 отсутствует/size или metadata checksum не совпадают missing_or_mismatched Сохраняет строку и все ссылки, ставит внутренний storage_missing; API возвращает 503 вместо ложного оригинала
storage_missing, оригинал восстановлен извне recoverable Потоково проверяет реальные байты SHA-256/size, только затем возвращает ready
Ready и корректный HEAD, даже без сообщения Защищено Никогда не удаляет
Свежее, занято row lock, неуправляемое имя/prefix Защищено/пропущено Не удаляет

storage_missing — внутреннее состояние, не дополнительное значение публичного enum lab4. Такой ресурс возвращает 503; восстановленная запись снова отдаёт нормальную Attachment со status=ready. Reconciler не может изобрести потерянные bytes: для восстановления нужна внешняя сохранённая копия/backup, в эксперименте это исходный fixture в памяти теста.

Ключевое доказательство безопасности: корректный API сначала фиксирует intent и потом создаёт объект с новым UUID. Поэтому старый key без строки не может быть обычным upload в окне до фиксации метаданных. Используемая строка защищена state, row lock и FK; ready-вложения сборщик вообще не удаляет. Если БД/S3 недоступны, проход прерывается без fail-open удаления. Уже выполненные S3 delete не откатываются вместе с PostgreSQL, но устойчивый intent делает повтор безопасным.

student-tests/research.py использует настоящие S3 и PostgreSQL: вводит исключение trigger непосредственно в ready UPDATE после успешного PUT; создаёт intent без PUT, объект без метаданных, удаляет оригинал используемого вложения, удерживает row lock как живой uploader, создаёт свежий intent/объект. Реальная выдержка 3 секунды делает старый orphan старше тестового grace=2, S3 LastModified и часы не подменяются. Dry-run, apply, повтор и восстановление имеют assert на фактические строки, bytes и ссылки. Тестовые grace=2 и SQL fault injection предназначены только для данного синтетического стенда.

Команды воспроизведения security и исследования (audit получает отдельные локальные тестовые секреты):

docker compose run --rm -T --no-deps -v "$PWD:/work:ro" -w /work audit python student-tests/storage_checks.py
docker compose run --rm -T --no-deps -v "$PWD:/work:ro" -w /work audit python student-tests/research.py

Измерения

Стенд: macOS arm64, Colima/Ubuntu Linux, 4 vCPU и примерно 4 GiB RAM. Лимиты контейнеров приведены выше. Остальные учебные стенды не останавливались; это локальный эксперимент без гарантии отсутствия соседней нагрузки. Генерация fixtures и bootstrap выполняются до начала измерения.

Для стоимости сверки использованы три популяции — 10, 110, 510 строк и столько же S3-объектов, три последовательных dry-run на каждой. Исходная популяция включает данные проверок; каждый этап добавляет соответственно 100 и 400 подтверждённых тестовых ready-объектов. При повторе сценария абсолютная исходная популяция может вырасти: результаты всегда содержат фактические counts, а не предполагаемый N.

Метаданных / объектов Медиана полного обхода Наблюдаемые HEAD
10 / 10 19,56 мс 9
110 / 110 136,28 мс 109
510 / 510 603,06 мс 509–510

Количество HEAD немного различается из-за grace. Полный проход включает создание S3 client, advisory lock, PostgreSQL-страницы/lookup, S3 list и HEAD. Основные bytes не скачиваются при обычном HEAD; GET/SHA-256 используются только при восстановлении storage_missing. Память прохода ограничена размером страниц. Последовательный алгоритм имеет O(N+M) обход, но не является snapshot между двумя хранилищами; пропущенное/изменившееся состояние проверяется следующим запуском. Увеличение 110→510 объектов дало примерно пропорциональный рост времени; это поддерживает гипотезу на данном диапазоне, не прогноз миллиардов объектов.

На каждом профиле 10 клиентов одновременно начинают upload, затем скачивают результат с тем же SHA-256. Один прогон на профиль; fixtures детерминированы, подготовлены заранее. Нет скрытых retry. Перед каждым профилем API перезапускаются, поэтому cgroup memory.peak относится к этому запуску. Опрос memory.current/peak/events и cpu.stat идёт дополнительными docker exec; это вносит накладные расходы. Измеряется end-to-end upload+download, не только POST и не предельный RPS. Для десяти запросов p95/p99 по nearest-rank оба равны максимуму.

PNG: bytes / pixels Успех / ошибки Весь сценарий p50 / p95=p99 end-to-end Пик API 1 / API 2
529,848 / 176,400 10/10 / 0 0.387 с 141.3 / 149.4 мс 67.05 / 67.18 MiB
7,563,763 / 2,520,000 10/10 / 0 2.042 с 1711.5 / 1743.2 мс 127.41 / 127.04 MiB
533,859 / 40,000,000 10/10 / 0 0.831 с 416.2 / 602.8 мс 326.36 / 319.54 MiB

В финальных трёх профилях 30/30 загрузок вернули 201, скачанные SHA-256 совпали, OOM kill = 0. Лимит каждой API — 512 MiB. Высокий пик третьего профиля связан с 40 млн декодированных RGB-пикселей при небольшом сжатом файле: размер HTTP-тела не равен размеру изображения в RAM. Различие реплик отражает распределение нагрузки и память аллокатора; это не доказательство разницы алгоритмов.

Средний CPU API за сценарий оценивается по разнице cgroup cpu.stat usage_usec, делённой на время сценария (100% = одно ядро; короткая длительность и docker exec влияют на оценку):

  • 176400 pixels: API 1 / API 2 = 45.7% / 43.7%.
  • 2520000 pixels: API 1 / API 2 = 36.2% / 35.1%.
  • 40000000 pixels: API 1 / API 2 = 77.7% / 79.5%.

Сверка и память при загрузках

Ранние прогоны сохранены, а не скрыты: с лимитом S3 gateway 192 MiB обнаружен его OOM; после изменения gateway на 512 MiB, GOMEMLIMIT=384MiB и ограничения concurrentUploadLimitMB до 32 повтор выявил отдельный OOM API на RGB-изображениях 40 Мп. Причина API устранена освобождением пиксельного буфера до освобождения decoder semaphore. Финальные прогоны с исходным поддерживаемым лимитом 512 MiB/API проверяют именно этот случай. Ошибочные запуски не включены в успешные итоговые измерения, их stderr и State с OOMKilled=true оставлены в evidence.

Проверки и доказательства

Критерий Команда/сценарий Результат / evidence
Оригинальные контракт и tests make check; git diff относительно skeleton Не изменены; final-tests.txt
Минимум lab3 + вложения make test Публичный lab4 smoke PASS; final-tests.txt
Дополнительные API/Unicode/сессии/гонки make test-student 21 тест PASS; final-tests.txt
PNG/JPEG, checksum, приватность, чужой chat/id test_attachments.py и storage_checks.py Побайтное совпадение; 400/401/404/413/415; storage-security.json
10 MiB/40 Мп и повреждённый файл test_bad_images_and_mime, test_valid_pixel_boundary 413 выше границы, 415 для подмены/повреждения, ровно 40 Мп принято
Остановка именно загрузившей API student-tests/faults.py Каждая реальная реплика остановлена отдельно, файл скачан другой с прежним Bearer; faults.json
Обязательный публичный failover сообщений make test-failover ACTION_SCRIPT=scripts/stop-one.sh 2 реплики, 116 подтверждённых записей, 1 транзитная ошибка, восстановление 2,594 с; public-failover.txt
Restart API, LB, PostgreSQL, Redis и обоих S3-компонентов make test-persistence ACTION_SCRIPT=scripts/restart.sh Прежние сессия, сообщения, attachment metadata/bytes сохранены; persistence.txt, restart-before/after.json
Недоступность S3, fallback Redis student-tests/faults.py S3: ready/content 503, live 200; после восстановления прежние bytes; Redis fallback; faults.json
Обрыв приёма student-tests/faults.py Нет intent для прерванного filename, PUT не выполнялся
Медленный непрерывный клиент student-tests/slow_upload.py 400 около общего deadline 15 с; slow-upload.json
Отдельные ограниченные S3 credentials и закрытая сеть storage_checks.py Anonymous GET/list 403, три запрещённых операции API 403, filer/admin недоступны; storage-security.json
Идемпотентный bootstrap bucket Повторный compose run bucket-bootstrap Exit 0; bucket-bootstrap-repeat.txt
Потоковое ограничение RAM, ≥10 одновременных файлов student-tests/uploads.py uploads.json, график; cgroup peaks и OOM counters
Согласованность, свежие/используемые/занятые объекты research.py Все 7 assertions-групп true; dry/apply/repeat/recover; reconciliation.json
Стоимость обхода research.py 9 реальных измерений на трёх популяциях; reconciliation.json
Чистый clone/новые volumes Отдельный проект, порт и секреты PASS: новые секреты, пустые PostgreSQL/S3 volumes, smoke + 21 тест + полный restart; clean-clone.txt

Публичные команды отказов управляют только lab4; после stop-one реплика остаётся остановленной по контракту теста и восстанавливается явно docker compose up -d --wait --no-deps api. Дополнительный faults.py сам восстанавливает каждую зависимость в finally. Снимки runtime содержат только разрешённые поля состояния, лимитов, mounts и портов, без environment/credentials. Не сохраняются тела Basic/Bearer или полные session responses.

export DOCKER_CONTEXT=colima-mtusi-labs
export BASE_URL=http://127.0.0.1:18089
make test-failover ACTION_SCRIPT=scripts/stop-one.sh BASE_URL=$BASE_URL
docker compose up -d --wait --no-deps api
make test-persistence ACTION_SCRIPT=scripts/restart.sh BASE_URL=$BASE_URL
python3 student-tests/faults.py
python3 student-tests/slow_upload.py
python3 student-tests/uploads.py

Для повторной генерации графиков нужен Python 3.11+ и pip install -r requirements-research.txt, затем python student-tests/plot.py; приложенные PNG/SVG уже готовы. Workflow Application добавлен отдельно от исходной проверки skeleton; hosted CI требует разрешений платформы и здесь не объявляется прошедшим автоматически.

Ограничения

Доказаны отказ API-реплики и restart с сохранёнными volumes; один PostgreSQL, один S3-store, один LB и один host остаются точками отказа. Это не multi-node HA и не гарантия сохранности при отключении питания. TLS отсутствует, поэтому публикуется только localhost с синтетическими данными. Root-доступ к Docker равносилен доступу к секретам стенда.

Распределённой транзакции нет, до очередного apply старые uploading/orphan могут оставаться. Готовые, но неиспользуемые вложения сборщик намеренно сохраняет, поскольку контракт не содержит удаления. Данные экспериментов/публичных тестов также накапливаются. Для постоянно работающего сервиса нужны расписание обслуживания, backup S3+БД и контроль расходов.

Обычный проход сверяет HEAD и сохранённую S3 checksum metadata, а не перечитывает каждый корректный объект: одинаково изменённые bytes и metadata сторонним привилегированным оператором так не обнаруживаются. Восстановление missing всегда проверяет реальные bytes. Параллельные изменения БД/S3 и значительный clock skew требуют повторного прохода и аккуратного grace; штатные API не переиспользуют ключи и не изменяют ready-объекты. Grace 3600 ориентирован на значительно более короткую обычную загрузку; уменьшать его на реальных данных без исследования нельзя.

Проверка изображений декодирует первый кадр, не выполняет антивирус и не создаёт thumbnail; дополнительные PNG-текстовые метаданные ограничены 1 MiB как защита parser RAM. UI, presigned upload и трек 1 не реализуются: выбран законченный трек 2. Показатели маленького локального эксперимента не задают SLA или максимальный RPS.

Источники и помощь

Перенесено собственное решение lab3 (Майорова Софья, PR 55); чужие студенческие решения не использовались. Задание/контракты текущего skeleton — основание обязательного поведения.

Использован Codex для разработки, подготовки тестов, запуска измерений и оформления. Все приведённые PASS/числа получены реальными командами данного стенда; утверждения ограничены фактически проверенными сценариями. Имя автора в Git — Майорова Софья; генеративная помощь раскрыта явно.