Files
mtusi2026lab4/REPORT.md
T
ricoromaandClaude Opus 5.5 1471f07a0e docs: re-capture s3-storage evidence after verify fixes
- evidence/s3 and evidence/tests re-captured from f57635a: first write
  after healthy, deleted bucket, netstat-based port check, readiness
  with s3 paused, prefix cleanup check
- PLAN: HEAD on a deleted bucket is an accepted limitation
- KNOWN_ISSUES: bootstrap after a manual bucket delete

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-20 21:47:01 +03:00

23 KiB
Raw Blame History

Отчёт — лабораторная 4

  • Автор, группа: TODO
  • Целевая оценка; выбранный трек 5, если нужен: TODO
  • Commit/PR: TODO после публикации
  • Использованные источники, библиотеки и помощь ИИ: TODO

Запуск из чистого clone

TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.

S3 (change s3-storage)

make env_setup создаёт новый .env из .env.example со случайными паролями PostgreSQL и Valkey и пятью секретами S3 и печатает только их имена. Существующий .env он не трогает.

Шаг оператора для .env, созданного до change s3-storage. Перенесите блок S3 из .env.example руками. Пять пустых секретов (S3_ROOT_ACCESS_KEY, S3_ROOT_SECRET_KEY, S3_JWT_SIGNING_KEY, S3_API_ACCESS_KEY, S3_API_SECRET_KEY) заполните значениями openssl rand -hex 32. Без них любая команда compose останавливается с сообщением «… is empty, copy S3 lines from .env.example».

  • make run_docker. Порядок старта:

    • postgres, valkey и s3 до healthy;
    • одноразовые migrate и s3-bootstrap (приватный bucket, пользователь API, проверки приватности);
    • api × 2 после успешного завершения обоих;
    • haproxy на 127.0.0.1:8080.

    Проверки — make test, make student_test, make s3_check.

  • make run_dev. Цепочка make upgrade, make start_cache и make start_s3: up -d --wait s3, затем up --no-deps --exit-code-from s3-bootstrap s3-bootstrap, код bootstrap — код цели. Затем сервис на 127.0.0.1:8080. В консоли S3 доступен на 127.0.0.1:8334.

  • make stop останавливает S3 плавно, ~15 с. make down volumes не трогает.

  • make wipe_data удаляет volumes mtusi-lab4_postgres_data и mtusi-lab4_s3_data только после ввода yes, оба тома запрос называет по имени.

Архитектура и решения

TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab3, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.

клиент → 127.0.0.1:8080 → haproxy → api × 2 → postgres (метаданные, сессии, ключи идемпотентности)
                                            → valkey (кэш карточек чатов)
                                            → s3 (байты вложений; SeaweedFS, приватный bucket)
                          migrate (один раз) ──→ postgres
                          s3-bootstrap (один раз, в сетевом пространстве s3) ──→ s3

Роль S3 и её граница

S3 хранит только байты вложений, метаданные лежат в PostgreSQL. Пишет и читает S3 только API своим ключом. Ручки вложений, attachment_ids, компенсация и уборщик — следующие changes (attachments, upload-consistency, upload-memory). Change s3-storage даёт сервер, bootstrap, клиент src/infra/s3/ и стенды.

Сервер — SeaweedFS 4.48. Выбор и проба — PLAN.md (решение 1) и design change s3-storage. Три места, где SeaweedFS по умолчанию не приватен, закрыты:

  • без учётных записей S3 открыт анониму — административная пара задана в окружении сервера с первого старта;
  • master, filer и volume слушают все интерфейсы — -ip.bind=127.0.0.1;
  • gRPC шлюза без ключа подписи принимает учётную запись администратора — ключ подписи обязателен.

Телеметрия, Iceberg, Lance и встроенный IAM API выключены.

Сервисы стенда

