Files
mtusi2026lab4/REPORT.md
T
2026-10-22 17:27:32 +03:00

26 KiB
Raw Blame History

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

  • Автор, группа: Гаджиев Нухбала, БВТ2303
  • Целевая оценка; выбранный трек 5, если нужен: 4, трек 5 не выбран
  • Commit/PR: ...
  • Использованные источники, библиотеки и помощь ИИ: всё из lab3 (FastAPI, uvicorn, pydantic, psycopg 3, argon2-cffi, valkey-py, HAProxy 3.2, PostgreSQL 17, Valkey 8.1) и новое: SeaweedFS 4.44 (S3-сервер), boto3/botocore 1.43.116 (клиент S3), Pillow 13.0.0 (проверка PNG/JPEG). Документация: AWS S3 (PutObject, GetObject, CreateBucket), SeaweedFS (weed server, S3 API, s3.json и действия Read/Write/List:bucket), Pillow (Image.open, verify, draft, MAX_IMAGE_PIXELS). ИИ использовался только как вспомогательный ресурс: для оценки решения, написания комментариев к коду и составления текстовых документов.

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

Проверял на Windows 11 в Git Bash с Docker Desktop. Нужны Docker с Compose, Python 3 (только для тестов, стандартная библиотека) и GNU Make. Образы закреплены: haproxy:3.2.25-alpine, python:3.12.8-slim-bookworm (основа образа API), postgres:17.10-bookworm, valkey/valkey:8.1.9, chrislusf/seaweedfs:4.44. MinIO не использован: его образы удалены с Docker Hub, а на quay.io требуют входа. Перед запуском остановить стенд lab3 (docker compose -p mtusi-lab3 down), иначе занят порт 8080.

git clone https://gitea.privcloud.tech/ng14/mtusi2026lab4.git && cd mtusi2026lab4
git checkout solution/bvt2303-gadzhiev
cp .env.example .env
sed -i 's/\r$//' .env                  # только Windows: убрать \r из .env
sh scripts/init-secrets.sh             # secrets/: пароли PostgreSQL, Valkey, ключи администратора S3, ключи S3 для API, s3_config.json
docker compose up -d --build --wait    # postgres, valkey, s3 -> migrate, s3-init -> 2 реплики api -> lb
make ps                                # api x2, lb, postgres, valkey, s3: healthy; migrate и s3-init: Exited (0)

make check PYTHON=python
make test PYTHON=python
make test-failover ACTION_SCRIPT=scripts/stop-one.cmd PYTHON=python     # Linux/macOS: scripts/stop-one.sh
make restore PYTHON=python
make test-persistence ACTION_SCRIPT=scripts/restart.cmd PYTHON=python  # Linux/macOS: scripts/restart.sh

Свои проверки lab4: make attachments, attachment-failover, failure-s3, orphan-cleanup, s3-checks, upload-memory (на Windows с PYTHON=python). Проверки lab2–lab3 остались: make student-test, failover, persistence, check-stack и др. Все тесты идут через балансировщик http://127.0.0.1:8080.

Bootstrap. Схему БД создаёт одноразовый migrate (миграции 001–005), bucket — одноразовый s3-init (src/messenger/s3bootstrap.py). Пользователи S3 и их права задаются файлом secrets/s3_config.json, его создаёт scripts/init-secrets.sh. Оба запускаются при каждом docker compose up, повторный запуск ничего не ломает. Повторить вручную: docker compose run --rm migrate, make s3-bootstrap. Действие оператора одно: один раз создать секреты (sh scripts/init-secrets.sh), значения не выводятся и не попадают в Git.

Безопасная остановка: make down (volumes pgdata и s3data остаются). Намеренное удаление учебных данных: docker compose down -v, затем rm -rf secrets и снова sh scripts/init-secrets.sh.

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

