forked from mtusi2026/mtusi2026lab4
165 lines
22 KiB
Markdown
165 lines
22 KiB
Markdown
# Отчёт — лабораторная 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
|
||
|
||
```text
|
||
Клиент (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:
|
||
|
||
```powershell
|
||
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.
|