Files
mtusi2026lab4/REPORT.md
T

18 KiB
Raw Blame History

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

  • Автор, группа: Каменски Лин, БПИ2301
  • Целевая оценка; выбранный трек 5, если нужен: 5; трек 2
  • Commit/PR: Pull Request 58
  • Использованные источники, библиотеки и помощь ИИ: материалы лабораторной; Go 1.27.1, chi v5, pgx v5, sqlc, goose, PostgreSQL 18.6, Redis 8.8.3, Nginx 1.31.7, Docker Compose, SeaweedFS 4.51; OpenCode - для ускорения работы и оформления отчёта

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

Требуются Go 1.26+ и Docker с Compose. Образы: golang:1.27.1, postgres:18.6, redis:8.8.3-alpine3.23, nginx:1.31.7-alpine3.24, chrislusf/seaweedfs:4.51.

Создать локальные секреты - файлы в secrets/, в каждый записать значение без лишних символов:

  • database_url.txt - URL PostgreSQL для API;
  • cache_url.txt - URL Redis;
  • postgres_password.txt - пароль пользователя messenger;
  • test_database_url.txt - URL БД для тестов;
  • s3_access_key_id.txt - S3 access key ID для API;
  • s3_secret_access_key.txt - S3 secret access key для API;
  • s3_bootstrap_access_key_id.txt - bootstrap access key ID;
  • s3_bootstrap_secret_access_key.txt - bootstrap secret access key.

Пример (значения заменить своими):

mkdir -p secrets
printf '%s' 'CHANGE_ME' > secrets/postgres_password.txt
printf '%s' 'postgres://messenger:CHANGE_ME@postgres:5432/messenger?sslmode=disable' > secrets/database_url.txt
printf '%s' 'redis://redis:6379/0' > secrets/cache_url.txt

Скопировать шаблон переменных окружения:

cp .env.example .env

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

docker compose up --build -d

Готовность API проверяется запросом к /health/ready; после этого API доступен на http://localhost:8080.

Сваггер доступен на http://localhost:8080/swagger/.

Безопасная остановка (данные в volume pgdata сохраняются):

docker compose down

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

docker compose down -v

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

Процессы/хранилища: api (Go, chi, pgxpool, sqlc, goose, s3-client) × API_REPLICAS (≥2) → PostgreSQL (источник истины метаданных) + Redis (кэш сессий с fallback) → SeaweedFS S3 (байты вложений, приватный bucket messenger-attachments). Единственная публичная точка входа - nginx на 127.0.0.1:8080.

Источник истины - PostgreSQL. API не хранит локального состояния: сессии доступны всем репликам через общее хранилище, режим выбирается переменной SESSION_STORE (postgres | redis). При недоступности Redis API обходит кэш и читает сессию из PostgreSQL.

Что перенесено из lab3: Go-приложение и PostgreSQL, аутентификация, сессии, чаты, сообщения, идемпотентность и X-Instance-Id, Redis-кэш сессий, compose.yaml, deploy/nginx.conf, Dockerfile, Dockerfile.migrate, scripts/restart.sh, scripts/stop-one.sh, student-tests, student.mk, Makefile, web/swagger, contracts.

Что изменено в lab4: Добавлен S3-совместимое объектное хранилище (SeaweedFS) в compose.yaml с приватным bucket messenger-attachments, политика доступа и bootstrap-конфигурация; таблица/миграция attachments + типы attachment_content_type и attachment_status; sqlc-запросы и DTO для вложений; attachment_ids в сообщениях (0-10 уникальных ID, по умолчанию []); POST /api/v1/chats/{chat_id}/attachments - загрузка raw PNG/JPEG с ограничениями (10 MiB, 40 млн пикселей, MIME по содержимому); эндпоинты GET /api/v1/attachments/{id} и GET /api/v1/attachments/{id}/content; поле attachment_ids в ответах сообщений; механизм queued → ready (upload пишет queued, после успешного S3 Put переводит в ready); Nginx client_max_body_size 11m; очистка orphan-объектов через reconciler с индексом idx_attachments_queued_created_at; отдельные S3 credentials: bootstrap (Admin) и API (Read/Write/List/Tagging, без Admin/Delete).

