forked from mtusi2026/mtusi2026lab4
131 lines
12 KiB
Markdown
131 lines
12 KiB
Markdown
# Отчёт — лабораторная 4
|
||
|
||
- Автор, группа: Журавлев Алексей, БПИ2301.
|
||
- Целевая оценка: 4; выбран MinIO, S3-совместимый сервер.
|
||
- Использованные источники и помощь: README/контракты лабораторных 3 и 4; собственная реализация; помощь ИИ при проверке.
|
||
|
||
## Запуск из чистого clone
|
||
|
||
Проверено на Windows 11, Docker Engine 29.8.2, Docker Compose v5.5.1,
|
||
Python 3.14.6 на хосте. Контейнер API собирается на Python 3.12.11.
|
||
Образы Postgres 16.8, Redis 7.4.2, Nginx 1.27.5 и MinIO
|
||
`RELEASE.2025-09-07T16-13-09Z` закреплены версиями; MinIO также закреплён
|
||
digest в `compose.yaml`.
|
||
|
||
PowerShell из корня проекта:
|
||
|
||
```powershell
|
||
.\scripts\init-local-secrets.ps1
|
||
# Если порт 8080 уже занят, изменить APP_PORT в локальном .env на 8081.
|
||
docker compose --env-file .env config --quiet
|
||
docker compose --env-file .env up -d --build
|
||
docker compose --env-file .env ps
|
||
py -3 -m venv .venv
|
||
.\.venv\Scripts\python.exe -m pip install -r requirements-dev.txt
|
||
make check PYTHON='py -3 -X utf8'
|
||
make validate PYTHON='.\.venv\Scripts\python.exe -X utf8'
|
||
make test PYTHON='py -3 -X utf8' BASE_URL=http://localhost:8081
|
||
make test-attachments PYTHON='py -3 -X utf8' BASE_URL=http://localhost:8081
|
||
make test-private-bucket PYTHON='py -3 -X utf8'
|
||
make test-s3-outage PYTHON='py -3 -X utf8' BASE_URL=http://localhost:8081
|
||
```
|
||
|
||
Скрипт создаёт локальные `.env` и `secrets/`; значения не выводятся и
|
||
исключены из Git. В этой среде порт `8080` занят стендом lab3, поэтому
|
||
используется `8081`. При отсутствии конфликта можно оставить порт `8080` и
|
||
передать соответствующий `BASE_URL`.
|
||
Для restart/failover checks используйте `make test-persistence` с
|
||
`ACTION_SCRIPT=scripts/restart.bat` и `make test-failover` с
|
||
`ACTION_SCRIPT=scripts/stop-one.bat`. Failover hook намеренно оставляет
|
||
реплику остановленной; после проверки восстановите две реплики:
|
||
`docker compose --env-file .env up -d --scale api=2`.
|
||
|
||
Остановка без удаления учебных данных: `docker compose --env-file .env down`.
|
||
Команда `docker compose --env-file .env down -v` намеренно удаляет volumes
|
||
PostgreSQL, Redis и MinIO и нужна только при осознанном сбросе тестового стенда.
|
||
|
||
## Архитектура и решения
|
||
|
||
```text
|
||
Клиент -> Nginx -> API x2 -> PostgreSQL (сессии вложений/сообщений)
|
||
-> Redis (сессии входа)
|
||
-> приватный MinIO bucket (байты вложений)
|
||
```
|
||
|
||
Из lab3 перенесены базовые API, авторизация, PostgreSQL/Redis, миграции,
|
||
идемпотентность сообщений, Dockerfile и Nginx. Метаданные вложений и связь
|
||
с сообщениями добавлены миграцией `003`; исходные байты хранятся только в
|
||
MinIO под случайным server-generated key. PostgreSQL определяет статус,
|
||
владельца и доступ; скачивание проходит через авторизованный API.
|
||
|
||
Загрузка ограничена 10 MiB и 40 млн пикселей. PNG/JPEG проверяются по
|
||
содержимому, MIME и имени файла. Тело читается чанками во временный
|
||
`SpooledTemporaryFile` с порогом 1 MiB; параллелизм настраивается
|
||
`MAX_CONCURRENT_UPLOADS` (по умолчанию 16, максимум 64). Есть таймауты S3.
|
||
Запись сначала резервируется в PostgreSQL как `processing`, затем пишется
|
||
объект, после чего metadata становится `ready`. Ошибки компенсируются
|
||
удалением объекта и переводом записи в `failed`.
|
||
|
||
У MinIO приватный bucket `messenger-attachments`, отдельный API user и
|
||
версионированная policy: `Get/Put/DeleteObject` только для `objects/*`,
|
||
`ListBucket` только с префиксом `objects/`, а `GetBucketLocation` разрешён
|
||
отдельно для readiness. Bootstrap повторно запускается без удаления volumes
|
||
и заменяет предыдущую policy. API, PostgreSQL, Redis и MinIO не имеют
|
||
опубликованных host ports; доступен только Nginx. MinIO console не опубликована.
|
||
|
||
Для старых `processing`/неиспользуемых объектов есть reconciler с dry-run
|
||
по умолчанию и обязательным grace period не менее 900 секунд:
|
||
|
||
```powershell
|
||
docker compose --env-file .env exec -T api python scripts/reconcile_attachments.py
|
||
docker compose --env-file .env exec -T api python scripts/reconcile_attachments.py --apply
|
||
```
|
||
|
||
## Доказательства критериев
|
||
|
||
| Критерий | Команда/сценарий | Наблюдаемый результат | Доказательство |
|
||
| --- | --- | --- | --- |
|
||
| Контракт и OpenAPI | `make check`, `make validate` | Оба PASS; offline structure и OpenAPI 3.1/JSON Schema валидны | stdout проверок |
|
||
| Публичный smoke lab4 | `make test ... BASE_URL=http://localhost:8081` | PASS: публичный сквозной сценарий, включая вложение и контроль доступа | stdout `tests/smoke.py` |
|
||
| Вложения и ошибки | `make test-attachments ...` | PASS: >10 MiB и >40 MP отклонены; damaged image/MIME spoof отклонены; опасное имя и чужие чаты/ID не дают 500 | stdout `student-tests/test_attachments.py` |
|
||
| Загрузка и скачивание | Smoke + attachment tests | Метаданные `ready`; скачанный оригинал совпадает побайтно; доступ проверяется членством в чате | публичный smoke |
|
||
| Отказ одной API-реплики | `make test-failover ... ACTION_SCRIPT=scripts/stop-one.bat` | Наблюдались 2 реплики; поочерёдные тестовые запуски останавливали `api-1` и `api-2`; подтверждённые записи и вложение читались после отказа | stdout `tests/resilience.py`; Compose status |
|
||
| Restart всего стенда | `make test-persistence ... ACTION_SCRIPT=scripts/restart.bat` | PASS: данные, оригинал вложения и существующая сессия доступны после restart API, PostgreSQL, Redis, MinIO и Nginx без удаления volumes | stdout `tests/resilience.py`; `scripts/restart.bat` |
|
||
| Отказ MinIO | `make test-s3-outage ...` | Upload при отказе вернул 503; сервис восстановился с сохранёнными volumes | stdout `student-tests/test_s3_outage.py` |
|
||
| Приватность и права bucket | `make test-private-bucket` | PASS: анонимный list получает 403; порт S3 не опубликован | stdout `student-tests/check_private_bucket.py` |
|
||
| Bootstrap и ограниченная policy | Два повторных bootstrap; проверка `mc admin policy info` | PASS: policy создана/повторно применена, старая policy удалена; bucket и volumes сохранены | Compose bootstrap logs и policy в MinIO |
|
||
| Reconciliation | Dry-run, затем `--apply` на искусственно состаренной записи | Dry-run обнаружил одну stale `processing` запись; apply пометил её `failed`. Финальный dry-run: 0 действий, 0 missing/orphan | stdout `reconcile_attachments.py` |
|
||
| Потоковая обработка и память | 10 параллельных медленных загрузок PNG 2,562,448 байт | PASS за 2.315 с; суммарная sampled RAM API baseline 128,198,901 B, peak 141,882,817 B, delta 13,683,916 B | [attachment-concurrency.json](./evidence/attachment-concurrency.json) |
|
||
|
||
Failover сценарии на двух репликах восстановили успешные записи примерно за
|
||
0.68–0.87 с; переходные неопределённые POST повторялись с тем же
|
||
idempotency key. После тестов обе реплики восстановлены. Выбран только уровень
|
||
4; исследовательский трек уровня 5 не заявляется.
|
||
|
||
## Эксперименты и отказы
|
||
|
||
| Воздействие | Ожидание | Наблюдение | Восстановление / потеря данных |
|
||
| --- | --- | --- | --- |
|
||
| 10 одновременных медленных PNG upload | Ограниченный буфер RAM, успех всех валидных файлов | 10/10; файл 2.56 MB; sampled peak delta около 13.7 MB для двух API-контейнеров | 2.315 с; ошибок/потерь нет |
|
||
| Остановка API-реплики | LB продолжает обслуживать запросы другой репликой; данные не дублируются | В двух запусках проверены `api-1` и `api-2`; финальные повторы дали 102/102 и 120/120 успешных записей, время до первого успеха 0.804/0.788 с | Данные, существующий token и вложение сохранены |
|
||
| Остановка MinIO | API явно сообщает временную недоступность, затем восстанавливается | Upload вернул 503; после возврата MinIO API стал healthy | Потери volumes не было |
|
||
| Restart API + PostgreSQL + Redis + MinIO + Nginx | Сохранить историю, вложение и существующую сессию | Persistence test PASS без повторного входа | Volumes сохранены |
|
||
| Сверка старой upload reservation | Не менять свежие записи; сначала показать план, затем исправить устаревшую | Dry-run нашёл одну искусственно состаренную запись; apply пометил её `failed`; финальный dry-run ничего не менял | Удаление выполняется только для объектов/записей старше grace period |
|
||
|
||
RAM измерялась `docker stats` примерно раз в секунду, всего три sample за
|
||
короткий запуск. Короткий пик мог быть пропущен; изменение RAM — измерение
|
||
агрегата двух API-контейнеров, а не строгая верхняя граница. Это проверка
|
||
ограниченного потокового профиля, не benchmark throughput и не track уровня 5.
|
||
|
||
## Ограничения и следующие шаги
|
||
|
||
- MinIO, PostgreSQL, Redis, Nginx и Docker host одноузловые. Сценарий
|
||
сохраняет данные при отказе API и рестарте с volumes, но не при потере host
|
||
или отдельного state volume.
|
||
- PostgreSQL и S3 не имеют общей транзакции; компенсация и reconciler уменьшают
|
||
последствия частичного сбоя, но не обеспечивают атомарность между системами.
|
||
- Проверка чистого скачивания MinIO image из внешнего registry не выполнялась:
|
||
этот digest был доступен локально в среде разработки.
|
||
- Данные smoke — синтетические и намеренно остаются в локальных volumes до
|
||
явного сброса.
|