forked from mtusi2026/mtusi2026lab4
135 lines
13 KiB
Markdown
135 lines
13 KiB
Markdown
# Отчёт — лабораторная 4
|
||
|
||
Целевая оценка: **3**. Исследовательский трек не заявлен.
|
||
Автор: Бахрамов Бахрам, БПИ2303.
|
||
Ветка: `solution/bpi2303-bakhramov`.
|
||
Репозиторий: https://gitea.privcloud.tech/bahram/mtusi2026lab4
|
||
Устройство решения и команды защиты приведены ниже.
|
||
|
||
## Запуск
|
||
|
||
Требуются Docker с Compose v2, Python 3.9+ и make на компьютере проверяющего.
|
||
Все команды выполняются из папки этой лабораторной.
|
||
|
||
```sh
|
||
cp .env.example .env
|
||
docker compose config --quiet
|
||
docker compose up -d --build
|
||
# Дождаться 200 по адресу http://localhost:8084/health/ready
|
||
curl -i http://localhost:8084/health/ready
|
||
make check
|
||
make test BASE_URL=http://localhost:8084
|
||
python3 tests/acceptance_extra.py --base-url http://localhost:8084
|
||
make test-persistence BASE_URL=http://localhost:8084 ACTION_SCRIPT=scripts/restart.sh
|
||
make test-failover BASE_URL=http://localhost:8084 ACTION_SCRIPT=scripts/stop-one.sh
|
||
# После failover одна API остаётся остановленной. Восстановить её:
|
||
docker compose up -d api1 api2
|
||
```
|
||
|
||
Порты двух лабораторных различаются, поэтому их можно запускать одновременно.
|
||
Для обычной остановки: `docker compose down` (volumes сохраняются).
|
||
Намеренный сброс только учебных данных: `docker compose down -v` (не применять при проверке persistence).
|
||
Значения .env.example — открытые демонстрационные credentials для локального стенда с синтетическими данными.
|
||
API и хранилища не публикуют порты. Только HAProxy принимает соединения на 127.0.0.1:8084.
|
||
|
||
## Архитектура и реализация
|
||
|
||
Клиент → HAProxy → api1 / api2 → PostgreSQL.
|
||
FastAPI 0.115.12, Uvicorn 0.34.2, Python 3.12.10; HAProxy 3.0.10; PostgreSQL 16.8.
|
||
Полные версии прямых Python-зависимостей закреплены в requirements.txt, образы — в compose.yaml.
|
||
Обе API работают с одной PostgreSQL; локальное состояние API не используется для сессий и сообщений.
|
||
Пароли — Argon2id, случайный Bearer-токен имеет 256 бит энтропии; в БД хранится SHA-256 токена.
|
||
Сессии имеют абсолютный expires_at, не продлеваются рестартом и отзываются DELETE.
|
||
Источник истины — PostgreSQL, подтверждённая запись читается из неё через любую реплику.
|
||
|
||
Одноразовый сервис migrate выполняет идемпотентный SQL до запуска API. Он не запускается каждой репликой.
|
||
Схема таблиц находится в migrations/001_init.sql. Пользовательские поля хранятся в JSONB,
|
||
идентификаторы и связи — также в отдельных колонках с внешними ключами.
|
||
Миграции здесь только создают начальную схему; обновление несовместимой схемы без остановки не заявляется.
|
||
|
||
Для сообщения PostgreSQL advisory transaction lock берётся по user+chat+key.
|
||
После блокировки повторно проверяется существующий результат за последние 24 часа.
|
||
Одинаковое нормализованное тело возвращает прежний Message и 201, отличающееся — 409.
|
||
Вставка сообщения и данных для повтора выполняется одной транзакцией.
|
||
При разрыве до ответа клиент повторяет тот же ключ: committed запись будет возвращена, rollback позволит новую запись.
|
||
Порядок JSON-ключей и отсутствие attachment_ids вместо [] не меняют сравнение.
|
||
|
||
HAProxy использует round-robin без sticky sessions. Каждый API сообщает hostname контейнера в X-Instance-Id.
|
||
GET /health/live проверяет процесс; /health/ready проверяет PostgreSQL, а также доступность S3 bucket.
|
||
Проверка backend идёт раз в 1 секунду; после двух неудач сервер исключается.
|
||
Connect timeout — 1 секунда, client/server timeout — 30 секунд. Это настройки обнаружения, не гарантия для любых сетевых отказов.
|
||
Docker DNS повторно разрешается HAProxy. При SIGTERM Uvicorn завершает текущие запросы до 5 секунд;
|
||
Compose даёт 10 секунд. Лимит каждой API — 512 MiB и 1 CPU.
|
||
|
||
Пагинация — keyset по (created_at,id). Cursor содержит scope и последнюю пару; от другого чата не принимается.
|
||
Это не snapshot: вставка с более ранним временем после уже прочитанного cursor может не попасть в продолжение.
|
||
Время UTC назначает API; при обычном локальном стенде контейнеры используют общие часы хоста.
|
||
|
||
## Проверки и доказательства
|
||
|
||
Проверено 12.11.2026 на Docker Desktop (Linux arm64). Все записанные проверки пройдены.
|
||
В failover наблюдались 2 разные API; за 15 секунд подтверждено 107 новых сообщений,
|
||
переходных неуспешных попыток — 6; первая успешная запись после воздействия — 0.97 с.
|
||
Подтверждённые данные и прежняя сессия сохранились. Это результат одного локального запуска, не SLA.
|
||
Фактические команды и результаты находятся в evidence/verification.txt.
|
||
Повторить полный набор: `python3 scripts/verify.py > evidence/verification.txt 2>&1`.
|
||
Публичные contracts/ и tests/smoke.py, tests/resilience.py не изменены.
|
||
|
||
| Требование на 3 | Проверка | Доказательство |
|
||
| --- | --- | --- |
|
||
| Один LB и две API с общей БД/сессиями | docker compose ps; failover наблюдает разные X-Instance-Id одной сессии | evidence/verification.txt |
|
||
| Обязательный API и ошибки | make test | evidence/verification.txt |
|
||
| Конкурентный повтор без дублей | 16 запросов с одним ключом через LB | tests/acceptance_extra.py; evidence/verification.txt |
|
||
| Остановка выбранной реальной API, восстановление чтения/записи ≤10 секунд | make test-failover, hook сопоставляет X-Instance-Id с hostname и останавливает контейнер | scripts/stop-one.sh; evidence/verification.txt |
|
||
| Сохранность пользователей, чатов, сообщений и действующих сессий после restart всех хранилищ | make test-persistence; сравнение StartedAt до/после | scripts/restart.sh; evidence/verification.txt |
|
||
|
||
## Вложения и S3
|
||
|
||
SeaweedFS 3.85 запускается одним S3-сервером в общем Compose. Его master, volume и filer
|
||
сохраняют данные в s3_data, рабочий каталог — /data. PostgreSQL хранит только метаданные, не байты.
|
||
Приватный bucket attachments создаётся отдельным bucket-init с повторными попытками до старта API.
|
||
Анонимной identity в infra/s3.json нет; S3 доступен только внутри Compose-сети, публичной policy нет.
|
||
Для уровня 3 API использует ту же учебную identity, что bootstrap; отдельные минимальные права не заявляются.
|
||
Если менять S3 credentials, нужно согласованно изменить .env и infra/s3.json.
|
||
|
||
Upload принимает сырые PNG/JPEG. Байты читаются порциями с пределом 10 MiB до декодирования;
|
||
Pillow проверяет реальный формат, соответствие MIME, целостность и предел 40 млн пикселей.
|
||
Имя не используется в S3: object key — UUID, назначенный сервером. Slash, backslash и управляющие символы отклоняются.
|
||
201 ready возвращается после S3 PUT и PostgreSQL COMMIT. Download проверяет участника чата и отдаёт исходные байты через API.
|
||
attachment_ids валидируются на принадлежность тому же чату; допустимо сообщение без текста с вложением.
|
||
|
||
| Требование на 3 | Проверка | Доказательство |
|
||
| --- | --- | --- |
|
||
| Побайтный оригинал, SHA-256, attachment_ids, запрет постороннему | make test | evidence/verification.txt |
|
||
| Upload → остановка загрузившей API → download через вторую, отдельно для api1 и api2 | tests/attachment_failover.py | evidence/attachment_failover.txt |
|
||
| Сохранность метаданных и оригинала после рестарта PostgreSQL и S3 | make test-persistence | evidence/verification.txt |
|
||
| Опасное имя, подмена MIME, повреждение, >10 MiB, >40 млн пикселей; настоящий JPEG; вложение другого чата | tests/acceptance_extra.py | evidence/extra_images.txt |
|
||
| Отказ S3 | tests/storage_failure.py | evidence/verification.txt |
|
||
| Анонимный S3 GET не возвращает объект | запрос из внутренней сети без подписи | evidence/verification.txt |
|
||
|
||
Для обеих API проверено: после остановки принявшей upload реплики другая отдала тот же SHA-256; время — 0,826 с (api1) и 1,498 с (api2). Подробности в evidence/attachment_failover.txt.
|
||
|
||
Команда дополнительного сценария: `python3 tests/storage_failure.py --base-url http://localhost:8084`.
|
||
|
||
Согласованность: сначала S3 PUT, затем INSERT/COMMIT метаданных. При сбое БД между ними возможен orphan object.
|
||
Автоматической сверки и очистки нет — это ограничение уровня 3, а не выполненный критерий уровня 4.
|
||
При отказе S3 ready и upload возвращают 503; HAProxy исключает неготовые API.
|
||
Повтор upload не идемпотентен и может создать ещё одно вложение.
|
||
Один файл хранится в памяти до 10 MiB, декодированное изображение — до 40 млн пикселей;
|
||
потоковая передача и эксперимент на 10 параллельных загрузках не заявлены.
|
||
|
||
## Ограничения
|
||
|
||
Устойчивость проверяется только при отказе одной API-реплики. LB, PostgreSQL и хост — единичные точки отказа.
|
||
Бэкапы, репликация БД, rolling update и нагрузочное исследование не реализованы.
|
||
HTTP предназначен для локальных синтетических данных. Уровни 4 и 5 не заявлены.
|
||
|
||
## Источники
|
||
|
||
- Исходное задание и неизменённый контракт: https://gitea.privcloud.tech/mtusi2026/mtusi2026lab4
|
||
- PostgreSQL advisory locks: https://www.postgresql.org/docs/16/explicit-locking.html#ADVISORY-LOCKS
|
||
- HAProxy configuration: https://docs.haproxy.org/3.0/configuration.html
|
||
- Docker Compose: https://docs.docker.com/compose/
|
||
- Argon2: https://argon2-cffi.readthedocs.io/
|
||
- SeaweedFS S3 identity configuration: https://github.com/seaweedfs/seaweedfs/blob/3.85/docker/compose/s3.json
|