Загрузка и память. Тело запроса ограничено 10 MiB и потоково записывается во временный файл с одновременным подсчётом SHA-256. По заголовку изображения проверяются формат, MIME и лимит 40 млн пикселей до распаковки. Затем выполняется полное декодирование для проверки целостности; на одной API-реплике одновременно работает не более одного декодера. Тело сохраняется потоково, но декодер держит распакованные пиксели в RAM. Затем файл передаётся в S3; временный файл удаляется при завершении запроса. Контекст запроса и чтение тела на стороне API ограничены 5 с; таймаут чтения возвращает 408 invalid_request. Локальный файл нужен только на время загрузки, оригинал хранится в S3.

Очистка незавершённых загрузок. До записи в S3 создаётся строка queued, после успеха - ready. Фоновая очистка каждые 10 минут обрабатывает брошенные queued старше 1 часа. Полную сверку объектов и метаданных выполняет отдельный reconciler; часовой grace period защищает свежие загрузки.

Готовность и недоступность S3. GET /health/ready теперь помимо PostgreSQL проверяет доступ к S3 bucket через HeadBucket с общим таймаутом 2 с. При недоступности S3 загрузка и скачивание возвращают 503 unavailable. Повторы Nginx при 503 отключены: PostgreSQL и S3 общие для всех API-реплик, поэтому переход на другую реплику при их недоступности не помогает. После рестарта S3 доступ к bucket может восстановиться раньше загрузки и скачивания - тест дополнительно ждёт их восстановления.

Bootstrap и доступ к S3. Bucket создаётся только при отсутствии; повторный запуск и одновременное создание несколькими репликами допустимы. API и bootstrap используют разные credentials. Порты S3 и административных интерфейсов не публикуются на хост, HTTP-интерфейс filer отключён. Прямой анонимный доступ к объекту возвращает 403 Forbidden.

Переменные .env.example: APP_HOST, APP_PORT - адрес и порт API; SESSION_TTL_SECONDS - срок жизни сессии; LOG_LEVEL - уровень логов; DATABASE_URL_FILE, CACHE_URL_FILE - пути к secrets с URL PostgreSQL и Redis; SESSION_STORE - режим хранения сессий, postgres или redis; IDEMPOTENCY_TTL_SECONDS - срок хранения ключей идемпотентности; API_REPLICAS - число реплик api; API_CPUS, API_MEM - лимиты CPU и памяти каждой реплики; LB_CPUS - лимит CPU Nginx; S3_ENDPOINT, S3_REGION, S3_BUCKET - настройки S3; MAX_UPLOAD_BYTES, MAX_IMAGE_PIXELS - лимиты загрузок; S3_ACCESS_KEY_ID_FILE, S3_SECRET_ACCESS_KEY_FILE, S3_BOOTSTRAP_ACCESS_KEY_ID_FILE, S3_BOOTSTRAP_SECRET_ACCESS_KEY_FILE - пути к secrets.

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

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Публичный smoke make test PASS evidence/make-test.txt
Уровень 3
Загрузка, ready, checksum и сообщение с вложением make test PASS evidence/make-test.txt
Запрет доступа постороннему make test 404 для метаданных и содержимого evidence/make-test.txt
PNG/JPEG, MIME, лимиты размера и пикселей, безопасный filename make test; make contract-go: TestAttachmentJPEG, TestAttachmentTooLarge, TestAttachmentTooManyPixels, TestAttachmentCorruptedImage, TestAttachmentMimeSubstitution, TestAttachmentUnsafeFilename PASS evidence/make-test.txt, evidence/contract-go.txt
Запрет прямого доступа к объекту S3 docker compose exec -T s3 wget -S -O /dev/null "http://127.0.0.1:9000/messenger-attachments/${OBJECT_KEY}" 403 Forbidden evidence/s3-private.txt
Скачивание после остановки загрузившей реплики make failure-go: TestAttachmentUploaderFailover PASS evidence/failure-go.txt
Сохранность метаданных и оригинала после restart make test-persistence ACTION_SCRIPT=scripts/restart.sh; docker compose ps -a до и после PASS evidence/test-persistence.txt
Отказ S3 и восстановление make s3-failure-go: TestS3Down PASS evidence/s3-failure-go.txt
Уровень 4
Негативные тесты вложений без 500 make contract-go: TestAttachmentTooLarge, TestAttachmentCorruptedImage, TestAttachmentMimeSubstitution, TestAttachmentForeignID, TestAttachmentFromAnotherChat PASS evidence/contract-go.txt
≥10 одновременных загрузок и пик памяти make load-go LOAD_WORKERS=10 LOAD_DURATION=30s PASS: 10 загрузчиков, 30,4 с, 632 ответа 201, ошибок 0; 20,82 загрузки/с; память API-1: 12,2 → 50,9 MiB, API-2: 13,3 → 56,7 MiB evidence/load-go.txt
Уровень 5, трек 2
Обнаружение и исправление orphan/missing при моделировании рассогласования S3/БД make reconcile-test-go: TestReconcileRepair PASS: dry-run нашёл 1 orphan и 1 missing без изменений; исправление удалило объект и пометило вложение failed; повторный запуск без изменений evidence/reconcile-test-go.txt
Свежие и используемые вложения сохраняются make reconcile-test-go: TestReconcileSafety PASS: пропущены 1 свежее и 1 используемое вложение; строки и оригиналы сохранены evidence/reconcile-test-go.txt
Стоимость обхода объектов и метаданных make reconcile-test-go: TestReconcileCost (3 обхода, объекты, строки, страницы, время) PASS: 14 607 объектов, 14 614 строк, 15 страниц S3; время обходов: 1609 / 1721 / 1587 мс evidence/reconcile-test-go.txt

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

