34 KiB
Отчёт — лабораторная 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 |
Результаты ручных сценариев зафиксированы в настоящем отчёте; исходные файлы тестов и конфигурации позволяют воспроизвести соответствующие проверки. Для ручных сценариев, не автоматизированных отдельным скриптом, повторное выполнение требует подготовки тестовых пользователей, чатов и файлов.
Эксперименты и отказы
Гипотезы
- Использование двух API-реплик и общих хранилищ позволяет продолжить обслуживание запросов при остановке одной реплики.
- Ограничение размера загружаемых файлов и ресурсов контейнеров позволяет выполнять параллельные загрузки без превышения лимита памяти.
- Reconciler обнаруживает расхождения между PostgreSQL и S3, а защитный период и повторные проверки позволяют избежать удаления свежих и зарегистрированных объектов.
- Увеличение количества объектов 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 прошли успешно. Причина нестабильности окончательно не установлена.
Ограничения и следующие шаги
-
Нет общей транзакции PostgreSQL и S3. Компенсация и периодическая сверка снижают риск рассогласования, но не заменяют распределённую транзакцию.
-
Reconciler не восстанавливает отсутствующие бинарные данные. При наличии метаданных без S3-объекта требуется вмешательство оператора, восстановление из резервной копии или отдельная процедура обработки повреждённого вложения.
-
Существует окно гонки между проверкой и удалением. Перед удалением выполняются дополнительные проверки, однако полной атомарности операций между двумя хранилищами нет.
-
Grace period не гарантирует сохранность всех незарегистрированных объектов. Он защищает недавно созданные объекты, но старые объекты без метаданных могут быть удалены при repair. Поэтому repair выполняется осознанно оператором.
-
Наблюдалась нестабильность Docker DNS. Некоторые запуски persistence завершались ошибкой до воздействия на инфраструктуру. Проблема не была устойчиво воспроизведена и не считается устранённой.
-
Измерения выполнены локально. Результаты RPS и задержек зависят от WSL2, ресурсов хоста, профиля нагрузки и размеров данных. Измерения не являются производственным бенчмарком.
-
Профиль reconciliation ограничен двумя размерами набора. Для оценки масштабируемости нужны дополнительные точки, большие объёмы данных и повторения на разных состояниях хранилища.
-
Локальные секреты создаются с правами
644. Каталогsecrets/ограничен режимом700, однако для многопользовательского хоста требуются более строгие права файлов и согласованная схема доступа контейнеров. -
Не реализованы распределённые блокировки и фоновое расписание 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.