25 KiB
Отчёт — лабораторная 4
- Автор, группа: Саватеев Артём, группа TODO
- Целевая оценка: 4; трек 5 не заявлен
- Commit/PR: TODO после публикации (ветка
feature/lab4-core-logic) - Использованные источники, библиотеки и помощь ИИ: FastAPI, asyncpg, redis-py, aiobotocore 3.9.1 (S3-клиент), Pillow 12.3.0 (проверка изображений), SeaweedFS 4.48 (S3-сервер); документация S3 API и SeaweedFS (identities,
-s3.config)
Запуск из чистого clone
Prerequisites: Docker Engine 29 / Compose v2.40, Python 3.12 + Poetry 2.2 (для собственных тестов), Python 3.9+ (публичные тесты)
| Компонент | Образ / версия |
|---|---|
| API, migrate, s3-bootstrap, janitor | mtusi-messenger:lab4 из Dockerfile (python:3.12.12-slim-bookworm) |
| PostgreSQL | postgres:18.2-alpine3.22 |
| Valkey | valkey/valkey:8.1.4-alpine3.22 |
| S3 | chrislusf/seaweedfs:4.48 |
| LB | nginx:1.28.0-alpine3.21 |
make init # .env из .env.example + секреты в secrets/ (повторный запуск ничего не меняет)
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --wait
# порядок: postgres, valkey, s3 → migrate (миграции) и s3-bootstrap (bucket)
# → api ×2, janitor → nginx; --wait ждёт healthy всех сервисов
make test # публичный smoke
make install && make student-test # собственные unit + black-box тесты
make test-storage # приватность bucket, права ключей, сверка janitor
make test-failures # отказы PostgreSQL/Valkey/S3 и реплики, принявшей файл
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh && ./scripts/restore.sh
make experiment-uploads # ≥10 одновременных загрузок, пик памяти → evidence/
make test-migrations # миграции с пустого volume (отдельный compose-проект)
Безопасная остановка: make down (volumes сохраняются). Намеренное удаление учебных данных: make destroy-data (down -v: PostgreSQL и S3). Секреты: scripts/init-secrets.sh создаёт secrets/ (в .gitignore), значения не печатает и не перезаписывает — иначе объекты bucket станут недоступны. Оператору больше ничего делать не нужно: bucket создаётся сервисом s3-bootstrap автоматически.
Если порт 8080 занят другим стендом (например, lab3), задайте LB_PORT в .env и BASE_URL=http://localhost:<порт> для тестов.
Архитектура и решения
клиент → nginx (edge) → api ×2 ─┬─ backend: PostgreSQL (метаданные, источник истины), Valkey (кэш сессий)
└─ storage: SeaweedFS S3 (байты оригиналов, приватный bucket)
janitor (backend + storage): сверка S3/БД
migrate, s3-bootstrap: одноразовые, до старта API
Перенесено из lab3 без изменений: пользователи, сессии (PostgreSQL + Valkey), чаты, история, Idempotency-Key, 2 реплики за nginx, graceful shutdown, X-Instance-Id, скрипты отказов. Изменено: сообщение получило attachment_ids (пустой текст разрешён только с вложениями); hash идемпотентности считается без полей по умолчанию, поэтому для текстовых сообщений он совпадает с lab3. Попутно исправлен Makefile lab3: потерянная строка цели test-expiry.
Слои (как в lab3): domain (схемы, ошибки) → interfaces (абстракции AttachmentRepository, ObjectStorage) → infrastructure (PostgreSQL/S3 реализации, AttachmentService, StorageReconciler, ImageInspector) → application (FastAPI endpoints). Сервисы зависят только от интерфейсов, поэтому отказы S3/БД проверяются unit-тестами на фейках.
Хранилище. MinIO не выбран: образы minio/minio и minio/mc больше не скачиваются из Docker Hub/quay, стенд не собрался бы из чистого clone. SeaweedFS 4.48 запускается одним контейнером weed server:
- master/volume/filer и их веб-интерфейсы слушают только
127.0.0.1внутри контейнера; в сетьstorageоткрыт лишь S3 API:9000. Порты наружу не публикуются, сетьstorage—internal, в неё входят только api, janitor, s3-bootstrap. - Identities (
secrets/s3_identities.json):bootstrap(Admin) — только уs3-bootstrap;messenger-api—Read/Write/Listтолько своего bucket — у API и janitor. Identityanonymousнет, поэтому любой неподписанный запрос получает 403. s3-bootstrapидемпотентен:CreateBucketс обработкойBucketAlreadyOwnedByYou, затем проверяет, что анонимный запрос получает 403. Иначе завершается ошибкой, и API не стартует.
Модель данных (migrations/0003_attachments.sql): attachments (метаданные + object_key + status pending/ready/deleting), message_attachments (порядок вложений). Составные FK гарантируют на уровне БД, что владелец — участник чата, а вложение и сообщение принадлежат одному чату. Используемое вложение удалить нельзя (FK без CASCADE). Ключ объекта originals/<128 бит random> назначает сервер; filename — только отображение.
Загрузка POST /chats/{id}/attachments (сырые байты):
- Аутентификация → членство в чате (404) → filename (400) → Content-Type (415) → Content-Length > 10 MiB (413). Всё это до чтения тела.
- Тело читается потоком: первые 1 MiB в RAM, остальное во временный файл запроса, который удаляется сразу. Чтение обрывается на байте 10 MiB+1 (413). SHA-256 считается по ходу.
ImageInspectorв пуле изIMAGE_INSPECT_WORKERSпотоков: формат по сигнатуре (подмена MIME → 415); размеры из заголовка до распаковки (> 40 Мпикс → 413); целостность: PNG — CRC всех chunk и IEND, JPEG — декодирование libjpeg в draft-режиме 1/8 (повреждено → 415).- Запись: строка
pending(COMMIT) → одинPUTв S3 сx-amz-checksum-sha256(S3 сверяет байты) →pending → ready→ 201. 201 возвращается только когда оригинал в S3 и метаданные подтверждены. PUT + подтверждение ограниченыATTACHMENT_STORE_TIMEOUT_SEC=30.
Скачивание — только через API, без redirect: проверка участника (чужое/неизвестное/незавершённое — одинаковый 404), затем поток из S3 по 64 KiB с истинным Content-Type, Content-Length, X-Content-Type-Options: nosniff, Content-Disposition (RFC 5987). Случайный ключ и приватный bucket не заменяют ACL: ключ мог бы утечь через логи или бэкап, а доступ к файлу определяется членством в чате, которое знает только приложение.
Согласованность S3 ↔ PostgreSQL (уровень 4). Инвариант: у каждого объекта под originals/ есть строка. Строка коммитится до PUT, а удаляется только после удаления объекта.
- Сбой после записи строки (S3 PUT упал или неизвестен, COMMIT
readyне прошёл, таймаут, отмена задачи при остановке реплики) компенсируется сразу:pending → deleting→DeleteObject→DELETEстроки. Строку сначала забирают: если UPDATE вreadyна самом деле прошёл, claim не сработает, и объект готового вложения уцелеет. - Если компенсация не удалась (S3/БД недоступны, процесс убит), остаётся строка
pendingилиdeleting. Её дочищает janitor (src/janitor.py, отдельный сервис, раз в 60 с):pendingстаршеATTACHMENT_PENDING_GRACE_SEC=900атомарно переводится вdeleting(FOR UPDATE SKIP LOCKED), затем удаляется объект (идемпотентно), затем строка. Прерванная очисткаdeletingповторяется при следующем проходе. - Безопасность grace period: API подтверждает только строку моложе grace (
created_at > now() - graceпо часам БД), janitor забирает только старше grace. Граничную гонку сериализует блокировка строки. Загрузка длится ≤ 30 с + проверка, что на порядки меньше 900 с. - Второй проход janitor — сверка bucket: объекты без строки старше grace удаляются. При соблюдении инварианта их нет; проход проверяет инвариант и страхует, например, от восстановления БД из старой копии. Свежие объекты и любые
readyне трогаются.--dry-runтолько отчитывается. - «S3 PUT прошёл, COMMIT нет»: объект учтён строкой
pending. Клиент получил 503 и id не знает. Компенсация удалит объект сразу, а если не сможет — janitor через ≤ grace + интервал.
Readiness = PostgreSQL + S3 (head_bucket с таймаутом 2 с): с lab4 вложения входят в обязательный синхронный путь. Valkey не критичен, как и раньше. При падении S3 реплика честно отвечает 503 на /health/ready. nginx не исключает реплики по readiness, поэтому сообщения, сессии и метаданные продолжают работать, а загрузка и скачивание отвечают быстрым 503.
Лимиты памяти по всей цепочке: nginx (proxy_request_buffering off на upload, client_max_body_size 11m: тело 10 MiB+1 отклоняет сама реплика с 413 по контракту), API (spool 1 MiB RAM на загрузку, проверка изображений в 1 потоке на реплику, лимит контейнера 512M), SeaweedFS (-s3.concurrentUploadLimitMB=128, GOMEMLIMIT=384MiB, лимит 512M). Последние два пункта — исправления по итогам эксперимента (см. ниже).
Переменные .env.example → конфигурация: S3_ENDPOINT/REGION/BUCKET → клиент aiobotocore (path-style); S3_ACCESS_KEY_ID_FILE/S3_SECRET_ACCESS_KEY_FILE → compose secrets /run/secrets/* у api и janitor; S3_ADMIN_*_FILE → только у s3-bootstrap; MAX_UPLOAD_BYTES, MAX_IMAGE_PIXELS → лимиты контракта; UPLOAD_SPOOL_MEMORY_BYTES, IMAGE_INSPECT_WORKERS → память на загрузку; S3_CONNECT/READ_TIMEOUT_SEC, S3_MAX_ATTEMPTS, ATTACHMENT_STORE_TIMEOUT_SEC → ограниченное время ответа; ATTACHMENT_PENDING_GRACE_SEC, JANITOR_INTERVAL_SEC → janitor.
Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|---|---|---|---|
| Публичный smoke | make test |
PASS: lab4 public API scenario | evidence/tests.txt |
| Lab3 сохранена | make student-test |
187 passed, 16 skipped (явные отказы и expiry запускаются своими целями) | evidence/tests.txt |
| S3 в стенде, метаданные в PG, байты в приватном bucket | compose.yaml, test_storage_security.py, test_attachments.py::test_public_api_does_not_expose_storage_details |
Объекты только в SeaweedFS (volume s3_data), на API нет volume. Ответ API не раскрывает ключ, bucket и адрес |
evidence/tests.txt |
| 201 ready, побайтный download, checksum, посторонний 404 | test_attachments.py (PNG fixture, JPEG baseline/progressive) |
SHA-256 и байты совпадают у второго участника; посторонний и неизвестный id — одинаковый 404 | evidence/tests.txt |
Сообщение с attachment_ids |
test_message_attachments.py |
Читается участником, порядок сохранён, text="" с вложением → 201 |
evidence/tests.txt |
| PNG/JPEG ≤ 10 MiB, ≤ 40 Мпикс, MIME по содержимому, опасные имена | test_attachments.py |
Ровно 10 485 760 байт → 201, +1 → 413 от API; 8000×5000 → 201, 8000×5001 → 413 (файл < 1 MiB, лимит до распаковки); 13 опасных filename → 400 | evidence/tests.txt |
| Failover upload → download | test_attachment_failover.py, make test-failover ×2 |
UPLOADED BY 5a67…, DOWNLOADED FROM [da68…]; публичный: 0 ошибок, восстановление записи 2.06 с и 1.62 с |
evidence/failures.txt, evidence/failover.txt |
| Restart с volumes | make test-persistence ACTION_SCRIPT=scripts/restart.sh |
PASS; uptime всех 7 контейнеров сброшен | evidence/persistence.txt |
| 4: слишком большой файл, повреждённое, подмена MIME, чужое id, файл другого чата, без 500 | test_attachments.py, test_message_attachments.py |
413 / 415 (6 видов повреждений, 9 видов подмены) / 404 / 404, сообщение не создаётся; каждый ответ проверен assert_not_server_error |
evidence/tests.txt |
| 4: обрыв загрузки и отказ между S3/БД | student-tests/unit/test_unit_attachment_service.py (8 сценариев отказа на фейках), test_storage_consistency.py (стенд), test_storage_failures.py |
Во всех сценариях итог — ни объектов, ни строк. На стенде janitor удалил 2 «упавшие» загрузки и 1 сироту, свежие и ready сохранены. Обрыв тела прямо в реплике — 0 строк |
evidence/tests.txt, evidence/failures.txt |
| 4: RAM ограничена, ≥ 10 одновременных загрузок | make experiment-uploads |
см. раздел «Эксперименты» | evidence/experiment-uploads.json |
| 4: идемпотентный bootstrap, отдельные ограниченные ключи, консоль закрыта, private bucket вне API | make test-storage (test_storage_security.py) |
2 запуска bootstrap: «уже существует», «приватен»; API-ключ: put/get/delete своего bucket — да, CreateBucket/DeleteBucket/PutBucketPolicy/PutBucketAcl — AccessDenied; у API нет админ-ключей; порты 9333/8888/8080/19333/18888/18080/8181/9101 закрыты; анонимный GET объекта, списка и сервиса — 403; nginx не видит S3 |
evidence/tests.txt |
| Миграции с нуля | make test-migrations |
0001–0003 применяются; 3 повторных запуска идемпотентны; API без migrate не стартует | вывод команды |
Эксперименты и отказы
Гипотеза: память API на загрузку ограничена (spool 1 MiB, потоковый PUT/GET, 1 поток декодирования на реплику), поэтому пик RSS не растёт как N × размер файла.
Методика (scripts/upload_experiment.py): 2 API-реплики (1 CPU / 512M каждая), Docker Desktop VM 10 CPU / 7.7 GiB, macOS arm64. Перед каждым раундом реплики перезапускаются, затем прогрев. N загрузок стартуют по одному барьеру через nginx. Память опрашивается внутри контейнеров каждые 0.2 с (VmRSS процесса, cgroup memory.current), плюс VmHWM. После раунда один файл скачивается и сверяется по SHA-256. Профили: PNG 9.19 MB из шума (приём тела, spool, S3) и progressive JPEG 8000×5000 = 40 Мпикс, 4.98 MB (худший случай декодера). Один прогон на точку, 2026-10-20.
| Профиль | N | 201 | p50 / p95 / max, с | RSS до → пик, МиБ (реплика 1 / 2) | cgroup пик, МиБ |
|---|---|---|---|---|---|
| PNG 9.19 MB | 10 | 10/10 | 2.01 / 2.09 / 2.09 | 99 → 122 / 126 | 153 / 166 |
| PNG 9.19 MB | 20 | 20/20 | 3.46 / 3.88 / 3.89 | 99 → 124 / 126 | 215 / 216 |
| PNG 9.19 MB | 30 | 30/30 | 4.62 / 4.98 / 7.21 | 99 → 127 / 142 | 255 / 280 |
| JPEG 40 Мпикс | 10 | 10/10 | 0.96 / 1.42 / 1.42 | 99 → 334 / 333 | 338 / 338 |
| JPEG 40 Мпикс | 20 | 20/20 | 1.77 / 2.59 / 2.74 | 94 → 336 / 336 | 362 / 362 |
| JPEG 40 Мпикс | 30 | 30/30 | 2.98 / 6.64 / 6.64 | 99 → 338 / 340 | 391 / 393 |
Выводы. При 15 одновременных PNG на реплику (135 МиБ данных) RSS вырос лишь на 28–43 МиБ. Пик для худшего JPEG (~335 МиБ, буфер коэффициентов libjpeg, ~6 Б/пиксель) не зависит от N: декодирование сериализовано одним потоком, остальные загрузки ждут в очереди, растёт только задержка. Рост cgroup сверх RSS — page cache временных файлов spool, он вытесняемый. Ни одного OOM.
Что эксперимент нашёл и что исправлено:
- Первый прогон: при N = 10 PNG соединения обрывались. В
memory.eventsnginxoom_kill 4: сproxy_request_buffering onnginx складывал тела во временные файлы, и грязный page cache выходил за лимит 64M. Исправлено отключением буферизации на upload-location: тело идёт потоком в API, где память на загрузку ограничена. - Затем при N = 20 все ответы 503. dmesg:
Killed process (weed) anon-rss:459380kB, SeaweedFS держал тела в Go-куче. Исправлено-s3.concurrentUploadLimitMB=128,-volume.concurrentUploadLimitMB=128,GOMEMLIMIT=384MiB. Сверх лимита запросы ждут. После исправлений: N = 10/20/30 — 100 % успешно.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|---|---|---|---|
| Остановка реплики, принявшей файл | Download через другую, тот же SHA-256 | 10/10 скачиваний с другой реплики, байты совпадают | Без перерыва / нет |
stop-one.sh под записью сообщений (×2) |
Восстановление ≤ 10 с, без дублей | 0 ошибок, 130 и 129 записей, 2.06 с и 1.62 с | ≤ 2.1 с / нет |
| Restart всего стенда с volumes | Данные, файл и прежний токен целы | PASS | ≈ 30 с (SeaweedFS останавливается ~25 с) / нет |
| Остановка S3 | Upload/download 503 < 6 с, сообщения и метаданные работают, ready 503 | Так и есть. Компенсация не смогла удалить объект → строка deleting → janitor дочистил |
Сразу после старта S3 / нет |
| Падение API между PUT и COMMIT (внедрено в БД/S3) | janitor удаляет после grace, свежие и ready не трогает |
unfinished 2, orphans 1 удалены; свежие пережили первый проход и удалены вторым |
grace + интервал / нет |
| Обрыв тела загрузки прямо в реплике | Ни строк, ни объектов | 0 строк; API журналирует 400 «Загрузка прервана клиентом» | Мгновенно / нет |
| PostgreSQL / Valkey (из lab3) | 503 ограниченно по времени / обход кэша | 4 passed | — |
Ограничения и следующие шаги
- Не выдерживается: потеря Docker-host. Единственные экземпляры PostgreSQL, SeaweedFS (один volume-сервер без репликации) и nginx — точки отказа. HA хранилищ не заявляется.
- PNG проверяется по структуре и CRC без распаковки IDAT: файл с корректными CRC, но испорченным zlib-потоком будет принят. Полное декодирование появится в lab5 у worker (статус
failed). JPEG декодируется в draft-режиме, это проверяет весь поток данных. - Худший случай памяти на реплику ≈ 100 МиБ база + ~240 МиБ (один progressive JPEG 40 Мпикс) + 1 МиБ × число загрузок.
IMAGE_INSPECT_WORKERS > 1требует соразмерно поднять лимит контейнера. - Slow-client: после отключения буферизации nginx медленная загрузка держит в API корутину (не поток) до
client_body_timeoutnginx (10 с между чтениями). Отдельного глобального лимита одновременных загрузок на реплику нет: их ограничивают пул SeaweedFS и таймауты. - Grace period 15 мин означает, что объект упавшей загрузки может занимать место до ~16 мин. Это осознанный компромисс в пользу безопасности.
- Эксперимент — по одному прогону на точку на ноутбуке. Числа задержек не переносятся на другую машину, переносимы выводы о форме роста памяти.
- Перед сдачей: повторить
make test-failuresиmake test-persistenceна финальной конфигурации. Последний повтор (12:32–12:33) недействителен: стенд lab4 был остановлен извне, и порт 8080 занял стенд lab3. Подробности вevidence/*.txt.