Files
mtusi2026lab4/REPORT.md
T

27 KiB
Raw Blame History

Отчёт — лабораторная 4. S3-хранилище и вложения

  • Автор, группа: Соколова Полина.
  • Целевая оценка: 4. Трек уровня 5 не заявляется.
  • Дата проверок: 05.11.2026.

1. Запуск из чистого clone

Требования и версии

Нужны Linux/WSL, Docker Engine, Docker Compose, Python 3.9+ и make. Команды выполняются из корня клонированного репозитория.

Образы закреплены:

  • приложение: python:3.12.10-slim-bookworm;
  • PostgreSQL: postgres:16.4-bookworm;
  • Redis: redis:7.2.5-bookworm;
  • балансировщик: haproxy:3.0.5-bookworm;
  • S3-хранилище: chrislusf/seaweedfs:4.44.

Python-зависимости закреплены в requirements.txt, в том числе boto3==1.43.124 и Pillow==13.0.0.

Используются оба файла Compose:

docker compose -f compose.yaml -f compose.s3.yaml --env-file .env ...

В compose.yaml сохранено историческое имя проекта mtusi2026lab3. При переносе реализации это позволило использовать прежние тома. Имя образа приложения для этой работы — mtusi-messenger:lab4. Переименование проекта без явного переноса/подключения томов не выполнялось.

Локальная конфигурация PostgreSQL

Если используется существующая БД, нужен прежний .env с её паролем. Новый пароль в .env не меняет пароль пользователя уже инициализированной БД.

Для нового стенда без существующего тома PostgreSQL .env можно создать так:

python3 - <<'PY'
import os
from pathlib import Path
import secrets
import subprocess

path = Path(".env")
if path.exists():
    raise SystemExit(".env уже существует; оставлен без изменений")

project = os.environ.get("COMPOSE_PROJECT_NAME", "mtusi2026lab3")
volumes = subprocess.check_output(
    [
        "docker", "volume", "ls", "-q",
        "--filter", f"label=com.docker.compose.project={project}",
        "--filter", "label=com.docker.compose.volume=postgres_data",
    ],
    text=True,
).strip()

if volumes:
    raise SystemExit(
        "Найден существующий том PostgreSQL. "
        "Восстановите прежний .env; новый пароль не генерируется."
    )

with path.open("x") as stream:
    stream.write("POSTGRES_PASSWORD=" + secrets.token_urlsafe(32) + "\n")
    stream.write("SESSION_TTL_SECONDS=3600\n")
    stream.write("USER_CACHE_TTL_SECONDS=60\n")

path.chmod(0o600)
print(".env создан; пароль не выводится")
PY

Файл .env локальный, в Git не включается.

Создание S3-credentials и запуск

python3 scripts/setup_s3_secrets.py
python3 scripts/setup_s3_secrets.py

docker compose -f compose.yaml -f compose.s3.yaml \
  --env-file .env config --quiet

docker compose -f compose.yaml -f compose.s3.yaml \
  --env-file .env up -d --build

docker compose -f compose.yaml -f compose.s3.yaml \
  --env-file .env ps -a

curl -i --max-time 10 http://127.0.0.1:18082/health/ready

Повторный запуск setup_s3_secrets.py проверяет существующий набор ключей, не ротирует его. Неполный или противоречивый набор не перегенерируется автоматически.

SeaweedFS запускается с постоянным каталогом /data. Параметр -bucket=messenger-attachments создаёт bucket при его отсутствии. API получает отдельную учётную запись с правами Read/Write/List только на messenger-attachments. Административная конфигурация в API не монтируется.

Сервис migrate применяет SQL-миграции до запуска API. Он проверяет контрольные суммы ранее применённых миграций. Изменения ЛР 4 находятся в migrations/003_attachments.sql.

Сервис s3-check проверяет доступ к bucket с ключами API. migrate и s3-check — одноразовые сервисы; Exited (0) для них означает успех.

Дождаться healthy у обеих API-реплик и HTTP 200 от /health/ready. Единственная опубликованная точка входа API: http://127.0.0.1:18082.

Остановка с сохранением данных

docker compose -f compose.yaml -f compose.s3.yaml \
  --env-file .env stop

