Files

22 KiB
Raw Permalink Blame History

Отчёт — лабораторная 4: S3-вложения

Автор / группа: Авзалов Артур Марсович / БПИ2301
Целевая оценка: 5
Выбранный трек: №2 — согласованность PostgreSQL и S3
Среда: Windows PowerShell, Docker Desktop, Python, Docker Compose; прогоны представлены в переписке 12.11.2026.
Статус: основной функционал, восстановление потерянного объекта, очистка orphan и сравнительная стоимость обхода проверены локально 12.11.2026. Не проверены отдельно одновременная потеря двух S3-копий и реальная авария COMMIT PostgreSQL; ограничения явно указаны ниже.

Архитектура и перенос Lab3

Клиент (127.0.0.1:8080)
          │
      HAProxy, HTTP L7, round-robin
          ├── FastAPI api1 ─┐
          └── FastAPI api2 ─┤
                           ├── PostgreSQL: пользователи, чаты, сообщения, metadata вложений, receipts
                           ├── Redis: общие bearer-сессии
                           └── SeaweedFS S3: приватные объекты-оригиналы и recovery copy

One-shot: migrate / s3-policy / s3-bootstrap
Maintenance: reconcile (dry-run по умолчанию)

Сохранены публичное API и механизмы Lab3: Bearer-сессии, сообщения, миграции, курсорная пагинация, Idempotency-Key, конкуренция через PostgreSQL advisory lock, X-Instance-Id, X-Request-Id, readiness/healthchecks, две взаимозаменяемые реплики и отказ одной из них. Все реплики используют общие PostgreSQL, Redis и S3. В наружную сеть публикуется только порт HAProxy 127.0.0.1:8080; S3-консоль/API и PostgreSQL/Redis не публикуются на хост.

В compose.yaml закреплены образы postgres:16.10-bookworm, redis:7.4.5-alpine, haproxy:3.1.7-alpine, chrislusf/seaweedfs:4.53. S3 хранит данные в именованных volumes. s3-policy формирует политику доступа, s3-bootstrap создаёт приватный bucket; API и reconciler используют выделенные ключи, ограниченные bucket. Локальные .env и приватные credentials не должны попадать в Git.

Контракт вложений

  • POST /api/v1/chats/{chat_id}/attachments?filename=...: raw PNG/JPEG, не multipart; 201 только после успешных S3 PUT оригинала/резервной копии и COMMIT метаданных в PostgreSQL.
  • Изображение проверяется по сигнатуре/декодированию, соответствию заявленному MIME, границам размера (10 MiB) и пикселей (40 млн), небезопасные имена файлов отклоняются. Имя файла используется только в metadata, S3-ключ генерирует сервер.
  • GET /api/v1/attachments/{id} и GET /api/v1/attachments/{id}/content проверяют участие пользователя в чате, иначе 404. Оригинал читается из общего S3 и отдаётся через API без публичного S3 URL.
  • Ограничение памяти: streaming/spool с RAM-порогом 1 MiB, максимум исходника 10 MiB; семафор для Pillow-декодирования. Контейнер API имеет mem_limit: 384m.
  • Для каждого attachment хранятся attachments/<uuid>/original и recovery/<uuid>/original. Это две логические копии на одном SeaweedFS, не защита от потери всего S3-узла.

Проблема согласованности PostgreSQL и S3

S3 PUT и PostgreSQL COMMIT не образуют распределённой транзакции. Возможные сбои:

  1. S3-объект уже создан, а транзакция БД не завершилась — orphan, объект без metadata.
  2. Metadata присутствует, но основного S3-ключа нет — missing primary; его можно восстановить из recovery copy.
  3. Metadata присутствует, но резервного S3-ключа нет — missing backup; его можно восстановить из основного.
  4. Отсутствуют обе копии — автоматическое восстановление невозможно; нужен внешний backup/ручной разбор.

