Files

165 lines
22 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Отчёт — лабораторная 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.