30 KiB
Отчёт — лабораторная 4
- Автор, группа: Максимова, БВТ2303 (TODO: полное ФИО)
- Целевая оценка; выбранный трек 5: 4 (трек не выбирается)
- Commit/PR: TODO после публикации (ветка
solution/maksimova_bvt2303) - Использованные источники, библиотеки и помощь ИИ: FastAPI, SQLAlchemy/asyncpg, argon2-cffi, redis-py, aiobotocore/botocore, Pillow (только для JPEG); SeaweedFS, PostgreSQL, Valkey, HAProxy. Документация: AWS S3 PutObject/SigV4, SeaweedFS wiki (S3 API,
s3.jsonidentities), спецификация PNG (RFC 2083), HAProxy 3.0 configuration manual. Помощь ИИ (Claude Code): ревью и доработка кода вложений, написание тестов вstudent-tests/, проведение экспериментов и черновик этого отчёта; все результаты получены реальными прогонами на стенде и проверены.
Запуск из чистого clone
Проверено на: Windows 11 + Docker Desktop 29.3.0 (WSL2, kernel 6.6.87, 14 vCPU, 7.4 GiB RAM), Docker Compose 5.1.0, Python 3.13 на хосте (для make test; достаточно 3.9+).
| Роль т | Service т | Образ | Health / readiness | Volume | Сеть / порт | Credentials |
|---|---|---|---|---|---|---|
| LB | lb |
haproxy:3.0.11-alpine |
/lb-health; backend-check GET /health/ready раз в 1 s |
— | edge; ${LB_PORT:-8080} на хосте, stats только 127.0.0.1:8404 |
— |
| API × 2 | api |
сборка Dockerfile (python:3.12.7-slim) |
/health/ready (PostgreSQL + не в drain) |
нет | edge + backend, порт не публикуется | Docker secrets: database_url, cache_url, s3_access_key_id, s3_secret_access_key |
| PostgreSQL | db |
postgres:16.4-alpine |
pg_isready |
postgres_data |
backend (internal) | postgres_password |
| Valkey (кэш сессий) | valkey |
valkey/valkey:8.0.1-alpine |
PING |
нет (кэш, источник истины — PostgreSQL) | backend | valkey_password |
| S3 | s3 |
chrislusf/seaweedfs:3.97 |
GET :9000/healthz |
s3_data |
backend, порт не публикуется; master/filer/volume слушают только 127.0.0.1 внутри контейнера |
admin + API ключи из secrets подставляются в s3.json при старте |
| Bootstrap bucket | s3-init |
образ API | one-shot, service_completed_successfully |
— | backend | единственный, кто получает admin-ключ S3 |
| Миграции | migrate |
образ API | one-shot | — | backend | database_url |
sh scripts/init-secrets.sh # создаёт infra/secrets/*.txt (случайные значения, не перезаписывает, не печатает)
cp .env.example .env # при занятом 8080 задайте LB_PORT=8081
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
# порядок: db, valkey, s3 -> healthy -> migrate (SQL migrations/*.sql, повтор = SKIP)
# s3-init (bucket + самопроверки приватности/прав, повтор = keep) -> api x2 healthy -> lb
curl -fsS http://localhost:${LB_PORT:-8080}/health/ready
make test BASE_URL=http://localhost:${LB_PORT:-8080} # на Windows: PYTHONUTF8=1 python tests/smoke.py --base-url ...
# hook-тесты и собственные проверки — в Linux-контейнере tester (docker CLI + docker.sock):
docker compose --profile tools run --rm tester make test-persistence ACTION_SCRIPT=scripts/restart.sh BASE_URL=http://lb:8080
docker compose --profile tools run --rm tester make test-failover ACTION_SCRIPT=scripts/stop-one.sh BASE_URL=http://lb:8080
docker compose --profile tools run --rm tester sh scripts/start-api.sh # вернуть остановленную реплику
docker compose --profile tools run --rm tester python3 student-tests/<test>.py
docker compose stop # безопасная остановка, данные сохраняются
docker compose down -v # НАМЕРЕННОЕ удаление всех учебных данных (volumes)
Архитектура и решения
client -> HAProxy (lb) -> api x2 --+--> PostgreSQL: users, chats, messages, sessions, idempotency_keys,
| attachments (метаданные), message_attachments, upload_intents
+--> Valkey: кэш сессий (tombstone при logout)
+--> SeaweedFS S3: приватный bucket messenger-attachments/originals/<random hex>
Перенесено из lab3 без изменения контракта: регистрация/Basic→Bearer, сессии в PostgreSQL с кэшем в Valkey, идемпотентная отправка сообщений, X-Instance-Id, graceful drain, HAProxy с active check, hooks restart.sh/stop-one.sh. Изменено: CreateMessage принимает attachment_ids (по умолчанию []) и text="" при наличии вложений; fingerprint идемпотентности без вложений совпадает с lab3, так что старые ключи повторяются корректно.
Модель. attachments (id, chat_id, owner_id, filename — только для отображения, content_type, size, sha256, width/height, status=ready, object_key UNIQUE) привязано к чату при загрузке. message_attachments(message_id, attachment_id, position) хранит порядок; одно вложение можно сослать из нескольких сообщений чата. Миграция 004_attachments.sql — expand-only.
Upload (app/attachments.py), всё до сохранения байтов:
- filename (400:
/,\, NUL, Cc/Cf/bidi, пустое/только точки, >255) → членство в чате (404) →Content-Typeровноimage/png|image/jpeg(415, multipart не принимается) →Content-Length > 10 MiB→ 413 без чтения тела; - слот загрузки: ≤
MAX_CONCURRENT_UPLOADS=8на реплику, ожидание ≤10 s, иначе 429; - тело читается потоково в
SpooledTemporaryFile(в RAM ≤ 1 MiB на загрузку), считается размер и SHA-256 на лету; превышение 10 MiB в chunked → 413; приём дольше 60 s → 400; - проверка содержимого в потоке: формат по magic bytes и совпадение с заявленным MIME; PNG — собственный потоковый валидатор (CRC каждого чанка, IHDR, распаковка IDAT кусками по 64 KiB с подсчётом и сравнением с ожидаемым размером, без хранения пикселей); лимит 40 млн пикселей проверяется по IHDR/SOF до распаковки (413); JPEG — Pillow
draft()1/8 +load()(повреждённый поток → 415); INSERT upload_intent+ COMMIT → S3 PUT (SigV4 подписывает SHA-256 тела) → одна транзакция «DELETE intent + INSERT attachment» → 201 ready. Честный 201 возможен только после этого COMMIT: и байты, и метаданные уже устойчивы.
Download: авторизация по chat_members в PostgreSQL (чужое/неизвестное → 404), затем потоковая отдача из S3 через API, без redirect, с истинным Content-Type, Content-Length, nosniff, Cache-Control: private, no-store. Приватный bucket не заменяет ACL: случайный ключ можно утечь через лог, а права участника чата знает только приложение.
Согласованность БД/S3 (ответ на «PUT прошёл, а COMMIT нет»):
| Отказ | Что делает система |
|---|---|
| PUT упал / истёк дедлайн | 503 сразу. Исход PUT неизвестен (S3 может дописать объект после нашего DELETE), поэтому объект удаляется best effort в фоне, а intent остаётся; janitor удалит объект ещё раз после grace и только потом intent |
| COMMIT упал | 503 сразу. Исход COMMIT тоже неизвестен (мог пройти, а потерялся ответ). Фоновая компенсация берёт SELECT … FOR UPDATE intent: intent нет → COMMIT прошёл, объект не трогаем; иначе DELETE объекта → DELETE intent |
| Процесс умер после PUT | intent остался; janitor каждой реплики (JANITOR_INTERVAL_SECONDS=60, jitter) через UPLOAD_GRACE_SECONDS=900 удаляет объект и intent; FOR UPDATE SKIP LOCKED — реплики не мешают друг другу и финализирующейся загрузке |
| Строка без объекта (потеря байтов вне приложения) | download → 500 internal_error и ERROR в логе; метаданные не удаляются (сообщения на них ссылаются) |
Инвариант: объект без строки существует, только пока жив его intent; объект закоммиченной строки никогда не удаляется. Grace 900 s ≫ максимального времени upload (60 s приём + 16 s PUT).
Недоступность S3. /health/ready S3 не проверяет: без S3 деградируют только вложения (503), чаты и сообщения работают; иначе отказ S3 вывел бы из LB все реплики. Каждый S3-вызов ограничен общим дедлайном S3_OPERATION_TIMEOUT_SECONDS=6 (DNS + повторы) — меньше timeout server 10s у LB; для PUT дедлайн 6 s + size / 1 MiB/s (≤16 s для 10 MiB), а HAProxy даёт POST вложения 40 s. L7-повторы HAProxy для /api/v1/attachments/ отключены: 503 там означает отказ общего S3, повтор на другой реплике бесполезен.
Права S3 (infra/seaweedfs/s3.json.template): identity admin есть только у s3-init; identity messenger-api — Read/Write/List только на messenger-attachments (Write нужен для DELETE janitor-а). Анонимного доступа нет. Admin UI/API SeaweedFS (master 9333, filer 8888, volume 8080, gRPC) слушают только 127.0.0.1 внутри контейнера.
Соответствие .env.example:* APP_HOST/APP_PORT, SESSION_TTL_SECONDS, DATABASE_URL_FILE, SESSION_STORE=valkey, CACHE_URL_FILE, API_REPLICAS, IDEMPOTENCY_TTL_SECONDS, S3_ENDPOINT, S3_REGION, S3_BUCKET, S3_ACCESS_KEY_ID_FILE, S3_SECRET_ACCESS_KEY_FILE, MAX_UPLOAD_BYTES, MAX_IMAGE_PIXELS читаются app/config.py под теми же именами. Дополнительно в compose.yaml (x-api-env): S3_OBJECT_PREFIX, S3_CONNECT/READ/OPERATION_TIMEOUT_SECONDS, S3_PUT_MIN_BYTES_PER_SECOND, UPLOAD_SPOOL_MEMORY_BYTES, UPLOAD_TIMEOUT_SECONDS, MAX_CONCURRENT_UPLOADS, UPLOAD_SLOT_WAIT_SECONDS, UPLOAD_GRACE_SECONDS, JANITOR_INTERVAL_SECONDS, FAULT_INJECTION (только для экспериментов, пусто в норме). APP_ENV не используется.
Доказательства критериев
Все файлы — в evidence/, тесты — в student-tests/; прогоны 2026-10-30 на стенде выше.
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|---|---|---|---|
| Публичный smoke | make test BASE_URL=http://localhost:8081 |
PASS: lab4 public API scenario (SHA-256, 404 постороннему) |
smoke.txt |
| 3: S3 в стенде, метаданные в PG, байты в приватном bucket | student-tests/s3_failures.py; api-no-local-files.txt |
object_key только в PG; анонимные GET/HEAD/LIST/PUT/DELETE напрямую в S3 → 403; у API нет volumes, /tmp пуст |
s3-failures.txt, api-no-local-files.txt |
| 3: PNG/JPEG ≤10 MiB, ≤40 Мпикс, MIME по содержимому, опасные filename | student-tests/attachment_edge_cases.py |
60/60 OK: ровно 10 MiB и ровно 40 Мпикс → 201; +1 байт → 413; бомба 50 Мпикс (~10 KB) → 413 | attachment-edge-cases.txt |
| 3: upload → стоп обслужившей реплики → download через другую | make test-failover ×2; student-tests/upload_failover.py |
failover: 0 ошибок, восстановление записи 4.0/4.2 s; для каждой из двух реплик SHA-256 совпал после её остановки | failover.txt, upload-failover.txt |
| 3: restart с volumes сохраняет метаданные и оригинал | make test-persistence ACTION_SCRIPT=scripts/restart.sh |
PASS; те же ID контейнеров db/s3/valkey/api/lb с новым StartedAt, volumes на месте |
persistence.txt |
| 4: тесты большого файла, повреждения, подмены MIME, чужого id, вложения другого чата; нет 500 | attachment_edge_cases.py |
обрезка/CRC/мусор в zlib при верном CRC/без IEND → 415; PNG как JPEG, JPEG как PNG, text/plain, multipart → 415; вложение чужого и своего другого чата → 404; ни одного 500 | attachment-edge-cases.txt |
| 4: компенсация/сверка/очистка с grace | student-tests/upload_compensation.py |
DB error после PUT → 503 + фоновая компенсация, intent не остался; crash после PUT → intent + объект, janitor до grace их не трогает, после grace удаляет оба; свежий intent и готовое вложение целы | upload-compensation.txt |
| 4: лимиты RAM, ≥10 одновременных загрузок | student-tests/upload_memory.py --concurrency 12/20 |
12 × 9.5 MiB: прирост пика RSS 13–14 MiB на реплику (наивно 57 MiB данных на реплику) | upload-memory-c12.json, upload-memory-c20.json |
| 4: идемпотентный bootstrap, отдельные ограниченные credentials | docker compose run --rm s3-init ×2, migrate |
keep bucket, все самопроверки PASS: API-ключ не создаёт/не удаляет bucket, не видит чужих; миграции SKIP |
bootstrap-idempotent.txt |
| 4: админ-консоль закрыта, private bucket проверен вне API | s3_failures.py из сети стенда |
порты 9333/8888/8080/19333/18888/23646 недоступны; S3 не опубликован на хосте; анонимные запросы → 403 | s3-failures.txt |
| 3/4: недоступность S3 | s3_failures.py (docker stop s3) |
ready 200, сообщения 201, metadata 200; upload/download → 503 за 6.0–6.2 s; 415 остаётся 415; после старта S3 всё работает, старый файл цел | s3-failures.txt |
Эксперименты и отказы
Память при одновременных загрузках (уровень 4)
Гипотеза: пик памяти API определяется конструкцией (spool ≤1 MiB/загрузку, потоковая проверка PNG, ≤8 слотов), а не числом × размером файлов.
Методика: upload_memory.py перезапускает обе реплики (сброс состояния), N потоков стартуют одновременно (Barrier) и загружают валидный PNG из шума 9 962 537 байт (9.5 MiB, несжимаемый — худший случай для проверки IDAT); внутри каждой реплики и S3 каждые 100 мс читаются VmRSS процесса и anon cgroup. VmHWM не подходит: пик импорта библиотек при старте (~170 MiB) выше пика загрузок. Лимиты: API 0.5 CPU / 256 MiB, S3 1 CPU / 1 GiB.
| N (на реплику) | Статусы | Wall, s | p50 / max, s | Пик RSS API − базовый (≈105 MiB) | Наивная оценка «всё в RAM» на реплику | Пик RSS SeaweedFS |
|---|---|---|---|---|---|---|
| 12 (6+6) | 12 × 201 | 5.2 | 5.0 / 5.2 | +12.9 / +13.7 MiB | 57 MiB | 546 MiB |
| 20 (10+10, > 8 слотов) | 20 × 201 | 9.9 | 8.6 / 9.9 | +16.5 / +17.7 MiB | 95 MiB | 779 MiB |
Гипотеза для API подтверждена: прирост ~2 MiB на одновременную загрузку и почти не растёт сверх 8 слотов (лишние ждут слот; в одном из повторов при N=20 двое получили 429 после 10 s ожидания — ожидаемый backpressure). SHA-256 проверен.
Побочная находка: узким местом оказался S3-сервер. С исходным лимитом 512 MiB SeaweedFS при 12 параллельных PUT дошёл до 519 MiB и был убит (контейнер перезапущен, все загрузки — 503). Исправлено: лимит 1 GiB и GOMEMLIMIT=600MiB (мягкий лимит Go GC); после нагрузки RSS возвращается к ~210 MiB. Это одно измерение на одном ноутбуке, а не ёмкость SeaweedFS вообще.
Компенсация отказа между S3 и БД (уровень 4)
Найденный дефект (до исправления). Сверка содержимого bucket со строками БД на «грязном» стенде нашла 12 объектов без строки и без intent — то, что запрещено инвариантом. Причина: при истёкшем дедлайне PUT компенсация удаляла объект и intent, а SeaweedFS дописывал PUT после DELETE. Второй риск того же рода: при неоднозначном COMMIT немедленное удаление объекта оставило бы строку без байтов. Исправлено (см. таблицу отказов выше); 12 лишних объектов удалены. upload_compensation.py после исправления проверяет компенсацию при ошибке БД и очистку janitor-ом после падения процесса.
Отказы
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|---|---|---|---|
docker stop обслужившей API-реплики (×2 + для каждой реплики) |
запись и download через другую | 0 ошибок записи; файл скачан по SHA-256 через оставшуюся | первая успешная запись через 4.0–4.2 s; потерь нет |
| Restart lb + api + db + valkey + s3 с volumes | данные, сессия и оригинал сохранены | PASS с прежним токеном | hook и ожидание готовности уложились в лимиты теста (90 + 90 s), длительность отдельно не замерялась; потерь нет |
docker stop s3 |
только вложения → 503, остальное работает | ready 200, message 201, metadata 200, upload/download 503 за ~6 s | сразу после старта S3; потерь нет, intents неудачных PUT убирает janitor |
| Падение процесса после PUT до COMMIT | клиент без 201, orphan не вечный | intent + объект → удалены janitor после grace | grace (900 s; 20 s в тесте) |
| Потеря БД после PUT | 503, без мусора | 503; фоновая компенсация удалила объект и intent | ~0.1 s |
| 12 параллельных PUT по 10 MiB при лимите S3 512 MiB | — | SeaweedFS убит по памяти, все 503 | исправлено лимитом 1 GiB + GOMEMLIMIT |
| Оборванная клиентом загрузка | реплика продолжает работу | следующая загрузка 201; по коду PUT начинается только после приёма всего тела, поэтому объекта нет (отдельно не измерялось) | — |
Ограничения и следующие шаги
- Один Docker host, один PostgreSQL, один SeaweedFS без репликации, один LB: выдерживается отказ одной API-реплики и перезапуск хранилищ с volumes, но не потеря host/диска/S3-тома. Резервного копирования нет.
- Нет отдельного reconciler: объект без строки и без intent (ручное вмешательство, баг) автоматически не удаляется; потеря байтов готового вложения видна только по 500 и ERROR в логе при download.
- Прогрессивные JPEG > 16 Мпикс проверяются только по структуре маркеров (полное декодирование держало бы все DCT-коэффициенты в памяти); такие повреждения внутри энтропийного потока не ловятся.
MAX_CONCURRENT_UPLOADS— на реплику, не глобально; общий предел S3 задаётся числом реплик × 8. Ёмкость SeaweedFS при большем числе реплик не измерялась.- Измерения памяти — по одному-два прогона на ноутбуке; при N=12 в разных прогонах прирост был от 3.6 до 13.7 MiB на реплику, абсолютные числа зависят от аллокатора и версии Python.