клиент --> lb: HAProxy, 127.0.0.1:8080 (единственная точка входа)
            +--> api-1 --+--> postgres: пользователи, чаты, сообщения, сессии, МЕТАДАННЫЕ вложений (volume pgdata)
            +--> api-2 --+--> valkey: общий кэш сессий
                         +--> s3: SeaweedFS, приватный bucket messenger-attachments, БАЙТЫ вложений (volume s3data)
migrate и s3-init (одноразовые): схема БД и bucket S3, потом завершаются с кодом 0
сети: edge (lb <-> api), backend internal (api <-> postgres, valkey, s3); наружу опубликован только lb
Роль Сервис Версия Health / готовность Volume Сеть / порт Credentials
Балансировщик lb haproxy:3.2.25-alpine /lb-health нет edge; 127.0.0.1:8080, :8081, :8404 не нужны
API ×2 api образ из Dockerfile /health/ready (PostgreSQL) нет edge + backend, портов нет database_url, cache_url, s3_access_key_id, s3_secret_access_key
Миграции migrate тот же образ код выхода 0 нет backend только database_url
База postgres postgres:17.10-bookworm pg_isready pgdata backend, 5432 POSTGRES_PASSWORD_FILE
Кэш сессий valkey valkey/valkey:8.1.9 valkey-cli ping нет backend, 6379 ACL-файл
S3 s3 chrislusf/seaweedfs:4.44 /healthz на :9000 s3data backend, 9000; master/filer/volume и их веб-интерфейсы только на 127.0.0.1 внутри контейнера s3_config.json (пользователи и права)
Bootstrap S3 s3-init образ API (python -m messenger.s3bootstrap) код выхода 0 нет backend только ключи администратора S3

Источник истины: метаданные — PostgreSQL (таблицы attachments, message_attachments), байты — bucket. Столбца с байтами в БД нет. API хранит оригинал только во временном буфере на время одного запроса (до 1 МиБ в памяти, остальное во временном файле, удаляется в конце запроса). Скачивание идёт через API из S3, поэтому файл отдаёт любая реплика.

Загрузка (src/messenger/attachments.py) и когда возвращается 201:

  1. До чтения тела: токен (401), участник ли чата (404), filename (400), Content-Type (415), Content-Length > 10 MiB (413).
  2. Тело читается кусками, размер и SHA-256 считаются на ходу. Больше 10 MiB — сразу 413, дальше не читаем. Передача дольше 60 с — 400.
  3. Тип по первым байтам должен совпасть с Content-Type (иначе 415). Ширина и высота читаются из заголовка до распаковки: больше 40 млн пикселей — 413. Затем полное декодирование по одной картинке за раз: битый файл — 415.
  4. В БД строка status=pending («намерение»), затем PUT в S3 под случайным ключом originals/<uuid> (его назначает сервер, filename только для показа), затем status=ready и COMMIT. Только после этого 201.

Согласованность БД и S3. Если сбой случился после шага «pending» (S3 недоступен, база не подтвердила ready, реплику убили), остаётся pending-строка и, возможно, объект. Объект сразу не удаляется: COMMIT мог пройти, а потеряться только ответ. Уборщик (src/messenger/cleanup.py) работает в каждой реплике раз в 5 мин и вручную (make cleanup ARGS=--dry-run). Pending-строки старше grace period (15 мин) он удаляет так: сначала объект, потом строку. Объекты без строки старше grace тоже удаляет. Готовые вложения не трогает никогда, готовые без объекта только считает. 15 мин намного больше самой долгой загрузки (~1,5 мин), поэтому идущая загрузка не пострадает. Повторный и параллельный запуск безопасен: удаления идемпотентны.

S3 и права. В s3_config.json два пользователя: администратор (только для s3-init, создаёт bucket) и messenger-api с действиями Read, Write, List только для messenger-attachments. Анонимного пользователя нет, поэтому запрос без подписи получает 403. s3-init создаёт bucket, только если его нет, и проверяет, что анонимный запрос получает 403. Внутренние части SeaweedFS (master :9333, filer :8888, volume :8080 — у master и filer есть веб-интерфейсы) слушают только 127.0.0.1 внутри контейнера, встроенный IAM API выключен. Из сети доступен только S3 API с подписью, на хосте портов S3 нет.

