Files
mtusi2026lab4/REPORT.md
T

34 KiB
Raw Blame History

Отчёт — лабораторная 4

  • Автор, группа: Мусаев Абдул-Хамид Рамзанович, БВТ-2303
  • Целевая оценка; выбранный трек 5, если нужен: 4, трек 5 не заявлен
  • Commit/PR: #42
  • Использованные источники, библиотеки и помощь ИИ:
    • библиотеки и образы: FastAPI 0.143.0, Uvicorn 0.54.0, psycopg 3.3.6, redis-py 8.1.0, argon2-cffi 25.1.0, boto3 1.43.122, HAProxy 3.2.26, PostgreSQL 17.11, Redis 7.4.11, SeaweedFS 4.50 (полный список в requirements.txt, compose.yaml, infra/);
    • источники: документация SeaweedFS (S3 API, конфигурация ключей), AWS S3 и boto3, спецификации PNG и JPEG (структура блоков и маркеров), contracts/README.md;
    • помощь ИИ: ИИ-ассистент использовался во вспомогательных целях.

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

Нужны Docker с Compose v2 (проверено на Docker 29.3.0, Compose 5.1.0), make, openssl, curl и Python 3.9+ на хосте для тестов.

make up             # создаёт .env с паролями и ключами, собирает образы, поднимает стенд и ждёт /health/ready

make check          # структура skeleton
make test           # публичный smoke
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
make restore        # вернуть реплику, остановленную failover-тестом

make attachment-demo # сценарий защиты: файл, сообщение, посторонний, прямой GET в S3
make student-test   # тесты API, вложений и разбора изображений
make test-failures  # сбой между S3 и БД, отказ S3, приватность bucket, отказ Redis и PostgreSQL
make upload-peak    # 1, 10 и 30 одновременных загрузок по 10 MiB с замером памяти
make janitor        # один проход очистки вручную
make failover-each  # остановка каждой реплики под нагрузкой
make rolling-update APP_VERSION=2
make explain        # синтетическая история и планы запросов

make down           # остановить контейнеры, данные остаются в volumes
make clean          # то же и удалить volumes: намеренное удаление учебных данных

Bucket и миграции отдельных команд не требуют: при up одноразовые контейнеры s3-init и migrate выполняются до старта реплик.

make test-failures сам останавливает и запускает redis, postgres, s3 и удаляет синтетические объекты, поэтому запускать его нужно только на учебном стенде. Прогон занимает около 5 минут.

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

              edge                     data (internal)
клиент ──> lb (HAProxy) ──┬──> api-1 ──┬──> postgres: метаданные, сообщения, ключи идемпотентности
      127.0.0.1:8080      └──> api-2 ──┼──> redis:    сессии
                                       │
                                       │   storage (internal)
                                       └──> s3 (SeaweedFS): байты вложений, приватный bucket
                                            ▲
                          janitor ──────────┘ также data: очистка незавершённых загрузок

s3-init, migrate: одноразовые контейнеры до старта реплик

Роли и сервисы

Роль Сервис Образ Готовность Volume Сеть и порт Лимиты Секреты
load_balancer lb infra/haproxy на haproxy:3.2.26-alpine /lb-health нет edge, опубликован только 127.0.0.1:8080 0,5 CPU, 128 МБ нет
api api, 2 реплики Dockerfile на python:3.13.16-slim-bookworm /health/ready нет, состояния не хранит edge, data, storage, порт не опубликован 1 CPU, 256 МБ БД, Redis, S3-ключ API
очистка janitor тот же образ нет, цикл с логом нет data, storage 0,25 CPU, 128 МБ БД, S3-ключ janitor
bootstrap migrate, s3-init тот же образ одноразовые, код выхода 0 нет data; storage 0,5 CPU, 128 МБ БД; S3-ключ admin
s3 s3 infra/s3 на chrislusf/seaweedfs:4.50 том данных зарегистрирован в мастере и S3 отвечает s3data storage, порт 9000 не опубликован 1 CPU, 1 ГБ все три S3-ключа
postgres postgres postgres:17.11-alpine pg_isready pgdata data 1 CPU, 512 МБ пароль файлом
redis redis redis:7.4.11-alpine redis-cli ping redisdata data 0,5 CPU, 128 МБ пароль файлом

Секреты описаны как secrets с источником из .env и попадают в контейнеры файлами в /run/secrets. Ключа администратора S3 у API нет (evidence/10-containers.txt).

Почему SeaweedFS. В задании на выбор MinIO, SeaweedFS или RustFS. Образы minio/minio и minio/mc на этом стенде из реестра не скачались («repository does not exist»), а зависеть от локального кэша нельзя: стенд должен собираться из чистого clone. У SeaweedFS права ключей задаются обычным JSON, отдельный административный клиент не нужен.

