docs(lab5): add initial report structure, setup guide and architecture diagram
This commit is contained in:
@@ -1,17 +1,129 @@
|
||||
# Отчёт — лабораторная 5
|
||||
Отчёт — лабораторная 5
|
||||
|
||||
- Автор, группа: TODO
|
||||
- Целевая оценка; выбранный трек 5, если нужен: TODO
|
||||
- Commit/PR: TODO после публикации
|
||||
- Использованные источники, библиотеки и помощь ИИ: TODO
|
||||
- Автор, группа: Голиков А.П., БВТ2303
|
||||
- Целевая оценка; выбранный трек 5, если нужен: Оценка 5, Трек 2
|
||||
- Commit/PR: будет добавлено после публикации.
|
||||
- Использованные источники, библиотеки и помощь ИИ: Документация RabbitMQ (Publisher Confirms, DLX), документация Go (pgx, Gin), библиотека `disintegration/imaging` для ресайза, `gen2brain/webp` для WebP. При написании кода использовалась помощь ИИ для генерации boilerplate-кода и архитектурных консультаций.
|
||||
|
||||
## Запуск из чистого clone
|
||||
|
||||
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
|
||||
**Требования (Prerequisites):**
|
||||
- Docker и Docker Compose (рекомендуется Docker Desktop).
|
||||
- Python 3.9+ (для запуска тестов).
|
||||
- OpenSSL (для генерации секретов, встроен в Git Bash).
|
||||
- ОС: Windows / Linux / macOS.
|
||||
|
||||
**Быстрый старт (Bash / Git Bash):**
|
||||
Для запуска стенда выполните следующие команды в корне проекта:
|
||||
```sh
|
||||
# 1. Создаем .env из шаблона
|
||||
cp .env.example .env
|
||||
|
||||
# 2. Генерируем секреты и автоматически обновляем .env
|
||||
chmod +x setup_secrets.sh
|
||||
./setup_secrets.sh
|
||||
|
||||
# 3. Собираем и запускаем весь стенд
|
||||
docker compose up -d --build
|
||||
|
||||
# 4. Ожидаем, пока все сервисы пройдут healthcheck
|
||||
Проверить статус: docker compose ps
|
||||
```
|
||||
|
||||
Запуск тестов (Windows / PowerShell):
|
||||
Для корректной работы Python на Windows с кириллицей в JSON-контрактах необходимо указать кодировку UTF-8:
|
||||
```powershell
|
||||
|
||||
$env:PYTHONUTF8 = "1"
|
||||
make test
|
||||
# или
|
||||
python -X utf8 tests/smoke.py
|
||||
```
|
||||
Безопасная остановка и удаление данных:
|
||||
```sh
|
||||
|
||||
# Остановить контейнеры
|
||||
docker compose stop
|
||||
|
||||
# Полностью удалить контейнеры и тома с учебными данными
|
||||
docker compose down -v
|
||||
```
|
||||
|
||||
## Архитектура и решения
|
||||
```
|
||||
[ Клиент ]
|
||||
│ POST /attachments (bytes)
|
||||
▼
|
||||
[ API (реплики) ] ───(1) быстрый sniff & DecodeConfig───> [ Проверка лимитов ]
|
||||
│
|
||||
├──(2) PUT объект в S3 (prefix: staging/{id})
|
||||
│
|
||||
└──(3) BEGIN TX
|
||||
├── INSERT INTO attachments (status='queued')
|
||||
└── INSERT INTO outbox (payload=JobMessage)
|
||||
COMMIT TX
|
||||
│
|
||||
▼ HTTP 202 Accepted (статус queued)
|
||||
│
|
||||
[ Outbox Publisher (горутина) ] ──(4) SELECT ... FOR UPDATE SKIP LOCKED──> [ PostgreSQL ]
|
||||
│
|
||||
├──(5) Publish в RabbitMQ с Publisher Confirm
|
||||
└──(6) UPDATE outbox SET published_at = now()
|
||||
│
|
||||
▼
|
||||
[ RabbitMQ ] (Очередь attachments.process, durable)
|
||||
│
|
||||
▼
|
||||
[ Worker ] ──(7) ClaimForProcessing (status='processing', аренда 5 мин)
|
||||
│
|
||||
├──(8) GET staging/{id} из S3
|
||||
├──(9) Генерация вариантов: Thumbnail, Crop, Optimized(WebP)
|
||||
├──(10) PUT оригинал и варианты в S3 (prefix: chats/{chat_id}/{id})
|
||||
├──(11) BEGIN TX
|
||||
│ ├── UPDATE attachments SET status='ready'
|
||||
│ └── INSERT INTO attachment_variants
|
||||
│ COMMIT TX
|
||||
└──(12) ACK сообщения в RabbitMQ
|
||||
```
|
||||
Источник истины и транзакционные границы
|
||||
|
||||
Источник истины: PostgreSQL. Только база данных является авторитетным хранилищем состояний (queued, processing, ready, failed) и метаданных.
|
||||
|
||||
Транзакционные границы: Для преодоления проблемы «двойной записи» (Dual-Write) между базой данных и брокером сообщений используется паттерн Transactional Outbox. Запись INSERT attachments и INSERT outbox происходит в рамках одной ACID-транзакции PostgreSQL. Это гарантирует, что если клиент получил 202 Accepted, задача сохранена на диске и не будет потеряна, даже если RabbitMQ временно недоступен (Publisher дослать её при восстановлении).
|
||||
|
||||
Идемпотентность: Брокер гарантирует доставку at-least-once (минимум один раз). Защита от дублей реализована на уровне метода ClaimForProcessing (атомарный UPDATE ... WHERE status='queued'), а также через защиту pipeline_version в методе CompleteJob.
|
||||
|
||||
Что перенесено из lab4 и что изменено
|
||||
|
||||
Сохранено: Базовая структура БД (пользователи, чаты, сообщения), аутентификация (Bearer/Basic), идемпотентность создания сообщений, интерфейсы репозиториев.
|
||||
|
||||
Изменено:
|
||||
|
||||
Отказ от синхронного ресайза: Метод Upload больше не делает полный image.Decode (который потреблял до 160 МБ RAM), теперь выполняется только быстрый image.DecodeConfig по заголовку.
|
||||
|
||||
Код ответа: 201 Created заменен на 202 Accepted, так как обработка стала асинхронной.
|
||||
|
||||
Staging: Оригинал при загрузке теперь сохраняется во временный префикс S3 (staging/), а не сразу в конечный (chats/).
|
||||
|
||||
Состояния: Удален статус pending, добавлены queued и processing.
|
||||
|
||||
Инфраструктура: Добавлены сервисы RabbitMQ и Worker. Появился фоновый процесс Outbox Publisher (внутри API) и Reconciler (сборка мусора и спасение зависших задач).
|
||||
|
||||
Обработка: Добавлена генерация crop (128x128) и optimized (WebP до 1280x1280) с удалением метаданных.
|
||||
|
||||
Конфигурация и переменные (.env.example)
|
||||
|
||||
Переменные окружения разделены на логические блоки и передаются в контейнеры через compose.yaml:
|
||||
|
||||
API: APP_PORT, SESSION_TTL_SECONDS, API_REPLICAS (масштабирование).
|
||||
|
||||
Лимиты файлов: MAX_UPLOAD_BYTES (10 МБ), MAX_IMAGE_PIXELS (40 млн).
|
||||
|
||||
Outbox & Worker: OUTBOX_INTERVAL_MS (частота опроса таблицы outbox), WORKER_CONCURRENCY (количество параллельных обработчиков), JOB_MAX_ATTEMPTS (лимит попыток), JOB_TIMEOUT_SECONDS (лимит времени на одну картинку).
|
||||
|
||||
Инфраструктура: Строки подключения (DATABASE_URL, CACHE_URL, RABBITMQ_URL) и настройки S3/MinIO. Все пароли вынесены в Docker Secrets (генерация через setup_secrets.sh).
|
||||
|
||||
|
||||
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab4, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
|
||||
|
||||
## Доказательства критериев
|
||||
|
||||
|
||||
Reference in New Issue
Block a user