36 KiB
Лабораторная 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
- Аутентификация и проверка членства предшествуют приёму тела файла. Проверяются query/filename, один Content-Length, отсутствие Transfer-Encoding, лимит bytes и MIME.
- Файл читается кусками до 64 KiB в
TemporaryFileвнутри ограниченного tmpfs/tmp(128 MiB на API). Это только временный буфер незавершённой операции, не источник хранения подтверждённого файла. При исключении/обрыве контекст закрывает файл; при падении процесса tmpfs исчезает. - Вычисляется SHA-256. Pillow открывает только PNG/JPEG, проверяет размеры до load, затем
verify()и полное декодирование первого изображения. MIME сравнивается с форматом по содержимому. Ошибки дают 415, превышение pixels — 413. Управляющие символы, NUL, slash/backslash в filename — 400. Для защиты от сжатых PNG-текстов установлен дополнительный лимит декодированных текстовых метаданных 1 MiB. - PostgreSQL фиксирует устойчивый intent со state=uploading до S3 PUT. Он уже содержит всю ожидаемую checksum/size и назначенный сервером key.
- В новой транзакции upload берёт row lock на intent, выполняет S3 PUT, затем обновляет ready. COMMIT завершён до возврата 201. Lock удерживается до COMMIT, поэтому reconciler не может собрать выполняющуюся операцию.
- Обрыв до 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 — основание обязательного поведения.
- SeaweedFS S3 API, S3 credentials и bucket-scoped actions, параметры mini проверены у закреплённого Docker-образа.
- Pillow Image: ограничения, verify/load/close.
- Boto3 put_object.
- PostgreSQL row-level/advisory locks.
Использован Codex для разработки, подготовки тестов, запуска измерений и оформления. Все приведённые PASS/числа получены реальными командами данного стенда; утверждения ограничены фактически проверенными сценариями. Имя автора в Git — Майорова Софья; генеративная помощь раскрыта явно.
