25 KiB
Отчёт — лабораторная 4
- Автор, группа: Запорожец Михаил, БВТ2304
- Целевая оценка: 3 (трек 5 не заявлен)
- Commit/PR: mtusi2026/mtusi2026lab4#115 (ветка
solution/bvt2304-zaporozhets, коммит2dca5c1) - Использованные источники, библиотеки и помощь ИИ: документация AWS S3 (object uploads, bucket policy), RustFS (docs.rustfs.com, переменные
RUSTFS_*), спецификация PNG (IHDR, IDAT, Adam7), Pillow (lazy open,verify,draft,MAX_IMAGE_PIXELS), Docker Compose (secrets, healthcheck,service_completed_successfully). Библиотеки: FastAPI 0.115, uvicorn 0.34, asyncpg 0.30, argon2-cffi 23.1, redis-py 5.2, minio-py 7.2.18 (S3-клиент), Pillow 11.3.0. Код, конфигурации и тесты написаны с помощью ИИ-ассистента (Claude); решения разобраны и проверены автором.
Запуск из чистого clone
Нужно: Docker Engine/Desktop с Compose v2.20+ (проверено: Docker 29.8.2, Compose 5.6.0, Windows 11 + Docker Desktop, WSL2) и POSIX-shell (Linux/macOS или Git Bash). Python и make на хосте не нужны: проверки запускаются в сервисе tester.
| Роль | Сервис | Образ | Health/readiness | Volume | Сеть / порт | Credentials |
|---|---|---|---|---|---|---|
| Балансировщик | lb |
haproxy:3.2.8-alpine |
wget /stats; сам проверяет API по /health/ready |
— | edge; единственная публикация 127.0.0.1:8080 (+ 127.0.0.1:8404 статистика) |
не нужны |
| API × N | api (deploy.replicas: ${API_REPLICAS:-2}) |
сборка Dockerfile (python:3.12.12-slim-bookworm) |
HEALTHCHECK /health/ready |
нет; root fs read-only, /tmp tmpfs |
edge + data; порты не публикуются | secrets database_url, cache_url, s3_access_key_id, s3_secret_access_key |
| Миграции | migrate (one-shot) |
тот же образ | exit 0 | — | data | secret database_url |
| S3 | s3 |
rustfs/rustfs:1.0.4@sha256:ed9210d6…dcc2 |
curl /health |
s3data |
data (internal); порты не публикуются, веб-консоль выключена | RUSTFS_ACCESS_KEY_FILE, RUSTFS_SECRET_KEY_FILE |
| Bootstrap bucket | s3-init (one-shot) |
образ API, python -m app.s3_bootstrap |
exit 0 | — | data | S3 secrets |
| PostgreSQL | postgres |
postgres:17.7-bookworm |
pg_isready |
pgdata |
data (internal) | POSTGRES_PASSWORD_FILE |
| Кэш сессий | valkey |
valkey/valkey:8.1.4 |
valkey-cli ping |
нет (кэш) | data (internal) | requirepass в secret valkey_conf |
| API с TTL=2 с | api-ttl (profile test) |
образ API | как у api | — | edge + data | как у api |
| Тестовый стенд | tester (profile tools) |
python:3.12.12-alpine3.22 + make + curl + docker-cli | — | bind . |
edge | docker.sock |
git clone <repo> && cd <repo>
sh scripts/init-secrets.sh # ./secrets/* (пароль БД, Valkey, ключи S3) и .env из .env.example; значения не печатает
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --wait
# postgres, s3, valkey -> migrate (схема) -> s3-init (bucket) -> api x2 (healthy) -> lb
# Публичные проверки (Linux-контейнер tester; на Linux-хосте можно просто `make ...`)
docker compose --env-file .env --profile tools run --rm tester make check
docker compose --env-file .env --profile tools run --rm tester make test
docker compose --env-file .env --profile tools run --rm tester make test-failover ACTION_SCRIPT=scripts/stop-one.sh
docker compose --env-file .env --profile tools run --rm tester sh scripts/restore.sh # вернуть реплику
docker compose --env-file .env --profile tools run --rm tester make test-persistence ACTION_SCRIPT=scripts/restart.sh
sh scripts/test-lab4.sh # собственные тесты lab4 + регрессия lab3 и lab2
sh scripts/collect-evidence.sh # все доказательства evidence/*.txt одной командой
- Bootstrap БД:
python -m app.migrate(сервисmigrate) применяетmigrations/NNNN_*.sqlпо порядку подpg_advisory_lock. Новая миграция lab4 —0004_attachments.sql, она только добавляет объекты (expand). - Bootstrap S3:
python -m app.s3_bootstrap(сервисs3-init). Создаёт bucketmessenger-attachments, если его нет. Если у bucket есть политика анонимного доступа, удаляет её. Затем кладёт служебный объект и делает анонимный GET в обход API: ожидается 403, иначе bootstrap падает и API не стартует. Повторный запуск безопасен: печатаетexistsи данные не трогает (evidence/stand.txt). - Действий оператора, кроме
init-secrets.sh, не требуется. Если на 8080 работает стенд lab3, его нужно остановить (docker compose -p mtusi-lab3 stop) или задатьLB_PUBLISHED_PORTв.env. - Безопасная остановка (данные сохраняются):
docker compose --env-file .env stopили... down. - Намеренное удаление учебных данных:
docker compose --env-file .env down -v(удаляет volumesmtusi-lab4_pgdataиmtusi-lab4_s3data); секреты — каталогsecrets/.
Архитектура и решения
клиент ──HTTP──> lb: HAProxy 3.2 (127.0.0.1:8080) сеть edge
│ roundrobin, без sticky, /health/ready раз в 1 с
┌───────┴────────┐
▼ ▼
api-1 ... api-N (FastAPI/uvicorn, stateless, read-only FS)
│ │ сеть data (internal)
┌──────┼────────────────┼──────────┐
▼ ▼ ▼ ▼
postgres (pgdata) s3: RustFS (s3data) valkey (кэш сессий)
users, chats, приватный bucket
messages, sessions, messenger-attachments/
attachments (мета), attachments/<uuid> ← байты оригиналов
message_attachments
Что перенесено из lab3 без изменений: HAProxy (DNS-обнаружение реплик, проверка готовности, повтор только безопасных запросов), drain по SIGTERM, X-Instance-Id, обязательный Idempotency-Key, Argon2id, Bearer-сессии в PostgreSQL с кэшем в Valkey, однократные миграции, hook-скрипты stop-one.sh/restore.sh. Тесты lab3 и lab2 оставлены как регрессия.
Что добавлено в lab4:
| Где | Что |
|---|---|
migrations/0004_attachments.sql |
Таблица attachments: id, chat_id, owner_id, filename, content_type, size_bytes, sha256, width, height, object_key, status, created_at, updated_at. Таблица message_attachments (message_id, attachment_id, chat_id, position). Ограничение text ослаблено до 0..4000: сообщение может состоять только из вложений. |
app/storage.py |
S3-клиент (minio-py → RustFS по S3 API): put/get/delete с дедлайном на операцию и компенсирующее удаление. |
app/images.py |
Ограниченное чтение тела и проверка PNG/JPEG по содержимому. |
app/s3_bootstrap.py |
Идемпотентное создание приватного bucket и проверка анонимного доступа. |
app/main.py |
POST /chats/{id}/attachments, GET /attachments/{id}, GET /attachments/{id}/content; attachment_ids в сообщениях. |
Источник истины. Метаданные вложения и связь с чатом и сообщением хранятся в PostgreSQL. Байты оригинала лежат только в S3: ни в БД, ни на диске API их нет. Вложение заранее привязано к чату: attachments.chat_id задаётся при загрузке, а к сообщению файл привязывается позже, через attachment_ids. Составные FK (attachment_id, chat_id) и (message_id, chat_id) не дают даже на уровне БД прикрепить файл другого чата.
Object key назначает сервер: attachments/<случайный UUID>. Имя файла клиента в ключе не участвует и хранится только для отображения. В ответах API ключа, адреса S3 и credentials нет.
Порядок загрузки и когда честно вернуть 201:
- Аутентификация, затем проверка членства в чате. Посторонний получает 404 до чтения тела, то есть не может залить в чужой чат ни байта.
- Проверка
filename(400) иContent-Type(толькоimage/pngилиimage/jpeg, иначе 415). - Чтение тела с лимитом. Если
Content-Lengthбольше 10 MiB — сразу 413. Тело читается потоком с обрывом на 10 485 761-м байте, так что и chunked без длины ограничен. - Проверка содержимого: сигнатура должна совпасть с
Content-Type, иначе 415. Размеры читаются из заголовка; еслиширина × высотабольше 40 млн, ответ 413 до распаковки пикселей. Только после этого идёт проверка целостности: у PNG — CRC чанков и потоковая распаковка IDAT со сверкой объёма с IHDR (пиксели не хранятся), у JPEG — декодирование в режиме draft 1/8. Повреждённый файл получает 415. PUTв S3. Сбой даёт 503, метаданных при этом нет.INSERTметаданных в PostgreSQL. Если он не прошёл (БД недоступна, клиент оборвал соединение), API удаляет только что записанный объект: это компенсация.- 201
status=readyотдаётся только послеCOMMIT. К этому моменту и байты, и запись уже надёжно сохранены.
Если S3 PUT прошёл, а COMMIT в PostgreSQL — нет, срабатывает компенсация из шага 6: объект удаляется, клиент получает 503 и может повторить загрузку. Если упадёт и сама компенсация (S3 тоже недоступен) или процесс API убьют между шагами 5 и 6, в bucket останется неучтённый объект. На метаданные и доступ он не влияет, но место занимает. Автоматическая сверка и очистка таких объектов с grace period — это критерий уровня 4, здесь она не реализована (см. «Ограничения»). Обратная ситуация невозможна: запись в БД без объекта не появится, потому что INSERT выполняется только после успешного PUT.
Скачивание проходит через API: сначала аутентификация, потом проверка членства в чате вложения, затем чтение из S3. Байты отдаются с истинным Content-Type и без redirect. Посторонний получает 404 одинаково на метаданные и на content. Ответ несёт заголовки Cache-Control: private, no-store, X-Content-Type-Options: nosniff и ETag = sha256.
Почему приватный bucket и случайный ключ не заменяют ACL приложения. Ключ попадает в логи, URL и историю браузера, его можно переслать. Кроме того, «случайный» не значит «секретный навсегда»: участника могут исключить из чата, а ключ останется прежним. Приватный bucket защищает только от анонимного доступа к S3, а знает, кто участник чата, одно приложение. Поэтому проверка выполняется на каждый запрос к API.
Почему файл в Docker volume одной реплики — не объектное хранилище. Volume привязан к конкретному контейнеру и хосту. Файл, загруженный через api-1, не виден api-2: после остановки api-1 download через другую реплику вернул бы 404 или 500. Именно это проверяет test_failover_of_uploading_replica. У API в этом решении корневая ФС read-only, а /tmp — tmpfs, так что локальной копии нет физически (test_no_local_copy_on_api).
Готовность (/health/ready). Критична только PostgreSQL, как и в lab3. Недоступность S3 не выводит реплики из балансировки: текст, история и метаданные вложений продолжают работать, а upload и download честно отвечают 503 за ограниченное время. Если бы S3 входил в readiness, его сбой выключил бы весь мессенджер, включая текстовые сообщения.
Таймауты S3. Подключение — 2 с, чтение — S3_TIMEOUT_MS (5 с), повторов на уровне HTTP-клиента нет. Дополнительно стоит общий дедлайн операции (asyncio.wait_for): DNS-резолв остановленного контейнера во внутренней сети Docker занимал около 8 с и не ограничивался таймаутами urllib3. Дедлайн (5 с) меньше timeout server HAProxy (15 с), поэтому клиент получает 503 от API, а не 504 от LB.
Память. Тело загрузки держится в памяти целиком (до 10 MiB). Проверку изображений одновременно выполняют не больше IMAGE_CHECK_WORKERS=2 на реплику. PNG не декодируется в пиксели, JPEG декодируется в масштабе 1/8. Лимит контейнера API — 384 MiB. Эксперимент с ≥10 одновременными загрузками и замером пика RAM относится к уровню 4 и не проводился.
S3-сервер: RustFS, а не MinIO. Образы MinIO на момент выполнения удалены из публичных реестров (Docker Hub: «repository does not exist», quay.io: 401). RustFS 1.0.4 (релиз 25.10.2026) закреплён по тегу и digest и совместим по S3 API, поэтому клиент — стандартный minio-py. Веб-консоль RustFS по умолчанию выключена (RUSTFS_CONSOLE_ENABLE не задан), порты S3 на хост не публикуются, сеть data помечена internal.
Соответствие .env.example реальной конфигурации:
| Переменная | Где используется |
|---|---|
S3_ENDPOINT, S3_REGION, S3_BUCKET |
app/config.py → app/storage.py, app/s3_bootstrap.py; RUSTFS_REGION у сервиса s3 |
S3_ACCESS_KEY_ID_FILE, S3_SECRET_ACCESS_KEY_FILE |
compose secrets s3_access_key_id, s3_secret_access_key (создаёт init-secrets.sh); те же файлы — root credentials RustFS |
MAX_UPLOAD_BYTES, MAX_IMAGE_PIXELS |
app/config.py, значения можно только уменьшить относительно контракта |
S3_TIMEOUT_MS, IMAGE_CHECK_WORKERS |
добавлены решением: дедлайн S3-операции и число параллельных проверок изображений |
| остальные | без изменений с lab3 |
Доказательства критериев
Все файлы получены одной командой sh scripts/collect-evidence.sh на запущенном стенде 12.11.2026.
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|---|---|---|---|
| Публичный smoke | make check, make validate, make test |
PASS: lab4 public API scenario (upload 201 ready, attachment_ids, download вторым участником = оригинал, 404 постороннему) |
evidence/public-tests.txt |
| Возможности lab3 сохранены | make test-failover ×2, регрессия test_lab3.py, test_lab2_regression.py |
обе реплики остановлены по очереди, failed_attempts: 0; 8/8 и 10/10 |
evidence/failover-hook.txt, evidence/student-tests.txt |
| S3 в общем стенде, приватный bucket | compose ps, логи s3-init, повторный запуск s3-init |
rustfs:1.0.4@sha256 healthy, volume s3data; анонимный GET → HTTP 403; повтор: exists |
evidence/stand.txt |
| Метаданные в PostgreSQL, байты в S3, не в БД и не на API | test_no_local_copy_on_api, test_bucket_private_outside_api |
rootfs API read-only, нет volume и записываемых bind, /tmp пуст; в attachments только метаданные и object_key |
evidence/student-tests.txt, migrations/0004_attachments.sql |
| 201 ready, побайтный download, SHA-256 | test_png_and_jpeg_roundtrip |
PNG и JPEG: status=ready, variants=[]; bytes и sha256 совпадают; Content-Type истинный |
evidence/student-tests.txt |
Message с attachment_ids читается участниками |
test_message_with_attachments |
text="" + 2 вложения, порядок сохранён, идемпотентный повтор равен оригиналу, история возвращает attachment_ids |
там же |
| Посторонний не имеет доступа | smoke, test_png_and_jpeg_roundtrip, test_foreign_attachment_rejected |
404 на метаданные и content, 401 без токена; upload в чужой чат → 404; вложение другого чата в сообщении → 404, сообщение не создано | там же |
| Лимиты ≤10 MiB / ≤40 Мпикс до чтения/декодирования | test_limits_and_mime |
10 MiB + 1 → 413; PNG-заголовок 10000×5000 (~100 байт) → 413 без декодирования; 6000×6000 без пикселей → 415 | там же |
| MIME по содержимому | test_limits_and_mime |
PNG как image/jpeg и JPEG как image/png → 415; GIF, обрезанные PNG/JPEG, пустое тело, text/plain, multipart → 415 |
там же |
| Опасные filename | test_dangerous_filenames |
../etc/passwd, a/b.png, a\b.png, NUL, \t, \n, DEL, пустое, .., 256 символов → 400; Unicode-имя и 255 символов принимаются |
там же |
| Upload → стоп обслужившей реплики → download через другую | test_failover_of_uploading_replica |
uploaded via 406b73449330-…, downloaded via 9f9f380ebef7-…, байты совпадают |
там же |
| Restart с volumes сохраняет метаданные и оригинал | make test-persistence ACTION_SCRIPT=scripts/restart.sh |
PASS (тест lab4 повторно читает метаданные и скачивает оригинал прежним токеном); StartedAt всех процессов (lb, api×2, postgres, s3, valkey) сменился |
evidence/persistence.txt |
| Недоступность S3 | test_s3_unavailable |
docker stop s3: upload и download → 503 (не 500, не 504), текст → 201, метаданные → 200, /health/ready → 200; после docker start тот же файл скачивается |
evidence/student-tests.txt |
Эксперименты и отказы
Стенд: Windows 11, Docker Desktop (WSL2) — VM 8 CPU / 4 GiB. Лимиты: API 1 CPU / 384 MiB на реплику, RustFS 1 CPU / 512 MiB, PostgreSQL 2 CPU / 768 MiB. Fixture: tests/fixtures/sample.png (111 817 байт) и синтетический student-tests/fixtures/sample.jpg 160×100 (1 992 байта).
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|---|---|---|---|
docker stop реплики, загрузившей файл |
download через другую реплику | тот же файл, другой X-Instance-Id |
сразу (LB исключил реплику по drain); потерь нет |
make test-failover для каждой реплики |
0 потерянных подтверждённых записей | 125 успешных записей, failed_attempts: 0, вложение скачано после отказа |
первая запись после отказа через 4,2–4,7 с; потерь нет |
docker stop s3 |
503 на файлы, остальное работает | upload/download 503 за ≤5 с каждый; текст 201; ready 200 | после docker start s3 файл снова скачивается (≤60 с ожидания в тесте); потерь нет |
scripts/restart.sh (lb, api, postgres, s3, valkey) |
данные, сессия и файл сохраняются | PASS, StartedAt всех 6 процессов новые |
весь hook с повторным migrate/s3-init — около 45 с; потерь нет |
Ограничения и следующие шаги
- Нет сверки и очистки неучтённых объектов (уровень 4). Компенсация на месте срабатывает при ошибке INSERT, но объект останется, если процесс API убьют между PUT и COMMIT, если не удастся сама компенсация или если PUT завершится в фоне уже после того, как дедлайн вернул клиенту 503. Следующий шаг — фоновый reconciler: обходит bucket, сравнивает ключи с
attachments.object_keyи удаляет объекты без метаданных старше grace period, например 24 часов. - API работает с root credentials RustFS. Отдельный пользователь S3 с правами только на bucket (уровень 4) не настроен.
- Тело загрузки целиком в памяти (до 10 MiB на запрос); потоковой передачи в S3 и замера пика RAM при ≥10 параллельных загрузках нет (уровень 4).
- RustFS в single-node режиме без избыточности (
storage_class has no parityв логе): отказ диска означает потерю файлов. Для учебного стенда это допустимо, в production нужен distributed-режим или реплицированное хранилище. - Неучтённые объекты от отменённых PUT возможны из-за дедлайна: поток, который нельзя прервать, может дописать объект уже после ответа 503. Это ещё одна причина, по которой нужен reconciler.
- Подтверждено: все обязательные сценарии уровня 3 и регрессия lab3/lab2 (
evidence/). Остальные пункты уровней 4 и 5 не заявлены.