Намеренное удаление учебных данных

Следующая команда разрушительная: выполнять только при осознанном сбросе стенда. Она не используется в проверках restart/failover.

docker compose -f compose.yaml -f compose.s3.yaml \
  --env-file .env down -v

2. Архитектура и решения

Клиент
  → HAProxy
    → API × 2
      → PostgreSQL: пользователи, чаты, членство, сессии,
                    сообщения, идемпотентность, метаданные вложений
      → Redis: кэш пользователей
      → SeaweedFS S3: оригинальные байты изображений

Периодический cleanup
  → PostgreSQL + S3: проверка и удаление старых объектов без метаданных

Подтверждённые бизнес-данные и сессии хранятся в PostgreSQL. Redis не является единственным хранилищем сессий. Оригиналы не сохраняются в БД или постоянном локальном каталоге API.

Сохранены возможности ЛР 3: Bearer-сессии, членство в чатах, пагинация, две API-реплики, X-Instance-Id и идемпотентная отправка сообщений.

Вложения

POST /api/v1/chats/{chat_id}/attachments принимает сырые байты PNG/JPEG. Ответ 201 ready возвращается после записи оригинала в S3 и успешного выхода из транзакции записи метаданных PostgreSQL.

Ограничения:

  • максимум 10 485 760 байт;
  • максимум 40 000 000 пикселей;
  • проверка реального формата и соответствия Content-Type;
  • проверка структуры и декодирования изображения через Pillow;
  • отклонение опасных filename;
  • filename не используется как путь или S3-ключ;
  • ключ originals/ генерирует сервер;
  • оригинал не перекодируется.

Тело читается частями с подсчётом размера; весь допустимый оригинал затем удерживается в ограниченном буфере памяти. Это не zero-copy и не сквозная передача клиента напрямую в S3.

На API-реплике одновременно выполняется одна бинарная операция. Ожидание слота ограничено 3 секундами, чтение тела — 60 секундами. Перегрузка может приводить к 503. Синхронное декодирование выполняется вне основного event loop.

У download проверяются доступ, размер и SHA-256. Байты возвращает API без redirect. Публичные метаданные не содержат object_key и credentials.

Сообщения и доступ

attachment_ids возвращается и для текстовых сообщений как []. Допускается пустой/пробельный текст только при наличии вложений. До 10 уникальных вложений, порядок сохраняется.

Любой участник может прикрепить доступное вложение своего чата, даже если его загрузил другой участник. Неизвестное или вложение другого чата даёт 404.

При повторе Idempotency-Key сравниваются текст и упорядоченный список attachment_ids. Отсутствующее поле и [] эквивалентны. Повтор возвращает то же Message, другой запрос с тем же ключом — 409.

Конфигурация и secrets

Реальная конфигурация соответствует логическим ролям .env.example:

  • PostgreSQL: PGHOST, PGPORT, PGDATABASE, PGUSER; PGPASSWORD в контейнерах берётся из POSTGRES_PASSWORD локального .env;
  • сессии: SESSION_TTL_SECONDS;
  • Redis: REDIS_HOST, REDIS_PORT, USER_CACHE_TTL_SECONDS;
  • S3: S3_ENDPOINT, S3_REGION, S3_BUCKET;
  • ключи S3: S3_ACCESS_KEY_ID_FILE и S3_SECRET_ACCESS_KEY_FILE;
  • лимиты 10 MiB и 40 млн пикселей заданы константами в app/images.py;
  • две API-реплики заданы в Compose.

DATABASE_URL_FILE и CACHE_URL_FILE из шаблона не используются: выбрана конфигурация через отдельные параметры подключения. MAX_UPLOAD_BYTES и MAX_IMAGE_PIXELS не являются изменяемыми настройками текущей реализации: контрактные пределы закреплены в коде.

secrets/ исключён из Git и Docker build context. API видит только свои ключи; полный s3_config.json доступен S3-сервису. S3 и внутренние API-порты не опубликованы на хост. Admin UI SeaweedFS отключён. HTTP используется только для локального учебного стенда.

3. Согласованность S3 и PostgreSQL

