- 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>
50 KiB
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, если тот пересоздан
(проверено).
Алгоритм — сведение к желаемому состоянию, каждый шаг безопасно повторять:
- Bucket: есть в
s3.bucket.list— «exists», нет —s3.bucket.create. s3.anonymous.set -access none.s3.policy -putполитикиapi-objects: создаёт или обновляет.- Пользователь
api: еслиs3.user.showего не находит —s3.user.createс ключами из окружения; затемs3.policy.attach(повтор не дублирует). - Ключи пользователя: чужие ключи удаляются, нужного нет — создаётся.
- Проверка — подписанные
curl --aws-sigv4запросы ключом API на127.0.0.1:$S3_PORT. ОтветSignatureDoesNotMatchзначит, что секрет в.envсменился: ключ пересоздаётся. Изменения IAM доходят до шлюза подпиской на filer, поэтому есть ожидание до 10 с. - Проверки приватности (требование «Проверка приватности вне 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→ 503unavailableпо таблице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: наDEBUGbotocore пишет заголовки с подписью. Запись «Started API» дополняетсяs3_host,s3_port,s3_bucket. Пустые ключи —warning, как пустой пароль Valkey.
Альтернатива: пропуск S3 на N секунд после отказа, как у Valkey.
Отвергнута: обхода нет, ответ всё равно 503. Пропуск только ускорил бы
ответы при зависшем S3, а это задача лимитов upload-memory.
8. Готовность и проверка приватности
-
/health/readyне меняется: S3 не трогает (решение 3PLAN.md, спекhealth). ВREPORT.md— перечень зависимостей. PostgreSQL критичен. Valkey не критичен — обход кэша. S3 не критичен — 503 на путях вложений, текст работает. -
make s3_check— команда драйвера скиллаrun-mtusi-messenger(driver.py s3-check, stdlib, какcache-check):docker compose run --rm --no-deps s3-bootstrap checkзаписывает проверочный объект ключом API и проверяет права.- Анонимные GET и LIST этого объекта идут с хоста через
127.0.0.1:$S3_OUT_PORTи из сети стенда одноразовым контейнером того же закреплённого образа (docker run --network <проект>_default … curl). - Финальный шаг
checkудаляет объект и временный bucket.
Вывод — таблица «проверка → ожидаемый код → полученный» без секретов, код выхода 1 при расхождении. Порты контейнера S3 из сети проверяет тот же одноразовый контейнер (
nc -z). -
Отказ gRPC-вызова без токена в evidence показывает разовая проба: клиент на protobuf SeaweedFS той же ревизии в одноразовом контейнере в сети стенда, как в Context. В проект и
uv.lockона не входит.
9. Стенды
-
scripts/restart.sh:stop haproxy api;restart postgres valkey s3;up -d --wait postgres valkey s3;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 shellfs.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
Порядок:
- Зависимость и настройки.
- Compose,
infra/s3/bootstrap.sh,.env.example, Makefile. - Клиент в
src/infra/s3/. - Стенды:
restart.sh, isolated, failures, bench. - Документы.
- Commit.
- 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.
--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ждёт завершения.- Режимы 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: ничего не пишется в слой контейнера. - Секрет сменился — ключ пересоздаётся по
SignatureDoesNotMatch, а не по любому 403 (решение 4, шаг 6): ожидание изменений IAM до 10 с даётInvalidAccessKeyId, его ждут, а не пересоздают ключ. - Клиент (решение 7):
open(key)отдаётStoredObjectсsize,content_type,iter_chunks()иread(); срок[s3] timeout_seconds— на вызов и на каждый блок чтения тела (отдача 10 MiB медленному клиенту дольше срока, блок — нет). ТипыStoredObjectInfoиStoredObject— вsrc/infra/s3/client.py. Переводятся только ошибки клиента и сети (ClientError,ConnectionErrorиHTTPClientErrorbotocore,IncompleteReadError,aiohttp.ClientError,OSError); прочие не перехватываются (500). Ключи передаются в botocore всегда, даже пустые: иначе он искал бы учётные данные в окружении и~/.awsхоста. - Ожидаемо красные шире списка tasks.md. Контракт лабы 4 сделал
attachment_idsобязательным полемMessage, а код лабы 3 его не отдаёт (вsrc/его нет с5d5d8f9). До changeattachmentsпадают все тесты, которые проверяют схему сообщения, с одной причиной «'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. Код 0make failure_checksдо тех пор недостижим, новая проверкаtest_readiness_without_object_storageзелёная. - Дельта
healthсинхронизирована в основной спек в apply, как вscaling-bench(«/opsx:syncтолько её»): сверка покрытия читает толькоopenspec/specs/, и маркер нового сценария «Хранилище объектов недоступно» без этого указывал бы на неизвестный сценарий. Остальные дельты — при archive. - Профиль
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):
- 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 рестартов и 6kill— первая запись 10–40 мс. Свежий volume (tmpfs) тоже проходит: data node регистрируется и без томов, bootstrap создаёт bucket. 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 агенту нельзя).- Ошибки 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, не клиента. - Уборка префикса проверяется (S2, решение 9).
weed shellвыходит с кодом 0 и при ошибке (rm: <путь>: LookupEntry1: … connection refused).remove_objectsразбирает строкиrm:(кроме «no entry is found» — префикса нет) и проверяет пустойfs.lsпрефикса; иначеRuntimeError: в начале прогона — код 1 до тестов, в уборке — «cleanup failed», код 1. - Готовность при замороженном S3 (S3).
test_readiness_without_ object_storageпараметризованstopиpause; сценарийhealth«Хранилище объектов недоступно» называет оба (основной спек и дельта). - Порты 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.