forked from mtusi2026/mtusi2026lab4
147 lines
9.7 KiB
Markdown
147 lines
9.7 KiB
Markdown
# Отчёт — лабораторная 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 секунды. |