26 KiB
Отчёт — лабораторная 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:
- До чтения тела: токен (401), участник ли чата (404),
filename(400),Content-Type(415),Content-Length> 10 MiB (413). - Тело читается кусками, размер и SHA-256 считаются на ходу. Больше 10 MiB — сразу 413, дальше не читаем. Передача дольше 60 с — 400.
- Тип по первым байтам должен совпасть с
Content-Type(иначе 415). Ширина и высота читаются из заголовка до распаковки: больше 40 млн пикселей — 413. Затем полное декодирование по одной картинке за раз: битый файл — 415. - В БД строка
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.