22 KiB
Отчёт — лабораторная 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 не образуют распределённой транзакции. Возможные сбои:
- S3-объект уже создан, а транзакция БД не завершилась — orphan, объект без metadata.
- Metadata присутствует, но основного S3-ключа нет — missing primary; его можно восстановить из recovery copy.
- Metadata присутствует, но резервного S3-ключа нет — missing backup; его можно восстановить из основного.
- Отсутствуют обе копии — автоматическое восстановление невозможно; нужен внешний 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.