В пути загрузки выполняется best-effort компенсационное удаление при ошибке. Периодическая сверка (python -m app.reconcile) перечисляет S3-ключи и записи PostgreSQL, классифицирует несовпадения, печатает JSON. По умолчанию dry-run, без изменений. --apply восстанавливает потерянную копию или удаляет orphan только после grace_seconds >= 300 и повторной проверки, что объект не указан в зафиксированной таблице БД. Повторный --apply при согласованном состоянии не должен делать действий. При потере обеих копий metadata не удаляются.

Гипотеза трека: сверка двух хранилищ, recovery copy и защитный интервал позволяют исправлять одиночные пропажи ключей и безопасно убирать orphan-объекты без удаления используемых файлов. Издержка решения — около двух копий занимаемого S3-пространства; полный проход держит инвентаризацию в памяти порядка O(N_s3_keys + N_db_rows) и выполняет соответствующее число проверок/перечислений.

Запуск с чистого clone (PowerShell)

Требуются Docker Desktop с Compose v2, Python 3.9+ (для локальных тестов), работающий Docker Engine. Запуск из корня текущей Lab4:

Copy-Item .env.example .env
notepad .env
# Установить разные случайные POSTGRES_PASSWORD, S3_ADMIN_SECRET_KEY, S3_SECRET_KEY;
# проверить значения остальных обязательных переменных без публикации секретов.
$env:PYTHONUTF8 = '1'
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --wait
docker compose --env-file .env ps
python scripts/check_contract.py
python tests/smoke.py
python tests/attachments_negative.py
python tests/idempotency_parallel.py

Эквивалент make check — python scripts/check_contract.py; эквивалент make test — python tests/smoke.py. В представленных логах проверялись прямые вызовы Python, а не отдельный запуск make. На Windows можно вызвать make check PYTHON=python и make test PYTHON=python, если make установлен.

Persistence: python tests/resilience.py --mode persistence --action-script scripts/restart.cmd
Failover: python tests/resilience.py --mode failover --action-script scripts/stop-one.cmd; после теста восстановить docker compose --env-file .env up -d --no-deps --wait api1 api2.
S3: docker compose --env-file .env run --rm reconcile python -m app.s3_probe.
Reconciler: docker compose --env-file .env run --rm reconcile python -m app.reconcile [--apply].
В LAB4_TEST_COMMANDS.md перечислены демонстрационные и негативные сценарии. Безопасная остановка: docker compose --env-file .env down без -v, иначе удалятся данные.

Фактические результаты локальных испытаний

Результаты ниже основаны на переданных stdout PowerShell/Docker. Это локальные прогоны, не CI. Следы команд и ключевые JSON-выводы обезличенно переписаны в evidence/verified_results_2026-11-12.md. Неинструментированная производительность из одного запуска не обобщается на production.

Проверка Результат Комментарий
docker compose config --quiet, up -d --build --wait PASS Контейнеры API × 2, HAProxy, PostgreSQL, Redis, S3 запущены; API/LB/DB/Redis healthy
python scripts/check_contract.py PASS Offline-проверка структуры и синтаксиса, не интеграционный тест
python tests/smoke.py PASS Public API, вложение, checksum, ACL
python tests/attachments_negative.py PASS MIME, повреждение, размер, filename, ACL, cross-chat
python tests/idempotency_parallel.py PASS Две реплики, одно сообщение, replay 201, конфликт 409
python -m app.s3_probe PASS Private bucket: анонимные listing/object GET запрещены
python -m app.reconcile_selftest PASS Изолированная проверка dry-run, grace, restore, повторного apply; не заменяет интеграционные тесты
python -m app.reconcile до инъекций PASS 4 S3-ключа, 2 строки БД; нет расхождений и ошибок
Persistence с restart.cmd PASS После перезапуска сохранены сообщения, сессия и байты вложения; тест сверяет скачанное с исходником
Failover с stop-one.cmd PASS 2 реплики до отказа, 6 успешных записей, 1 неуспешная попытка; восстановление за 6,156 с
10 параллельных PNG-загрузок PASS 10/10, ошибок 0, 2,796 с, 3,577 upload/s, p50 2164 мс, max 2344 мс, 111817 байт/файл
RAM API при конкурентных загрузках Наблюдено Пиковые из выборочных docker stats: api1 109,1 MiB, api2 96,21 MiB, оба лимита 384 MiB; не абсолютный пик
Отказ S3 PASS После docker compose stop s3 HAProxy вернул HTTP 503; после запуска S3 и готовности API smoke PASS
Повторная сверка после всех восстановлений PASS 34 S3-ключа, 17 строк БД; проблем нет; время обхода 0,213 с