Сообщения: attachment_ids (0–10 уникальных, по умолчанию []). Текст может быть пустым, если есть вложение. Ссылки на вложения пишутся в той же транзакции, что и сообщение. Каждое вложение должно быть готовым вложением этого чата, иначе 404 и откат. Отсутствующий attachment_ids и [] дают одинаковый отпечаток для Idempotency-Key.

Readiness. Критична только PostgreSQL (как в lab3). S3 не критичен: без него не работают только файлы (503), а текстовый мессенджер работает, и реплики остаются в балансировке.

Что перенесено из lab3: весь код, миграции 001–004, свои тесты, Dockerfile, compose.yaml, конфиги HAProxy/Valkey, скрипты. Что изменено: сервисы s3 и s3-init, volume s3data, секреты S3, миграция 005, модули objects.py, images.py, attachments.py, cleanup.py, три адреса вложений в api.py, attachment_ids в store.py, timeout server HAProxy 15 → 30 с (загрузка файла дольше обычного запроса), S3 в hook перезапуска, MALLOC_ARENA_MAX=2 в Dockerfile (по результату эксперимента с памятью).

Новые переменные (остальные как в lab3, см. .env.example):

Переменная Что делает
S3_ENDPOINT, S3_REGION, S3_BUCKET адрес SeaweedFS внутри сети, регион, имя bucket
S3_ACCESS_KEY_ID_FILE, S3_SECRET_ACCESS_KEY_FILE ключи пользователя API (не администратора) в /run/secrets/
MAX_UPLOAD_BYTES, MAX_IMAGE_PIXELS 10 485 760 байт и 40 000 000 пикселей
S3_CONNECT/READ_TIMEOUT_SECONDS, S3_MAX_ATTEMPTS 2 с, 5 с, 2 попытки: недоступный S3 даёт быстрый 503
S3_OPERATION_TIMEOUT_SECONDS общий предел на одну операцию S3 (6 с), включая поиск имени в DNS
UPLOAD_SPOOL_BYTES, UPLOAD_TIMEOUT_SECONDS 1 МиБ в памяти на загрузку, вся передача до 60 с
IMAGE_DECODE_CONCURRENCY, IMAGE_DECODE_WAIT_SECONDS декодирование по 1 картинке, ожидание очереди до 10 с (иначе 503)
ATTACHMENT_GRACE_SECONDS, CLEANUP_INTERVAL_SECONDS grace period 900 с, уборщик раз в 300 с

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

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Публичный smoke make test PASS: lab4 public API scenario (файл, SHA-256, посторонний 404) evidence/test.txt
Структура skeleton и контракт не изменены make check PASS: offline skeleton structure evidence/check.txt
3: возможности lab3 сохранены make student-test; make failover; make persistence все тесты OK; public failover PASS для каждой реплики; persistence PASS evidence/student-test.txt, failover.txt, persistence.txt
3: S3 в общем стенде, версия закреплена, bucket приватный compose.yaml; make check-stack; make s3-checks s3 без портов, веб-интерфейсы SeaweedFS только внутри контейнера, образ chrislusf/seaweedfs:4.44; анонимный GET/список — 403 evidence/stack.txt, evidence/s3-checks.txt
3: метаданные в PostgreSQL, байты в bucket, не в БД и не на API make s3-checks столбцов bytea в attachments нет; объект в S3 с тем же SHA-256; на дисках реплик API копии нет evidence/s3-checks.txt
3: POST вложения — 201 ready после сохранения; оригинал побайтно; участник читает, посторонний — 404 make test; make attachments status=ready, variants=[], SHA-256 и размер совпали; Боб скачал те же байты; Ева — 404 на метаданные и байты evidence/test.txt, evidence/student-test.txt
3: message с attachment_ids читается участниками make attachments (test_message_with_attachments) порядок attachment_ids сохранён, история отдаёт то же; text="" с вложением — 201 evidence/student-test.txt
3: реальные PNG/JPEG ≤10 MiB и ≤40 млн пикселей; MIME по содержимому; опасные filename; лимиты до чтения/декодирования make attachments PNG и JPEG — 201; 10 MiB+1 — 413 сразу по заголовку и при chunked; «бомба» 42 Мп (0,55 МБ) — 413 по заголовку; filename с / \ NUL управляющими — 400 evidence/student-test.txt
3: upload → остановка обслужившей реплики → download через другую make attachment-failover; make failover реплика из X-Instance-Id загрузки остановлена, другая отдала тот же SHA-256; публичный failover тоже читает файл evidence/attachment-failover.txt, evidence/failover.txt
3: restart с сохранением volumes сохраняет метаданные и оригинал make persistence api ×2, postgres, valkey, s3, lb — те же контейнеры, новое время старта; файл и токен на месте evidence/persistence.txt
3: недоступность S3 make failure-s3 S3 остановлен: upload и download — 503 (не 500), метаданные, текст и readiness работают; после запуска файл цел evidence/failure-s3.txt
3: чужой чат make attachments загрузка в чужой чат — 404; чужое вложение — 404 на метаданные и байты evidence/student-test.txt
4: тесты: большой файл, повреждённое изображение, подмена MIME, чужое attachment_id, файл другого чата; без 500 make attachments 13 тестов OK; каждый случай даёт точный код 400/404/413/415 evidence/student-test.txt
4: прерывание загрузки и сбой между S3/БД не оставляют вечных объектов; grace period make orphan-cleanup сбой «PUT прошёл, COMMIT нет» убран (объект и строка); свежие не тронуты до grace; dry-run ничего не удаляет; повтор — no-op; обрыв на трети файла не оставил ни строки, ни объекта evidence/orphan-cleanup.txt
4: лимиты, таймауты, потоковая обработка; ≥10 одновременных загрузок с пиком памяти make upload-memory таблица ниже evidence/upload-memory.json, evidence/upload-memory.txt
4: bootstrap идемпотентен make s3-checks (s3-init ещё 2 раза) оба запуска — код 0, число объектов то же, файл скачивается evidence/s3-checks.txt
4: отдельные S3 credentials с ограниченными правами make s3-checks; make check-stack ключ API читает объект, но create/delete bucket и сделать bucket публичным — отказ, чужих bucket не видит; ключи администратора S3 только у s3-init evidence/s3-checks.txt, evidence/stack.txt
4: консоль не открыта в общей сети; проверка private bucket вне API make s3-checks порты 9333/8888/8080 SeaweedFS закрыты и внутри сети, на хосте порты S3 не опубликованы; анонимный GET объекта — 403 evidence/s3-checks.txt
Выбранный трек 5 — не выбран —

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