Трек 2: согласованность двух хранилищ

Гипотеза: сверка S3 и PostgreSQL обнаруживает объекты без метаданных и метаданные без оригинала; исправление повторяемо, а свежие и используемые вложения сохраняются.

Методика: make reconcile-test-go создаёт вложения через API и подменяет S3-ключ одного из них в БД. Исходный объект становится orphan, строка указывает на отсутствующий объект (missing). Затем выполняются dry-run, исправление и повторное исправление. В этом сценарии grace period сокращён до 1 с; в проверке безопасности используется штатный 1 час. Команда запускается на стенде без параллельных загрузок.

Проверка Что ожидаем Что наблюдали
Dry-run после рассогласования Найти orphan/missing без изменения данных Обнаружены 1 orphan и 1 missing; изменений нет
Исправление Удалить orphan и отметить missing как ошибку Orphan удалён; missing переведён в failed с object_missing
Повторное исправление Не менять уже исправленные данные Расхождения устранены, новых изменений нет
Защита вложений Сохранить свежие и используемые вложения Свежий queued и привязанный к сообщению queued старше 2 часов пропущены; строки сохранены, скачанные оригиналы совпадают побайтно

Стоимость полного обхода измерена тремя последовательными dry-run: 14 607 объектов S3, 14 614 строк PostgreSQL, 15 страниц списка S3. Время: 1609 / 1721 / 1587 мс, медиана 1609 мс. Доказательство: evidence/reconcile-test-go.txt.

Ограничения: моделируются последствия рассогласования через SQL, а не реальные сетевые отказы или падение процесса между операциями. Сверка не восстанавливает утраченные байты: missing помечается ошибкой. Списки объектов и строк загружаются в память целиком; стоимость растёт с объёмом данных. Измерен один объём, поэтому масштабируемость не доказана. Время трёх обходов составило 1,59-1,72 с.

Вывод: Гипотеза подтверждена на подготовленных сценариях: reconciler обнаружил и исправил orphan/missing, повторный запуск не внёс изменений, свежие и используемые вложения сохранились. Обход 14,6 тыс. объектов занял 1,59-1,72 с. Утраченный оригинал не восстанавливается, а отмечается ошибкой.

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

  • Nginx, PostgreSQL и SeaweedFS работают в одном экземпляре на одном хосте. Реплики API не защищают от отказа этих компонентов или самого хоста.
  • При недоступном Redis logout возвращает 204, но прежний токен может приниматься до истечения кэша, до 60 с.
  • Полное декодирование требует памяти под распакованное изображение. Для ограничения расхода RAM на каждой API-реплике работает один декодер, поэтому параллельные загрузки ожидают своей очереди.
  • Общей транзакции PostgreSQL и S3 нет: расхождения исправляются последующей сверкой. Reconciler отмечает отсутствие оригинала, но не восстанавливает байты. Сохранность volumes не заменяет резервные копии обоих хранилищ.
  • Фоновая очистка сначала удаляет строку БД, затем объект S3. Если удаление из S3 не удалось, объект останется без метаданных до запуска reconciler.
  • Reconciler загружает списки объектов и метаданных целиком в память, поэтому расход памяти растёт с объёмом хранилища.