Между S3 и PostgreSQL нет общей распределённой транзакции.

Перед PUT загрузчик получает PostgreSQL advisory lock для пары bucket/object_key. Блокировка удерживается до завершения транзакции метаданных. Для этой транзакции idle timeout увеличен до 60 секунд.

Если PUT прошёл, а метаданные не зафиксированы, объект может временно остаться без строки в attachments.

Очистка app.cleanup_orphans:

  1. Постранично обходит originals/.
  2. Рассматривает только управляемые ключи originals/.
  3. Пропускает объекты моложе grace period.
  4. Пробует получить ту же транзакционную блокировку.
  5. Пропускает занятый ключ.
  6. Проверяет отсутствие метаданных в PostgreSQL.
  7. Повторно проверяет LastModified через HEAD.
  8. Удаляет только старый незанятый объект без метаданных.

Объект с метаданными сохраняется, даже если ещё не прикреплён к сообщению. При ошибке проверки БД или S3 скрипт не принимает отсутствие данных за разрешение на удаление.

По умолчанию команда работает в dry-run:

docker compose -f compose.yaml -f compose.s3.yaml \
  --env-file .env run --rm --no-deps api \
  python -m app.cleanup_orphans

Сервис cleanup запускает режим apply с grace period 86 400 секунд и интервалом между обходами 3 600 секунд. При ошибке процесс завершается; используется restart: unless-stopped. Следовательно, при исправных зависимостях orphan становится кандидатом после grace period и удаляется при последующем успешном обходе.

Укороченный grace period 60 секунд использовался только в контролируемом тесте, ограниченном собственными тестовыми ключами.

4. Доказательства критериев

Критерий Команда/сценарий Наблюдение Доказательство
Структура и синтаксис make check PASS Результат ручного запуска, этот отчёт
Публичный сценарий ЛР 4 make test BASE_URL=http://127.0.0.1:18082 PASS tests/smoke.py, результат запуска
Две API-реплики docker compose ... ps -a Обе healthy Ручное наблюдение
Сохранность после restart make test-persistence BASE_URL=http://127.0.0.1:18082 ACTION_SCRIPT=scripts/restart.sh PASS, сохранены данные и прежняя сессия scripts/restart.sh, времена StartedAt до/после
Failover при записях make test-failover BASE_URL=http://127.0.0.1:18082 ACTION_SCRIPT=scripts/stop-one.sh 2 реплики, 116 успешных записей, 3 неудачные попытки, первое восстановление 2,72 с, PASS scripts/stop-one.sh, результат запуска
Оригинал после отказа загрузившей реплики Загрузка, остановка точного контейнера по X-Instance-Id, download через другую реплику Байты и SHA-256 совпали Ручной сценарий, раздел отказов
Приватность bucket Подписанный GET существующего оригинала, затем неподписанные GET объекта и списка С ключами читается; анонимно оба запроса дают 403 Ручной сценарий
Отрицательные проверки python3 tests/attachments_negative.py 22 проверки с подготовкой данных, PASS tests/attachments_negative.py
Отказ S3 python3 tests/s3_outage.py Метаданные 200, upload/download 503, оригинал после восстановления цел tests/s3_outage.py
Компенсация после PUT/rollback БД tests/cleanup_orphans_check.py в контейнере Старый orphan удалён, свежий и занятый сохранены, dry-run и повтор безопасны tests/cleanup_orphans_check.py
Прерывание загрузки tests/upload_abort_check.py в контейнере Три обрыва, новых объектов и метаданных нет, следующая загрузка успешна tests/upload_abort_check.py
Конкурентные загрузки и RAM python3 tests/upload_memory.py Два запуска по 10 клиентов, все ответы 201, новых OOM нет evidence/upload_memory.json, evidence/upload_memory.csv
Идемпотентность настройки ключей Дважды python3 scripts/setup_s3_secrets.py Existing credentials verified; keys unchanged scripts/setup_s3_secrets.py
Периодическая очистка docker compose ... logs cleanup mode=apply, grace_seconds=86400 compose.s3.yaml, app/cleanup_orphans.py

Текстовые выводы большинства проверок были просмотрены вручную. Отдельные raw-логи для каждой строки не сохранялись. Машинные результаты эксперимента памяти сохранены в evidence/.

