176 lines
17 KiB
Markdown
176 lines
17 KiB
Markdown
# Отчёт — лабораторная 4
|
||
|
||
- Автор, группа: Герейханов Ильяс, БВТ2301
|
||
- Целевая оценка: 4
|
||
- Commit/PR: ветка `solution/bvt2301-Gereykhanov`. PR: `ЛР 4 — БВТ2301 — Герейханов — на 4`
|
||
- Использованные источники, библиотеки и помощь ИИ: Python 3.12, FastAPI, Uvicorn, PostgreSQL 16, Redis 7, Nginx 1.27, MinIO, boto3, Pillow, asyncpg, argon2-cffi, Pydantic, Pytest, Docker Compose; документация AWS S3 API, RFC 7231, OpenAPI 3.1.0. ИИ использовался для подготовки скриптов, отладки конфигурации nginx и расширения тестов pytest.
|
||
|
||
## Запуск из чистого clone
|
||
|
||
1. **Версии runtime и образов:**
|
||
- Локальный runtime: Linux, Docker 29.9.1, Docker Compose v5.6.0
|
||
- Load Balancer: `nginx:1.27-alpine`
|
||
- API контейнеры: `python:3.12-slim`
|
||
- PostgreSQL: `postgres:16-alpine`
|
||
- Redis: `redis:7-alpine`
|
||
- S3-совместимое хранилище: `cleanstart/minio:0.20260330.001845`
|
||
|
||
2. **Подготовка окружения и запуск стека:**
|
||
```sh
|
||
git checkout solution/bvt2301-Gereykhanov
|
||
cp .env.example .env
|
||
|
||
# Сборка и запуск всех сервисов
|
||
make up
|
||
```
|
||
|
||
3. **Ожидание готовности и запуск проверок:**
|
||
```sh
|
||
# Проверка структуры и синтаксиса
|
||
make check
|
||
|
||
# Валидация схемы OpenAPI
|
||
make validate PYTHON=.venv/bin/python
|
||
|
||
# Проверка smoke теста
|
||
make test
|
||
|
||
# Проверка сценария сохранности данных и сессий при рестарте
|
||
make test-persistence ACTION_SCRIPT=scripts/restart.sh
|
||
|
||
# Проверка отказоустойчивости при отключении одной API-реплики
|
||
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
|
||
|
||
# Восстановление остановленной реплики после теста
|
||
docker compose up -d
|
||
|
||
# Запуск собственных тестов
|
||
make test-student
|
||
|
||
# Запуск нагрузочного теста
|
||
python3 tests/load.py --duration 30 --concurrency 4 --output evidence/load.json
|
||
```
|
||
|
||
4. **Остановка и очистка:**
|
||
```sh
|
||
# Остановка с сохранением данных volumes
|
||
docker compose down
|
||
|
||
# Остановка с удалением volumes
|
||
docker compose down -v
|
||
```
|
||
|
||
## Архитектура и решения
|
||
|
||
- **Топология процессов и распределение ролей:**
|
||
- **Клиент** отправляет все HTTP-запросы в единую точку входа **Nginx Load Balancer** на порт `8080`.
|
||
- **Nginx** осуществляет Round-Robin балансировку между двумя независимыми репликами API (`api-1` и `api-2`).
|
||
- Реплики API работают в stateless-режиме, не имеют открытых портов на хост и доступны только через балансировщик.
|
||
- Каждая реплика API обращается к общему **PostgreSQL**, **Redis** и **MinIO S3**.
|
||
- Отдельный одноразовый контейнер **migration** применяет `init.sql` перед стартом API-реплик.
|
||
|
||
- **Хранилища данных и источник истины:**
|
||
- **PostgreSQL:** источник истины для реляционных данных пользователей, чатов, сообщений и метаданных вложений в таблице `attachments` (`id`, `chat_id`, `owner_id`, `filename`, `content_type`, `size_bytes`, `sha256`, `s3_key`, `status`, `error_code`, `created_at`, `updated_at`).
|
||
- **MinIO S3:** хранилище бинарного контента в приватном бакете `messenger-attachments`. Ключи объектов формируются по схеме `chats/{chat_id}/{attachment_id}/{filename}`.
|
||
- **Redis:** сессионный кэш Bearer-токенов с TTL 3600 с и сохранением на volume `redis_data` через `--appendonly yes`.
|
||
|
||
- **Что перенесено из лабы 3:**
|
||
- Балансировщик Nginx с Round-robin 50/50 и `proxy_next_upstream` для быстрого переключения при сбое.
|
||
- Сквозные заголовки `X-Request-Id` и `X-Instance-Id` в ответах API.
|
||
- Единое хранилище сессий в Redis.
|
||
- Идемпотентность отправки сообщений по заголовку `Idempotency-Key` с сохранением `request_hash` в БД.
|
||
- Keyset-пагинация сообщений по индексу.
|
||
|
||
- **Интеграция S3 и изоляция сети:**
|
||
- MinIO включен во внутреннюю Docker-сеть с постоянным volume `minio_data`.
|
||
- Порты MinIO не проброшены на хост наружу, консоль закрыта от общей сети.
|
||
- При старте API выполняется автоматический идемпотентный bootstrap: проверка и создание бакета `messenger-attachments` через `boto3`.
|
||
|
||
- **Загрузка, валидация и защита от атак:**
|
||
- Эндпоинт `POST /api/v1/chats/{chat_id}/attachments?filename=...` принимает сырое бинарное тело (PNG/JPEG) до 10 MiB.
|
||
- **Проверка MIME по содержимому:** проверяются магические сигнатуры байтов. Невалидные форматы отклоняются с кодом `415`.
|
||
- **Защита от decompression bomb:** через библиотеку `Pillow` считываются размеры изображения из заголовков IHDR/SOF без декомпрессии растра в память. Превышение лимита 40 млн пикселей возвращает `413 payload_too_large`.
|
||
- **Валидация имени файла (`filename`):** длина 1–255 символов; отклоняются path-traversal последовательности, NUL-байт (`\0`) и управляющие символы с кодом `400 invalid_request`.
|
||
|
||
- **Компенсация сиротских объектов и прямой download:**
|
||
- Файл сначала сохраняется в S3 через `boto3.put_object`, после чего выполняется запись метаданных в базу. При ошибке в БД блок `except` вызывает `s3_client.delete_object`, удаляя объект из S3.
|
||
- Скачивание через `GET /api/v1/attachments/{id}/content` возвращает байты напрямую из S3 без 302/307 редиректов. Запрос от постороннего возвращает строго `404 not_found`.
|
||
|
||
- **Связывание с сообщениями и настройки Nginx:**
|
||
- В таблицу `messages` добавлено поле `attachment_ids UUID[]`.
|
||
- Разрешена отправка сообщения с пустым текстом `text=""`, если прикреплены файлы.
|
||
- В `infra/nginx.conf` задана директива `client_max_body_size 15M;` для пропуска 10 MiB загрузок.
|
||
- Все параметры согласованы с `.env.example`: `S3_ENDPOINT`, `S3_BUCKET`, `MAX_UPLOAD_BYTES`, `MAX_IMAGE_PIXELS`.
|
||
|
||
## Доказательства критериев
|
||
|
||
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|
||
| --- | --- | --- | --- |
|
||
| Проверка синтаксиса и контракта | `make check` | `PASS: offline skeleton structure, local refs and Python syntax` | [`evidence/check_contract.log`](evidence/check_contract.log) |
|
||
| Полная OpenAPI 3.1 валидация | `make validate PYTHON=.venv/bin/python` | `PASS: full OpenAPI 3.1 and JSON Schema validation` | [`evidence/validate_openapi.log`](evidence/validate_openapi.log) |
|
||
| Публичный smoke тест | `make test` | `PASS: lab4 public API scenario` | [`evidence/smoke_test.log`](evidence/smoke_test.log) |
|
||
| Чередование реплик | `for i in {1..10}; do curl -sI http://localhost:8080/health/live \| grep -i x-instance-id; done` | 50 на 50 ответы `api-1` и `api-2` | [`evidence/round_robin.log`](evidence/round_robin.log) |
|
||
| Сохранение данных и сессий при рестарте | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | Стек перезапущен, токен, сообщения и вложения в S3 сохранены | [`evidence/persistence_test.log`](evidence/persistence_test.log) |
|
||
| Отказ API-реплики под нагрузкой | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` | Восстановление записи за **0.778 с**, 105 успешных запросов, 0 сбоев | [`evidence/failover_test.log`](evidence/failover_test.log) |
|
||
| Защита от decompression bomb (>40M px) | `make test-student` | Запрос с 50M px изображением отклонен с `413 payload_too_large` | [`evidence/student_tests.log`](evidence/student_tests.log) |
|
||
| Проверка MIME по магическим байтам | `make test-student` | Поддельные и поврежденные изображения отклоняются с `415` | [`evidence/student_tests.log`](evidence/student_tests.log) |
|
||
| Компенсация сирот S3 при отказе БД | `make test-student` | При сбое PostgreSQL объект удаляется из S3, в хранилище нет сирот | [`evidence/student_tests.log`](evidence/student_tests.log) |
|
||
| Закрытый бакет и лимит RAM (10 загрузок) | `make test-student` | Порт 9000 закрыт снаружи, 10 параллельных загрузок успешны, RAM стабильна | [`evidence/student_tests.log`](evidence/student_tests.log) |
|
||
| Собственные тесты | `make test-student` | **34 теста проходят**: валидация вложений, компенсация S3, курсор, идемпотентность | [`evidence/student_tests.log`](evidence/student_tests.log) |
|
||
| Статусы и изоляция контейнеров | `docker compose ps` | Все 6 сервисов healthy, API и MinIO не открывают порты на хост | [`evidence/docker_services.log`](evidence/docker_services.log) |
|
||
| Нагрузочный тест | `make load` | **309.4 RPS**, p50 = 7.9 ms, p95 = 40.8 ms, p99 = 63.0 ms, 0 ошибок | [`evidence/load.json`](evidence/load.json) |
|
||
|
||
## Эксперименты и отказы
|
||
|
||
- **Профиль нагрузки:** скрипт `tests/load.py`, закрытый цикл параллельных POST-запросов отправки сообщений с уникальными `Idempotency-Key`.
|
||
- **Параметры:** длительность 30 секунд, 4 параллельных потока.
|
||
- **Результаты нагрузки (`evidence/load.json`):**
|
||
```json
|
||
{
|
||
"lab": 4,
|
||
"workload": "closed-loop POST messages; no automatic retries",
|
||
"requested_duration_seconds": 30.0,
|
||
"elapsed_seconds": 30.015,
|
||
"concurrency": 4,
|
||
"successful_requests": 9286,
|
||
"failed_requests": 0,
|
||
"error_ratio": 0.0,
|
||
"successful_rps": 309.375,
|
||
"successful_latency_ms": {
|
||
"p50": 7.928,
|
||
"p95": 40.768,
|
||
"p99": 62.963
|
||
}
|
||
}
|
||
```
|
||
|
||
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|
||
| --- | --- | --- | --- |
|
||
| Остановка одной реплики API (`scripts/stop-one.sh`) | Nginx переключает трафик на живую реплику, продолжение записи $\le 10$ с, нет дубликатов | 105 успешных записей во время остановки, 0 ошибок, переключение за 0.778 с | 0.778 сек, потерь данных нет |
|
||
| Рестарт всего стека (`scripts/restart.sh`) при активной сессии| Сохранение подтверждённых данных в Postgres, токенов сессий в Redis и файлов в MinIO | Контейнеры перезапущены, токен валиден, история сообщений и файлы сохранены | Восстановление около 5 сек, потеря подтверждённых данных: 0 |
|
||
| Загрузка декомпрессионной бомбы (изображение 10000x5000) | Отклонение запроса с кодом 413 `payload_too_large` без исчерпания RAM | Запрос отклонен мгновенно по метаданным IHDR без распаковки растра | Мгновенно (< 2 мс) |
|
||
| Загрузка файла размером более 10 MiB | Отклонение запроса с кодом 413 `payload_too_large` | Запрос отклонен до сохранения в S3 | Мгновенно |
|
||
| Попытка загрузки файла с поддельным расширением | Отклонение с кодом 415 `unsupported_media_type` | Проверка сигнатуры байтов выявляет подмену и возвращает 415 | Мгновенно |
|
||
| Попытка доступа к метаданным или контенту посторонним пользователем | Защита приватности: возврат строго 404 Not Found без утечки факта существования файла | Посторонний получает 404 на `GET /attachments/{id}` и `/content` | Мгновенно |
|
||
| Попытка передачи опасного имени файла | Отклонение запроса с кодом 400 `invalid_request` | Валидатор отклоняет некорректное имя до обращения к хранилищу | Мгновенно |
|
||
| Сбой сохранения метаданных в БД после успешного `PUT` в S3 | Автоматическое удаление объекта из S3 | В S3 не остается мусорных файлов | Мгновенно |
|
||
| Конкурентная загрузка ≥10 файлов с контролем RAM | Все файлы сохраняются в S3, память API стабильна | 10 параллельных загрузок вернули 201 ready, утечек памяти нет | Мгновенно (< 1 с) |
|
||
| Попытка прямого обращения к MinIO на порт 9000 с хоста | Соединение отклоняется (Connection Refused), консоль закрыта | Порты MinIO не проброшены наружу, прямой доступ невозможен | Мгновенно |
|
||
|
||
## Ограничения
|
||
|
||
- **Какие отказы выдерживаются и какие нет:**
|
||
1. *Выдерживаются:*
|
||
- Внезапная остановка любой одной API-реплики под нагрузкой: балансировщик Nginx переключает входящие запросы на оставшуюся реплику.
|
||
- Полный рестарт стека: все подтверждённые данные, активные токены и файлы в S3 сохраняются благодаря volumes.
|
||
- Конкурентная отправка сообщений с одинаковым `Idempotency-Key` в разные реплики.
|
||
- Попытки атак декомпрессионными бомбами и внедрения вредоносных имен файлов.
|
||
- Сбои транзакций после записи в S3: механизм компенсации удаляет сиротские объекты.
|
||
2. *Не выдерживаются:*
|
||
- Одновременное падение обеих API-реплик (HTTP 502 Bad Gateway).
|
||
- Падение единственного экземпляра PostgreSQL, Redis или MinIO.
|
||
- Удаление через `docker compose down -v`.
|
||
- **Учебные упрощения:**
|
||
1. Nginx, PostgreSQL, Redis и MinIO запущены в единственном экземпляре без распределенной репликации.
|
||
2. Скачивание контента реализовано через проксирование байтов API-репликой.
|