Files
mtusi2026lab4/REPORT.md
T

34 KiB
Raw Blame History

Отчёт — лабораторная 4

  • Автор, группа: Станислав Травкин, группа: БВТ2304.
  • Целевая оценка: 5.
  • Выбранный трек оценки 5: трек 2 — Согласованность двух хранилищ.
  • Git: ветка solution/bvt2304-travkin; опубликованный коммит реализации 0ef8d739d7c843ac82f3843f11321d8732580a07. Финальный коммит с отчётом будет опубликован в той же ветке. PR: создаётся после публикации финальных изменений.
  • Использованные источники, библиотеки и помощь ИИ: README и методические требования лабораторной работы; Python 3.13, FastAPI, SQLAlchemy, Alembic, PostgreSQL, Redis, boto3, Pillow, MinIO, Nginx, Docker Compose. ChatGPT использовался для обсуждения архитектуры, реализации, диагностики ошибок, подготовки тестовых сценариев и отчёта. Реализация проверялась запуском тестов и экспериментами в локальном окружении.

Запуск из чистого clone

Окружение

Разработка и испытания проводились в Ubuntu 22.04 под WSL2, с использованием Docker Engine, Docker Compose, Python 3.13 и виртуального окружения .venv.

Используемые контейнерные образы:

Компонент Образ
PostgreSQL postgres:17.6
Redis redis:8.2.2
MinIO dappros/minio:RELEASE.2025-09-07T16-13-09Z
Nginx nginx:1.29-alpine
API и миграции Локальная сборка из Dockerfile

Для запуска необходимы Docker Engine, Docker Compose, Python 3.13, Bash и свободные локальные порты 8080 и 9001. Порт 9001 публикуется только на 127.0.0.1; API MinIO доступен внутри сети Compose.

Подготовка

После клонирования репозитория необходимо перейти в каталог проекта, создать локальное виртуальное окружение и установить зависимости проекта.

python3.13 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -r requirements-dev.txt

Подготовить локальные секреты и конфигурацию командой:

./scripts/bootstrap.sh

Скрипт создаёт каталог secrets/ и семь файлов: postgres_password, database_url, cache_url, minio_root_user, minio_root_password, s3_access_key_id, s3_secret_access_key. Для отсутствующих секретов генерируются значения, а уже существующие непустые файлы сохраняются. database_url создаётся со значением для пользователя PostgreSQL lab2 и паролем из postgres_password; cache_url указывает на Redis. Учётные данные S3-приложения отличаются от административных данных MinIO.

Скрипт также копирует .env.example в .env, если локального .env ещё нет, и выполняет docker compose config --quiet. Параметры реального стенда задаются главным образом через environment в compose.yaml, а секреты подключаются как файлы /run/secrets. Вручную заполнять .env для текущего Compose не требуется.