Ноутбук: AMD Ryzen 7 4700U, 7,4 ГБ памяти, Windows 11, Docker Desktop. Лимиты: api — 1 CPU и 512 МиБ на реплику, s3 — 0,5 CPU и 512 МиБ. Данные синтетические, их создают сами тесты. Клиент и стенд на одной машине.

Эксперимент с памятью (make upload-memory). Гипотеза: память реплики почти не растёт от числа одновременных загрузок, потому что тело читается кусками (в памяти до 1 МиБ), картинки декодируются по одной, а слишком большой файл отклоняется по заголовку. Методика: перезапуск реплик (чистый счётчик пика), вход пользователей, замер VmHWM (пик RSS процесса) до и после серии, опрос VmRSS во время серии. Профиль A — 12 одновременных PNG по 8,8 МиБ (случайные пиксели 1800×1700). Профиль B — 12 одновременных запросов, заявляющих 11 МиБ.

Первый прогон (без MALLOC_ARENA_MAX, evidence/upload-memory-arena-default.json): все 12 файлов приняты, SHA-256 совпали, но пик RSS каждой реплики вырос на 103–106 МиБ (95 → 198–201 МиБ). Это больше, чем сами тела загрузок (6 × 8,8 = 53 МиБ). Значит, гипотеза в первой версии не подтвердилась. Причина — распределитель памяти glibc: у каждого потока своя «куча» (arena), и освобождённая после загрузки память другим потокам не достаётся. Отдельная проверка на одной реплике вне стенда (6 одновременных загрузок по 8,8 МиБ): рост пика 111 МиБ без настройки и 31 МиБ с MALLOC_ARENA_MAX=2. Настройка добавлена в Dockerfile, ниже повторный прогон с ней. Профиль B (11 МиБ) в обоих прогонах — 413 без роста памяти (0–1,2 МиБ).

