Стенд: PostgreSQL 16 + две API-реплики за HAProxy + SeaweedFS S3 в приватном bucket. Метаданные вложений в PostgreSQL, байты в S3, object key назначает сервер. Лимиты 10 MiB и 40 млн пикселей, MIME по магическим байтам, проверка filename. Добавлены smoke/негативные тесты, хуки restart/stop-one, сценарий отказа S3 и отчёт с доказательствами.
20 KiB
Отчёт — лабораторная 4
- Автор, группа: Ким Владимир, БВТ2302
- Целевая оценка; 3
- Commit/PR: ветка
solution/bvt2302-kim; PR в исходный репозиторий открывается после push. - Использованные источники, библиотеки и помощь ИИ: контракт и рубрика репозитория; документация S3
(upload/presigned), SeaweedFS (S3 gateway,
s3.jsonidentities), boto3/botocore, psycopg 3, Pillow, HAProxy.
Запуск из чистого clone
Версии закреплены:
| Роль | Образ | Версия |
|---|---|---|
| API | python:3.12.7-slim-bookworm (digest sha256:60d9996b6a8a3689d36db740b49f4327be3be09a21122bd02fb8895abb38b50d) + requirements.txt |
boto3 1.35.36, Pillow 11.0.0, psycopg 3.2.3, psycopg_pool 3.2.3 |
| PostgreSQL | postgres:16.4-alpine |
16.4 |
| S3 | chrislusf/seaweedfs:3.71 |
3.71 |
| Load balancer | haproxy:3.0.8-alpine |
3.0.8 |
# 1. Локальная конфигурация: секреты только в .env, файл в Git не попадает.
cp .env.example .env
# Отредактировать пароли/секреты. Для локального стенда достаточно синтетических значений.
# 2. Проверка структуры и конфигурации Compose.
python scripts/check_contract.py
python scripts/validate_openapi.py # требует requirements-dev.txt
# На Windows глобальный Python может не иметь openapi-spec-validator;
# полная валидация выполнялась интерпретатором из .venv:
# .\.venv\Scripts\python.exe scripts/validate_openapi.py
docker compose --env-file .env config --quiet
# 3. Сборка и запуск. Bucket создаёт one-shot контейнер `bootstrap`; схему
# PostgreSQL мигрирует каждая API-реплика при старте (идемпотентно, под
# advisory lock).
docker compose --env-file .env up -d --build
# 4. Готовность (PostgreSQL + S3). LAB4_PORT по умолчанию 8080;
# на машине автора порт 8080 занят стендом lab3, поэтому в .env стоит 8081.
curl -fsS http://127.0.0.1:8081/health/ready
# 5. Публичный smoke и собственные проверки.
python tests/smoke.py --base-url http://127.0.0.1:8081
python -m unittest discover -s student-tests -v
python student-tests/test_api_negative.py --base-url http://127.0.0.1:8081
# 6. Сценарии отказов (явные, останавливают инфраструктуру).
python tests/resilience.py --mode persistence --action-script scripts/restart.cmd --base-url http://127.0.0.1:8081
python tests/resilience.py --mode failover --action-script scripts/stop-one.cmd --base-url http://127.0.0.1:8081
python scripts/evidence_s3_outage.py
scripts/restart.sh / scripts/stop-one.sh — POSIX-варианты для Linux/macOS (chmod +x нужен перед
запуском). scripts/restart.cmd / scripts/stop-one.cmd — эквиваленты для Windows: тест запускает hook
без shell interpolation, поэтому на Windows нужен исполняемый файл с расширением .cmd.
Безопасная остановка (данные сохраняются):
docker compose --env-file .env stop
Намеренное удаление учебных данных (необратимо, только для локального стенда):
docker compose --env-file .env down -v
Архитектура и решения
клиент ──HTTP──> HAProxy :8080 ──> api1:8080 ─┐
│ ├──> PostgreSQL (users, chats, members,
└────────> api2:8080 ────┘ messages, attachments, idempotency)
└──> SeaweedFS S3 :8333 (приватный bucket,
только байты изображений)
- Источник истины — PostgreSQL. Метаданные вложения (
id,chat_id,owner_id,filename,content_type,size_bytes,sha256,object_key,status,variants,error_code, таймстемпы) хранятся только там. Байты — только в приватном bucket; локального каталога с оригиналами у API нет. - Object key назначает сервер:
chats/<chat_id>/<attachment_id>/original.filename— только отображаемое имя, в путь/ключ не попадает. - Транзакционные границы. Upload: проверка доступа и лимитов → проверка изображения →
PUTв S3 →INSERTметаданных в PostgreSQL. ЕслиINSERTне удался, объект удаляется компенсацией (app/server.py,_upload_attachment), поэтому неучтённых объектов не остаётся. Обратный случай (метаданные без объекта) виден как404на download и не превращается в 500. - 201 ready возвращается только после успешной записи объекта и метаданных, то есть когда оригинал действительно доступен любой реплике.
- Идемпотентность сообщений. Таблица
idempotency(user_id, chat_id, key)+ транзакционный advisory lock по SHA-256 области уникальности; сообщение и запись результата создаются в одной транзакции, повтор с другим body —409. - Сессии. Непрозрачный токен (32 случайных байта, base64url), в БД только SHA-256 токена и expiry.
TTL —
SESSION_TTL_SECONDS(по умолчанию 3600). - Пароли —
scrypt(N=2^14, r=8, p=1) с солью, сравнениеhmac.compare_digest; для неизвестного username выполняется фиктивная проверка, чтобы не выдавать существование пользователя по времени. - Курсоры пагинации — HMAC-подписанный base64url JSON с
(created_at, id)и привязкой к ресурсу (kind,chat_id); чужой/испорченный курсор —400. - Readiness.
/health/readyпроверяет PostgreSQL и S3, потому что обязательный синхронный путь включает скачивание оригинала. При недоступности S3 реплики исключаются из LB, клиент получает503; это осознанный выбор, зафиксированный вapp/server.py. - Лимиты.
Content-Length/chunked чтение ограниченыMAX_UPLOAD_BYTES(10 MiB) до чтения тела; MIME проверяется по магическим байтам, число пикселей — по заголовку изображения до полного декодирования (MAX_IMAGE_PIXELS= 40 млн). Полное тело ограничено 10 MiB, поэтому RAM одной загрузки ограничена сверху; download идёт чанками по 64 KiB. - Инфраструктура. SeaweedFS запускается одним процессом
weed serverс master/volume/filer/S3. Административная идентичность (S3_ADMIN_*) используется только one-shotbootstrap; API использует отдельную идентичность с действиямиRead/Write/List/Tagging. Bucket создаётся идемпотентно (app/bootstrap_s3.py:head_bucket→create_bucket, повторный запуск безопасен). Порт S3 и внутренние порты API не публикуются на хост; наружу открыт только LB (loopback). - LB. HAProxy в режиме HTTP с
option http-server-close: без него клиентские keep-alive соединения закреплялись за одной репликой и roundrobin не наблюдался. Имена реплик разрешаются через DNS Docker (resolvers docker,init-addr none) с периодическим переразрешением: иначе HAProxy запоминал IP, полученный при одновременном старте, и после пересоздания контейнера мог ходить не туда.timeout connect 500ms,retries 2,option redispatchи частые health-check дают переключение на живую реплику за единицы секунд.
Соответствие переменных .env.example реальной конфигурации:
| Переменная | Где используется |
|---|---|
APP_HOST, APP_PORT |
адрес прослушивания API (app/config.py) |
DATABASE_URL |
строка подключения psycopg (в Compose собирается из POSTGRES_*) |
POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB |
сервис PostgreSQL и сборка DATABASE_URL |
S3_ENDPOINT, S3_REGION, S3_BUCKET |
клиент S3 и bootstrap |
S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY |
идентичность API в s3.json SeaweedFS |
S3_ADMIN_ACCESS_KEY_ID, S3_ADMIN_SECRET_ACCESS_KEY |
идентичность one-shot bootstrap |
SESSION_TTL_SECONDS, IDEMPOTENCY_TTL_SECONDS |
TTL сессий и окно идемпотентности |
MAX_UPLOAD_BYTES, MAX_IMAGE_PIXELS |
лимиты загрузки |
CURSOR_SECRET |
HMAC-подпись курсоров, одинаковый у всех реплик |
LAB4_PORT |
host-порт LB (по умолчанию 8080, у автора 8081) |
Приложение также поддерживает *_FILE-варианты секретов (DATABASE_URL_FILE,
S3_SECRET_ACCESS_KEY_FILE и т.д.) на случай запуска вне Compose.
Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|---|---|---|---|
| Офлайн-структура контракта | python scripts/check_contract.py |
PASS: offline skeleton structure... |
evidence/check-contract.txt |
| Полная валидация OpenAPI 3.1 | python scripts/validate_openapi.py (после requirements-dev.txt) |
PASS: full OpenAPI 3.1 and JSON Schema validation |
evidence/validate-openapi.txt |
| Compose-конфигурация | docker compose --env-file .env config --quiet |
exit 0, ошибок нет | вывод команды в логе работы |
| Публичный smoke (health, users, sessions, chats, messages, pagination, idempotency, upload/download, SHA-256, чужой доступ, logout) | python tests/smoke.py --base-url http://127.0.0.1:8081 |
PASS: lab4 public API scenario |
evidence/smoke.txt |
| S3-сервер в общем стенде, приватный bucket | docker compose ps; python scripts/verify_private_bucket.py (внутри сети) |
объекты в bucket есть; анонимный GET объекта — 403, анонимный list — 403 |
evidence/docker-ps.txt, evidence/private-bucket.txt |
| Метаданные в PostgreSQL, байты не в БД/локальном каталоге | \d attachments; поиск файлов в контейнере API |
таблица attachments без BLOB-колонок; в /app только код, оригиналов нет |
evidence/db-schema.txt |
| 201 ready после сохранения; побайтное скачивание PNG и JPEG | smoke + student-tests/test_api_negative.py |
status=ready, SHA-256 и размер совпадают, скачанные байты идентичны; отдельный сценарий реального JPEG 640×480 проходит загрузку и скачивание |
evidence/smoke.txt, evidence/negative.txt |
Message с attachment_ids читается участниками чата |
student-tests/test_api_negative.py (сценарий attachment_ids survive message history) |
элемент истории совпадает с ответом POST, attachment_ids сохранены |
evidence/negative.txt |
| PNG/JPEG ≤10 MiB и ≤40 млн пикселей; MIME по содержимому; опасные filename; лимиты до декодирования | python student-tests/test_api_negative.py --base-url ... |
12/12 сценариев PASS: 413 на размер и пиксели, 415 на битый файл/подмену MIME, 400 на /, \, NUL, LF |
evidence/negative.txt |
| Чужой чат и чужое вложение | smoke (eve → 404), test_api_negative.py |
404 на метаданные и bytes, 404 при привязке вложения другого чата, сообщение не создаётся |
evidence/smoke.txt, evidence/negative.txt |
| Upload → остановка обслужившей реплики → download через другую | tests/resilience.py --mode failover --action-script scripts/stop-one.cmd |
2 реплики до отказа, 112 успешных записей, 0 неопределённых ошибок, восстановление 2.33 с, остановленная реплика не обслуживает, вложение скачано через другую | evidence/failover.txt |
| Restart стенда с сохранением volumes | tests/resilience.py --mode persistence --action-script scripts/restart.cmd |
сессия и данные живы, оригинал скачан побайтно после рестарта всех сервисов | evidence/persistence.txt |
| Недоступность S3 | python scripts/evidence_s3_outage.py |
readiness 503, upload/download 503 (в т.ч. JSON unavailable с X-Request-Id от реплики), после старта S3 оригинал идентичен |
evidence/s3-outage.txt |
| Unit-проверки валидаторов | python -m unittest discover -s student-tests -v |
6 тестов OK (пароли, курсоры, изображения, filename) | evidence/unit-tests.txt |
Дополнительно: make test BASE_URL=http://127.0.0.1:8081, make test-negative, make student-tests —
те же сценарии через Makefile. make check требует UTF-8 режим Python на Windows (PYTHONUTF8=1),
иначе contracts/openapi.json читается в cp1251. На машине автора make не установлен, поэтому все
результаты выше получены прямыми командами из блока «Запуск из чистого clone»; цели Makefile —
эквивалентные обёртки для POSIX-окружения.
Эксперименты и отказы
Аппаратура: AMD Ryzen 7 7700 (8C/16T), 31.1 GiB RAM, Docker Desktop 29.4.3, Windows 11. Лимиты CPU/RAM контейнерам не задавались (учебный локальный стенд). Данные синтетические.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|---|---|---|---|
docker stop обслужившей API-реплики во время потока POST |
LB уводит трафик на вторую реплику, подтверждённые сообщения не теряются, дублей нет | 2 реплики наблюдались до отказа; 112 успешных записей за 15 с, 0 ошибок; первая успешная запись после старта hook — 2.33 с; остановленная реплика отсутствует в последних ответах. В более ранних прогонах (до настройки timeout connect/health-check) было 58–59 записей и 2–4 ошибки переходного периода, дублей не возникало ни разу |
восстановление 2.3 с (ранее 5.3–7.4 с); потерь подтверждённых данных нет |
Рестарт postgres, seaweedfs, haproxy, api1, api2 с теми же volumes |
сессия, чат, сообщения, метаданные и оригинал сохраняются | PASS: persistence preserved confirmed data and existing session; download после рестарта побайтно совпал |
простой на время рестарта (~10–20 с); потерь нет |
Остановка S3 (docker stop lab4-seaweedfs) |
attachment endpoints отвечают 503, метаданные остаются, данные не теряются | LB /health/ready → 503; upload и download → 503; прямой запрос к реплике: метаданные 200, content 503 с error_code=unavailable; после старта S3 оригинал идентичен |
после старта S3 готовность вернулась; потерь нет |
Повторная загрузка с тем же Idempotency-Key и другим body |
409 без второго сообщения | 409 conflict в smoke |
— |
Ограничения измерений: отдельный нагрузочный эксперимент (RPS/p50/p95/p99, пик RAM при ≥10 одновременных загрузках) не проводился, так как он относится к уровню 4. Числа failover — это наблюдения нескольких локальных прогонов, а не гарантия SLA: LB, PostgreSQL и S3 развёрнуты на одном Docker-host, поэтому потеря хоста не выдерживается.
Ограничения и следующие шаги
- Заявлен и реализован уровень 3. Инженерно закрыты отдельные практики уровня 4 (компенсация при сбое между S3 и PostgreSQL, отдельная ограниченная идентичность API, проверка приватности bucket, расширенные негативные тесты), но полный уровень 4 не заявляется: нет документированного reconciler с grace period и эксперимента с ≥10 одновременными загрузками и измерением пика RAM.
- Изображение читается в память целиком, но не более 10 MiB на запрос; потоковая обработка тела загрузки и вынесение декодирования в отдельный процесс — следующий шаг.
- Rate limiting (
429) не реализован: схема допускает код, но рубрика уровня 3 его не требует. - Сессии хранятся в PostgreSQL; отдельный Redis/Valkey не используется.
- Один Docker-host: отказ диска/host/сети не выдерживается; HA PostgreSQL и LB не заявляются.
- Компенсация покрывает сбой между
PUTв S3 иCOMMITв PostgreSQL. Полная сверка «БД ↔ S3» (reconciler с dry-run и grace period) — трек 2 уровня 5, он не реализован. - Ключи и пароли в
.env— синтетические локальные значения;.envв Git не попадает.