Команды собственных контейнерных тестов

docker compose -f compose.yaml -f compose.s3.yaml --env-file .env \
  run --rm --no-deps -e PYTHONPATH=/app \
  -v "$PWD/tests/cleanup_orphans_check.py:/tmp/cleanup_orphans_check.py:ro" \
  api python /tmp/cleanup_orphans_check.py

docker compose -f compose.yaml -f compose.s3.yaml --env-file .env \
  run --rm --no-deps -e PYTHONPATH=/app \
  -v "$PWD/tests/upload_abort_check.py:/tmp/upload_abort_check.py:ro" \
  api python /tmp/upload_abort_check.py

Для cleanup-теста нужно существующее корректное вложение; его создаёт предшествующий smoke. Во время теста прерывания нельзя параллельно загружать другие файлы: он сравнивает набор S3-ключей до и после обрывов.

5. Перезапуски и отказы

Persistence

Штатная проверка завершилась:

PASS: persistence preserved confirmed data and existing session.
Hook scope needs operator evidence.

StartedAt до → после:

  • API-4: 2026-11-05T14:38:46Z → 2026-11-05T14:45:31Z;
  • API-5: 2026-11-05T14:33:11Z → 2026-11-05T14:45:32Z;
  • LB: 2026-11-05T14:33:12Z → 2026-11-05T14:45:33Z;
  • PostgreSQL: 2026-10-29T17:28:22Z → 2026-11-05T14:45:26Z;
  • Redis: 2026-10-29T17:28:22Z → 2026-11-05T14:45:26Z;
  • S3: 2026-11-05T14:31:54Z → 2026-11-05T14:45:27Z.

Времена UTC, дробные секунды в отчёте опущены. Изменение времён подтверждает перезапуск всех перечисленных компонентов, а не только API. Тома не удалялись.

Ручной failover оригинала

  • Загрузившая реплика: dbaf4bc268d2:2b8507b1cf45.
  • После её остановки скачала: 1e244991e550:6f695457e5ac.
  • SHA-256: 4258699ba0181027db1c32e7d9360339ccf87658015a24cd1424a0a5bd1b329c.
  • Сообщение с вложением сохранилось.
  • Остановленная реплика затем восстановлена.
Воздействие Наблюдение Ограничение вывода
Остановка одной API-реплики Штатный failover PASS; восстановление записи 2,72 с Не доказывает HA PostgreSQL/LB/хоста
Перезапуск API и всех хранилищ Persistence PASS с прежней сессией Проверен restart с сохранёнными томами, не потеря диска
Остановка S3 На обеих API live=200, ready=503 LB может отдавать собственную ошибку без API-заголовков
Upload/download при остановленном S3 Оба 503 unavailable Проверены прямым обращением к API в Docker-сети
Возврат S3 Readiness восстановился; оригинал скачался побайтно Точное время восстановления не измерялось
Разрыв тела upload Метаданные и S3-объекты не появились Все три проверенных обрыва пришлись на одну реплику
S3 PUT и откат БД Остался orphan, затем безопасно очищен Контролируемый rollback, не физический отказ диска

6. Эксперимент с конкурентными загрузками

Цель и методика

Гипотеза: при ограничении бинарной обработки одним слотом на реплику 10 конкурентных клиентов не вызывают одновременное декодирование 10 больших изображений и не приводят к OOM в проверенном сценарии.

Стенд: Linux amd64 в локальном Docker/WSL. Лимиты каждой API-реплики: 0,75 CPU и 512 MiB RAM. Точная модель CPU и общий объём RAM хоста в данном опыте не фиксировались.

PNG: 6000×6000, 36 000 000 пикселей, 8 540 172 байта. Изображение воспроизводимо генерируется тестом. Часть строк содержит псевдослучайные данные, остальные хорошо сжимаются.

Профиль:

  1. одиночная загрузка;
  2. 10 клиентов, синхронизированных barrier;
  3. повторный запуск 10 клиентов.

Между запусками — паузы 2 секунды. Отдельного длительного прогрева не было; первая одиночная загрузка является базовым сравнением. Для каждого запроса сохранены статус, длительность и X-Instance-Id. Прозрачные повторы upload отсутствуют.

