Files
mtusi2026lab4/openspec/changes/s3-storage/design.md
T
ricoromaandClaude Opus 5.5 f57635a5fb fix: address s3-storage verify findings
- s3 healthcheck and fault hook probe wait for the volume server to
  register with master (first write after restart no longer waits ~5 s)
- s3-bootstrap mounts /data as tmpfs: no anonymous volume per container
- S3 client: NoSuchBucket and AccessDenied are 503 with their own error
  logs, not a missing object or rejected credentials; delete ignores only
  a missing key
- test_isolated verifies prefix removal (weed shell exits 0 on errors)
- s3_check derives ports from listening sockets in the s3 container
- readiness without S3 is also checked with s3 paused

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

50 KiB
Raw Blame History

Design

Context

Мотивация — proposal.md, раздел Why. Требования — specs/.

Код в состоянии лабы 3 (5d5d8f9): S3 нет. Стенд состоит из postgres, valkey, одноразового migrate, реплик api и haproxy. Его копии используются ещё тремя способами:

  • make test_isolated — отдельный контейнер api на временной базе;
  • make failure_checks — проект <рабочий>-failures с override;
  • bench/ — проект mtusi-bench с override и своими секретами.

Все три читают тот же docker-compose.yml, поэтому новый сервис и обязательные переменные compose задевают их сразу.

Известное состояние до change attachments, от этого change не зависит (PLAN.md):

  • публичный smoke (make test) и make test-persistence / test-failover с LAB=4 загружают вложение и падают на нём: tests/resilience.py делает загрузку до вызова hook;
  • make student_test красный на test_exclusion_evidence_exists.

Поэтому make test_isolated в этом change тоже ненулевой. Рестарт hook-ом проверяется напрямую (решение 9), без публичного теста.

Проба SeaweedFS (2026-10-20, временный проект compose вне репозитория)

Образ — chrislusf/seaweedfs:4.48, digest индекса sha256:4e61d15fd35994cb1e43e1e553dff106794841fd9a99ade2fc8c8bfce4d7872d. Сборка 2026-09-28, это последний выпуск: тег latest указывает на него же. Платформы — amd64 и arm64, база — Alpine 3.24. Volume образа — /data. Entrypoint сам переходит с root на пользователя seaweed (uid 1000). В образе есть wget, curl 8.22 (с --aws-sigv4) и nc. Команды s3.configure из PLAN.md в 4.48 нет. Учётные записи — IAM сервера: s3.user.*, s3.policy*, s3.accesskey.*, s3.anonymous.*, политики в формате AWS.