Эксперимент A: потерян основной S3-объект

Инъекция: python -m app.reconcile_fault delete-primary --id <uuid> под LAB4_ALLOW_FAULT_INJECTION=yes. Только учебное окружение. Изменён объект attachments/045ee0a6-be0d-4712-884f-b82145888ad6/original (идентификатор синтетического вложения).

Шаг Наблюдение
Удаление оригинала fault: delete-primary; recovery copy сохранена
Первый dry-run missing_primary_repairable содержит UUID, actions=[], errors=[]; 31 ключ, 16 строк, 0,162 с
--apply action: restore, копирование из recovery/<uuid>/original → attachments/<uuid>/original, errors=[]; 0,216 с
Повторный dry-run 32 ключа, 16 строк, пустые mismatch и actions; 0,159 с
Повторный apply, отдельный прогон 34 ключа, 17 строк, actions=[] и errors=[]; 0,179 с
Smoke после восстановления PASS

Вывод: успешное восстановление одиночной пропажи основного ключа подтверждено на реальном SeaweedFS/PostgreSQL. Приведённый публичный smoke проходил после исправления, но байтовая сверка именно выбранного вручную UUID отдельно не снималась.

Эксперимент B: объект существует в S3 без metadata

Инъекция: python -m app.reconcile_fault create-orphan (моделирует разрыв «S3 PUT успел, PostgreSQL COMMIT не произошёл»). Создан attachments/db466391-0d91-4757-990f-f2bb93872f5d/original.

Шаг Наблюдение
Dry-run сразу после создания orphan_keys_young содержит объект, orphan_keys=[], actions=[], 35 ключей/17 строк, 0,190 с
--apply до истечения 300 с Объект не удалён, actions=[], orphan_keys_young содержит ключ, 0,225 с
Пауза Явное Start-Sleep -Seconds 310
--apply после паузы orphan_keys содержит ключ, action: delete-old-orphan, errors=[], 0,228 с
Финальный dry-run 34 ключа, 17 строк, нет orphan/missing/errors/actions, 0,213 с

Вывод: grace period не позволяет удалить свежий объект; stale orphan удаляется только в apply. Отдельная авария/откат реальной PG-транзакции при загрузке не инъецировалась — испытан эквивалентный итоговый случай «S3 объект есть, metadata нет».

Эксперимент C: недоступность SeaweedFS

docker compose --env-file .env stop s3 → публичный GET /health/ready через HAProxy вернул HTTP 503 (No server is available to handle this request). Затем up -d s3, up -d --wait api1 api2 lb и python tests/smoke.py → PASS. Это подтверждает отказ публичной готовности и восстановление работоспособности. Прямые ответы каждой реплики /health/ready при отключённом S3 отдельно не снимались.

Эксперимент D: стоимость обхода при трёх объёмах данных

Гипотеза: при увеличении числа объектов S3 и строк PostgreSQL растёт объём инвентаризации и потенциальная стоимость полной сверки, но для небольшого локального набора время одного прохода остаётся приемлемым.