Модель данных и запись файла

Таблица attachments: чат, владелец, отображаемое имя, тип, размер, sha256, object_key, state. Таблица message_attachments: связь сообщения с вложениями и их порядок. Одно вложение можно прикрепить к нескольким сообщениям, контракт это допускает. Ключ объекта — originals/<uuid>, его назначает сервер; имя файла в нём не участвует и используется только для показа. В S3 не передаётся ни имя файла, ни id пользователя.

Загрузка в POST /api/v1/chats/{id}/attachments:

  1. Проверки до чтения тела: токен → членство в чате (посторонний 404) → имя файла → Content-Type → Content-Length → лимит параллельных загрузок.
  2. Тело пишется блоками во временный файл без имени, считается размер и sha256. Превышение 10 MiB обрывает приём сразу.
  3. Содержимое проверяется в src/images.py, после чего загрузка ждёт очереди на запись в S3.
  4. Запись в три шага: строка pending в PostgreSQL (COMMIT) → PUT в S3 → UPDATE ... state = 'ready' (COMMIT).
  5. Только после этого ответ 201 status=ready.

Статус pending внутренний: такое вложение нельзя получить через API и прикрепить к сообщению, контракт видит только ready.

Что если S3 PUT прошёл, а COMMIT нет

Главное решение: строка в БД появляется раньше объекта. Поэтому в S3 не может появиться объект, о котором БД ничего не знает, а любой сбой оставляет понятное состояние.

Где произошёл сбой Что осталось Что видит клиент Что происходит дальше
обрыв клиента при приёме файла ничего: временный файл удаляется, S3 и БД не тронуты соединение оборвано ничего не нужно
БД недоступна до записи строки ничего 503 ничего не нужно
PUT в S3 не прошёл строка pending 503 janitor удаляет строку после grace period
PUT прошёл, подтверждение не прошло строка pending и объект 503 janitor удаляет объект, затем строку
реплика упала посреди записи то же ошибка от балансировщика то же

Механизм очистки — сервис janitor (src/janitor.py), свой S3-ключ, проход раз в 5 минут:

  1. Строки pending старше grace period: сначала удаляется объект, потом строка. Если упасть посередине, следующий проход повторит то же самое; удаление отсутствующего объекта безопасно.
  2. Сверка: объекты старше grace period без строки в БД удаляются. Обычно таких нет, это защита от потери строки, например при восстановлении БД из старой копии. Сверка идёт постранично.

Grace period — 1 час (ATTACHMENT_GRACE_SECONDS), он намного больше самой долгой загрузки: приём файла не больше 60 с, очередь 10 с, S3 7 с. Свежая незавершённая загрузка этим не затрагивается, вложения ready не удаляются никогда. Если очень медленная загрузка всё же проснётся после очистки, UPDATE не найдёт строку, и клиент получит 503, а не ложный 201.

--dry-run только считает, --grace-seconds меняет порог для проверок.

Потоковая обработка и лимиты

Ограничение Значение Что будет при превышении
размер файла 10 MiB (MAX_UPLOAD_BYTES) 413; по Content-Length сразу, без него на ходу приёма
грубый предел на балансировщике 11 MiB 413 до API
пиксели 40 млн (MAX_IMAGE_PIXELS) 413 из заголовка, без распаковки
тело JSON-запроса 1 MiB 413
время приёма файла 60 с 400
загрузок на реплику 32 429 с Retry-After
одновременных записей в S3 с реплики 4 ждёт очереди до 10 с, затем 503
соединение / чтение S3 2 с / 5 с, без повторов 503

В памяти одновременно находится только текущий блок: тело читается потоком, файл уходит в S3 из временного файла, скачивание отдаётся блоками по 64 КБ.

Проверка изображения без декодирования (src/images.py). Пиксели в память не распаковываются, поэтому decompression bomb не опасна: размер берётся из заголовка до любой работы с данными. PNG: сигнатура, порядок блоков, CRC каждого блока, потоковая распаковка IDAT с выбрасыванием результата, сверка объёма данных с размером изображения, запрет данных после IEND. JPEG: структура маркеров, наличие кадра и скана, маркер конца. Настоящий тип должен совпасть с Content-Type, иначе 415. Pillow не используется: полное декодирование 40 млн пикселей заняло бы около 120 МБ на файл при лимите реплики 256 МБ.

Имя файла. 1–255 символов Unicode, запрещены /, \, NUL, управляющие символы, символы смены направления текста (ими маскируют расширение), строки из пробелов, . и ...

