18 KiB
Отчёт — лабораторная 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 возвращает
503 unavailable: сессия уже удалена из PostgreSQL, но старый токен может приниматься из кэша до 60 с. Несмотря на503, может потребоваться повторный вход. Пока Redis недоступен, получить204нельзя, хотя сессия в БД уже удалена; после восстановления повторный logout вернёт401. - Полное декодирование требует памяти под распакованное изображение. Для ограничения расхода RAM на каждой API-реплике работает один декодер, поэтому параллельные загрузки ожидают своей очереди.
- Общей транзакции PostgreSQL и S3 нет: расхождения исправляются последующей сверкой. Reconciler отмечает отсутствие оригинала, но не восстанавливает байты. Сохранность volumes не заменяет резервные копии обоих хранилищ.
- Фоновая очистка сначала удаляет строку БД, затем объект S3. Если удаление из S3 не удалось, объект останется без метаданных до запуска reconciler.
- Reconciler загружает списки объектов и метаданных целиком в память, поэтому расход памяти растёт с объёмом хранилища.