Результаты

Сценарий Клиентов Максимум активных запросов клиента Ответы 201 Время всего запуска
single 1 1 1/1 0,7324 с
concurrent_1 10 10 10/10 2,3296 с
concurrent_2 10 10 10/10 2,2903 с

Для всех 21 ответа 201 дополнительно проверены SHA-256, size_bytes и status=ready; все проверки метаданных успешны. Это не заменяет отдельную побайтную проверку каждого из 21 оригинала.

Память

На каждую реплику собрано 130 измерений, ориентировочно раз в 100 мс.

Реплика Начальный memory.peak Итоговый memory.peak Максимум выборок memory.current Итоговый VmHWM
5d51a6717cdb 153268224 байт 273399808 байт 270393344 байт 255696 KiB
eab2fd1a7047 152104960 байт 265211904 байт 261709824 байт 253240 KiB

Итоговый пик cgroup: примерно 261 и 253 MiB при лимите 512 MiB. На обеих репликах прирост oom=0 и oom_kill=0. Состояния, времена запуска и счётчики рестартов контейнеров не изменились. Ошибок измерителя нет.

memory.peak и VmHWM — накопленные максимумы, не обнулялись. Исходные значения сохранены, итоговые выше исходных. VmRSS/VmHWM — оценочные показатели Linux. Измеритель работает внутри контейнера: его память входит в cgroup, но не в показатели процесса PID 1.

Вывод: для проверенного изображения и двух повторов нагрузки все запросы успешны, память ниже лимита, новых OOM и рестартов нет. Это не доказательство универсальной границы памяти при любой нагрузке.

Raw-данные:

  • evidence/upload_memory.json — параметры, запросы, состояния, сводка;
  • evidence/upload_memory.csv — временные выборки памяти.

Эксперимент ориентирован на RAM, а не максимальный throughput. p50/p95/p99 и CPU не использовались как критерий успеха; длительности отдельных запросов сохранены в JSON.

7. Ограничения и следующие шаги

  • Нет общей транзакции S3/PostgreSQL; окно orphan компенсирует очистка.
  • Очистка требует доступности БД и S3; при длительном отказе удаление откладывается до успешного обхода.
  • Не реализовано восстановление метаданных, для которых потерян S3-объект.
  • S3, PostgreSQL, Redis и LB — одиночные экземпляры, не кластер HA.
  • Нет утверждений о сохранности при потере диска/всего Docker-хоста.
  • В памяти удерживается целый допустимый оригинал и декодированное изображение; это ограниченная буферизация, не zero-copy.
  • При более тяжёлой нагрузке возможны документированные 503 по ожиданию слота.
  • HTTP и локальные файлы secrets — учебное упрощение для изолированного стенда.
  • Механизмы TTL идемпотентности не сокращают существующие записи автоматически: записи сохраняются дольше обязательного окна повторов.
  • Полная матрица форматов и fuzz-тестирование декодеров не выполнялись.
  • Треки уровня 5, presigned upload, фоновые варианты изображений не заявляются.

8. Источники и библиотеки

  • Контракт и задание этого репозитория: README.md, contracts/README.md, contracts/openapi.json, contracts/infrastructure.json, tests/README.md.
  • Docker Documentation: Compose, secrets, зависимости сервисов, stop/start/restart, работа с несколькими Compose-файлами.
  • SeaweedFS: справка weed mini версии 4.44, S3 Credentials.
  • PostgreSQL Documentation: Explicit Locking, advisory locks.
  • Psycopg 3 Documentation: управление транзакциями и пул соединений.
  • Boto3/Botocore Documentation: S3 PUT/GET/HEAD/LIST/DELETE, ошибки, таймауты.
  • Pillow Documentation: Image.open, verify, load, защита от больших изображений.
  • Python Documentation: urllib.request, http.client, concurrent.futures.
  • Linux Kernel Documentation: /proc, cgroup v2 memory counters.
  • Python-библиотеки: FastAPI, Uvicorn, psycopg, psycopg-pool, Redis client, argon2-cffi, boto3, Pillow.