Доступ и приватность

Bucket приватный: в конфигурации сервера нет анонимного пользователя, запрос без подписи получает 403. Скачивание идёт только через API, без redirect. Каждый запрос проверяет членство в чате; посторонний получает тот же 404, что и при несуществующем вложении. Случайный ключ и приватность bucket этой проверки не заменяют: они защищают от доступа в обход API, но не решают, кому из пользователей можно видеть файл.

Ключ S3 Кто использует Права Проверено
admin s3-init всё используется только при создании bucket
api реплики чтение и запись объектов этого bucket список объектов, создание и удаление bucket — AccessDenied
janitor очистка список и запись (удаление) объектов этого bucket чтение не выдано

Ограничение SeaweedFS: право Write включает удаление объекта, поэтому ключ API может удалить объект, зная его ключ. Полностью разделить «запись» и «удаление» этими средствами не удалось.

Административного интерфейса наружу нет: порты s3 не опубликованы, сеть storage внутренняя, в ней только s3, API, janitor и s3-init. Веб-страница мастера SeaweedFS (9333) доступна только внутри этой сети.

Отказ S3 и готовность

/health/ready не проверяет S3 намеренно: текст, история и метаданные работают без него. Если бы реплики становились неготовыми, отказ S3 остановил бы весь мессенджер. При недоступном S3 загрузка и скачивание дают 503, остальное работает (test_s3_down).

Готовность самого контейнера s3 проверяет регистрацию тома в мастере. Порт S3 открывается раньше, а до этого запросы к объектам зависают. После перезапуска на это уходит 20–30 с, scripts/restart.sh ждёт. На пустом хранилище первая запись запускает создание томов дольше таймаута API, поэтому s3-init делает пробную запись, чтение и удаление, и реплики стартуют только после неё.

Идемпотентность с вложениями

Ключ, сообщение и ссылки на вложения пишутся одной транзакцией. Проверка вложений (готово и лежит в этом чате) выполняется в ней же: чужое или неизвестное вложение даёт 404 и откатывает занятие ключа, поэтому ключ можно использовать снова. Повтор сравнивается по тексту и списку attachment_ids; отсутствующий список равен пустому, другой список — 409.

Что перенесено из lab3 и что изменено

Перенесены: балансировщик и реплики, сессии в Redis, идемпотентность, миграции, поочерёдная замена, строгий разбор JSON, все тесты. Добавлены: сервисы s3, s3-init, janitor, сеть storage, миграция 0003, endpoint вложений, поле attachment_ids. Изменено: timeout server балансировщика 20 с вместо 12; строгие лимиты тела JSON (раньше лимита не было). Миграция 0003 снимает требование непустого текста и добавляет таблицы, версия lab3 на такой схеме продолжила бы работать; совместная работа разных версий не проверялась.

Соответствие переменных окружения

Переменная По умолчанию Что делает
S3_ENDPOINT, S3_REGION, S3_BUCKET http://s3:9000, us-east-1, messenger-attachments адрес и bucket; endpoint в compose задан жёстко
S3_ACCESS_KEY_ID_FILE, S3_SECRET_ACCESS_KEY_FILE /run/secrets/... ключ API
MAX_UPLOAD_BYTES, MAX_IMAGE_PIXELS 10485760, 40000000 лимиты контракта
MAX_PARALLEL_UPLOADS, UPLOAD_TIMEOUT_SECONDS 32, 60 загрузок на реплику, время приёма
S3_PARALLEL_WRITES, S3_WRITE_QUEUE_SECONDS 4, 10 записей в S3 с реплики, ожидание очереди
ATTACHMENT_GRACE_SECONDS, JANITOR_INTERVAL_SECONDS 3600, 300 возраст брошенной загрузки, период проходов
S3_ADMIN_*, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY, S3_JANITOR_* создаёт init-env.sh источник compose-секретов
остальные см. .env.example как в lab3

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

