Files
mtusi2026lab4-fork/REPORT.md
T
2026-11-06 15:58:30 +03:00

17 KiB
Raw Blame History

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

  • Автор, группа: Морозова Ольга Андреевна, БВТ2303
  • Целевая оценка: 4 (треки на 5 не заявлены)
  • Commit/PR: TODO после публикации
  • Использованные источники: README.md, COURSE.md, contracts/openapi.json, документация Go, MinIO, PostgreSQL, Nginx, Redis, Docker.
  • Библиотеки: Go 1.22 (stdlib), github.com/google/uuid v1.6.0, github.com/jackc/pgx/v5 v5.5.5, github.com/redis/go-redis/v9 v9.5.1, golang.org/x/crypto v0.23.0, github.com/minio/minio-go/v7 v7.0.72. Тесты — Python 3 (stdlib).
  • Помощь ИИ: Deepseek — написание и проверка кода.

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

Команды выполнялись в WSL2 (Ubuntu) на Windows 11.

Требования: Docker 24+ (Compose v2), Python 3.9+ (для тестов), make.

Версии (фиксированные теги образов):

  • golang:1.22-alpine — build stage
  • alpine:3.20 — runtime stage
  • postgres:16.3-alpine — база данных
  • redis:7.2.5-alpine — кэш
  • nginx:1.27.0-alpine — балансировщик
  • pgsty/silo:RELEASE.2026-10-26T00-00-00Z — S3-совместимое хранилище

Подготовка

git clone https://gitea.privcloud.tech/MiniLynx/mtusi2026lab4-fork
cd mtusi2026lab4-fork