Методика: из корня Lab4 запущен powershell -ExecutionPolicy Bypass -File scripts/measure_reconcile.ps1. На каждом этапе выполнялось 5 независимых dry-run, всего 15. После этапов 0 и 1 добавлялось по 50 PNG-вложений (5 пакетов × 10 параллельных upload), всего 100 новых вложений, 0 ошибок загрузки. Каждый upload создаёт две S3-копии. Измеряется scan_elapsed_seconds внутри reconciler, а не общее время создания временного Docker-контейнера. Никакого --apply во время замеров не было.

Этап Ключей S3 Строк БД Прогонов Среднее, с Медиана, с Диапазон, с
0 36 18 5 0,3208 0,245 0,207–0,624
1 136 68 5 0,3068 0,285 0,270–0,401
2 236 118 5 0,3814 0,341 0,289–0,568

Измерения из stdout соответствуют файлу, созданному на машине тестирования: evidence/reconcile-cost-20261112-180238.csv. Приложите оригинальный CSV, а не вручную переписанные данные, в Git вместе с отчётом. Обезличенная сводка и 15 значений приведены также в evidence/verified_results_2026-11-12.md.

Интерпретация: при росте числа ключей с 36 до 236 (≈6,56 раза) медиана выросла с 0,245 до 0,341 с (≈39%). Среднее на этапе 1 оказалось чуть ниже этапа 0 из-за разброса/первого длительного замера; упорядоченный рост трёх медиан — наблюдение, не доказательство линейной масштабируемости. Малый набор, один хост, 5 прогонов на этап, кеширование и сетевые колебания ограничивают переносимость результатов. Полный inventory хранит списки ключей/строк в RAM; для больших объёмов нужны потоковая пагинация и батчинг.

Отдельный ранний контрольный замер: 34 ключа S3 + 17 строк БД → 0,213 с; он относится к другому моменту измерений и не заменяет серию выше.

Что пока не заявляется как PASS

  • Инъекция одновременной потери обеих S3-копий и подтверждение nonzero/ручной обработки. Алгоритм содержит ветку missing_both_unrecoverable, но интеграционный тест не предъявлен.
  • Полноценная реальная ошибка PostgreSQL COMMIT посреди upload; созданный orphan моделирует конечное состояние этого сбоя.
  • Вариант, когда чужой объект получает ссылку из БД строго между inventory и DELETE, отдельно не проверен в живой гонке (в коде есть повторная проверка ссылки).
  • Измерены только небольшие локальные наборы (36–236 S3-ключей); на сотнях тысяч и миллионах объектов время/память не измерялись.
  • Стресс ≥10 параллельных больших файлов: тест использовал 10 файлов по 111817 байт; измеренные значения RAM относятся к этому профилю.
  • Доступность при потере PostgreSQL, Redis, S3-диска, Docker-host/HAProxy, реальное rolling deployment несовместимых версий, TLS/дистрибутивные секреты.

Ограничения и безопасность

Один Docker-host, один S3/PG/Redis/LB — точки отказа. Recovery copy находится на том же SeaweedFS и не заменяет внешний backup. Результат HTTP 503 ожидаем при критической недоступности S3. На локальном учебном окружении transport S3/PG/Redis не использует mTLS; для production нужны TLS, внешний secret manager, backups, логи и метрики. При оборванной потоковой отдаче уже отправленный 200 нельзя отозвать: проверяйте полноту ответа/checksum на стороне клиента. Поведение отката при сбое между двух независимых хранилищ основано на компенсации и сверке, не на общей ACID-транзакции. Полный inventory держится в памяти и требует батчинга на больших объёмах.

Источники и применение ИИ

Основание: README.md, contracts/, tests/README.md лабораторной №4, документация S3/SeaweedFS, PostgreSQL, Redis, Docker Compose, HAProxy, FastAPI и Pillow. ChatGPT использовался для проектирования, программирования, SQL-миграций, тестов, Docker-конфигурации, скриптов и текста отчёта. Данные испытаний получены локальными командами пользователя, а не сгенерированы ИИ. В Git не публикуются .env, credentials, session tokens, приватные ключи, приватные данные и volumes.