Стенд: Apple M3 Pro, 11 CPU, 18 ГБ RAM, macOS 26.1, Docker 29.3.0, Compose 5.1.0. Лимиты контейнеров в таблице ролей. Все файлы получены из чистого clone на пустых volumes; код в них совпадает с коммитом этого PR.

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Публичный smoke сразу после чистого запуска make up, make test PASS: lab4 public API scenario evidence/01-up-and-smoke.txt
3: S3 в общем стенде, метаданные в PostgreSQL, байты в приватном bucket make up, make attachment-demo сервис s3, прямой GET без подписи 403 evidence/01-up-and-smoke.txt, evidence/02-defense-scenario.txt
3: 201 ready, побайтное скачивание, сообщение с вложением, посторонний 404 make attachment-demo, test_attachments.py sha256 совпал, посторонний 404 на метаданные и байты evidence/02-defense-scenario.txt, evidence/03-student-tests.txt
3: PNG/JPEG ≤10 MiB и ≤40 млн пикселей, проверка по содержимому, опасные имена test_attachments.py, test_images.py ровно 10 MiB — 201, на байт больше — 413; bomb — 413; подмена — 415 evidence/03-student-tests.txt
3: upload → остановка реплики → download через другую make test-failover, 2 прогона PASS, контейнер exited, файл скачан и совпал evidence/05-failover-public.txt
3: restart сохраняет метаданные и оригинал make test-persistence PASS, новое время старта у всех контейнеров, включая s3 evidence/04-persistence.txt
4: большой файл, повреждённое изображение, подмена MIME, чужой id, файл другого чата test_attachments.py 413, 415, 415, 404, 404; ни одного 500 evidence/03-student-tests.txt
4: прерывание загрузки и отказ между S3 и БД test_storage.py, настоящий kill PostgreSQL при 12 потоках загрузки 8 объектов остались в S3 без подтверждения; после очистки S3 и БД совпадают, 6 подтверждённых файлов скачиваются evidence/08-failures.txt
4: grace period и безопасность очистки test_grace_period_protects_fresh_upload, test_ready_attachments_are_never_removed свежий pending и ready не тронуты evidence/08-failures.txt
4: лимиты, потоковая обработка, ≥10 одновременных загрузок, пик памяти make upload-peak, 5 прогонов см. таблицу ниже, OOM 0 evidence/09-upload-memory.txt, evidence/upload-peak.json
4: bootstrap идемпотентен docker compose run --rm s3-init bucket уже есть, объекты не изменились evidence/04-persistence.txt, evidence/08-failures.txt
4: отдельный S3-ключ с ограниченными правами test_bucket_is_private_and_api_key_is_limited list, create, delete bucket — AccessDenied evidence/08-failures.txt
4: консоль не открыта, проверка private bucket вне API docker compose ps, тот же тест порты s3 не опубликованы, анонимный GET 403 evidence/10-containers.txt, evidence/08-failures.txt
Отказ S3 test_s3_down, test_failed_upload_is_cleaned 503 на файлах, текст и готовность работают, pending убран evidence/08-failures.txt
Возможности lab3: failover, поочерёдная замена make failover-each, make rolling-update см. таблицу ниже evidence/06-failover-each.txt, evidence/07-rolling-update.txt
Возможности lab2 и lab1: истечение, отказы, индекс, SIGTERM make test-failures, make explain, sigterm_check.py тесты ok, Index Scan, выход за 1,73 с evidence/08-failures.txt, evidence/12-explain.txt, evidence/11-sigterm.txt

Собственные тесты: 142 в make student-test (39 вложения, 16 разбор изображений, остальные API) и 27 в make test-failures (12 про хранение). test_images.py дополнительно портит настоящие изображения случайными байтами 12 000 раз и проверяет, что разбор не падает.

Эксперименты и отказы

Память при одновременных загрузках

Гипотеза: при потоковой обработке пик памяти процесса почти не зависит от числа загрузок. Методика (scripts/upload_peak.py): реплики перезапускаются, затем идут 1, 10 и 30 одновременных загрузок через балансировщик настоящего PNG 10 481 664 байт. Измеряется VmHWM процесса (пик RSS) на обеих репликах. 5 прогонов подряд.

Параллельно Время, с (мин–макс) Успешных Пик RSS реплики, МиБ
0 (после старта) — ��” 117
1 0,14–1,83 5 из 5 117–118
10 1,29–3,87 50 из 50 124–126
30 3,79–6,43 150 из 150 126–129

Вывод: 30 файлов общим объёмом 300 МиБ добавили к пику примерно 12 МиБ, гипотеза подтверждается. Наивная версия, держащая файлы в памяти, потребовала бы около 150 МиБ на реплику сверх базовых 117 и упёрлась бы в лимит 256 МБ.

Ограничение измерения: memory.peak контейнера доходит до лимита 256 МБ, но в него входит кэш страниц временных файлов, который система освобождает. OOM на репликах не было. Разброс времени большой: S3 и генератор нагрузки работают на одном компьютере.

