This commit is contained in:
caramelteawithmint
2026-11-13 18:24:10 +03:00
parent a72f814e65
commit 8254ea2c1d
+70 -17
View File
@@ -1,37 +1,90 @@
# Отчёт — лабораторная 4
- Автор, группа: TODO
- Целевая оценка; выбранный трек 5, если нужен: TODO
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: TODO
- **Автор, группа:** [Впиши сюда свои ФИО и Группу, например: Иванова А.А., БИВ-231]
- **Целевая оценка:** 4 (весь уровень 3 + весь уровень 4)
- **Commit/PR:** [Вставь ссылку на свой Pull Request после пуша]
- **Использованные источники, библиотеки и помощь ИИ:**
Использованы библиотеки: FastAPI, Uvicorn, psycopg3, boto3, Pillow, pydantic.
Инфраструктура: PostgreSQL 16, MinIO (совместимый форк pgsty/silo), Nginx, помощь ИИ.
## Запуск из чистого clone
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
**Prerequisites:** Docker Desktop, Python 3.11+ (для запуска тестов), Git Bash (или WSL).
1. **Создание секрета базы данных:**
В корне проекта создайте папку `secrets` (если её нет) и файл `secrets/database_url` со строкой подключения:
`postgresql://messenger:messenger@postgres:5432/messenger`
2. **Сборка и запуск:**
```sh
docker compose up -d --build
```
3. **Ожидание готовности:**
Дождитесь статуса `healthy` у всех контейнеров:
```sh
docker compose ps
```
4. **Запуск публичных тестов:**
```sh
PYTHONUTF8=1 python tests/smoke.py --base-url http://localhost:8080
```
5. **Запуск собственных тестов (уровень 4):**
```sh
PYTHONUTF8=1 python student-tests/test_level4.py
```
6. **Безопасная остановка:**
```sh
docker compose down
```
*Для намеренного удаления всех учебных данных используйте `docker compose down -v` (удалит volumes).*
## Архитектура и решения
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab3, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
**Схема процессов:**
Клиент → Nginx (порт 8080) → 2 API-реплики (FastAPI) → PostgreSQL (метаданные) + MinIO (файлы).
**Ключевые решения:**
1. **Источник истины:** PostgreSQL (пользователи, чаты, сообщения, сессии, метаданные вложений, ключи идемпотентности).
2. **Сессии:** Хранятся в PostgreSQL, что позволяет им выживать при перезапуске и быть доступными обеим репликам. Токены хранятся в виде SHA-256 хешей.
3. **Балансировка:** Nginx с директивой `least_conn` и таймаутами (`proxy_next_upstream`), чтобы быстро исключать упавшую реплику.
4. **Хранение файлов:** Байты хранятся в приватном бакете MinIO (`messenger-attachments`). Ключ объекта генерируется сервером (UUID), оригинальное имя файла используется только для отображения.
5. **Потоковая обработка:** Загрузка файлов реализована через `request.stream()` и `tempfile.SpooledTemporaryFile`. Файл не читается целиком в оперативную память, что защищает от OOM при пиковых нагрузках.
6. **Безопасность S3:** API использует отдельного пользователя `api-user` с ограниченной IAM-политикой (только GetObject/PutObject), а не root-доступ. Админ-консоль MinIO не проброшена наружу.
7. **Компенсация ошибок:** Если при загрузке файла S3 PUT прошел успешно, а запись в PostgreSQL упала, срабатывает блок `except`, который удаляет "осиротевший" объект из S3.
**Соответствие переменных `.env`:**
Переменные `S3_*` и `SESSION_TTL_SECONDS` передаются контейнерам через `compose.yaml`. Секрет БД передается через Docker Secrets (`/run/secrets/database_url`).
## Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | make test | TODO | TODO |
| Остальные пункты уровня 3 | TODO | TODO | TODO |
| Все пункты уровня 4, если заявлен | TODO | TODO | TODO |
| Выбранный трек 5, если заявлен | TODO | TODO | TODO |
| Критерий README | Команда/сценарий | Наблюдаемый результат |
| --- | --- | --- |
| Публичный smoke | `make test` | `PASS: lab4 public API scenario` |
| Уровень 3: S3, вложения | `make test` | Файл загружается, checksum совпадает, чужой получает 404 |
| Уровень 4: Негативные тесты | `python student-tests/test_level4.py` | PASS: 413 (big), 415 (broken), 415 (fake MIME), 400 (path traversal), 404 (ACL) |
| Уровень 4: Нагрузка на RAM | `python student-tests/test_level4.py` | 10 параллельных загрузок успешно, RAM не утекает (SpooledTemporaryFile) |
| Уровень 4: Failover | `python tests/resilience.py --mode failover --action-script scripts/stop_one.bat` | `PASS: failover preserved confirmed data and existing session` |
| Уровень 4: Persistence | `python tests/resilience.py --mode persistence --action-script scripts/restart.bat` | `PASS: persistence preserved confirmed data and existing session` |
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
*(Скриншот с успешным прохождением тестов прилагается в папке evidence).*
## Эксперименты и отказы
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| TODO | TODO | TODO | TODO |
| Остановка одной API-реплики (`stop_one.bat`) | Переключение трафика, ошибки только в момент отказа | 50 успешных записей, 4 ошибки (во время рестарта) | Восстановление за 0.953 сек. Данные сохранены. |
| Перезапуск всей системы (`restart.bat`) | Данные и сессии выживают | Успешно | Старый токен валиден. Вложения и сообщения на месте. |
| Загрузка файла > 10 МБ | Отклонение с 413 | Отклонено | Потери данных нет. |
| Одновременная загрузка 10 файлов | Отсутствие падения по памяти | Все 10 успешно | Потери данных нет. |
## Ограничения и следующие шаги
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
1. **Один Docker-host:** Стенд развернут на одной машине. Отказоустойчивость к потере физического сервера (host) не обеспечивается. Если сервер выключится, Nginx, PostgreSQL и MinIO упадут вместе.
2. **Секреты в Compose:** Для уровня 4 допустимо использование тестовых credentials для MinIO в открытом виде в `compose.yaml` (для синтетического стенда). Для production необходимо использовать Vault или Docker Secrets для всех компонентов.
3. **Orphan-очистка:** Компенсация работает на уровне кода API (try/except), но нет фонового "сборщика мусора" (reconciler), который бы проходил по S3 раз в час и удалял объекты старше 24 часов, не имеющие метаданных в БД. Это реализуется на оценку 5 (Трек 2).
4. **Производительность:** Замеров RPS для загрузки изображений не производилось (тестировалась только надежность и отсутствие OOM).
```