forked from mtusi2026/mtusi2026lab4
208 lines
17 KiB
Markdown
208 lines
17 KiB
Markdown
# Lab4, трек 2: согласованность PostgreSQL и S3
|
||
|
||
## Задача и гипотеза
|
||
|
||
S3 PUT и PostgreSQL COMMIT не образуют общую транзакцию. При сбоях возможны:
|
||
объект без Attachment, зависший pending без объекта и Attachment с потерянным
|
||
оригиналом. Гипотеза: устойчивый журнал намерений, общая блокировка на ключ и
|
||
повторяемая сверка устраняют бесхозные объекты, сохраняя свежие, активные и
|
||
используемые вложения. Время обхода ожидается примерно линейным по числу ключей.
|
||
|
||
## Что хранится в БД
|
||
|
||
- `attachments` — опубликованные вложения. Наличие записи защищает оригинал,
|
||
даже если вложение ещё не использовано в сообщении.
|
||
- `upload_intents` — ключ, время регистрации и состояние `pending`, `committed`
|
||
или `abandoned`. Это внутренний журнал, не публичные статусы Attachment.
|
||
- `storage_findings` — наблюдения orphan/missing, время обнаружения/последней
|
||
проверки/закрытия и отпечаток объекта для диагностики.
|
||
- `attachments.storage_missing_since` — внутренняя отметка о потере оригинала.
|
||
|
||
Миграция `008` добавляет эти данные без изменения предыдущих вложений. Старые
|
||
Attachment защищаются и без журнала. Наличие строки журнала само по себе не
|
||
защищает мусор навсегда: старые pending проверяются и закрываются.
|
||
|
||
## Загрузка и транзакции
|
||
|
||
1. Проверить пользователя, чат, имя, размер, MIME, структуру и число пикселей.
|
||
До S3 файл находится во временном ограниченном хранилище; считать SHA-256.
|
||
2. Назначить уникальный `originals/<uuid>`.
|
||
3. В отдельной транзакции взять advisory lock на ключ, записать pending и COMMIT.
|
||
4. В HTTP-транзакции взять ту же блокировку, повторно проверить pending.
|
||
5. Выполнить S3 PUT, удерживая блокировку.
|
||
6. Одним COMMIT сохранить Attachment и перевести журнал в committed.
|
||
7. Только после COMMIT вернуть 201 ready.
|
||
|
||
Блокировка `pg_advisory_xact_lock` вычисляется по стабильному хешу object key;
|
||
она действует до конца транзакции и освобождается PostgreSQL при разрыве
|
||
соединения. Reconciler использует `pg_try_advisory_xact_lock`: занятый ключ
|
||
пропускается, а не задерживает весь обход. Случайная коллизия хеша только
|
||
сериализует независимые ключи, но не разрешает удаление используемого объекта.
|
||
|
||
При неизвестном результате COMMIT файл сразу не удаляется. Журнал и последующая
|
||
проверка Attachment позволяют разобрать исход без риска удалить уже подтверждённый
|
||
оригинал. При обрыве HTTP до этапа S3 PUT постоянного объекта ещё нет.
|
||
|
||
## Алгоритм сверки
|
||
|
||
Область действия — только настроенный `S3_BUCKET` и `originals/` либо более узкий
|
||
префикс. Другие bucket и префиксы не перечисляются. ListObjectsV2 читается лениво
|
||
постранично; приложение не собирает весь список в RAM. Записи БД читаются
|
||
порциями по 200 с продолжением по ключу.
|
||
|
||
Для каждого объекта:
|
||
|
||
1. Попробовать взять блокировку; занят — пропустить.
|
||
2. Проверить Attachment заново под блокировкой. Есть запись — сохранить.
|
||
3. Проверить актуальный S3 HEAD и pending, зафиксировать наблюдение.
|
||
4. Если объект или намерение свежие — сохранить.
|
||
5. Иначе закрыть существующее намерение как abandoned, удалить бесхозный объект,
|
||
закрыть наблюдение и COMMIT.
|
||
|
||
Запас `RECONCILE_GRACE_SECONDS=300` — один настраиваемый период, без второго
|
||
ожидания после первого обнаружения. Он проверяется относительно времени изменения
|
||
S3-объекта и создания намерения. Он не заменяет блокировку и не является lease:
|
||
сколько бы ни длилась активная загрузка, занятый ключ пропускается.
|
||
|
||
Старые pending без Attachment и без S3-объекта переводятся в abandoned. Отложенный
|
||
загрузчик повторно проверяет состояние и не публикует закрытую попытку.
|
||
Незавершённые multipart parts не видны в ListObjectsV2. SDK пытается отменить
|
||
неудачный multipart; дополнительно MinIO настроен на expiry незавершённых загрузок
|
||
через 24 часа с проверкой раз в час. Объекты целиком по этим настройкам не удаляются.
|
||
|
||
Обратный проход проверяет S3 HEAD для каждого Attachment:
|
||
|
||
- Подтверждённое NoSuchKey/NoSuchObject отмечается как missing. Метаданные,
|
||
сообщения и связи сохраняются. API отвечает 503 на чтение такого вложения;
|
||
новые сообщения с ним получают 409. Повтор ранее подтверждённого сообщения
|
||
с прежним Idempotency-Key сохраняет прежний результат.
|
||
- Если отсутствовавший объект появился снова, проверяются размер и фактический
|
||
SHA-256 при ограниченном чтении. Совпали — отметка снимается. ETag не считается SHA-256.
|
||
- AccessDenied, пропавший bucket, timeout и другие ошибки прерывают проход;
|
||
они не интерпретируются как отсутствие всех файлов.
|
||
|
||
Отдельный проход закрывает оставшиеся orphan-наблюдения, если S3 DELETE выполнился,
|
||
но его ответ или последующий COMMIT потерялись. Повтор удаления безопасен.
|
||
Reconciler не восстанавливает потерянные байты из метаданных: для восстановления
|
||
нужна копия исходного файла. Он безопасно изолирует потерю и проверяет восстановление.
|
||
|
||
## Запуск и наблюдение
|
||
|
||
Compose запускает отдельный reconciler: apply каждые 300 секунд, grace 300 секунд.
|
||
Процесс пишет JSON: режим, область обхода, действия, ограниченную выборку ключей,
|
||
время, число SQL statements, HTTP-запросы S3 по операциям и пик RSS процесса.
|
||
Healthcheck этого контейнера проверяет жизнь процесса; результаты проходов — в JSON.
|
||
Сбой обслуживания S3/БД оставляет цикл работающим для повторной попытки.
|
||
|
||
```sh
|
||
make -f student.mk reconcile # просмотр, без изменения БД и S3
|
||
make -f student.mk reconcile-apply # применить безопасные исправления
|
||
# Полные отчёты фонового процесса:
|
||
docker compose logs reconciler
|
||
```
|
||
|
||
Dry-run не пишет наблюдения, не меняет статусы и не удаляет файлы. Он не обещает,
|
||
что последующий apply увидит ровно то же состояние: apply перепроверяет всё заново.
|
||
Другой фоновый процесс может менять данные одновременно с dry-run. Для спокойного
|
||
просмотра без фоновой очистки:
|
||
|
||
```sh
|
||
docker compose stop reconciler
|
||
docker compose run --rm --no-deps reconciler python -m src.maintenance.reconcile
|
||
# После просмотра восстановить периодическую работу:
|
||
docker compose up -d reconciler
|
||
```
|
||
|
||
## Права доступа
|
||
|
||
Bootstrap с MinIO owner credentials создаёт приватный bucket и двух отдельных
|
||
пользователей. Декларативные политики находятся в `infra/s3/api-policy.json` и
|
||
`infra/s3/reconciler-policy.json`; Dockerfile копирует их в образ. Python-сценарий
|
||
явно выполняет подготовку bucket и настройку каждого пользователя. В API-контейнерах owner/reconciler credentials переопределены пустыми
|
||
значениями; в reconciler нет owner/API credentials.
|
||
|
||
| Роль | Права |
|
||
| --- | --- |
|
||
| API | ListBucket/GetBucketLocation своего bucket; GetObject/PutObject и multipart операции только в originals/; нет DeleteObject |
|
||
| Reconciler | ListBucket/GetBucketLocation/GetBucketVersioning своего bucket; GetObject/DeleteObject только в originals/; нет PutObject и admin прав |
|
||
| Bootstrap | Создание bucket, пользователей и политик; доступен только как отдельная завершающаяся задача |
|
||
|
||
`MINIO_ROOT_*` должны сохранять прежние credentials владельца при обновлении
|
||
существующего volume. `S3_ACCESS_KEY_ID`/`S3_SECRET_ACCESS_KEY` теперь относятся к
|
||
отдельному API-пользователю. Значения по умолчанию предназначены для локального
|
||
учебного стенда. Консоль выключена, порты S3 наружу не публикуются.
|
||
|
||
## Методика и доказательства
|
||
|
||
```sh
|
||
make -f student.mk test-reconciliation
|
||
make -f student.mk test-upload-memory PYTHON=.venv/bin/python
|
||
make -f student.mk test
|
||
make -f student.mk test-attachments PYTHON=.venv/bin/python
|
||
```
|
||
|
||
`tests/reconciliation.py` использует отдельную UUID-схему PostgreSQL и приватный
|
||
UUID-bucket MinIO; при завершении удаляет только собственные тестовые ресурсы.
|
||
Проверяет реальные PUT/HEAD/GET/DELETE, процесс, аварийно завершающий настоящий
|
||
код загрузки после PUT, ошибку COMMIT, отказ PUT, занятую блокировку, свежий файл,
|
||
публикацию между dry-run и apply, missing, неправильное и правильное восстановление,
|
||
потерянный ответ DELETE, AccessDenied и отказ БД. Snapshot доказывает отсутствие
|
||
изменений при dry-run. Отдельно проверяются развёрнутые S3-права API/reconciler.
|
||
|
||
Стоимость обхода измеряется на 10, 100 и 1005 объектах, по три прогона; 1005
|
||
объектов проверяют переход между страницами ListObjectsV2. Используется dry-run
|
||
по свежим бесхозным объектам: на объект приходится HEAD и примерно пять SQL
|
||
statements. Размер объекта почти не влияет на этот профиль, поскольку его байты
|
||
не читаются. Hash-проверка восстановленного missing имеет отдельную стоимость
|
||
чтения исходника. Точные результаты — `evidence/lab4-final-reconciliation.txt`.
|
||
|
||
Локальное исследование не доказывает ту же скорость на удалённых сервисах:
|
||
RTT, объём bucket и задержки СУБД могут существенно изменить время. Текущий обход
|
||
последовательный; пакетная сверка могла бы уменьшить число SQL round trips.
|
||
|
||
Эксперимент памяти временно задаёт 5 принимаемых загрузок на каждую из двух API-
|
||
реплик; декодирование изображений ограничено одним потоком на реплику. Запускает
|
||
10 одновременных загрузок для двух размеров PNG, проверяет SHA-256 и скачивание,
|
||
измеряет cgroup memory.current каждые 20 мс, включая tmpfs. После теста восстанавливает
|
||
обычную настройку параллелизма. Короткие пики между измерениями могут быть пропущены;
|
||
эти два размера не доказывают worst case для изображения в 40 млн пикселей.
|
||
|
||
## Границы безопасности
|
||
|
||
Поддерживается один неверсионируемый bucket. CLI отказывается работать с Enabled
|
||
или Suspended versioning: там нужны отдельный учёт версий и политика delete markers.
|
||
Все штатные писатели должны соблюдать протокол блокировок. Прямая административная
|
||
перезапись/удаление S3-объекта одновременно со сверкой обходят эту координацию.
|
||
Не обещается автоматическое восстановление БД/S3 из backup или защита от потери
|
||
всего Docker host. Согласованность S3-провайдера, расхождение часов и допустимый срок
|
||
pending нужно учитывать при переносе; будущие временные метки консервативно задерживают очистку.
|
||
Журнал и закрытые наблюдения пока сохраняются без автоматического удаления истории.
|
||
|
||
## Итоговые измерения
|
||
|
||
Все 16 этапов `make -f student.mk verify-lab4` завершились с exit code 0. Интеграционный
|
||
набор сверки содержит 15 проверок, включая отказ DELETE до удаления
|
||
и прямой unsigned GET существующего объекта с результатом 403.
|
||
|
||
| Объектов | Медиана 3 обходов, с | LIST | HEAD | SQL statements |
|
||
| --- | --- | --- | --- | --- |
|
||
| 10 | 0.0181 | 1 | 10 | 53 |
|
||
| 100 | 0.1559 | 1 | 100 | 503 |
|
||
| 1005 | 1.9679 | 2 | 1005 | 5028 |
|
||
|
||
Оба профиля по 10 одновременных загрузок завершились без отказов: 20 ответов 201,
|
||
все SHA-256 и скачанные оригиналы совпали. Пики RAM: **124.71 / 128.91 MiB**
|
||
при 512 MiB на реплику. Размеры PNG: 197105 и
|
||
4923446 байт. Обычный UPLOAD_CONCURRENCY=1 восстановлен.
|
||
|
||
При замороженной PostgreSQL уже выполнявшаяся история вернула 503 за
|
||
**5.0988 с**, readiness — за **2.1109 с**.
|
||
После unpause восстановились 200 без рестарта API. Пустой стенд дошёл до миграции
|
||
008; API build --no-cache занял 32.829 с. Временный проект,
|
||
volumes и его теги образов удалены; действующие данные сохранены.
|
||
|
||

|
||
|
||
Усы на графике — min/max трёх запусков, не доверительный интервал.
|
||
Указанная RAM — максимум отсчётов, а не доказанный абсолютный пик между ними.
|