Роль Сервис Версия / digest индекса Health / readiness Volume Сеть / порт Credentials
load_balancer haproxy haproxy:3.4.6-trixie@sha256:e2739156…db26 /lb/ready на :8404 изнутри: есть готовая реплика — 127.0.0.1:8080 → 8080; :8404 только в сети нет
api × 2 api образ из Dockerfile, база python:3.12.14-slim-trixie@sha256:f77ac9e4…e51f HEALTHCHECK образа: /health/ready — (config.toml read-only) 8080 только в сети пароли PostgreSQL и Valkey, ключи пользователя API в S3 — мосты DATABASE__PASSWORD, CACHE__PASSWORD, S3__ACCESS_KEY_ID, S3__SECRET_ACCESS_KEY из .env
миграции migrate образ API код выхода 0 (service_completed_successfully) — сеть пароль PostgreSQL
postgres postgres postgres:18.6-trixie@sha256:5a5a84b1…9722 pg_isready -h 127.0.0.1 postgres_data 127.0.0.1:5433 → 5432 POSTGRES_PASSWORD
кэш (необязательная роль) valkey valkey/valkey:9.1.2-trixie@sha256:418652cf…9dfd valkey-cli ping с паролем — (persistence выключен) 127.0.0.1:6380 → 6379 VALKEY_PASSWORD
s3 s3 chrislusf/seaweedfs:4.48@sha256:4e61d15f…7872d wget: /cluster/healthz master, том зарегистрирован (DataNodes в /dir/status), /healthz filer и шлюза (loopback) s3_data:/data 127.0.0.1:8334 → 8333 (только API S3); в сети — 8333 и gRPC шлюза 18333, служебные порты на loopback административная пара (AWS_* из S3_ROOT_*) и ключ подписи (WEED_JWT_FILER_SIGNING_KEY из S3_JWT_SIGNING_KEY) — окружением
bootstrap S3 s3-bootstrap тот же образ S3 код выхода 0; реплики ждут service_completed_successfully — (/tmp и /data — tmpfs) network_mode: service:s3, портов нет ключ подписи и ключи API — окружением; в weed shell через stdin, в curl файлом на tmpfs

Лимиты:

  • postgres 2 CPU / 1 ГБ, valkey 0,5 / 128 МБ, s3 1 / 512 МБ;
  • s3-bootstrap 0,5 / 128 МБ, migrate 0,5 / 256 МБ;
  • api 1 / 512 МБ на реплику, haproxy 1 / 256 МБ.

Сумма — 7,5 CPU / 3,25 ГиБ, без одноразовых сервисов — 6,5 CPU / 2,9 ГиБ. Секреты по сервисам проверены в evidence/s3/privacy.md (раздел 4).

Bootstrap S3 и его безопасный повтор