# 1. Секреты (не входят в Git)
mkdir -p secrets
printf 'local-dev-postgres-password\n' > secrets/postgres_password.txt
printf 'postgres://messenger:local-dev-postgres-password@postgres:5432/messenger?sslmode=disable\n' > secrets/database_url.txt
printf 'redis://redis:6379/0\n' > secrets/cache_url.txt
printf 'minioadmin\n' > secrets/minio_root_user.txt
printf 'minioadmin-dev-password\n' > secrets/minio_root_password.txt
printf 'messenger-api\n' > secrets/s3_access_key_id.txt
printf 'messenger-api-dev-secret\n' > secrets/s3_secret_access_key.txt
chmod 600 secrets/*.txt

# 2. Локальный .env
cp .env.example .env
# ВАЖНО: В .env нужно исправить S3_ENDPOINT на s3:9000 (без http://), так как minio-go ожидает host:port
sed -i 's|S3_ENDPOINT=.*|S3_ENDPOINT=s3:9000|' .env

# 3. Python для проверок

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements-dev.txt

# 4. Скрипты

chmod +x scripts/restart.sh scripts/stop-one.sh scripts/restore-api.sh

Сборка и запуск

docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
# Дождаться /health/ready
docker compose ps

Для запуска с другим количеством реплик добавить API_REPLICAS=$n перед docker compose --env-file .env up -d --build, где $n - желаемое количество реплик.

Тесты

make check
make validate PYTHON=.venv/bin/python
make test

# Persistence
make test-persistence ACTION_SCRIPT=scripts/restart.sh

# Failover
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
# Восстановление реплики после теста:
./scripts/restore-api.sh

# Собственные тесты (негативные сценарии, нагрузка, отказ S3, GC)
make my_tests

Остановка (с сохранением volumes)

docker compose --env-file .env down

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

docker compose --env-file .env down -v
rm -f secrets/*.txt

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

HTTP-клиент → Nginx (порт 8080) → API (Go, x N реплик, non-root)
										├── PostgreSQL 16.3 ─ users, chats, messages, sessions, idempotency_keys, attachments, attachment_gc
										├── Redis 7.2.5     ─ кэш сессий
										└── S3 (pgsty/silo) ─ приватный bucket messenger-attachments
  • S3-хранилище: Развернуто S3-совместимое хранилище pgsty/silo. Создание бакета и ограниченного пользователя API вынесено в отдельный идемпотентный сервис s3-init (infra/minio/bootstrap.sh), который запускается один раз перед стартом API. Бакет приватный (mc anonymous set none). Консоль управления (9001) не проброшена наружу.
  • Права S3: API использует отдельные креды (messenger-api), которым через политику api-attachments разрешены только PutObject, GetObject, DeleteObject и ListBucket в рамках бакета. Root-креды (minioadmin) используются только на этапе bootstrap.
  • Потоковая обработка (без OOM): В src/domain/s3.go метод PutValidatedImage читает тело запроса с жестким лимитом (MAX_UPLOAD_BYTES + 1) напрямую во временный файл на диске (os.CreateTemp). Это исключает выделение оперативной памяти под весь файл. MIME определяется по первым 512 байтам (http.DetectContentType), размеры проверяются через image.DecodeConfig до полного декодирования. Пиксели ограничены MAX_IMAGE_PIXELS. Затем файл стримится в S3 с одновременным вычислением SHA-256.
  • Устойчивость к отказам S3: В S3Store настроен кастомный http.Transport с короткими таймаутами (Dial — 3с, Response Header — 5с). Для скачивания реализована логика ретраев (до 2 попыток с интервалом 500 мс) с общим дедлайном 6 секунд. Это предотвращает «зависание» API-реплики при недоступности S3.
  • Компенсация (GC): При загрузке сначала создается запись pending в attachments. После успешного PutObject и проверки файла запись переводится в ready транзакцией. Если S3 PUT прошел, а COMMIT в БД упал — ключ объекта помещается в таблицу attachment_gc. Фоновый процесс (запускается каждые 2 минуты в main.go) вызывает ReconcileOrphans, который безопасно удаляет объекты из attachment_gc и «зависшие» pending-записи старше grace period (600 секунд).
  • Авторизация: Скачивание и получение метаданных вложения доступно только участникам чата (JOIN с chat_members). Посторонние получают 404.
  • Graceful shutdown: API перехватывает SIGTERM и корректно завершает текущие запросы (15 секунд).

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

  • PostgreSQL, миграции, структура Go-пакета.
  • Argon2id для паролей, схема sessions.
  • Redis как кэш, горизонтальное масштабирование, Nginx как балансировщик.
  • Механизм идемпотентности на базе idempotency_keys.

Что изменено

  • Добавлена миграция 0005_attachments.sql (таблицы attachments, attachment_gc, поле attachment_ids в messages).
  • Добавлены обработчики загрузки (POST /api/v1/chats/{id}/attachments), метаданных и скачивания (GET /api/v1/attachments/{id}/content).
  • В compose.yaml добавлены сервисы s3 и s3-init, проброшены секреты MinIO.
  • В messages добавлена поддержка массива attachment_ids, который валидируется при отправке сообщения (вложение должно принадлежать этому чату).
  • В domain/s3.go добавлены кастомные таймауты, запись во временный файл и ретраи.

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

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Offline-структура и локальные refs make check PASS png
Полная OpenAPI 3.1 и JSON Schema make validate PYTHON=.venv/bin/python PASS png
Публичный smoke (lab4) make test PASS png
Persistence: перезапуск API+БД+Redis+S3, вложение живо make test-persistence ACTION_SCRIPT=scripts/restart.sh PASS png
Уровень 3: остановка любой 1 реплики (с вложением) make test-failover ACTION_SCRIPT=scripts/stop-one.sh observed_instances_before: 2, successful_writes: 78, failed_attempts: 1, first_recovery: 2.8s png
Уровень 4: негативные сценарии (413, 415, MIME, ACL) python3 student-tests/negative.py PASS: lab4 negative suite png
Уровень 4: эксперимент ≥10 параллельных загрузок python3 student-tests/load_mem.py Пик памяти API: 62.89 MB (лимит 128M) png, txt
Уровень 4: private bucket вне API docker compose exec api wget ... 403 Forbidden png
Уровень 4: отказ S3 и восстановление python3 student-tests/test_s3_failure.py Остановка S3 → 503, Запуск S3 → 200 png
Уровень 4: очистка orphan-объектов (GC) python3 student-tests/test_gc.py Записи удалены фоновым reconciler за 22 с. png
Топология: 2 реплики, S3, LB docker compose ps Все контейнеры healthy png

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

Эксперимент с памятью (≥10 параллельных загрузок)

Гипотеза: Запись тела запроса во временный файл на диске (os.CreateTemp) и ограничение чтения (io.LimitReader) предотвратят неограниченный рост RAM при множественных одновременных загрузках больших файлов.

Методика:

  • Запуск 10 параллельных POST-запросов на загрузку изображения размером 5 МБ.
  • В процессе выполнения каждые 100 мс снимались показатели docker stats целевого контейнера API.
  • Лимит памяти контейнера API: 128M.

Результат:

  • Все 10 запросов завершились успешно (201 Created) за 1.97 с.
  • Пиковое потребление памяти (RSS) на API-реплике: 62.89 MB.
  • Превышения лимита и OOM-kill не произошло, память зависит от размера буферов HTTP, а не от общего объема загружаемых файлов.

Вывод: Обработка безопасна по памяти, буферизация в RAM отсутствует.

Отказы

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
SIGTERM (graceful shutdown) Корректное завершение, 0 потерь shutting down... → stopped ≤1 с
SIGKILL одной реплики (failover) Nginx убирает её, трафик на живые make test-failover PASS 2.8 с; данные и вложения сохранены
Отказ S3 (контейнер остановлен) Ошибка 503 для загрузки/скачивания 503 Service Unavailable До восстановления контейнера S3 (проверено скриптом)
Redis недоступен API работает через PostgreSQL 200 на /health/ready без потерь
PostgreSQL недоступен /health/ready → 503 503 до восстановления контейнера
Прерывание между S3 и БД Объект не остается вечным мусором attachment_gc + фоновый ReconcileOrphans Grace period 600 с
Скачивание файла посторонним 404 Not Found 404 —

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

  • Один Docker-host: падение хоста или PostgreSQL/Redis/S3-контейнеров не покрывается. Nginx, БД и S3 остаются SPOF (Single Point of Failure) для физических серверов.
  • Reconciler: запускается внутри каждого процесса API раз в 2 минуты. При масштабировании реплик возможна параллельная работа нескольких реконсилеров (частично решается FOR UPDATE SKIP LOCKED или выделенным фоновым процессом).
  • Безопасность: Соединение между API и S3 идет по HTTP внутри изолированной Docker-сети (backend), без TLS/mTLS.