Важно: текущий bootstrap устанавливает для файлов secrets/* режим 644, то есть локальные пользователи хоста могут получить право чтения. Это учебное ограничение: каталог имеет режим 700, но права файлов следует ужесточить для многопользовательского хоста, предварительно обеспечив доступ непривилегированным контейнерам. Не публиковать содержимое secrets/, .env, пароли и токены. При повторном запуске на уже заполненных томах PostgreSQL/MinIO нельзя бездумно менять согласованные учётные данные.

Сборка и запуск

docker compose config --quiet
docker compose build
docker compose up -d
docker compose ps -a

При первом запуске PostgreSQL создаёт базу данных, контейнер migrate применяет миграции Alembic, а s3-init создаёт приватный бакет и пользователя приложения с ограниченными правами.

Оператор должен дождаться состояния healthy для PostgreSQL, Redis, MinIO и обеих API-реплик, а также успешного завершения migrate и s3-init.

Проверка версии схемы:

docker compose run --rm migrate alembic current

В испытаниях наблюдалась версия d9e53b20f7c1 (head).

Проверка

После запуска дождаться готовности API:

curl --fail http://localhost:8080/health/ready

Затем выполнить:

make check
make validate
make test
make test-reconcile
make test-compensation
make reconcile

Дополнительные испытания:

make load
make test-failover ACTION_SCRIPT=./scripts/stop-one.sh
make test-persistence ACTION_SCRIPT=./scripts/restart.sh

Тест отказоустойчивости намеренно останавливает API-реплику; после него её необходимо запустить снова:

docker compose up -d api-1 api-2

Reconciler в обычном режиме ничего не удаляет. Для разрешённой оператором очистки устаревших незарегистрированных объектов предусмотрена команда:

make reconcile-repair

По умолчанию применяется защитный период 24 часа. Перед очисткой рекомендуется выполнить make reconcile и изучить список расхождений.

Остановка

Безопасная остановка без удаления данных:

docker compose down

Намеренное удаление учебных данных, включая постоянные тома PostgreSQL, Redis и MinIO:

docker compose down -v

Последняя команда необратимо удаляет данные в томах данного Compose-проекта и не должна использоваться при обычном перезапуске.

Архитектура и решения

Схема компонентов

Клиент
   |
   v
Nginx :8080
   |
   +------ API-1 :8080
   |
   +------ API-2 :8080
              |
              +------ PostgreSQL
              |       пользователи, чаты,
              |       сообщения, вложения
              |
              +------ Redis
              |       сессии
              |
              +------ MinIO (S3)
                      бинарные данные вложений

Nginx распределяет запросы между двумя экземплярами FastAPI. API-реплики не используют локальное состояние для хранения пользовательских данных. Метаданные сохраняются в PostgreSQL, сессии — в Redis, содержимое вложений — в приватном бакете MinIO.

PostgreSQL является источником истины для регистрации вложений и их принадлежности чатам. S3 хранит бинарные данные, адресуемые через s3_key.

Что перенесено из лабораторной 3

Сохранены пользовательские операции, авторизация через сессии, чаты, сообщения, идемпотентность создания сообщений, две API-реплики, балансировщик Nginx, PostgreSQL и Redis.

Что добавлено в лабораторной 4

  • Приватное S3-хранилище MinIO с постоянным томом.
  • Идемпотентная инициализация бакета и ограниченной учётной записи приложения.
  • Загрузка PNG/JPEG с проверкой MIME-типа, содержимого и имени файла.
  • Ограничения: не более 10 МиБ и 40 млн пикселей.
  • Метаданные вложений в PostgreSQL и связь вложений с сообщениями.
  • Проверка принадлежности вложений чату.
  • Компенсация при сбое записи метаданных после успешной загрузки в S3.
  • Отдельный reconciler для обнаружения и обработки расхождений между PostgreSQL и MinIO.
  • Тесты компенсации, безопасной сверки и исправления расхождений.

Транзакционные границы

PostgreSQL и MinIO не участвуют в общей распределённой транзакции.

При загрузке изображения сначала проверяются права пользователя и содержимое файла, затем объект записывается в S3, после чего создаётся запись PostgreSQL со статусом ready.

Ответ 201 Created возвращается только после успешной записи объекта и завершения транзакции PostgreSQL.

Если запись в БД завершается ошибкой, приложение откатывает транзакцию и проверяет наличие зарегистрированного s3_key через отдельную сессию. Удаление объекта допускается только при подтверждённом отсутствии записи. Если состояние PostgreSQL невозможно проверить, объект сохраняется для последующей сверки.

Это уменьшает риск удаления зарегистрированного вложения, но не обеспечивает атомарность двух хранилищ. Оставшиеся после аварий объекты обнаруживаются reconciler.

Reconciliation

Утилита scripts/reconcile.py получает список ключей из таблицы attachments и перечень объектов S3.

Она вычисляет:

  • orphan_objects — объекты S3 без соответствующей записи PostgreSQL;
  • missing_objects — записи PostgreSQL, для которых отсутствует объект S3.

Режим dry-run только сообщает о расхождениях.

В режиме --repair допускается удаление устаревших незарегистрированных объектов. Для защиты данных используются период ожидания, повторная проверка существования записи PostgreSQL и повторная проверка метаданных объекта S3 непосредственно перед удалением.

Отсутствующие объекты S3 не восстанавливаются автоматически: reconciler сообщает о них, не удаляя метаданные PostgreSQL.

Конфигурация

Параметры S3 (S3_ENDPOINT, S3_REGION, S3_BUCKET), пути к секретам, SESSION_TTL_SECONDS, MAX_UPLOAD_BYTES и MAX_IMAGE_PIXELS передаются через compose.yaml.

INSTANCE_ID различает реплики api-1 и api-2.

Параметры APP_HOST, APP_PORT, SESSION_STORE, API_REPLICAS и IDEMPOTENCY_TTL_SECONDS из преподавательского .env.example не используются как управляющие настройки в текущем Compose-файле. Число реплик задаётся двумя сервисами, порт — конфигурацией контейнера и Nginx, а сессии фактически хранятся в Redis.

Доказательства критериев

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Публичный smoke make test PASS tests/smoke.py, REPORT.md
Проверка структуры make check PASS scripts/check_contract.py, REPORT.md
Проверка OpenAPI make validate PASS scripts/validate_openapi.py, REPORT.md
Две API-реплики docker compose ps api-1 api-2 Обе реплики healthy compose.yaml, REPORT.md
PostgreSQL и Redis docker compose ps -a Хранилища healthy compose.yaml, REPORT.md
Приватное S3-хранилище Анонимный запрос списка объектов бакета HTTP 403 AccessDenied; прямой анонимный GET оригинала также должен быть запрещён infra/minio/attachments-policy.json, REPORT.md
Ограниченные права приложения Запрос политики бакета от имени S3-приложения HTTP 403 AccessDenied infra/minio/attachments-policy.json, REPORT.md
Идемпотентный bootstrap Повторный docker compose run --rm s3-init Успешное выполнение, существующие объекты сохранены infra/minio/init.sh, REPORT.md
Повторные миграции docker compose run --rm migrate Успешно; схема на head migrations/versions/, REPORT.md
Загрузка PNG/JPEG POST изображения в чат HTTP 201; объект S3 и запись БД созданы src/main.py, src/images.py, REPORT.md
Ограничение 10 МиБ POST изображения больше лимита HTTP 413 src/images.py, REPORT.md
Ограничение 40 млн пикселей POST изображения с превышением лимита HTTP 413 src/images.py, REPORT.md
Неподдерживаемый формат POST GIF HTTP 415 src/images.py, REPORT.md
Несоответствие MIME содержимому PNG, заявленный как JPEG HTTP 400 src/images.py, REPORT.md
Повреждённое изображение POST повреждённого файла HTTP 400 src/images.py, REPORT.md
Доступ только участникам чата Запрос вложения посторонним пользователем HTTP 404 src/main.py, src/repositories.py, REPORT.md
Защита неавторизованного запроса GET вложения без сессии HTTP 401 src/main.py, REPORT.md
Получение метаданных и содержимого GET вложения участником чата HTTP 200; SHA-256 содержимого совпал src/storage.py, REPORT.md
Вложения в сообщениях Создание сообщения с attachment_ids HTTP 201 src/models.py, src/repositories.py, REPORT.md
Некорректные вложения в сообщении Передача недопустимых attachment_ids HTTP 400 src/repositories.py, REPORT.md
Идемпотентность сообщений Повтор ключа с тем же содержимым / изменение содержимого Повтор принят; конфликт HTTP 409 src/repositories.py, REPORT.md
Отказ MinIO Остановка S3 и попытка загрузки HTTP 503; после восстановления загрузка HTTP 201 src/storage.py, REPORT.md
Компенсация при ошибках make test-compensation 5 тестов, OK tests/test_upload_compensation.py, REPORT.md
Параллельные загрузки 10 одновременных загрузок изображений примерно по 4,13 МиБ 10 ответов HTTP 201; OOM не наблюдался REPORT.md
Отказ одной API-реплики make test-failover ACTION_SCRIPT=./scripts/stop-one.sh PASS; 95 успешных записей, 2 неудачные попытки scripts/stop-one.sh, REPORT.md
Сохранность при перезапуске make test-persistence ACTION_SCRIPT=./scripts/restart.sh PASS при повторной проверке; данные и сессия сохранились scripts/restart.sh, REPORT.md
Тесты reconciler make test-reconcile 8 тестов, OK tests/test_reconcile.py, REPORT.md
Поиск orphan-объектов Добавление объекта S3 без записи БД, запуск dry-run Объект обнаружен scripts/reconcile.py, REPORT.md
Поиск missing-объектов Добавление записи БД без объекта S3 Отсутствующий объект обнаружен scripts/reconcile.py, REPORT.md
Безопасный repair Искусственно состаренный тестовый orphan-объект Объект удалён, повторная сверка чистая scripts/reconcile.py, REPORT.md
Защита свежих объектов Repair при действующем grace period Свежий объект пропущен tests/test_reconcile.py, REPORT.md
Защита зарегистрированных объектов Повторная проверка БД перед удалением Зарегистрированный объект сохранён tests/test_reconcile.py, REPORT.md
Защита изменившихся объектов Повторная проверка LastModified Обновлённый объект сохранён tests/test_reconcile.py, REPORT.md
Повторяемость reconciliation Повторный dry-run после очистки тестовых объектов Нет расхождений scripts/reconcile.py, REPORT.md
Измерение стоимости сверки 10 запусков на 28 и 128 объектах S3 Медиана 5,161 и 13,029 мс соответственно REPORT.md

Результаты ручных сценариев зафиксированы в настоящем отчёте; исходные файлы тестов и конфигурации позволяют воспроизвести соответствующие проверки. Для ручных сценариев, не автоматизированных отдельным скриптом, повторное выполнение требует подготовки тестовых пользователей, чатов и файлов.

Эксперименты и отказы

Гипотезы

  1. Использование двух API-реплик и общих хранилищ позволяет продолжить обслуживание запросов при остановке одной реплики.
  2. Ограничение размера загружаемых файлов и ресурсов контейнеров позволяет выполнять параллельные загрузки без превышения лимита памяти.
  3. Reconciler обнаруживает расхождения между PostgreSQL и S3, а защитный период и повторные проверки позволяют избежать удаления свежих и зарегистрированных объектов.
  4. Увеличение количества объектов S3 повышает время полной сверки.

Условия испытаний

Среда: WSL2, Ubuntu 22.04, Docker Engine и Docker Compose.

Ресурсы контейнеров:

Сервис CPU RAM
API-1 1 512 МиБ
API-2 1 512 МиБ
PostgreSQL 1 768 МиБ
Redis 0,5 256 МиБ
MinIO 1 512 МиБ
Nginx 0,5 256 МиБ

Модель процессора хост-машины, выделенная память WSL2, показатели CPU во время нагрузочного теста и отдельная длительность прогрева не фиксировались. Эксперименты выполнялись в локальном учебном окружении; независимая проверка запуска на другом хосте не проводилась.

Нагрузочный тест API

Команда:

make load

Сохранённая сводка одного успешного прогона:

duration_seconds: 30
concurrency: 4
successful_requests: 12959
failed_requests: 0
successful_rps: 431.857
p50_ms: 8.592
p95_ms: 11.866
p99_ms: 16.363

Тест выполнял синтетические операции записи. Показатель 431,857 RPS характеризует конкретный локальный сценарий, а не гарантированную производительность в производственной среде.

Отдельные значения CPU/RAM для данного прогона не записывались.

Параллельная загрузка изображений

Выполнены два прогона по 10 одновременных загрузок файлов размером приблизительно 4,13 МиБ.

Все 10 запросов в каждом прогоне завершились HTTP 201.

Наблюдаемая длительность прогонов — приблизительно 1,26 и 0,83 секунды.

Зафиксированные максимальные значения потребления памяти API-контейнеров:

api-1: 154.71 MiB
api-2: 138.84 MiB
limit: 512 MiB per container
oom_kill: 0

Значения максимума памяти получены из счётчиков контейнеров и отражают накопленный пик, а не обязательно только интервал данного эксперимента.

Измерение стоимости reconciliation

Выполнены по 10 последовательных запусков полной сверки для двух размеров S3-хранилища.

Сценарий A: 28 записей PostgreSQL и 28 объектов S3.

times_ms:
20.772, 5.299, 5.023, 4.952, 4.469,
5.794, 5.492, 4.698, 4.678, 5.451

min_ms: 4.469
mean_ms: 6.663
median_ms: 5.161
max_ms: 20.772

Сценарий B: 28 записей PostgreSQL и 128 объектов S3, включая 100 временных объектов.

times_ms:
46.378, 13.201, 13.230, 13.349, 14.940,
12.856, 12.455, 11.603, 12.088, 11.242

min_ms: 11.242
mean_ms: 16.134
median_ms: 13.029
max_ms: 46.378

Медианное время выросло приблизительно в 2,52 раза при увеличении числа объектов S3 с 28 до 128.

Результат подтверждает увеличение стоимости полного обхода в исследованном диапазоне. Двух точек недостаточно для доказательства линейной асимптотики. Дополнительные временные объекты после эксперимента удалены.

Эксперименты с отказами

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
Остановка одной API-реплики Оставшаяся реплика продолжает обслуживать запросы Failover PASS, 95 успешных записей и 2 неудачные попытки Первое восстановление успешных запросов через 0,89 с; подтверждённой потери сохранённых данных нет
Перезапуск PostgreSQL, Redis и двух API Данные и сессии сохраняются Persistence PASS при повторном запуске Кратковременная недоступность; данные и сессия сохранились
Остановка MinIO Загрузка временно недоступна HTTP 503, после запуска S3 — HTTP 201 Восстановление после запуска MinIO; подтверждённой потери ранее сохранённых объектов нет
Ошибка вставки или commit в PostgreSQL Незарегистрированный объект компенсируется Соответствующие модульные тесты OK Удаление при подтверждённом отсутствии записи
Недоступность PostgreSQL при компенсации Не удалять объект с неизвестным состоянием регистрации Модульный тест OK Объект сохраняется до последующей сверки
Добавление orphan-объекта Reconciler обнаруживает лишний объект Обнаружен; устаревший тестовый объект удалён при repair Повторная сверка без расхождений
Добавление missing-записи Reconciler обнаруживает отсутствие бинарных данных Запись обнаружена; автоматическое удаление БД не выполнялось Восстановление содержимого не реализовано

При отдельных запусках теста persistence возникал TimeoutError ещё до выполнения сценария перезапуска. В логах Nginx наблюдались ошибки разрешения имён Docker DNS для api-2, включая wrong ident и could not be resolved. Повторные проверки DNS и последующий запуск persistence прошли успешно. Причина нестабильности окончательно не установлена.

Ограничения и следующие шаги

  1. Нет общей транзакции PostgreSQL и S3. Компенсация и периодическая сверка снижают риск рассогласования, но не заменяют распределённую транзакцию.

  2. Reconciler не восстанавливает отсутствующие бинарные данные. При наличии метаданных без S3-объекта требуется вмешательство оператора, восстановление из резервной копии или отдельная процедура обработки повреждённого вложения.

  3. Существует окно гонки между проверкой и удалением. Перед удалением выполняются дополнительные проверки, однако полной атомарности операций между двумя хранилищами нет.

  4. Grace period не гарантирует сохранность всех незарегистрированных объектов. Он защищает недавно созданные объекты, но старые объекты без метаданных могут быть удалены при repair. Поэтому repair выполняется осознанно оператором.

  5. Наблюдалась нестабильность Docker DNS. Некоторые запуски persistence завершались ошибкой до воздействия на инфраструктуру. Проблема не была устойчиво воспроизведена и не считается устранённой.

  6. Измерения выполнены локально. Результаты RPS и задержек зависят от WSL2, ресурсов хоста, профиля нагрузки и размеров данных. Измерения не являются производственным бенчмарком.

  7. Профиль reconciliation ограничен двумя размерами набора. Для оценки масштабируемости нужны дополнительные точки, большие объёмы данных и повторения на разных состояниях хранилища.

  8. Локальные секреты создаются с правами 644. Каталог secrets/ ограничен режимом 700, однако для многопользовательского хоста требуются более строгие права файлов и согласованная схема доступа контейнеров.

  9. Не реализованы распределённые блокировки и фоновое расписание reconciliation. Утилита запускается оператором. Для производственного применения целесообразны планировщик, аудит удалений, метрики, оповещения и резервное копирование.

Демонстрация преподавателю

Все команды выполняются из корня репозитория. Перед демонстрацией должны быть подготовлены локальные секреты и запущены контейнеры.

1. Запуск и проверка инфраструктуры

docker compose up -d
docker compose ps -a
docker compose run --rm migrate alembic current

Показать две работающие API-реплики, PostgreSQL, Redis, MinIO, Nginx и применённые миграции.

2. Проверка API

make check
make validate
make test

Показать успешные результаты проверки структуры, OpenAPI и публичного smoke-теста.

3. Проверка компенсации и reconciler

make test-compensation
make test-reconcile
make reconcile

Показать 5 успешных тестов компенсации, 8 успешных тестов reconciler и JSON-отчёт сверки в режиме dry-run.

Последняя зафиксированная сверка:

{
  "mode": "dry-run",
  "grace_hours": 24,
  "database_objects": 33,
  "storage_objects": 33,
  "orphan_objects": [],
  "missing_objects": [],
  "deleted_objects": [],
  "skipped_objects": [],
  "duration_seconds": 0.0263
}

Количество объектов зависит от текущих тестовых данных и при повторном запуске может отличаться.

4. Демонстрация нагрузки

make load

Показать количество успешных запросов, RPS, ошибки и задержки p50/p95/p99.

5. Демонстрация отказа одной API-реплики

make test-failover ACTION_SCRIPT=./scripts/stop-one.sh
docker compose up -d api-1 api-2
docker compose ps api-1 api-2

Показать, что сценарий действительно останавливает одну реплику, а затем восстановить обе.

6. Демонстрация сохранности данных

make test-persistence ACTION_SCRIPT=./scripts/restart.sh

Скрипт scripts/restart.sh перезапускает PostgreSQL, Redis, api-1 и api-2. Проверка должна подтвердить сохранение данных и сессии после восстановления.

7. Повторная проверка согласованности

make reconcile

Показать отсутствие незарегистрированных и отсутствующих объектов после испытаний.

Режим make reconcile-repair во время защиты без предварительного просмотра и согласования не запускать: он может удалять устаревшие незарегистрированные объекты.

8. Завершение демонстрации

docker compose down

Команда останавливает контейнеры, сохраняя данные PostgreSQL, Redis и MinIO.