Проверка Результат
Без учётных записей аноним создал bucket, записал и прочитал объект — 200. S3 открыт целиком
AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY в окружении сервера с первой секунды есть администратор, анонимные запросы — 403
-ip.bind=127.0.0.1, -s3.ip.bind=0.0.0.0 из сети открыты только 8333 (S3) и 18333 (gRPC шлюза). Порты 9333, 19333, 8888, 18888, 8080, 18080, 23646, 8181, 9101, 7333, 8111, 6060 закрыты
gRPC 18333 без ключа подписи PutIdentity без токена принят: «злоумышленник» из сети стал администратором и увидел все bucket-ы
gRPC 18333 с WEED_JWT_FILER_SIGNING_KEY UNAUTHENTICATED missing authorization metadata, ключи «злоумышленника» — InvalidAccessKeyId
Аноним: GET и HEAD объекта, GET отсутствующего ключа, список bucket, список bucket-ов, PUT все 403
Ключ API с политикой s3:GetObject, s3:PutObject, s3:DeleteObject на bucket/* PUT, GET (SHA-256 совпал), HEAD, COPY и DELETE — да; DELETE отсутствующего — 204; HEAD и GET отсутствующего — 404
Ключ API: список объектов, создание и удаление bucket, политика и ACL bucket, публичный ACL объекта все 403
Ключ API: чужой bucket (GET, PUT, LIST, DELETE) все 403; ListBuckets — пустой список
Ключ API и root: встроенный IAM API API — 403; root — только чтение (запись IAM выключена по умолчанию)
Bootstrap дважды и трижды без ошибок, «exists», объекты на месте
Новый секрет API в окружении bootstrap ключ пересоздан; старый секрет — SignatureDoesNotMatch, новый — 200
Ошибка шага (имя bucket Bad_Bucket) код 1, «FAILED: bucket create», секретов в выводе нет
Bootstrap от пользователя seaweed работает; пик памяти 35 MiB, 0,76 с CPU
Свежий volume: s3 healthy → bootstrap → зависимый сервис 8,8 с
Рестарт с volume bucket, пользователь, политика и объекты на месте; root добавляется из окружения снова
Перезапуск при -master.electionTimeout 10 с (по умолчанию) лидер через ~18 с, до healthy ~24 с
То же при 1 с 6,5–7,7 с от restart до healthy; узел один, выборам ждать некого
SIGTERM плавная остановка ~15 с, код 0: filer ждёт свои gRPC-подписки, срок 15 с зашит в код. При сроке compose 10 с — SIGKILL, код 137
SIGKILL сразу после 20 подтверждённых PUT 20/20 объектов читаются с тем же SHA-256
Память без настроек, лимит 512 МБ простой 140–160 MiB; 10 × 10 MiB PUT — 512 MiB (на пределе); 20 × 10 MiB — OOM-kill
GOMEMLIMIT=400MiB + -s3.concurrentUploadLimitMB=64 20 и 40 × 10 MiB PUT и GET без ошибок, анонимная память ≤ 271 MiB; лимит загрузки ставит запросы в очередь, а не отклоняет
Без GOMEMLIMIT, только лимит загрузки 40 × 10 MiB выдержал, анонимная память 476 MiB из 512
Клиент aiobotocore 3.9.2 (botocore 1.43.106, aiohttp 3.14.5), без повторов botocore (total_max_attempts=1) контрольные суммы botocore по умолчанию принимаются; первый вызов старым клиентом после рестарта S3 проходит; pause — вызов обрывает asyncio.timeout ровно в срок; stop — EndpointConnectionError за 9 мс
Первая запись сразу после healthy в 3 прогонах из 6 ждала ~2,5 с, кем бы ни был клиент; следующие — 5–25 мс. Причина найдена в verify (уточнения apply, п. 8): healthy по master, filer и шлюзу наступает до регистрации тома у master (~4 с разницы), ожидание доходило до 4,8 с при сроке вызова 5 с. Healthcheck теперь ждёт и том
Цена клиента на хосте импорт 80–160 мс, создание клиента 35–60 мс, +45 MiB RSS, установленные пакеты ~27 MiB

Без ключа подписи сервер к тому же пишет при старте ошибку «no signing key found for STS service». С ключом её нет.

Goals / Non-Goals

Goals:

  • Bucket приватен с первой секунды жизни сервера. Учётные данные API ограничены объектами своего bucket. Обойти это из сети стенда через служебные порты нельзя.
  • Bootstrap — сервис compose, а не ручной шаг. Он идемпотентен, сводит состояние к .env и сам проверяет приватность при каждом запуске.
  • Стенд с S3 перезапускается hook-ом за 90 с. Повторный bootstrap после рестарта ничего не меняет.
  • make test_isolated, make failure_checks и bench/ работают с новым compose. Методика прежних профилей bench/ не меняется.
  • Клиент приложения готов для attachments: сроки, ошибки, ключи по имени базы.

Non-Goals:

  • Ручки вложений, запись намерения, уборщик и reconciler — следующие changes (proposal.md, «Не входит»).
  • Подбор лимитов памяти и цепочки таймаутов под загрузку 10 MiB через API — upload-memory. Здесь — безопасный базовый уровень по пробе (решение 2).
  • Репликация, TLS и шифрование данных в покое: одна нода S3 на одном хосте (Risks), TLS — лаба 7.
  • Публичный make test-persistence с рестартом S3. Он проходит после attachments, когда загрузка вложения работает (Context).

Decisions

1. Один контейнер weed server, служебное — на loopback

Сервис s3 запускает weed server с master, volume, filer и шлюзом S3 в одном процессе. Аргументы и зачем они:

Аргумент Зачем
-ip=127.0.0.1 -ip.bind=127.0.0.1 master, volume и filer слушают loopback контейнера: из сети и с хоста их нет
-s3 -s3.ip.bind=0.0.0.0 -s3.port=${S3_PORT} в сеть выходит только шлюз S3
-s3.port.iceberg=0 -s3.port.lance=0 REST Catalog и Lance по умолчанию открыты на 8181 и 9101; они не нужны
-s3.iam=false встроенный IAM API на порту S3 не нужен: bootstrap идёт через weed shell
-master.telemetry=false по умолчанию master шлёт статистику на telemetry.seaweedfs.com
-master.electionTimeout=1s перезапуск до healthy за ~7 с, а не ~24 с (Context)
-volume.preStopSeconds=0 10 с паузы перед остановкой тома нужны кластеру, а не одному узлу
-s3.concurrentUploadLimitMB=64 решение 2

Entrypoint образа добавляет -dir=/data -volume.max=0 -master.volumeSizeLimitMB=1024. Остальное в сервисе:

  • volume s3_data:/data (Config.Volumes образа);
  • restart: unless-stopped;
  • stop_grace_period: 20s — решение 2;
  • алиас в сети ${S3_HOST};
  • публикация 127.0.0.1:${S3_OUT_PORT}:${S3_PORT}.

Healthcheck на wget проверяет /cluster/healthz master, список data node в /dir/status master (непустой DataNodes), /healthz filer на loopback и /healthz шлюза S3 на $$S3_PORT, с start_interval: 1s. Процесс один, но так healthy значит «master выбран, том зарегистрирован у master, filer и шлюз отвечают» и первая запись не ждёт регистрации тома (уточнения apply, п. 8).

Альтернатива: отдельные контейнеры master, volume, filer и s3 в своей сети. Отвергнута: четыре сервиса с healthcheck, лимитами и рестартом вместо одного, а изоляцию даёт loopback. Альтернатива: weed mini. Отвергнута: он поднимает admin UI на 23646 и создаёт bucket без пользователей и политик. Альтернатива: отдельная сеть compose для S3 и API. Отвергнута: от API она не защищает, а служебные порты закрыты и так. Стенды bench/ и отказов пришлось бы учить ещё и второй сети.

2. Память и остановка

  • Лимиты s3: 1 CPU и 512 МБ. Без настройки 10 одновременных загрузок по 10 MiB доводят память до лимита, а 20 дают OOM-kill (Context).

  • Защита в два слоя:

    • GOMEMLIMIT=400MiB в окружении: сборщик мусора Go работает чаще у предела;
    • -s3.concurrentUploadLimitMB=64: шлюз держит не больше 64 МБ загрузок одновременно, лишние ждут.

    С обоими слоями 40 загрузок прошли (Context).

  • Лимит API на одновременные загрузки и подбор этих чисел под него — upload-memory.

  • stop_grace_period: 20s: плавная остановка занимает ~15 с, срок 15 с зашит в код filer. Со сроком 10 с, как у остальных сервисов, остановка всегда кончалась бы SIGKILL. По пробе и это безопасно для подтверждённых записей, но журнал и код выхода показывали бы аварию. Цена — make stop и restart.sh дольше на ~15 с.

3. Учётные данные: администратор сервера, ключ подписи, пользователь API

Секрет Где в .env Кому в compose Зачем
административные ключ и секрет S3 S3_ROOT_ACCESS_KEY, S3_ROOT_SECRET_KEY только s3 (AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY) у сервера всегда есть учётная запись: анонимного окна нет ни до bootstrap, ни если кто-то удалит пользователей; оператору — доступ к bucket для разбора (list в evidence)
ключ подписи служебных вызовов S3_JWT_SIGNING_KEY s3 и s3-bootstrap (WEED_JWT_FILER_SIGNING_KEY) закрывает IAM-вызовы filer и gRPC-кэш IAM шлюза (Context); weed shell bootstrap подписывает им свои вызовы
ключи пользователя API S3_API_ACCESS_KEY, S3_API_SECRET_KEY s3-bootstrap, api (мостами S3__ACCESS_KEY_ID / S3__SECRET_ACCESS_KEY) единственный доступ приложения

Решение 5 PLAN.md — «root только у bootstrap» — выполняется так. Административной пары нет ни у API, ни у будущего уборщика. Сам bootstrap работает не ею, а weed shell на loopback сервера с ключом подписи. Пару хранит только сервер: без неё он был бы открыт. Ключи доступа — случайные hex, как и секреты. make env_setup генерирует все пять значений для нового .env, существующий не трогает (как с Valkey).

Права пользователя api задаёт политика api-objects: s3:GetObject, s3:PutObject, s3:DeleteObject на arn:aws:s3:::<bucket>/*. Владельца у bucket нет, а владелец получил бы больше прав. Анонимный доступ — none. Пользователь уборщика (List, Get, Delete) появится в upload-consistency одной строкой bootstrap. Заводить его заранее незачем: без уборщика он никому не нужен.

Альтернатива: права через устаревшие действия Read:bucket, Write:bucket на identity. Отвергнута: у политики формат AWS, она точнее (Write включает и multipart, и ACL) и понятнее в отчёте. Альтернатива: bootstrap административными ключами через S3 и IAM API. Отвергнута: нужен клиент IAM (ещё образ или код подписи), а запись IAM на шлюзе пришлось бы включить.

4. Bootstrap: сервис s3-bootstrap в сетевом пространстве s3

Сервис s3-bootstrap:

  • образ тот же, что у s3, network_mode: service:s3: master и filer на 127.0.0.1 сервера доступны ему, а в сети их нет;
  • user: seaweed, restart: "no", tmpfs: [/tmp, /data] (/data — volume образа: без tmpfs каждый новый контейнер оставлял бы анонимный volume, уточнения apply, п. 9);
  • скрипт infra/s3/bootstrap.sh монтируется только на чтение длинной записью с create_host_path: false;
  • depends_on: s3: service_healthy;
  • лимиты 0,5 CPU и 128 МБ.

Реплики api ждут s3-bootstrap: service_completed_successfully, как migrate. Compose пересоздаёт его вместе с s3, если тот пересоздан (проверено).

Алгоритм — сведение к желаемому состоянию, каждый шаг безопасно повторять:

  1. Bucket: есть в s3.bucket.list — «exists», нет — s3.bucket.create.
  2. s3.anonymous.set -access none.
  3. s3.policy -put политики api-objects: создаёт или обновляет.
  4. Пользователь api: если s3.user.show его не находит — s3.user.create с ключами из окружения; затем s3.policy.attach (повтор не дублирует).
  5. Ключи пользователя: чужие ключи удаляются, нужного нет — создаётся.
  6. Проверка — подписанные curl --aws-sigv4 запросы ключом API на 127.0.0.1:$S3_PORT. Ответ SignatureDoesNotMatch значит, что секрет в .env сменился: ключ пересоздаётся. Изменения IAM доходят до шлюза подпиской на filer, поэтому есть ожидание до 10 с.
  7. Проверки приватности (требование «Проверка приватности вне API»). Ключ API: PUT, GET, DELETE проверочного объекта .s3-bootstrap/… — да; LIST и создание bucket — 403. Аноним: GET этого объекта и LIST — 403. Любое расхождение — FAILED: <проверка> и код 1.

Секреты передаются в weed shell через stdin, в curl — файлом -K на tmpfs, поэтому в argv процессов и в журнале их нет. Вывод — строки s3-bootstrap: bucket … exists|created, user … exists|created, key … recreated, checks passed (…). Запуск — ~2 с.

Режим check того же скрипта не меняет конфигурацию. Он добавляет проверки против временного bucket <bucket>-check-<случайное>, который создаёт и удаляет weed shell, и административные запросы ключом API. Его вызывает make s3_check (решение 8).

Альтернатива: s3.iam.import -apply целиком из JSON. Отвергнута: команда заменяет всю конфигурацию IAM, а управляемые политики s3.iam.export не выгружает ("policies": [] при созданной политике). Повтор мог бы стереть политику, и JSON с секретами пришлось бы держать файлом. Альтернатива: статический -s3.config с identity в JSON. Отвергнута: секреты оказались бы в файле на хосте, а bucket всё равно создаёт отдельный шаг. Альтернатива: docker compose exec s3 weed shell из Makefile. Отвергнута: голый docker compose up не делал бы bootstrap, и стенды bench/ и отказов повторяли бы его сами. Альтернатива: bootstrap внутри entrypoint s3. Отвергнута: скрипт становится PID 1 вместо weed и мешает сигналам, а «готов» смешивает сервер и bucket.

5. Настройки и .env

Секция [s3] — класс S3 в Settings:

Поле По умолчанию Откуда
host, port 127.0.0.1, 8333 .env: в консоли мосты S3__HOST=127.0.0.1, S3__PORT=${S3_OUT_PORT}; в docker — x-s3-env: ${S3_HOST:-s3}, ${S3_PORT:-8333}
bucket messenger .env: S3__BUCKET — читают и приложение, и bootstrap (S3_BUCKET: ${S3__BUCKET:-messenger}); проверка по S3_BUCKET_NAME_PATTERN
access_key_id, secret_access_key (SecretStr) "" мосты из S3_API_*; пусто — warning при старте
region us-east-1 config.toml; подпись SigV4 его требует, SeaweedFS берёт его из запроса
connect_timeout_seconds 1 config.toml
timeout_seconds 5 config.toml: срок всего вызова; меньше timeout server HAProxy (10 с)
max_connections 10 config.toml: пул aiohttp на процесс

endpoint_url — свойство http://{host}:{port}, как Database.url. Порт API S3 внутри сети — S3_PORT (8333), публикация — S3_OUT_PORT (8334, по образцу 5433 и 6380). Литералов адресов в compose нет, только 127.0.0.1 публикации. Блок переменных S3 в .env.example комментирован, шапка шаблона больше не говорит «строк S3 пока нет». Строка config_example.toml [s3] — без адреса, bucket и ключей.

Имена skeleton в REPORT.md, как в лабе 3:

  • S3_ENDPOINT → S3__HOST и S3__PORT;
  • S3_REGION → [s3] region;
  • S3_BUCKET → S3__BUCKET;
  • S3_ACCESS_KEY_ID_FILE и S3_SECRET_ACCESS_KEY_FILE → мосты из S3_API_*: значения, а не файлы, как с DATABASE_URL_FILE.

MAX_UPLOAD_BYTES и MAX_IMAGE_PIXELS — change attachments.

6. Клиент: aiobotocore

Зависимость aiobotocore>=3.9.2,<4: асинхронный клиент поверх botocore, тот же код подписи и моделей, что у AWS CLI. aiobotocore закрепляет узкий диапазон botocore (сейчас <1.43.107), uv.lock это фиксирует.

Вариант Почему нет
boto3 в потоке (to_thread) поток не отменить: asyncio.timeout отпускает запрос, а поток висит до таймаута сокета, как command_timeout asyncpg (infra.md); пул потоков по умолчанию на 1 CPU — 5 потоков, и он же ограничил бы одновременные загрузки; потоковое чтение для download — по вызову в поток на каждый блок
aioboto3 последний выпуск 2025-10, тянет aiobotocore 2.25
своя подпись SigV4 поверх httpx своя криптография и разбор XML-ошибок S3
obstore, minio-py меньше распространены; MinIO в режиме сопровождения (решение 1 PLAN.md)

Цена — импорт и создание клиента ~0,1–0,2 с при старте и +45 MiB RSS на реплику (Context). У реплики 512 МБ, из них ~350 МБ — интерпретатор и Argon2id. Запас для загрузок считает upload-memory.

7. Клиент: устройство и поведение

Пакет src/infra/s3/ по образцу cache/:

  • client.py — фабрика create_object_storage и обёртка ObjectStorage;
  • instance.py — глобал object_storage, создаётся при импорте по settings.s3 с namespace=settings.database.name.

Глобал импортируют только src/main.py и src/api/dependencies.py (infra.md). В этом change потребителя в зависимостях нет.

  • Клиент aiobotocore создаётся асинхронно. Lifespan вызывает await object_storage.start(): модели botocore грузятся при старте, а не в первом запросе. Сети при этом нет, соединения aiohttp открывает при первом вызове. Без start() клиент создаётся при первом вызове под замком. aclose() — в lifespan рядом с cache.aclose().

  • Конфигурация botocore:

    • адресация path: виртуальные хосты bucket.s3 в Docker DNS не разрешаются;
    • connect_timeout и read_timeout из [s3];
    • retries={"total_max_attempts": 1};
    • max_pool_connections=[s3] max_connections;
    • контрольные суммы по умолчанию.
  • Простаивающее соединение aiohttp закрывает через 15 с, раньше шлюза S3 (120 с), как в цепочке keep-alive balancer.md.

  • Срок: каждый вызов в asyncio.timeout([s3] timeout_seconds). Повторов нет. Рестарт S3 повтора не требует (Context), а таймаут, как у Valkey, не повторяется. Загрузку клиент контракта повторяет сам. Первая запись после старта S3 ждала регистрации тома у master до 4,8 с — почти весь срок; теперь healthy наступает после регистрации (решение 1), и первая запись после рестарта — 10–40 мс (уточнения apply, п. 8).

  • Операции:

    • put(key, data, content_type);
    • open(key) — асинхронный контекст с размером, типом и чтением блоками; для download в attachments;
    • head(key) → метаданные или None;
    • delete(key): отсутствие — не ошибка.

    Списка нет: у ключа API нет права List.

  • Ошибки переводятся в доменные исключения, как требует infra.md:

    Что пришло Исключение Журнал
    отказ соединения, обрыв, таймаут сокета или срока, 5xx ObjectStorageUnavailable (наследник ServiceUnavailable → 503 unavailable по таблице errors.py) warning «Object storage is unavailable» с классом ошибки
    403 InvalidAccessKeyId, SignatureDoesNotMatch то же исключение error «Object storage rejected credentials» без ключей
    403 AccessDenied и 403 без тела (HEAD) то же исключение error «Object storage denied access» (уточнения apply, п. 10)
    404 NoSuchBucket то же исключение error «Object storage bucket is missing» (п. 10)
    NoSuchKey / 404 без тела (HEAD) StoredObjectMissing, новое в src/core/exceptions/storage.py; HTTP-ответ на него решает attachments нет
    прочие ошибки S3 без перевода 500 и traceback, это дефект
  • Ключ объекта строит repo в attachments: f"{namespace}/{…}". Здесь — константа разделителя и поле namespace. Имя базы разделяет объекты make test_isolated и рабочие так же, как ключи кэша.

  • Журнал: модуль object_storage. В записи — адрес, bucket, ключ объекта, размер, длительность, класс ошибки (спек service-logging). Логгеры botocore, aiobotocore и aiohttp явно стоят на WARNING: на DEBUG botocore пишет заголовки с подписью. Запись «Started API» дополняется s3_host, s3_port, s3_bucket. Пустые ключи — warning, как пустой пароль Valkey.

Альтернатива: пропуск S3 на N секунд после отказа, как у Valkey. Отвергнута: обхода нет, ответ всё равно 503. Пропуск только ускорил бы ответы при зависшем S3, а это задача лимитов upload-memory.

8. Готовность и проверка приватности

  • /health/ready не меняется: S3 не трогает (решение 3 PLAN.md, спек health). В REPORT.md — перечень зависимостей. PostgreSQL критичен. Valkey не критичен — обход кэша. S3 не критичен — 503 на путях вложений, текст работает.

  • make s3_check — команда драйвера скилла run-mtusi-messenger (driver.py s3-check, stdlib, как cache-check):

    1. docker compose run --rm --no-deps s3-bootstrap check записывает проверочный объект ключом API и проверяет права.
    2. Анонимные GET и LIST этого объекта идут с хоста через 127.0.0.1:$S3_OUT_PORT и из сети стенда одноразовым контейнером того же закреплённого образа (docker run --network <проект>_default … curl).
    3. Финальный шаг check удаляет объект и временный bucket.

    Вывод — таблица «проверка → ожидаемый код → полученный» без секретов, код выхода 1 при расхождении. Порты контейнера S3 из сети проверяет тот же одноразовый контейнер (nc -z).

  • Отказ gRPC-вызова без токена в evidence показывает разовая проба: клиент на protobuf SeaweedFS той же ревизии в одноразовом контейнере в сети стенда, как в Context. В проект и uv.lock она не входит.

9. Стенды

  • scripts/restart.sh:

    1. stop haproxy api;
    2. restart postgres valkey s3;
    3. up -d --wait postgres valkey s3;
    4. start api haproxy, он запускает и migrate, и s3-bootstrap: повтор — no-op.

    Ожидаемо ~30–35 с: S3 останавливается ~15 с. Публичный test-persistence до attachments не пройдёт (Context). Поэтому hook проверяется напрямую. До и после — StartedAt всех контейнеров и «exists» bootstrap после рестарта. Объект, записанный клиентом, читается после рестарта с тем же SHA-256. make student_test через LB.

  • make run_dev: upgrade start_cache start_s3. start_s3 — это up -d --wait s3 s3-bootstrap: --wait считает успешно завершённый одноразовый сервис готовым, проверено.

  • make test_isolated зависит от start_s3. run_isolated.py удаляет префикс test_<db>/ bucket в начале и в уборке: docker compose exec -T s3 + weed shell fs.rm -r /buckets/<bucket>/test_<db>. Отсутствие префикса — не ошибка (проверено). Префикс собирается только из проверенного имени временной базы (test_ + [a-z0-9_]+), иначе отказ: ошибка не может удалить рабочий префикс. KEEP_TEST_DB=1 оставляет и префикс.

  • make failure_checks:

    • run_failures.py поднимает postgres valkey s3 s3-bootstrap;
    • в failures.compose.yml у s3 порты сброшены и stop_grace_period: 2s: на стенде отказов проверяется отказ, а не плавная остановка, и stop не тянет 15 с;
    • fault_hook.py знает сервис s3 (stop, start, pause, unpause, проба — та же команда, что healthcheck);
    • новая проверка test_readiness_without_object_storage — health, «Хранилище объектов недоступно».
  • bench/:

    • compose_env генерирует пять секретов S3 на прогон;
    • фильтр app_env паспорта убирает не только PASSWORD, но и SECRET и ACCESS_KEY: иначе секрет API попал бы в meta.json;
    • bench.env — S3_HOST, S3_PORT, S3__BUCKET=bench;
    • override s3: container_name: mtusi-bench-s3, restart: "no", порты сброшены.

    Профили лаб 2–3 S3 не запускают: старт стенда перечисляет сервисы и поднимает api с --no-deps. Стенд, нагрузка и паспорт прежние, методика не меняется (bench.md). Лимиты BENCH_S3_* и S3 в паспорте появятся с профилем, который его запускает (upload-memory, трек 2).

  • scripts/rolling-update.sh не меняется. Bootstrap, как миграции, только расширяет: новые пользователи и политики не отбирают прав у старых реплик. Его изменения применяет docker compose up -d s3-bootstrap или make run_docker. Это пишется в balancer.md.

  • make wipe_data называет удаляемые volumes Postgres и S3. stop_s3 — stop s3.

10. Evidence

Файл Что
evidence/s3/bootstrap.md свежий стенд: журнал s3-bootstrap «created», затем два повтора «exists»; смена секрета разовым run -e и возврат; ошибка шага; время
evidence/s3/privacy.md make s3_check; docker compose ps и docker port (опубликован только S3 на 127.0.0.1); порты контейнера S3 из сети стенда; окружение сервисов из docker compose config без значений (у кого какие секреты)
evidence/s3/grpc-admin.md проба gRPC без токена — UNAUTHENTICATED, ключ «злоумышленника» — отказ
evidence/s3/restart.md scripts/restart.sh: StartedAt до и после, время hook-а; объект клиента с тем же SHA-256; kill -9 после записей
evidence/s3/client.md разовый скрипт клиента: операции, stop / pause / возврат с временем, неверный секрет — 503 и error без секрета; журнал без секретов
evidence/s3/memory.md 20 одновременных PUT по 10 MiB ключом API: memory.peak и анонимная память контейнера S3, OOM нет
evidence/tests/ make failure_checks с новой проверкой; строки уборки префикса в выводе make test_isolated

Risks / Trade-offs

  • [Одна нода S3 без репликации и fsync: отказ диска или ВМ теряет объекты, а запись, подтверждённая перед падением ВМ, может пропасть. SIGKILL процесса не теряет ничего (Context)] → Ограничение учебного стенда, в REPORT.md («Что стенд не переживает»), рядом с одним PostgreSQL.
  • [Плавная остановка SeaweedFS ~15 с] → stop_grace_period: 20s, время hook-а меряется (≤ 90 с). На стенде отказов срок короткий намеренно.
  • [Память шлюза S3 растёт с одновременными загрузками] → GOMEMLIMIT и лимит загрузки (решение 2); подбор чисел — upload-memory. Граница: memory.peak включает страничный кэш томов, считать надо анонимную память.
  • [gRPC-порт шлюза открыт в сети, отдельно закрыть его нельзя: у него нет своего адреса привязки и выключателя (weed/command/s3.go)] → ключ подписи обязателен: compose без S3_JWT_SIGNING_KEY не стартует, evidence — grpc-admin.md.
  • [Секреты видны в docker inspect контейнеров s3 и s3-bootstrap; сервер пишет административный ключ доступа (не секрет) при старте] → Как POSTGRES_PASSWORD: стенд локальный, порты только на 127.0.0.1. Ключ доступа не секрет, секрет в журнал не попадает.
  • [SeaweedFS выпускается почти каждый день, вывод weed shell может поменяться, а bootstrap разбирает таблицы s3.bucket.list и s3.accesskey.list] → Образ закреплён digest. Обновление образа — повтор пробы из Context, и bootstrap сам упадёт на проверках, если разбор сломался.
  • [aiobotocore закрепляет узкий диапазон botocore] → Обновлять их только вместе через uv lock. CVE botocore закрываются выпуском aiobotocore.
  • [Старт реплики дольше на ~0,1–0,2 с, память +45 MiB] → Окно A раннего обработчика SIGTERM (run-modes.md) растёт на это время. Ранний обработчик стоит до импорта, поэтому поведение не меняется. Память — в бюджете реплики (решение 6).
  • [make test_isolated, test-persistence, test-failover и smoke красные до attachments (Context)] → Задачи явно называют ожидаемо красные части. Проверки этого change опираются на свои команды и evidence.

Migration Plan

Порядок:

  1. Зависимость и настройки.
  2. Compose, infra/s3/bootstrap.sh, .env.example, Makefile.
  3. Клиент в src/infra/s3/.
  4. Стенды: restart.sh, isolated, failures, bench.
  5. Документы.
  6. Commit.
  7. Evidence и REPORT.md.

На рабочем стенде в существующий .env добавляются строки S3 из .env.example с новыми случайными секретами. make env_setup существующий .env не меняет, а агент .env не читает, поэтому это делает пользователь или агент с его согласия (PLAN.md, «Вопросы»). Затем make run_docker.

Откат — git revert коммитов change, затем docker compose up -d --remove-orphans: контейнеры s3 и s3-bootstrap уходят как сироты. Volume mtusi-lab4_s3_data после отката compose не знает, и make wipe_data его уже не удалит — только явный docker volume rm. Данные PostgreSQL change не трогает.

Уточнения apply

Решения, принятые в /opsx:apply (2026-10-20) по ходу работы; копия — PLAN.md, «Вопросы и решения по ходу changes» → s3-storage.

  1. --wait не ждёт завершения bootstrap (уточнение решения 9). Compose v5.5.1 считает одноразовый сервис без healthcheck готовым, как только тот запущен: up -d --wait s3 s3-bootstrap вернулся через 5,6 с, а bootstrap закончил позже. Поэтому make start_s3 — это up -d --wait s3, затем up --no-deps --exit-code-from s3-bootstrap s3-bootstrap (код выхода bootstrap — код цели), как миграции в rolling-update.sh. Так же — run_failures.py. Реплики штатного стенда это не задевает: depends_on: service_completed_successfully ждёт завершения.
  2. Режимы bootstrap: apply, check, cleanup (уточнение решений 4 и 8). Проверки с хоста и из сети идут между записью проверочного объекта и его удалением, поэтому удаление — отдельный режим cleanup, а не последний шаг check. Объект — .s3-check/probe (повтор перезаписывает остаток прерванного прогона); временный bucket <bucket>-check-<hex> создаёт и удаляет сам check (и trap при сбое), cleanup удаляет и забытые. Строки проверок — s3-bootstrap: check<TAB>имя<TAB>ожидаемо<TAB>получено<TAB>ok|FAIL, их собирает driver.py s3-check. Вывод weed shell печатается только у шагов без секретов. HOME=/tmp (tmpfs) у s3-bootstrap: ничего не пишется в слой контейнера.
  3. Секрет сменился — ключ пересоздаётся по SignatureDoesNotMatch, а не по любому 403 (решение 4, шаг 6): ожидание изменений IAM до 10 с даёт InvalidAccessKeyId, его ждут, а не пересоздают ключ.
  4. Клиент (решение 7): open(key) отдаёт StoredObject с size, content_type, iter_chunks() и read(); срок [s3] timeout_seconds — на вызов и на каждый блок чтения тела (отдача 10 MiB медленному клиенту дольше срока, блок — нет). Типы StoredObjectInfo и StoredObject — в src/infra/s3/client.py. Переводятся только ошибки клиента и сети (ClientError, ConnectionError и HTTPClientError botocore, IncompleteReadError, aiohttp.ClientError, OSError); прочие не перехватываются (500). Ключи передаются в botocore всегда, даже пустые: иначе он искал бы учётные данные в окружении и ~/.aws хоста.
  5. Ожидаемо красные шире списка tasks.md. Контракт лабы 4 сделал attachment_ids обязательным полем Message, а код лабы 3 его не отдаёт (в src/ его нет с 5d5d8f9). До change attachments падают все тесты, которые проверяют схему сообщения, с одной причиной «'attachment_ids' is a required property»: в make student_test через LB — 32 упавших и 2 ошибки фикстуры, в make test_isolated — 29 и 2 (тесты реплик там пропущены), в make failure_checks — 5 (test_database_stopped_and_back, test_valkey_stopped, test_message_failure_keeps_key_free, test_database_outage_keeps_key_free, test_key_free_after_ttl). От этого change это не зависит; правка — поле в attachments. Код 0 make failure_checks до тех пор недостижим, новая проверка test_readiness_without_object_storage зелёная.
  6. Дельта health синхронизирована в основной спек в apply, как в scaling-bench («/opsx:sync только её»): сверка покрытия читает только openspec/specs/, и маркер нового сценария «Хранилище объектов недоступно» без этого указывал бы на неизвестный сценарий. Остальные дельты — при archive.
  7. Профиль rollout ссылается на commit лабы 3 (rollout_from c50b721, его нет в истории лабы 4) — дефект переноса, записан в KNOWN_ISSUES.md. make bench_rollout_quick падает за 6 с; самопроверка профиля — bench/run.py --profile rollout_quick --from 5d5d8f9 (код 0).

Правки по находкам /opsx:verify (2026-10-20, tasks.md, группа 7):

  1. Healthcheck ждёт регистрации тома (W1, решение 1). healthy по master, filer и шлюзу наступал через ~3 с после старта, а volume регистрировался у master через ~7 с (опрос /dir/status раз в 0,5 с: до регистрации "DataCenters":null, после — "DataNodes":[{…}]). Первая запись ждала регистрации: до правки 2 из 8 рестартов — 4771 и 2523 мс, у verify 3 из 12 — до 4784 мс при сроке 5 с. Проверка wget -q -O - …/dir/status | grep -qF '"DataNodes":[{' в healthcheck и пробе fault_hook.py. После правки: 12 рестартов и 6 kill — первая запись 10–40 мс. Свежий volume (tmpfs) тоже проходит: data node регистрируется и без томов, bootstrap создаёт bucket.
  2. tmpfs: [/tmp, /data] у s3-bootstrap (W2, решение 4). Образ объявляет VOLUME /data, и каждый новый контейнер bootstrap создавал анонимный volume. Пересоздание контейнера compose переносит прежний анонимный volume на новый — на рабочем стенде он отвязан docker compose up -d --no-deps --renew-anon-volumes s3-bootstrap и остался висячим (удалять volumes агенту нельзя).
  3. Ошибки bucket и доступа (S1, решение 7). NoSuchBucket — ObjectStorageUnavailable и error «Object storage bucket is missing»; AccessDenied и 403 без тела — ObjectStorageUnavailable и error «Object storage denied access»; «rejected credentials» — только InvalidAccessKeyId и SignatureDoesNotMatch. Любой 404 больше не значит «объекта нет»: только NoSuchKey и 404 без тела у HEAD. delete глушит только StoredObjectMissing. Проверено на временном стенде с удалённым bucket: PUT SeaweedFS отвечает AccessDenied, GET и DELETE — NoSuchBucket, HEAD — 404 без тела, как у отсутствующего ключа. Поэтому head удалённого bucket по-прежнему None, а неверный секрет у HEAD — «denied access» (403 без кода): ограничение HEAD, не клиента.
  4. Уборка префикса проверяется (S2, решение 9). weed shell выходит с кодом 0 и при ошибке (rm: <путь>: LookupEntry1: … connection refused). remove_objects разбирает строки rm: (кроме «no entry is found» — префикса нет) и проверяет пустой fs.ls префикса; иначе RuntimeError: в начале прогона — код 1 до тестов, в уборке — «cleanup failed», код 1.
  5. Готовность при замороженном S3 (S3). test_readiness_without_ object_storage параметризован stop и pause; сценарий health «Хранилище объектов недоступно» называет оба (основной спек и дельта).
  6. Порты S3 — со слушающих сокетов (S4, решение 8). driver.py s3-check берёт netstat -tuln контейнера s3: вне loopback (не 127.0.0.0/8 и не ::1) должно быть ровно S3_PORT и S3_PORT + 10000, а остальные слушающие TCP-порты из сети закрыты (nc -z). Фиксированный список S3_CLOSED_PORTS убран: новый порт нового выпуска SeaweedFS он бы пропустил. Отрицательная проверка — временный стенд с -ip.bind=0.0.0.0: код 1, лишние 8080, 8888, 9333, 18080, 18888, 19333.