Профиль A: 12 одновременных PNG по 8.8 МиБ за 7.3 с, все 201, SHA-256 совпали при скачивании; профиль B: 12 одновременных по 11 МиБ за 0.06 с, все 413. Лимит памяти реплики 512 МиБ. Сырые данные: evidence/upload-memory.json.

Реплика Загрузок A RSS до, МиБ Пик RSS до → после A, МиБ Рост пика, МиБ Тела целиком в памяти были бы, МиБ Рост пика от B (11 МиБ ×12), МиБ memory.peak cgroup, МиБ
81410605dad3 6 95.1 95.1 → 131.0 35.9 52.6 0.0 None
ccaea065f01a 6 97.2 97.2 → 130.8 33.6 52.6 0.0 None

Вывод: с MALLOC_ARENA_MAX=2 рост пика на реплику 34–36 МиБ вместо 103–106 МиБ (примерно в 3 раза меньше) и меньше суммы самих тел (53 МиБ). Гипотеза подтвердилась: память ограничена буфером 1 МиБ на загрузку, одной декодируемой картинкой и служебными буферами, а не размером и числом файлов. До лимита 512 МиБ большой запас. Отклонённые 11 МиБ получили 413 за 0,06 с без роста памяти. Столбец memory.peak пуст: этот файл cgroup недоступен в Docker Desktop, поэтому пик взят по VmHWM процесса.

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
docker stop реплики, принявшей файл другая реплика отдаёт тот же файл тот же SHA-256 через другую реплику сразу; потерь нет
docker compose stop s3 файлы — 503, текст работает upload/download 503 не дольше 6 с (общий предел на операцию S3), текст, история и readiness — 200 после start s3 файл снова скачивается через ~13 с (время запуска SeaweedFS); потерь нет
Перезапуск всего стенда с volumes файл и метаданные на месте persistence PASS, тот же файл с прежним токеном время — в evidence/persistence.txt; потерь нет
«PUT прошёл, COMMIT ready нет» (созданное состояние) уборщик убирает после grace объект и строка удалены, готовые на месте один запуск уборщика; неучтённых объектов нет
Клиент оборвал загрузку ничего не сохраняется ни строки, ни объекта сразу
Файл > 10 MiB, «бомба» 42 Мп 413 до чтения/декодирования 413, память не растёт (профиль B) —

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

  • Всё на одном узле: SeaweedFS в одном экземпляре без репликации (replication 000), PostgreSQL и HAProxy тоже по одному. Выдерживается отказ одной реплики API.
  • Состояние «PUT прошёл, COMMIT нет» в тесте создаётся напрямую (pending-строка часовой давности и объект), а не настоящим падением базы в нужную миллисекунду. Это то же состояние, которое остаётся после сбоя.
  • Готовое вложение без объекта (missing) уборщик только считает и пишет в лог: байты не восстановить. Полный reconciler с отчётом и dry-run для обеих сторон — это трек 2 на «5».
  • Временный буфер загрузки лежит на диске контейнера API до конца запроса. Это не хранилище: после ответа его нет, и скачивание идёт только из S3.
  • Подписанных URL (presigned) нет, вся передача идёт через API. Ограничения частоты (429) нет.
  • Сначала был выбран MinIO, но его образы удалены с Docker Hub, а на quay.io требуют входа. Перешёл на SeaweedFS 4.44. API это не затронуло: он использует обычный протокол S3, поменялись только сервисы s3 и s3-init.