Что эксперимент нашёл по дороге

  • Первая версия замера была недействительна. Генератор PNG сжимал повторяющиеся строки, файлы оказались по 72 КБ вместо 10 МиБ. Заметил по полю file_bytes. Теперь пиксели случайные, а размер проверяется тестом.
  • S3 падал под нагрузкой. С настоящими файлами 30 параллельных загрузок дали 503, причём нестабильно: то проходили, то нет. Причины две. Сначала S3 не успевал за таймаут, поэтому появилась очередь записи вместо увеличения таймаута. Затем выяснилось, что контейнер убивается OOM killer при лимите 512 МБ (die exit=137). Лимит поднят до 1 ГБ, Go получил мягкий предел GOMEMLIMIT. Поэтому прогонов 5, а не 1.
  • Первая загрузка на пустом стенде падала с 503, это нашёл только прогон из чистого clone. Описано в разделе про готовность.

Сбой между S3 и БД

Гипотеза: при любом сбое после очистки множество объектов S3 совпадает со строками ready, а подтверждённые файлы целы. Методика (test_postgres_lost_during_parallel_uploads): 12 потоков загружают файлы по 3 МиБ, через 0,25 с PostgreSQL убивается (docker compose kill), затем запускается, выполняется проход janitor. Результат: 6 файлов подтверждено (3 из них до сбоя), 8 объектов осталось в S3 без подтверждения, после очистки расхождений нет, подтверждённые файлы скачиваются с верным sha256. Состав окна зависит от момента сбоя, поэтому 3 подтверждения делаются заранее: проверка сохранности не может оказаться пустой.

Остальные отказы

Нагрузка scripts/chaos.py та же, что в lab3: 4 клиента пишут текстовые сообщения, неопределённый результат повторяется с тем же ключом.

Воздействие Реплика Длительность, с Успешных RPS Ошибок Исключена LB через, с Пауза записи, с Потери / дубли
docker stop 1 17,89 10 761 602 0 0,90 1,03 0 / 0
docker stop 2 19,96 11 872 595 0 1,51 1,02 0 / 0
rolling update, 15,5 с обе 25,51 17 974 705 0 — 1,00 0 / 0
Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
upload, остановка реплики, download файл доступен через другую реплику PASS, запись восстановилась за 1,7–2,0 с потерь нет
docker compose restart всего стенда данные, сессия и файл на месте PASS, прежний токен скачал прежний файл 20–30 с на S3, потерь нет
docker compose stop s3 файлы 503, остальное работает загрузка и скачивание 503, текст 201, /health/ready 200 20–30 с после запуска
kill postgres при загрузках неподтверждённое убрано, подтверждённое цело см. выше очистка при следующем проходе после grace period
обрыв 4 загрузок клиентом ничего не остаётся S3 и attachments не изменились —

Индекс истории (make explain, 101 045 сообщений, 10 000 в чате). К истории добавился подзапрос attachment_ids, это 1 буфер на сообщение, поэтому числа выше, чем в lab3, но характер тот же:

Запрос Буферов Время
первая страница 63 0,255 мс
страница после 5000-го сообщения, keyset 59 0,232 мс
та же страница через OFFSET 5552 5,152 мс
keyset без индекса 1454 3,202 мс

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

  • Не выдерживается отказ lb, postgres, redis, s3 или хоста: всё в одном экземпляре на одном Docker-хосте. У S3 один том без репликации, потеря s3data означает потерю файлов. Резервных копий нет.
  • JPEG проверяется по структуре: порча внутри сжатых данных не обнаруживается, для этого нужно декодирование. У PNG содержимое проверяется полностью.
  • Ключ API может удалять объекты (ограничение прав SeaweedFS).
  • Вложение ready, не прикреплённое ни к одному сообщению, хранится бессрочно: контракт разрешает прикрепить его позже, а механизма удаления в API нет.
  • Сверка находит лишние объекты, но не обратный случай: строка ready, а объект потерян. Такое скачивание даст 503, автоматического обнаружения нет.
  • На диске реплики временно может лежать до 32 файлов по 10 MiB, файлы не шифруются и исчезают после обработки. Это не хранилище: реплика не нужна для чтения файла.
  • При нагрузке выше пропускной способности S3 загрузки получают 503 после 10 с очереди. Предел в числах не измерялся.
  • Записи idempotency_keys с истёкшим сроком не очищаются.
  • SeaweedFS пишет предупреждение о gRPC IAM без аутентификации на filer: порт доступен только внутри сети storage.
  • Ответ при Content-Length больше лимита приходит сразу, клиент может не успеть его прочитать, если продолжает отправку: это обычное поведение HTTP.
  • X-Instance-Id раскрывает короткий id контейнера. В lab7 нужен alias.
  • Проверено на одном стенде (macOS, Docker Desktop). На Linux не запускалось. Генератор нагрузки работал на том же компьютере, замеры дают порядок величин, а не предел стенда.