forked from mtusi2026/mtusi2026lab4
Замер 32 одновременных загрузок показал: семафор ограничивал только чтение тела, а буферы копились на этапе S3 PUT (+214 МБ при 4 слотах). Теперь пик при 32 клиентах тот же, что при 16. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
86 lines
16 KiB
Markdown
86 lines
16 KiB
Markdown
# Отчёт — лабораторная 4
|
||
|
||
- Автор, группа: Боданюк Алексей, БВТ2302
|
||
- Целевая оценка: **5**, трек 2 «Согласованность двух хранилищ»
|
||
- Ветка: `solution/bvt2302-bodanyuk`. Форк: `https://gitea.privcloud.tech/wfa/mtusi2026lab4`. PR: «ЛР 4 — БВТ2302 — Боданюк — на 5» в mtusi2026/mtusi2026lab4
|
||
- Стек: Python 3.13.16, Starlette 1.7.0, uvicorn 0.54.0, psycopg 3.3.6 + psycopg-pool 3.3.3, redis-py 8.1.0, argon2-cffi 25.1.0, **aiobotocore 3.9.2** (S3), **libjpeg-turbo 2.1.5 `djpeg`** (проверка JPEG); PostgreSQL 18.6, Valkey 8.1.3, HAProxy 3.2.26, **SeaweedFS 4.46**. Все образы закреплены по тегу **и** digest, все Python-пакеты — по sha256 ([requirements.txt](requirements.txt)), Debian-пакет — по версии ([Dockerfile](Dockerfile))
|
||
- Источники: README, COURSE, контракт ([openapi.json](contracts/openapi.json), [семантика](contracts/README.md)), документация S3 (PutObject/Content-MD5, ListObjectsV2), SeaweedFS (`weed server`, s3.json identities), PNG (RFC 2083 / W3C PNG 3rd ed.: chunks, CRC, zlib, фильтры, Adam7), libjpeg-turbo (`djpeg -strict`, `-scale`, `-maxmemory`), HAProxy 3.2 (`nbsrv`, `use_backend`, `http-request set-timeout`), cgroup v2 (`memory.peak`, `memory.events`). Учтены все замечания преподавателя к PR lab4 других студентов ([раздел ниже](#проверки-на-которых-ловили-другие-работы))
|
||
- Помощь ИИ: код, тесты, скрипты экспериментов и черновик отчёта написаны с помощью ИИ-ассистента Claude Code (Anthropic). Все команды и замеры реально выполнены на стенде ниже; вывод — в [evidence/](evidence/). Ответы на вопросы защиты — [docs/DEFENSE.md](docs/DEFENSE.md), согласованность хранилищ — [docs/CONSISTENCY.md](docs/CONSISTENCY.md), запуск на Windows и сценарий защиты — [docs/WINDOWS.md](docs/WINDOWS.md)
|
||
|
||
## Запуск из чистого clone
|
||
|
||
Нужны Git, Docker с Compose v2 (проверено: Docker 29.8.0, Compose 5.5.1), Python 3.9+ и GNU make (на Windows — см. [WINDOWS.md](docs/WINDOWS.md)). Учётные данные в Git не хранятся, их создаёт скрипт.
|
||
|
||
```sh
|
||
git clone https://gitea.privcloud.tech/wfa/mtusi2026lab4 mtusi2026lab4 && cd mtusi2026lab4 && git checkout solution/bvt2302-bodanyuk
|
||
python3 scripts/init_secrets.py # пароли PostgreSQL/Valkey и ТРИ пары ключей S3 -> ./secrets (git-ignored), идемпотентно
|
||
cp .env.example .env
|
||
docker compose --env-file .env config --quiet
|
||
docker compose --env-file .env up -d --build --wait
|
||
# postgres, valkey, s3 healthy -> migrate (0001..0004) и s3-init (bucket + проверка прав) exit 0 -> api x2 healthy -> lb
|
||
docker compose logs s3-init # anonymous GET/LIST -> 403, права ключей api/reconciler -> OK
|
||
make check && make test
|
||
make test-persistence ACTION_SCRIPT=scripts/restart.sh
|
||
make test-failover ACTION_SCRIPT=scripts/stop-one.sh && make restore
|
||
make reconcile # трек 2: dry-run, read-only отчёт JSON
|
||
```
|
||
|
||
- **Windows:** публичным тестам нужен `PYTHONUTF8=1`; хуки — через `scripts/restart.cmd` и `scripts/stop-one.cmd` (тот же `.sh` в Git Bash).
|
||
- **Свои тесты:** `python3 -m venv .venv`, `pip install --require-hashes --no-deps -r requirements.txt`, `pip install -r requirements-test.txt`, затем `make student-test` (~25 мин, стенд должен быть поднят). Без стенда — `make unit-test`.
|
||
- **Все доказательства одной командой** (на чистом clone, ~70 мин): `python scripts/collect_evidence.py`.
|
||
- **Bootstrap S3** — одноразовый сервис `s3-init` (`python -m messenger.s3_bootstrap`), идемпотентный: существующий bucket не трогает, sentinel-объект перезаписывает, затем проверяет модель доступа и **валит стенд** (exit 1), если bucket не приватный или у ключей лишние права. Повтор: `docker compose run --rm s3-init`.
|
||
- **Остановка:** безопасно — `docker compose down` (volumes `pgdata`, `valkeydata`, `s3data` сохраняются). Намеренное удаление учебных данных — `docker compose down -v` и `rm -rf secrets`.
|
||
|
||
## Архитектура и решения
|
||
|
||
```text
|
||
клиент ──127.0.0.1:8080──> lb: HAProxy 3.2 ──edge──> api × 2 (Starlette, без состояния и без volume)
|
||
│ backend api: /health/ready (PG + Valkey + S3) │
|
||
│ backend api_core: /health/ready/core (PG + Valkey) — только если ├─data (internal)──> postgres 18.6: users, chats, messages, attachments (метаданные)
|
||
│ в api нет ни одного UP (S3 упал у всех) │ valkey 8.1.3: сессии
|
||
└ upload: timeout server 60 s └─storage (internal)─> s3: SeaweedFS 4.46, bucket messenger-attachments (байты)
|
||
migrate ──data──> 0001…0004 s3-init ──storage──> bucket, sentinel, проверка прав reconciler (по требованию) ──data+storage──> сверка
|
||
```
|
||
|
||
| Роль | Service | Образ | Health / readiness | Volume | Сеть / порт | Credentials | CPU / RAM |
|
||
| --- | --- | --- | --- | --- | --- | --- | --- |
|
||
| Точка входа | `lb` | `haproxy:3.2.26-alpine@sha256:254e6370…` | `haproxy -c` + stats; бэкенды — активные проверки | — | edge; `127.0.0.1:8080`, `[::1]:8080`, `127.0.0.1:8404` | нет | 1.0 / 128m |
|
||
| API × 2 | `api` | `mtusi-messenger:lab4` из исходников | `/health/ready` (PG, Valkey, S3) | — | edge + data + storage, только `expose 8080` | `database_url`, `cache_url`, **своя** пара S3 (Read+Write bucket) | 1.0 / 512m, без swap |
|
||
| Миграции | `migrate` | тот же образ | exit 0 | — | data | `database_url` | 0.5 / 256m |
|
||
| Bootstrap S3 | `s3-init` | тот же образ | exit 0 | — | storage | admin + api + reconciler (для проверки прав) | 0.5 / 256m |
|
||
| БД | `postgres` | `postgres:18.6-bookworm@sha256:afc7e2d4…` | `pg_isready` | `pgdata` | data | `postgres_password` | 2.0 / 1g |
|
||
| Сессии | `valkey` | `valkey/valkey:8.1.3-bookworm@sha256:fea8b3e6…` | `valkey-cli ping` | `valkeydata` | data | `valkey_password` | 0.5 / 256m |
|
||
| Объекты | `s3` | `chrislusf/seaweedfs:4.46@sha256:08d51613…` | `GET /healthz` | `s3data` | storage, `8333` (S3 API) — не опубликован | identities из secrets ([start.sh](infra/seaweedfs/start.sh)) | 1.0 / 1g |
|
||
| Сверка (трек 2) | `reconciler` (профиль `tools`) | тот же образ | — | — | data + storage | `database_url`, пара S3 reconciler (+List) | 1.0 / 256m |
|
||
|
||
**Что перенесено из lab3** (отдельный коммит `d916d09`, без изменений): API, миграции 0001–0003, HAProxy без sticky с re-resolve DNS, общая идемпотентность, graceful shutdown, сессии в Valkey, все тесты lab3. **Что сделано в lab4:**
|
||
|
||
- **Выбор S3: SeaweedFS 4.46.** Репозитория `minio/minio` в Docker Hub больше нет (проверено при выборе), SeaweedFS активно развивается и поддерживает identity с правами на bucket. Один контейнер (`weed server`: master + volume + filer + S3 gateway). Web-интерфейсы master/filer/volume и их gRPC слушают **только 127.0.0.1 внутри контейнера** (`-ip.bind`), в сеть `storage` выходит лишь S3 API (8333/18333). Сеть internal, на хосте ничего не опубликовано. Телеметрия выключена, встроенный IAM API выключен, автосоздание bucket выключено.
|
||
- **Права.** Три пары ключей (`init_secrets.py`): `admin` (создание bucket) — только у `s3` и `s3-init`; `messenger-api` — `Read`+`Write` **на один bucket**, без `List` и `Admin`; `messenger-reconciler` — плюс `List`. Анонимной identity нет, поэтому bucket приватный. `s3-init` проверяет всё это при каждом запуске, включая канареечный bucket: API не видит его в ListBuckets и не может читать из него (403).
|
||
- **Модель данных** ([0004_attachments.sql](migrations/0004_attachments.sql), [DATA_MODEL.md](docs/DATA_MODEL.md)): `attachments` (метаданные; `object_key = o/<128 случайных бит>` назначает сервер; `status pending|ready`; карантин `lost_at/lost_reason`), `message_attachments` (FK + обратный поиск), `messages.attachment_ids uuid[]` (порядок, чтение истории остаётся одним index range scan). Отправка сообщения — SQL-функция `post_message_v2`, тоже одна транзакция.
|
||
- **Загрузка** ([attachments.py](src/messenger/attachments.py), [images.py](src/messenger/images.py)): `auth → членство (404) → filename / Content-Type / Content-Length (400/415/413) → слот загрузки → тело кусками с дедлайном → формат и пиксели по первым байтам → полная проверка → pending → PUT → ready → 201`. Подробно о порядке и сбоях — [CONSISTENCY.md](docs/CONSISTENCY.md).
|
||
- **Проверка содержимого.** PNG — свой потоковый валидатор: сигнатура, CRC **каждого** chunk, порядок chunk'ов, zlib-поток IDAT распаковывается порциями по 1 MiB и сразу выбрасывается, его длина должна быть ровно `height × (1 + байт в строке)` (Adam7 — по проходам), байт фильтра каждой строки ≤ 4, IEND в конце и ничего после него. Растр в памяти не создаётся. JPEG — `djpeg -strict -scale 1/8 -maxmemory`: эталонный декодер в отдельном процессе декодирует весь файл, любое предупреждение libjpeg — ошибка. Pillow для этого не годится: JPEG без данных после SOS он «успешно» декодирует в серую картинку (проверено). MIME определяется по байтам; несовпадение с `Content-Type` — 415.
|
||
- **Лимиты до чтения/декодирования.** `Content-Length > 10 MiB` → 413 без чтения тела; без длины (chunked) — 413 при пересечении лимита. Пиксели — из IHDR/SOFn по первым байтам: 20000×10000 → 413 через 33 байта, ничего не декодируется. Тело — один буфер ровно `Content-Length` байт (без копий до S3 и djpeg). Одновременно на реплику: `UPLOAD_CONCURRENCY=4` тела (остальные ждут ≤ 5 с с байтами в TCP-буфере, затем 503 + `Retry-After`), `IMAGE_VERIFY_CONCURRENCY=1` полная проверка. Дедлайны: тело 30 с, проверка 10 с, S3 3 с (+ время на объём), в HAProxy для загрузки `timeout server 60s`.
|
||
- **Скачивание** — только через API, без redirect: членство → `GET` объекта → стриминг кусками по 64 KiB (память не зависит от размера). Заголовки: настоящий `Content-Type`, `Content-Length`, `Content-Disposition: attachment` (ASCII-fallback + RFC 5987), `X-Content-Type-Options: nosniff`, `Cache-Control: private, no-store`, `ETag` = SHA-256.
|
||
- **Готовность и деградированный режим.** `/health/ready` включает S3 (загрузка и скачивание — обязательный синхронный путь): S3 недоступен → 503. S3 — общая зависимость, и если он упал у всех, HAProxy переключается на backend `api_core` (проверка `/health/ready/core`: PG + Valkey). Чаты и текст работают, запросы к вложениям API сам отвечает 503 за ≤ 3 с. Если S3 потеряла одна реплика, она DOWN в `api`, трафик идёт на другую.
|
||
- **Janitor** (в каждой реплике, раз в ~60 с, advisory-замок): `pending` старше `PENDING_GRACE_SECONDS=900` → под `FOR UPDATE SKIP LOCKED` удалить объект, затем строку.
|
||
- **Reconciler (трек 2)** — [reconcile.py](src/messenger/reconcile.py), раздел «Трек 2» ниже.
|
||
- **`FAULT_POINTS`** (`after_s3_put`, `after_ready_commit`) — внедрение отказа ровно между шагами записи, только для экспериментов. По умолчанию пусто; неизвестное значение — ошибка конфигурации.
|
||
|
||
Readiness-критичные зависимости: PostgreSQL, Valkey и S3. LB в деградированном режиме обходится без S3.
|
||
|
||
Соответствие `.env.example` реальной конфигурации ([config.py](src/messenger/config.py), [compose.yaml](compose.yaml)):
|
||
|
||
| Переменная | Значение | Где используется |
|
||
| --- | --- | --- |
|
||
| `APP_HOST`, `APP_PORT`, `APP_ENV`, `SESSION_TTL_SECONDS`, `DATABASE_URL_FILE`, `SESSION_STORE`, `CACHE_URL_FILE`, `API_REPLICAS`, `IDEMPOTENCY_TTL_SECONDS` | как в lab3 | без изменений |
|
||
| `S3_ENDPOINT`, `S3_REGION`, `S3_BUCKET` | `http://s3:8333`, `us-east-1`, `messenger-attachments` | клиент S3 API, s3-init, reconciler; bucket создаёт s3-init |
|
||
| `S3_ACCESS_KEY_ID_FILE`, `S3_SECRET_ACCESS_KEY_FILE` | `/run/secrets/s3_access_key_id`, `…/s3_secret_access_key` | у API это **его** пара (secrets `s3_api_*` смонтированы под этими именами), у reconciler — его пара |
|
||
| `MAX_UPLOAD_BYTES`, `MAX_IMAGE_PIXELS` | `10485760`, `40000000` | лимиты контракта; можно уменьшить, увеличить нельзя (ConfigError) |
|
||
| `UPLOAD_CONCURRENCY`, `UPLOAD_QUEUE_TIMEOUT_SECONDS`, `UPLOAD_READ_TIMEOUT_SECONDS` | `4`, `5`, `30` | слоты загрузки на реплику, ожидание слота, дедлайн тела |
|
||
| `IMAGE_VERIFY_CONCURRENCY`, `IMAGE_VERIFY_TIMEOUT_SECONDS`, `JPEG_MAX_MEMORY_MB` | `1`, `10`, `256` | одновременные полные проверки, дедлайн проверки, `djpeg -maxmemory` |
|
||
| `S3_TIMEOUT_SECONDS` | `3` | дедлайн каждого вызова S3 (PUT — плюс время на объём) |
|
||
| `PENDING_GRACE_SECONDS`, `JANITOR_INTERVAL_SECONDS` | `900`, `60` | janitor незавершённых загрузок |
|
||
| `FAULT_POINTS` | пусто | внедрение отказов в экспериментах |
|
||
| `API_CPUS/MEMORY`, `S3_CPUS/MEMORY`, `PG_*`, `VALKEY_CPUS`, `LB_CPUS` | 1.0/512m, 1.0/1g, 2.0/1g, 0.5, 1.0 | лимиты контейнеров |
|