30 KiB
Отчёт — лабораторная 5
- Автор, группа: Кушнаренко Николай Вячеславович, БПИ2302
- Целевая оценка; выбранный трек 5, если нужен: 5, трек 1 «Очередь под перегрузкой»
- Commit/PR: PR №52, ветка
solution/bpi2302-kushnarenkoиз форка kolya вmtusi2026/mtusi2026lab5:main; проверенная базовая реализация —5dbb905. - Использованные источники, библиотеки и помощь ИИ: Python 3.12, uvicorn, asyncpg, aiobotocore, aio-pika (RabbitMQ), Pillow (обработка изображений); RabbitMQ 4.1.8, SeaweedFS 4.48, PostgreSQL 17, Valkey 8, HAProxy 3.0. Код lab4 перенесён. ИИ-ассистенты использовались для помощи с кодом, тестами и отчётом; Codex проверил подготовку к сдаче, исправил перенос reconciler, усилил методику исследования и выполнил реальные запуски 12.11.2026
Запуск из чистого clone
Prerequisites: Docker Compose v2, bash (Git Bash на Windows), Python ≥ 3.9; на Windows PYTHONUTF8=1.
Версии: python:3.12.12-slim-bookworm@sha256:593bd06e…, postgres:17.11-alpine@sha256:b0f9560a…, valkey/valkey:8.1.10-alpine@sha256:081c2f5c…, haproxy:3.0-alpine@sha256:56b887da…, chrislusf/seaweedfs:4.48@sha256:4e61d15f…, rabbitmq:4.1-alpine@sha256:6a0f7984… (4.1.8), зависимости — requirements.txt (закреплены).
sh scripts/init-secrets.sh # secrets/*: БД, S3 (admin + ключи API), RabbitMQ (rabbitmq.conf, broker_url)
cp .env.example .env
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --wait --wait-timeout 120 # postgres, valkey, seaweedfs, rabbitmq -> migrate + s3-init -> api x2, worker -> lb
curl http://127.0.0.1:8080/health/ready
python3 tests/smoke.py --base-url http://127.0.0.1:8080 # upload -> 202 -> ready -> thumbnail 256x160
python3 tests/resilience.py --mode persistence --action-script scripts/restart.sh --base-url http://127.0.0.1:8080
python3 tests/resilience.py --mode failover --action-script scripts/stop-one.sh --base-url http://127.0.0.1:8080
sh scripts/restore-replicas.sh
# собственные тесты
python3 -m unittest discover -s student-tests -p "test_api.py" -v # + test_idempotency.py, test_attachments.py
python3 student-tests/test_pipeline.py # Pillow желателен (пиксельные проверки)
python3 student-tests/test_resilience5.py # семь окон отказа
python3 student-tests/test_reconcile5.py # варианты и staging не удаляются
python3 student-tests/test_expiry.py
python3 student-tests/test_dependencies.py
# операторские команды
docker compose --env-file .env run --rm -T worker python -m app.replay list
docker compose --env-file .env run --rm -T worker python -m app.replay replay <attachment_id>
Windows: scripts/restart.cmd, scripts/stop-one.cmd. Остановка с сохранением данных — docker compose --env-file .env stop; намеренное удаление учебных данных — down -v (volumes pgdata, valkeydata, seaweeddata, rabbitmqdata). Учётные данные RabbitMQ задаются конфигурационным файлом-секретом secrets/rabbitmq.conf; hostname контейнера фиксирован (rabbitmq), иначе очередь не переживает пересоздание контейнера.
Архитектура и решения
Клиент ─▶ LB ─▶ API ─┬─(1) staging в S3 (приватный prefix staging/)
└─(2) ОДНА транзакция PostgreSQL: attachments(status=queued) + outbox ──▶ 202 queued
outbox ──relay (в API и worker, SKIP LOCKED)──▶ RabbitMQ (quorum, persistent, publisher confirm) ──▶ worker
worker: claim(queued→processing, lease) → staging → thumbnail/crop/WebP → S3 att/<id>/… → ОДНА транзакция: варианты + ready → ack → очистка staging
Все сервисы находятся в сети Compose backend; наружу опубликован только LB. Полные digest перечислены в compose.yaml и Dockerfile.
| Роль → service name | Образ / ресурсы | Health/readiness | Volume | Порт | Credentials |
|---|---|---|---|---|---|
API → api × 2 |
собственный образ, Python 3.12.12; по 1 CPU / 256 MiB | /health/ready, отдельно /health/live |
нет локального состояния | 8080, только backend | файловые secrets database_url, S3, broker_url |
БД → postgres |
PostgreSQL 17.11; 1 CPU / 512 MiB | pg_isready |
pgdata |
5432, backend | postgres_password; клиентам database_url |
Кэш сессий → valkey |
Valkey 8.1.10; 0.5 CPU / 128 MiB | valkey-cli ping |
valkeydata, AOF |
6379, backend | отдельного пароля нет; не опубликован на host |
S3 → seaweedfs |
SeaweedFS 4.48; 1 CPU / 768 MiB | master cluster status + S3 socket; restart hook дополнительно читает объекты | seaweeddata |
8333 и внутренние служебные порты, backend | seaweed_s3_config; admin только для bootstrap, API-ключ ограничен bucket |
Брокер → rabbitmq |
RabbitMQ 4.1.8; 1 CPU / 512 MiB | rabbitmq-diagnostics ping |
rabbitmqdata |
5672, backend | rabbitmq_conf; клиентам broker_url |
Worker → worker |
собственный образ, Python 3.12.12; 1 CPU / 768 MiB | heartbeat-файл моложе 30 с | нет локального устойчивого состояния | нет слушающего порта | файловые secrets БД/S3/брокер |
Балансировщик → lb |
HAProxy 3.0; 1 CPU / 128 MiB | внутренний :8081/healthz; backend checks API |
конфигурация read-only | 127.0.0.1:8080 | credentials не нужны |
Bootstrap: init-secrets.sh создаёт недостающие локальные файлы без перезаписи; migrate применяет версионные SQL-миграции; s3-init создаёт bucket при отсутствии и проверяет права; API/worker идемпотентно объявляют durable RabbitMQ topology. Повтор s3-init проверен дважды. Секреты и volumes не переносятся из предыдущей лабораторной. .gitattributes сохраняет LF в shell hooks при Windows clone.
- Границы приёма (до 202): байты проверены (формат, целостность, размеры) и записаны в устойчивый staging (приватный S3-prefix
staging/<id>, не локальный диск); метаданные и намерение обработки записаны одной транзакцией PostgreSQL (таблицыattachmentsиoutbox). Только после COMMIT клиент получает202со снимкомstatus=queued. Если брокер недоступен — это не мешает приёму: задание остаётся в outbox и публикуется позже. HTTP-передача байт клиентом по-прежнему синхронна (честная граница: staging уже в S3). - Состояния и переходы (
contracts/attachment-states.md):queued → processing → ready | failed;processing → queuedпри временной ошибке (backoff) и при истечении lease (sweeper);failed → queuedтолько явным операторским replay. Повторная доставка готовой задачи — no-op с ack; завершённое состояние не откатывается дубликатом. Условия UPDATE (status='queued',lease_owner=…) исключают конкурирующую запись. - Задание в брокере (
jobs.schema.json): толькоschema_version, job_id, type, attachment_id, pipeline_version, attempt, created_at— без байт, ключей S3 и credentials; worker берёт доверенные метаданные (ключи, тип) из БД.job_idне меняется при redelivery;attempt— управляемая попытка. - Доставка и подтверждения: durable quorum-очередь
attachment.process, persistent-сообщения, publisher confirm (подтверждение приёма брокером) → только затемpublished_atв outbox; ack consumer — только после COMMIT результата (устойчивый эффект). Это разные границы. Доставка at-least-once; эффект идемпотентен: ключ(attachment_id, pipeline_version, name)(PKattachment_variants,ON CONFLICT DO NOTHING), детерминированные ключи объектов S3. - Обработка (
src/app/pipeline.py): thumbnail — JPEG, вписан в 256×256 без увеличения, EXIF-ориентация применяется, alpha на белый, размеры округляются вниз (320×200 → 256×160), quality 85, метаданные не сохраняются; crop — JPEG, центрированный квадрат 128×128 (мелкие допускается увеличивать); optimized — WebP, вписан в 1280×1280 без увеличения,quality=80, method=4, EXIF/ICC не сохраняются, прозрачность сохраняется.size_bytes/sha256/content_typeвложения всегда описывают оригинал; у вариантов — свои поля. Готовность (ready) ставится после сохранения оригинала и всех вариантов. - Лимиты обработки: API отклоняет файл >10 MiB (413) и >40 млн пикселей (413) до распаковки; worker — таймаут задания 45 с (
JOB_TIMEOUT), число пикселей,WORKER_CONCURRENCY(= prefetch = число потоков), лимит памяти контейнера 768 MiB; JPEG >2560×2560 декодируется сразу в масштабе 1/2. - Retry: ограниченное число попыток
MAX_ATTEMPTS=5; временные ошибки (S3/БД/таймаут) →queued+ новая запись outbox с отложенной публикацией; задержка — экспоненциальный backoff с jitter (случайное значение в [50 %, 100 %] отmin(60 с, 2 с × 2^(n−1))); постоянные ошибки (нечитаемое изображение) → сразуfailedсerror_code(invalid_image,image_too_large,processing_failed); исчерпание попыток →failed/retry_exhausted. - Реестр failed и DLQ: реестр — таблица
attachmentsсоstatus=failed+job_events(журнал событий, без секретов);python -m app.replay list. Нечитаемые сообщения брокера (schema_version, типы) отправляются в DLQattachment.process.deadчерез DLX. Replay (python -m app.replay replay <id>) допускается только дляfailed(иначеskipped): новая попытка, новыйjob_id, записьoperator_replayвjob_events; повторное исполнение уже успешной работы невозможно. - Lease и зависшие задачи: при захвате задание получает lease (
LEASE_SECONDS=60); sweeper worker возвращает просроченныеprocessingвqueued(илиfailed/retry_exhausted); публиковать результат может только владелец lease (FOR UPDATE+ проверка владельца). - Outbox (уровень 4): relay в API и worker читает
FOR UPDATE SKIP LOCKED; после краха между COMMIT и publish задание публикуется автоматически (проверено). Повторная публикация после краха между confirm иpublished_atдаёт дубликат, обрабатываемый как no-op. - Очистка staging: удаляется после COMMIT результата; для
failedхранитсяSTAGING_FAILED_RETENTION_SECONDS(7 суток) для разбора/replay; фоновая очистка не затрагивает текущую работу. - Backpressure: перед приёмом тела API проверяет число активных заданий; при
queued+processing ≥ MAX_QUEUED_JOBS—503 unavailable+Retry-After(контракт допускает 503). Readiness API не зависит от брокера и worker (их отказ не должен останавливать приём/чтение).
Исправления при подготовке к сдаче — 12.11.2026
Перенесено исправление HAProxy из ЛР4: когда общая БД недоступна и все API теряют readiness, резервный backend по liveness позволяет приложению вернуть контрактный JSON, Retry-After и X-Request-Id; /health/live остаётся доступен. Автоматический retry HAProxy ограничен ошибкой установления соединения, чтобы повтор уже отправленного upload POST не создавал лишнюю загрузку. Восстановлены собственные проверки TTL, PostgreSQL и Valkey.
Исправлен опасный перенос reconciler из ЛР4. Старый dry-run считал три готовых варианта осиротевшими, поскольку учитывал только attachments.s3_key; вывод до исправления сохранён в reconcile_before_fix.json. Теперь учитываются метаданные вариантов, staging и владелец серверного префикса att//… . Объект внутри префикса существующего вложения защищён даже до COMMIT метаданных worker. Перед удалением перепроверяются references и владелец. Такой подход консервативен: неизвестный объект внутри существующего вложения остаётся до отдельного операторского разбора.
Для staging можно явно выполнить docker compose run --rm -T api python -m app.reconcile --prefix staging/ (dry-run). Рабочий grace по умолчанию 900 с; --apply включает исправление. В тестах grace=0 применяется только к созданным тестом префиксам после окончания записи. Staging принятой задачи не удаляется; корректные оригинал и варианты не становятся failed. Очистку staging после ready и по retention для failed по-прежнему выполняет worker.
Повторный dry-run того же вложения после исправления: reconcile_after_fix.json — четыре объекта, orphan/missing/size mismatch = 0, изменений нет.
Доказательства критериев
Текущий skeleton — 276dbda. README, COURSE, CONTRIBUTING, публичные tests/ и contracts/ сохранены без изменений. В Windows запущены Python-команды, соответствующие make check, make validate и make test. Полный реальный вывод — checks_2026-11-12.txt; команды всех собственных тестов — student-tests/README.md.
| Проверка | Результат |
|---|---|
| check_contract, полная OpenAPI-валидация, публичный smoke | PASS; upload → 202 queued → ready; original и JPEG thumbnail проверены |
| API и аутентификация | 12 тестов OK |
| Идемпотентность и несколько API-реплик | 9 тестов OK |
| Изображения, лимиты, MIME, filename, ACL, private bucket, прерывание upload | 11 тестов OK |
| Топология, порты, лимиты, непривилегированный пользователь | 6 тестов OK |
| Варианты, EXIF, alpha, размеры, оригинал, redelivery, cleanup | 9 тестов OK, включая пиксельные проверки Pillow |
| Безопасная сверка вариантов и staging | 2 теста OK; сохраняются все варианты и незавершённый S3-эффект, orphan защищён grace и удаляется после него |
| Семь сценариев отказа pipeline | 7 тестов OK: worker/API/broker, outbox, crash до COMMIT/ack, lease, retry exhaustion, registry/replay |
| TTL сессий и отказ PostgreSQL/Valkey | 2 + 2 теста OK |
| Persistence и failover | PASS; 121 успешных записей, 0 неуспешных попыток; восстановление 2.344 с |
| Bootstrap S3 дважды | OK: bucket сохранён, анонимный доступ 403, создание bucket ключом API запрещено |
Итого 60 собственных тестов. После экспериментов первый дополнительный persistence выявил гонку старта SeaweedFS: S3-порт уже открыт, но тома ещё не зарегистрированы, и чтение объекта получает 503. Этот неуспешный запуск сохранён в commands.txt. Исправлены операторские scripts/restart.sh и .cmd: после healthy модуль app.s3_recovery ждёт LIST и ranged GET существующих объектов, читая по одному байту с параллелизмом 8 и общим таймаутом 45 с. Это отдельная проверка восстановления, а не изменение публичного теста или обещание полной готовности S3 по /health/ready API. Для большого хранилища время такого обхода может превысить лимит; hook завершится ошибкой.
После исправления три последовательных persistence и финальный smoke прошли: restart_recheck.txt. lifecycle.json подтверждает в каждом повторе изменение StartedAt всех семи ролей (восемь контейнеров, включая две API-реплики), сохранение имён volumes и healthy после restart. SHA-256 изменённых после матрицы скриптов восстановления — restart_source_metadata.json; обработка API/worker и измерительные скрипты матрицы не менялись.
Эксперименты и отказы (трек 1)
Гипотеза. Увеличение concurrency/prefetch ускоряет работу до насыщения CPU, но повышает память и может ухудшить latency крупных файлов. Ограничение приёма по глубине активной работы даёт предсказуемую перегрузку: отклонённые запросы получают Retry-After, а принятые задачи завершаются; после разгрузки приём восстанавливается.
Методика. Один worker, фактические лимиты проверяются через docker inspect: 1 CPU / 768 MiB, concurrency=prefetch ∈ {1, 2, 4}. Девять точек: small 320×200 PNG (109 KiB, 80 загрузок), medium 2400×1600 PNG (1961 KiB, 24 загрузки), large 6000×4000 JPEG (3100 KiB, 12 загрузок). Перед каждой точкой worker пересоздаётся, чтобы VmHWM начинался заново. Клиент — один Python-процесс, 8 одновременных загрузчиков; HTTP-соединения не переиспользуются после блокирующих Docker-команд. Неопределённый результат upload при сетевой ошибке автоматически не повторяется.
Клиент: Python 3.11.9, aiohttp 3.14.3, Pillow 12.3.0, matplotlib 3.11.2. Стенд: Docker Desktop, Linux-контейнеры; версии приложения и инфраструктуры закреплены в Git. На компьютере оставался другой Docker-проект. Время до ready = ready_at − accepted_at из PostgreSQL; p95 — nearest rank. Throughput — число ready / интервал от первого accepted_at до последнего ready_at: это измерение конвейера, включающее темп приёма следующих файлов. Queue lag — возраст старейшего активного задания (queued + processing); это не только ожидание в брокере. Глубина и возраст снимаются примерно каждые 0,4 с плюс время SQL/CLI. Пик RSS — VmHWM процесса worker, не память всего стенда.
| concurrency | Изображение | ready | Throughput, файлов/с | p95, с | RSS, MiB | Пик queued+processing | Возраст старейшего, с |
|---|---|---|---|---|---|---|---|
| 1 | small | 80 | 23.84 | 2.84 | 72.5 | 67 | 2.7 |
| 1 | medium | 24 | 4.09 | 5.21 | 133.2 | 22 | 5.4 |
| 1 | large | 12 | 3.38 | 3.35 | 160.4 | 11 | 3.3 |
| 2 | small | 80 | 44.13 | 1.48 | 75.4 | 56 | 1.1 |
| 2 | medium | 24 | 4.6 | 4.78 | 194.9 | 22 | 4.3 |
| 2 | large | 12 | 3.84 | 2.98 | 250.9 | 12 | 2.7 |
| 4 | small | 80 | 52.3 | 1.25 | 79.9 | 50 | 1.1 |
| 4 | medium | 24 | 4.56 | 4.82 | 318.9 | 24 | 4.8 |
| 4 | large | 12 | 3.39 | 3.36 | 430.0 | 12 | 2.8 |
Все 348 из 348 загрузок матрицы достигли ready; failed=0, OOMKilled=false. Максимальный измеренный RSS — 430.0 MiB из 768. Наибольший throughput крупных изображений в этом прогоне получен при concurrency=2 (3.84 файлов/с, p95=2.98 с). Это наблюдение одного прогона на точку, а не статистически доказанный оптимум; близкие результаты следует считать сопоставимыми. На мелких файлах throughput изменился с 23.84 до 52.3 файлов/с при concurrency 1 → 4. Память крупных изображений: 160.4 → 430.0 MiB.
Backpressure и восстановление
MAX_QUEUED_JOBS=30, один worker concurrency=1, burst из 200 мелких файлов с 32 клиентами. Принято 54, получено 146 ответов 503; Retry-After реально прочитан и проверен (5 с). Пик активной очереди — 48, время разгрузки от начала burst — 2.7 с; все 54 принятых задач стали ready, failed=0, p95=1.88 с. После разгрузки три новые загрузки приняты и также достигли ready.
Порог является мягким, а не строгим резервированием мест: несколько запросов могут одновременно проверить старую глубину очереди перед приёмом тела. Поэтому пик может превышать 30. Число находящихся в приёме запросов дополнительно ограничено API concurrency/очередью и MAX_INFLIGHT. Для строгого лимита нужна атомарная резервация слотов. Этот эксперимент подтверждает ограничение приёма и восстановление, но не доказывает универсальную границу памяти при любом размере/параллелизме.
Из исследовательского скрипта удалён заранее выставленный retry_after_header_seen=True: результат определяется HTTP-заголовками. Проверяются коды/число ответов, отсутствие транспортных ошибок, готовность всех подтверждённых задач, восстановление, фактические ресурсы и OOM. Ошибка Docker или измерения не маскируется; промежуточные результаты сохраняются после каждой точки. Настройки API/worker восстанавливаются в finally.
Воспроизведение: python -m pip install -r research/requirements.txt, затем python research/queue_overload.py --out evidence/recheck_2026-11-12. Данные: queue_overload.json, вывод команд, SHA-256 исходников.
Ограничения. Один компьютер, по одному прогону на точку, фиксированный worker CPU=1; фоновые процессы и темп клиента влияют на абсолютные числа. При нескольких worker или другом CPU результаты требуют повторной проверки. Октябрьские данные в evidence/queue_overload.json и старые PNG сохранены как исторические; текущие выводы основаны на повторе 12.11.2026.
Окна отказа (contracts/attachment-states.md)
| Окно | Воздействие | Результат |
|---|---|---|
| после staging до записи задания | сбой БД после записи в staging (lab4-механизм) | staging удаляется компенсацией; иначе исправленный reconcile с --prefix staging/ и grace |
| после COMMIT до publish | остановка брокера + kill всех API | outbox довёл задание |
| после publish до confirm | таймаут/разрыв | публикация повторяется, дубликат — no-op |
| после записи S3 до COMMIT результата | crash_once:after_s3_before_commit |
lease → повтор тем же результатом |
| после COMMIT результата до ack | crash_once:after_commit_before_ack |
redelivery = no-op + ack |
Ограничения и следующие шаги
- Один узел RabbitMQ, S3, PostgreSQL (SPOF). Отложенные повторы реализованы через outbox (брокерных delayed-exchange нет).
- Один worker-процесс по умолчанию (
WORKER_REPLICASможно увеличить); lease иSKIP LOCKED/условные UPDATE допускают несколько worker. - Конкурентные записи старой и новой
pipeline_versionзащищены ключом эффекта и условиемpipeline_version <= job.pipeline_version; версионирование нескольких пайплайнов (трек 2) не реализовано. - Подтверждено экспериментами: различия измеренных throughput/p95/RSS, backpressure и восстановление; гипотеза без доказательства: поведение при >1 worker и при другом лимите CPU.

