Files
mtusi2026lab4/REPORT.md

147 lines
9.7 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Отчёт — лабораторная 4
- **Автор, группа:** Матвиенко, БПИ2304
- **Целевая оценка:** 3
- **Commit/PR:** добавить после публикации
- **Использованные источники, библиотеки и помощь ИИ:** материалы курса, OpenAPI-контракт и публичные тесты; Python 3.12, FastAPI, Uvicorn, psycopg, boto3, Pillow, PostgreSQL 16, RustFS 1.0.3, Nginx 1.29, Docker Compose. Помощь ИИ использовалась при разработке, отладке и оформлении отчёта.
## Запуск из чистого clone
Для запуска необходимы Docker Desktop с Docker Compose, Git и WSL Ubuntu с Python 3 и Make.
В корне проекта создать `.env` с локальными значениями:
```dotenv
POSTGRES_PASSWORD=<локальный_пароль>
SESSION_TTL_SECONDS=3600
S3_ACCESS_KEY=<локальный_ключ>
S3_SECRET_KEY=<локальный_секрет>
S3_BUCKET=messenger-attachments
```
Секреты не должны попадать в Git. Адрес S3 внутри Docker-сети: `http://minio:9000` (сервис `minio` использует RustFS).
Сборка и запуск:
```bash
docker compose up -d --build
docker compose ps -a
curl http://127.0.0.1:8080/health/ready
```
Сервис `migrate` применяет SQL-миграции до запуска API, а `s3-init` создаёт приватный bucket. Повторная проверка:
```bash
docker compose run --rm --no-deps migrate
docker compose run --rm s3-init
```
Публичные проверки:
```bash
make test
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
```
После проверок восстановить обе API-реплики:
```bash
docker compose up -d --wait api1 api2
```
Безопасная остановка с сохранением данных:
```bash
docker compose down
```
Намеренное удаление учебных данных и постоянных томов:
```bash
docker compose down -v
```
## Архитектура и решения
**Схема:** клиент → Nginx → API1 / API2 → PostgreSQL + RustFS (S3).
Единая точка входа — `localhost:8080`. Nginx балансирует запросы между двумя независимыми экземплярами FastAPI. PostgreSQL является источником истины для пользователей, сессий, чатов, сообщений и метаданных вложений. Оригинальные файлы сохраняются в приватном S3-bucket RustFS, а не в PostgreSQL или локальных каталогах API.
Из lab3 перенесены регистрация, аутентификация, чаты, сообщения, идемпотентность, балансировка и проверка отказа реплики.
В lab4 добавлены:
- Загрузка оригинальных PNG/JPEG и авторизованное скачивание через API.
- Проверка MIME по содержимому, контроль размера до 10 MiB и количества пикселей до 40 миллионов.
- Проверка имени файла и создание серверного S3 object key.
- Таблицы `attachments` и `message_attachments`.
- Привязка изображений к сообщениям через `attachment_ids`.
- Проверка доступа к чату перед получением метаданных и скачиванием.
- Постоянный Docker volume для S3-хранилища.
Сначала оригинал сохраняется в S3, затем в PostgreSQL фиксируются метаданные со статусом `ready`. При ошибке записи метаданных выполняется попытка удалить S3-объект. Полностью атомарной транзакции между PostgreSQL и S3 нет. Создание сообщения, привязка вложений и запись ключа идемпотентности выполняются в одной транзакции PostgreSQL.
В `.env.example` используются параметры `POSTGRES_PASSWORD`, `SESSION_TTL_SECONDS`, `S3_ACCESS_KEY`, `S3_SECRET_KEY` и `S3_BUCKET`; внутренний `S3_ENDPOINT` задаётся в Compose.
## Доказательства критериев
| Критерий | Команда / сценарий | Наблюдаемый результат | Доказательство |
|---|---|---|---|
| Публичный API | `make test` | PASS, включая сценарий вложений | `evidence/smoke.txt` |
| Две API-реплики | Проверка `X-Instance-Id` | Два разных UUID | `evidence/instances.txt` |
| Отказ API-реплики | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` | PASS, 121 успешная запись, 0 ошибок | `evidence/failover.txt` |
| Восстановление записи | Failover-сценарий | 0,903 секунды | `evidence/failover.txt` |
| Сохранность данных | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | PASS, подтверждённые данные и сессия сохранены | `evidence/persistence.txt` |
| PostgreSQL и S3 | `docker compose ps -a` | Хранилища запущены, API-реплики healthy | `evidence/containers.txt` |
| SQL-миграции | `docker compose run --rm --no-deps migrate` | Миграции применены | Журнал миграций |
| Реальный перезапуск хранилищ | Скрипт `restart.sh`, `docker inspect` | PostgreSQL и RustFS перезапущены | `evidence/restart-after.txt`, журнал действия |
Уровень 4 и трек 5 не заявлены.
## Эксперименты и отказы
**Гипотеза:** при остановке одной API-реплики запросы продолжат обрабатываться второй, поскольку метаданные и оригиналы изображений находятся в общих хранилищах. После перезапуска PostgreSQL и RustFS данные должны сохраниться благодаря постоянным Docker volumes.
**Среда:** локальный стенд Windows / WSL Ubuntu / Docker Desktop, Python 3.12, PostgreSQL 16, RustFS 1.0.3, две API-реплики, Nginx 1.29.
Публичный smoke-тест завершился успешно:
```text
PASS: lab4 public API scenario; infrastructure and grading evidence remain separate.
```
Результаты failover-теста:
```text
observed_instances_before: 2
successful_writes: 121
failed_attempts: 0
first_recovery_seconds: 0.903
PASS: failover preserved confirmed data and existing session.
```
Persistence-тест:
```text
PASS: persistence preserved confirmed data and existing session.
```
| Воздействие | Ожидание | Результат | Восстановление / данные |
|---|---|---|---|
| Остановка одной API-реплики | Продолжение работы через вторую | PASS, 121 запись, 0 ошибок | 0,903 с, подтверждённые данные сохранены |
| Перезапуск PostgreSQL и RustFS | Сохранение данных и сессии | PASS | Потеря подтверждённых данных не выявлена |
| Загрузка и чтение PNG/JPEG | Совпадение оригинала и проверка прав доступа | Smoke PASS | Проверка целостности выполнена публичным сценарием |
После проверок обе API-реплики восстановлены и имеют разные `X-Instance-Id`.
Публичные тесты не являются полноценным нагрузочным испытанием. Отдельные измерения RPS, p50/p95/p99, CPU/RAM, точного профиля параллелизма и длительности прогрева не проводились.
## Ограничения и следующие шаги
Реализация выдерживает отказ одной API-реплики и перезапуск контейнеров с сохранением volumes. PostgreSQL, RustFS и Nginx остаются едиными точками отказа.
Для хранения оригиналов применяется синхронная загрузка без фоновой обработки и генерации превью. При редком сбое между записью в S3 и фиксацией метаданных возможен временно неиспользуемый объект, поэтому в дальнейшем полезно добавить очистку таких объектов.
Следующие улучшения: резервирование PostgreSQL и S3, мониторинг, резервное копирование и нагрузочные испытания.
**Вывод:** реализовано общее S3-хранилище изображений для двух API-реплик. Публичный smoke, persistence и failover пройдены. При отказе реплики выполнена 121 успешная запись без ошибок, восстановление заняло 0,903 секунды.