82 lines
9.0 KiB
Markdown
82 lines
9.0 KiB
Markdown
# Отчёт по лабораторной работе №4
|
||
|
||
- Автор, группа: Борзов Никита, БВТ2304
|
||
- Целевая оценка: 5, трек 2 «Согласованность двух хранилищ»
|
||
- Commit/PR: `11c227c`, [MR !26](https://gitea.privcloud.tech/mtusi2026/mtusi2026lab4/pulls/26)
|
||
- Основа: проект лабораторной 3 с сохранением PostgreSQL, Redis, четырёх API-реплик, Nginx и общей идемпотентности
|
||
|
||
## Запуск из чистого clone
|
||
|
||
Требуются Docker Desktop с Compose v2 и Python 3.9+. Старые Docker Hub-образы MinIO больше не используются: стенд закрепляет digest-образы `cgr.dev/chainguard/minio` и `cgr.dev/chainguard/minio-client`.
|
||
|
||
```sh
|
||
cp .env.example .env
|
||
docker compose config --quiet
|
||
docker compose build api-1 minio-init
|
||
docker compose up -d --no-build --wait
|
||
make check
|
||
make test BASE_URL=http://localhost:8080
|
||
```
|
||
|
||
`minio` и одноразовый `minio-init` один раз создают приватный bucket и отдельного API-пользователя с правами только на нужный bucket. Консоль и порт S3 наружу не опубликованы. `docker compose down` останавливает стенд с сохранением volumes, а `docker compose down -v` намеренно удаляет учебные данные PostgreSQL, Redis и S3.
|
||
|
||
Проверка публикации портов: `docker compose port minio 9000` и `docker compose port minio 9001` не возвращают адресов. Поэтому прямой unauthenticated GET к MinIO с хоста невозможен, а доступ к файлам идёт только через авторизованный API.
|
||
|
||
## Архитектура и решения
|
||
|
||
```text
|
||
Клиент -> Nginx -> API × 4 -> PostgreSQL (метаданные) + Redis (сессии/кэш)
|
||
|
|
||
+-> приватный S3 bucket (байты)
|
||
```
|
||
|
||
PostgreSQL хранит пользователей, чаты, сообщения и метаданные вложений. S3 хранит только оригинальные байты. В таблице `attachments` находятся chat_id, владелец, отображаемое имя, MIME, размер, SHA-256, статус и назначенный сервером object key. Файл заранее привязан к чату.
|
||
|
||
`POST /api/v1/chats/{chat_id}/attachments` принимает сырые PNG/JPEG до 10 MiB. Запрос читается потоково небольшими кусками с жёстким ограничением размера. Pillow проверяет реальный формат файла и число пикселей до записи в S3. Имя не используется как путь или object key. Сначала выполняется S3 PUT, затем транзакционная запись метаданных; если запись PostgreSQL не удалась, выполняется компенсационный S3 DELETE.
|
||
|
||
Метаданные и байты выдаются только через авторизованный API. Участник чата получает метаданные и побайтный download, посторонний получает 404. Message принимает `attachment_ids`; все ID должны принадлежать тому же чату и иметь статус `ready`. Текст может быть пустым, если прикреплено хотя бы одно вложение.
|
||
|
||
Сохранены все возможности ЛР3: Bearer-сессии в Redis, PostgreSQL, keyset-пагинация, X-Instance-Id, Nginx, health/readiness, таймауты, Idempotency-Key, отказ одной API-реплики и restart с volumes.
|
||
|
||
## Доказательства критериев
|
||
|
||
| Критерий | Команда | Результат | Доказательство |
|
||
| --- | --- | --- | --- |
|
||
| Контракт и структура | `make check` | PASS | вывод проверки |
|
||
| Публичный API и вложения | `make test BASE_URL=http://localhost:8080` | `PASS: lab4 public API scenario` | `tests/smoke.py` |
|
||
| Реальные S3-байты | smoke | SHA-256 и размер download совпали с fixture | `tests/fixtures/sample.png` |
|
||
| Проверка негативных случаев | `python3 student-tests/attachments.py` | повреждённый файл и MIME mismatch — 415, большой файл — 413, чужой доступ — 404 | `student-tests/attachments.py` |
|
||
| Сохранность | `make test-persistence BASE_URL=http://localhost:8080 ACTION_SCRIPT=scripts/restart.sh` | подтверждены данные, токен и вложение после restart | `scripts/restart.sh` |
|
||
| Отказ API-реплики | `make test-failover BASE_URL=http://localhost:8080 ACTION_SCRIPT=scripts/stop-one.sh` | записи и download продолжаются через другие реплики | `scripts/stop-one.sh` |
|
||
| Общая идемпотентность | `python3 student-tests/idempotency.py` | конкурентные запросы создали один Message ID | проверка ЛР3 |
|
||
| Reconciler | `docker compose run --rm --no-deps api-1 python scripts/track_s3.py` | старый orphan удалён, свежий сохранён, missing metadata помечена failed | `evidence/track_s3.json` |
|
||
| Память загрузок | `python3 student-tests/upload_load.py` при сборе `docker stats` | 10 одновременных upload завершились успешно; peak API — 125.1 MiB из 256 MiB | `student-tests/upload_load.py`, `evidence/upload_memory.txt` |
|
||
|
||
## Исследовательский трек: согласованность двух хранилищ
|
||
|
||
Гипотеза: рассогласование PostgreSQL и S3 можно обнаруживать безопасным повторяемым обходом, не удаляя свежие объекты и не скрывая missing metadata.
|
||
|
||
Скрипт `scripts/reconcile_s3.py` сравнивает список объектов bucket с таблицей `attachments`. По умолчанию он работает в dry-run. Orphan удаляется только после grace period, заданного `--grace-seconds`; metadata без объекта переводится в `failed` с кодом `object_missing`. Используемые и свежие вложения не удаляются.
|
||
|
||
`scripts/track_s3.py` создаёт старый orphan, свежий orphan и строку metadata без объекта. Затем выполняет dry-run и apply с grace period 5 секунд. В результате:
|
||
|
||
```json
|
||
{
|
||
"old_orphan_removed": true,
|
||
"fresh_orphan_preserved": true,
|
||
"missing_marked_failed": true
|
||
}
|
||
```
|
||
|
||
После завершения эксперимента тестовые объекты и строка metadata удаляются. Отдельно 10 конкурентных загрузок fixture завершились успешно; при лимите API 256 MiB наблюдался максимум 125.1 MiB по `docker stats`. Ограничение измерения — один локальный MinIO с одним диском; это проверка согласованности и безопасного исправления, а не отказоустойчивость самого S3-кластера.
|
||
|
||
## Отказы и ограничения
|
||
|
||
Стенд выдерживает остановку одной API-реплики, перезапуск API/PostgreSQL/Redis/MinIO с сохранёнными volumes и переключение download через другую реплику. PostgreSQL, Redis, Nginx и один MinIO остаются единичными точками отказа. Потеря Docker-host и удаление volumes не входят в модель.
|
||
|
||
S3 credentials API отделены от root credentials MinIO и получают только `GetObject`, `PutObject`, `DeleteObject` и `ListBucket` для учебного bucket. Прямой S3-порт и административная консоль в Compose не опубликованы.
|
||
|
||
Локальные значения паролей в Compose нужны только для учебного запуска. В реальном окружении их задают через `.env` или секреты; файл `.env` в репозиторий не добавляется.
|
||
|
||
Исходный контракт и публичные tests не изменялись. ИИ использовался как помощник при разборе требований и подготовке кода; команды и результаты проверены на локальном Compose-стенде.
|