Сервис s3-bootstrap выполняет infra/s3/bootstrap.sh в режиме apply. Каждый шаг можно повторять:

  1. Bucket: есть — «exists», нет — создаётся.
  2. Анонимный доступ — none. Если он открыт, bootstrap его закрывает.
  3. Политика api-objects (s3:GetObject, s3:PutObject, s3:DeleteObject на arn:aws:s3:::<bucket>/*) создаётся или обновляется.
  4. Пользователь api: если его нет, создаётся с ключами из .env; политика привязывается.
  5. Чужие ключи пользователя удаляются, нужный создаётся, если его нет.
  6. Проверка ключом API: PUT, GET и DELETE проверочного объекта. SignatureDoesNotMatch значит, что секрет в .env сменился, — ключ пересоздаётся.
  7. Проверки приватности: ключ API получает 403 на список и создание bucket, аноним — 403 на чтение и список. Расхождение — FAILED: <шаг>, код 1, реплики не стартуют.

Повтор не меняет правильное состояние: bucket и объекты сохраняются, пользователь не пересоздаётся (evidence/s3/bootstrap.md, раздел 2).

Смена секрета API: новое значение в .env, затем make run_docker. Bootstrap пересоздаёт ключ, прежний секрет перестаёт действовать (раздел 3), а реплики с новым окружением пересоздаёт compose.

Bootstrap работает не административной парой S3, а weed shell на loopback сервера с ключом подписи. Административная пара есть только у сервера. make rolling_update bootstrap не запускает: он, как миграции, только расширяет права. Его изменения применяет docker compose up -d s3-bootstrap или make run_docker.

Критичные и некритичные зависимости готовности

  • PostgreSQL критичен: в нём источник истины и сессии. /health/ready выполняет SELECT 1 со сроком 2 с, без него — 503.
  • Valkey не критичен: это кэш, без него обязательные запросы идут в PostgreSQL.
  • S3 не критичен: без него недоступны только пути вложений (503 unavailable), текст работает. /health/ready к S3 не обращается: иначе отказ S3 вывел бы из LB все реплики, и текст перестал бы работать тоже. Проверка — test_readiness_without_object_storage в make failure_checks.

Соответствие имён skeleton S3_*

Имя .env.example skeleton Реальная конфигурация
S3_ENDPOINT S3__HOST и S3__PORT: в консоли — мосты 127.0.0.1 и ${S3_OUT_PORT}, в docker — S3_HOST и S3_PORT через x-s3-env
S3_REGION [s3] region в config.toml (us-east-1, нужен подписи SigV4)
S3_BUCKET S3__BUCKET в .env: читают приложение и bootstrap
S3_ACCESS_KEY_ID_FILE, S3_SECRET_ACCESS_KEY_FILE мосты S3__ACCESS_KEY_ID=${S3_API_ACCESS_KEY} и S3__SECRET_ACCESS_KEY=${S3_API_SECRET_KEY}: значения из .env, а не файлы, как с DATABASE_URL_FILE
MAX_UPLOAD_BYTES, MAX_IMAGE_PIXELS change attachments

Доказательства критериев

Строки S3 (change s3-storage) сняты на стенде make run_docker, если не сказано иное: evidence/s3/restart.md, client.md, privacy.md, evidence/tests/failure-checks.md и test-isolated-s3-cleanup.md — с commit f57635a (правки по verify), остальные файлы evidence/s3/ — с 2e997f9.

До change attachments красные:

  • публичный smoke, make test-persistence и make test-failover: они загружают вложение;
  • тесты схемы Message в make student_test и make failure_checks — список уточнён в шапке tasks.md change s3-storage.

Причина одна: контракт лабы 4 требует attachment_ids, а код лабы 3 его не отдаёт. Чинит change attachments (ответ пользователя 2026-10-20, PLAN.md). Строки про вложения появятся с ним.

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Публичный smoke make test TODO после attachments; сейчас FAIL: response: missing required fields (нет attachment_ids) evidence/tests/test-isolated-s3-cleanup.md
«3»: S3-сервер в общем стенде, закреплённая версия make run_docker, docker compose ps s3 на chrislusf/seaweedfs:4.48@sha256:… в состоянии healthy, s3-bootstrap — Exited (0), реплики стартуют после него evidence/s3/privacy.md (раздел 3), evidence/s3/bootstrap.md (раздел 1)
«3»: persistent volume S3 scripts/restart.sh; docker kill -s KILL сервера S3 ID контейнеров прежние, StartedAt новый, hook — 24 с; объекты клиента читаются с тем же SHA-256: 3/3 после рестарта, 20/20 после SIGKILL; первая запись после healthy — 11–27 мс в 18 рестартах и kill (healthcheck ждёт регистрации тома) evidence/s3/restart.md
«3»: создание приватного bucket описано docker compose logs s3-bootstrap на пустом volume «bucket messenger created», «user api created», «checks passed» evidence/s3/bootstrap.md (раздел 1), «Архитектура и решения» → «Bootstrap S3»
«4»: bootstrap идемпотентен docker compose run --rm s3-bootstrap дважды; повтор с новым секретом; S3_BUCKET=Bad_Bucket повтор — «exists», код 0, объекты на месте; новый секрет работает, прежний — 503; ошибка — код 1, «FAILED: bucket create», реплики не стартуют evidence/s3/bootstrap.md
«4»: отдельные ограниченные credentials API make s3_check (строки api key …); секреты по сервисам из docker compose config ключ API: объекты своего bucket — 200 / 204; список, bucket, политика, ACL, чужой bucket — 403; административной пары у API нет evidence/s3/privacy.md (разделы 1, 4)
«4»: административная консоль не в общей сети make s3_check: слушающие сокеты контейнера S3 (netstat), затем nc -z из сети стенда; docker port; gRPC без токена вне loopback слушают только 8333 и 18333; master, filer и volume — только на 127.0.0.1 и из сети закрыты, admin UI не слушает; со служебными серверами на 0.0.0.0 (временный стенд) — код 1 и список лишних портов; на хосте — только 127.0.0.1:8334; PutIdentity без токена — UNAUTHENTICATED evidence/s3/privacy.md, evidence/s3/grpc-admin.md
«4»: проверка private bucket вне API make s3_check; затем открыть чтение s3.anonymous.set -access Read 48 проверок, код 0; после открытия чтения — 10 FAIL с названиями; следующий bootstrap закрывает доступ, снова PASS evidence/s3/privacy.md
«4»: S3 недоступен — ограниченная ошибка, текст работает make failure_checks (test_readiness_without_object_storage[stop|pause]); клиент при pause и stop S3, без bucket и без прав без S3 (остановлен или заморожен) /health/ready и /health/live — 200 быстрее 1 с; вызов клиента — 503 за 1–8 мс (stop) или за срок 5 с (pause), после возврата проходит; удалённый bucket и отказ в доступе — 503 с записью error, а не «объекта нет» (кроме HEAD: 404 без тела) evidence/tests/failure-checks.md, evidence/s3/client.md
«4»: память S3 при одновременных загрузках 20 одновременных PUT по 10 MiB ключом API все подтверждены, анонимная память не больше 379 MiB из 512, OOM нет; подбор лимитов API — upload-memory evidence/s3/memory.md
Логи без секретов S3 grep -F значений секретов по журналу клиента и make run_dev 0 совпадений; отказ в учётных данных — одна запись error без секрета evidence/s3/client.md
Остальные пункты уровня 3 TODO (attachments) TODO TODO
Все пункты уровня 4, если заявлен TODO (attachments, upload-consistency, upload-memory) TODO TODO
Выбранный трек 5, если заявлен TODO TODO TODO

TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.

Эксперименты и отказы

TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
docker pause сервера S3 вызов клиента — 503 не позже срока 5 с 5 004–5 005 мс, TimeoutError → 503, без повторов после unpause следующий вызов — 8 мс; потерь нет
docker compose stop s3 плавная остановка без SIGKILL; вызовы — 503 сразу остановка 15,3 с, код 0; вызов — 503 за 1–8 мс после start первый вызов тем же клиентом проходит (29 мс)
SIGKILL сервера S3 сразу после 20 подтверждённых PUT подтверждённое не теряется 20/20 с тем же SHA-256 healthy через 5 с; потерь нет
scripts/restart.sh все хранилища и реплики перезапущены, данные целы 24 с; bootstrap — «exists»; 3/3 объекта с тем же SHA-256 —
Рестарт и SIGKILL S3, сразу первая запись запись не ждёт регистрации тома после healthy до правки healthcheck — 2 из 8 рестартов ждали 4 771 и 2 523 мс (срок 5 с); после — 11–27 мс в 12 рестартах и 6 kill —
Bucket удалён мимо bootstrap 503 и error, а не «объекта нет» put, open, delete — 503, «bucket is missing» / «denied access»; head — None (404 без тела, ограничение принято) —
Неверный секрет API у приложения 503 и запись error без секрета SignatureDoesNotMatch → 503, одна запись error —
20 одновременных PUT по 10 MiB без OOM анонимная память не больше 379 MiB; последний PUT подтверждён через 7,2 с (очередь лимита загрузок 64 МБ) —

Ограничения и следующие шаги

TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.

S3 (change s3-storage):

  • Одна нода S3 без репликации и fsync. SIGKILL процесса подтверждённых объектов не теряет (evidence/s3/restart.md). Отказ диска или ВМ теряет объекты, и запись, подтверждённая перед падением ВМ, может пропасть. Учебное упрощение, как один PostgreSQL.
  • Плавная остановка SeaweedFS ~15 с: срок зашит в filer. Поэтому stop_grace_period: 20s, а make stop и scripts/restart.sh дольше на ~15 с. На стенде отказов — 2 с: там проверяется отказ.
  • gRPC шлюза открыт в сети стенда: отдельно его не закрыть, он защищён ключом подписи (evidence/s3/grpc-admin.md).
  • Секреты S3 видны в docker inspect контейнеров s3 и s3-bootstrap, как POSTGRES_PASSWORD. Стенд локальный, порты только на 127.0.0.1. TLS — лаба 7.
  • Лимит загрузок шлюза ставит запросы в очередь. 20 одновременных загрузок по 10 MiB заканчиваются через 7,2 с, это больше срока вызова клиента (5 с). Подбор лимитов и сроков — change upload-memory.
  • Отказ S3 — 503 на путях вложений, а не отказ сервиса. Отказ хоста, LB и PostgreSQL стенд не переживает (.claude/rules/balancer.md).
  • Профиль rollout стенда bench/ ссылается на commit лабы 3 (KNOWN_ISSUES.md), чинится в change attachments.