- 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>
46 KiB
План лабы 4 на «5»
Рабочий документ на время лабы (составлен 2026-10-20). Пункты
закрываются changes OpenSpec по порядку из раздела «Последовательность
работ»; решение, принятое в design change, важнее этого плана. Когда
change заархивирован, его строку здесь отметить; когда закрыты все —
итоги перенести в REPORT.md, а файл удалить.
Задание — README.md, переходы API — COURSE.md, семантика —
contracts/README.md, раздел «Вложения (с lab4)». Код пока в состоянии
лабы 3 (commit 5d5d8f9, «carry lab 3 over»): S3 и вложений нет. Поэтому
по коду, без запуска:
- публичный smoke (
LAB=4) упадёт на загрузке вложения; make student_testкрасный наtest_exclusion_evidence_exists: файлов evidence исключений сверки ещё нет (AGENTS.md, «Переход в следующую лабу»).
Оба пункта закрывает change attachments.
Что требует рубрика и чем закрываем
| Уровень | Пункт рубрики | Как закрываем | Change |
|---|---|---|---|
| 3 | S3 в общем стенде, persistent volume, закреплённая версия, создание приватного bucket описано | сервис S3 в docker-compose.yml, одноразовый bootstrap как migrate |
s3-storage |
| 3 | метаданные в PostgreSQL, байты в приватном bucket, не в БД и не в локальном каталоге API | таблица вложений, ключ объекта назначает сервер | attachments |
| 3 | POST вложения → 201 ready после сохранения, побайтный download, attachment_ids в сообщении, smoke с checksum и 404 постороннему |
ручки upload / метаданные / content, поле сообщения, история | attachments |
| 3 | реальные PNG/JPEG ≤ 10 MiB и ≤ 40 млн пикселей, MIME по содержимому, опасный filename отклонён, лимиты до неограниченного чтения и декодирования |
Content-Length до чтения, потоковое чтение со счётчиком, сигнатура по байтам, размеры из заголовка до декодирования |
attachments |
| 3 | upload → остановка обслужившей реплики → download через другую тот же файл; restart с volumes сохраняет метаданные и оригинал | make test-persistence, make test-failover и свой сценарий: остановить реплику по X-Instance-Id загрузки |
attachments |
| 3 (п. 5 «Что сделать») | недоступность S3, чужой чат, restart всего стенда | 503 вместо 500 при отказе S3, текстовые сообщения работают; тесты отказов | attachments, upload-consistency |
| 4 | тесты: большой файл, повреждённое изображение, подмена MIME, чужое attachment_id, вложение другого чата; пользовательская ошибка не 500 |
student-tests/test_attachments.py |
attachments |
| 4 | прерванная загрузка и отказ между S3 и БД не оставляют вечных неучтённых объектов; механизм компенсации / очистки с grace period описан | строка-намерение до PUT, компенсация, уборщик зависших намерений | upload-consistency |
| 4 | лимиты, таймауты и потоковая обработка ограничивают RAM; ≥ 10 одновременных загрузок с замером пика памяти | лимит одновременных загрузок на реплику, профиль uploads стенда bench/ |
upload-memory |
| 4 | bootstrap идемпотентен; у API отдельные S3 credentials с ограниченными правами; консоль не в общей сети; проверка приватности bucket вне API | bootstrap дважды, пользователь API только на объекты bucket, анонимный GET / LIST → 403 | s3-storage |
| 5 | трек 2 «Согласованность двух хранилищ» | раздел «Трек 5» ниже | track2-reconciler, track2-reconcile-cost |
Сценарий защиты (README): п. 1 — smoke и команда драйвера; п. 2 — 404
постороннему и анонимный GET в S3 (s3-storage); п. 3 —
test-persistence и test-failover; п. 4 — нет локального файла
оригинала на API, отказы и эксперименты.
Ключевые решения
Ниже предложения. Окончательное решение принимается в design соответствующего change.
1. S3-сервер: SeaweedFS, не MinIO — подтверждено 2026-10-20
README разрешает любой из трёх: MinIO, SeaweedFS, RustFS. MinIO — самый известный вариант, но закрепить его образ из чистого clone сейчас нельзя. Проверено 2026-10-20:
docker buildx imagetools inspect minio/minio:latestиminio/mc:latest— «pull access denied, repository does not exist»; API Docker Hub наminio/minioотвечает 404;quay.io/minio/minio— 401 без авторизации;- для сравнения
chrislusf/seaweedfsиrustfs/rustfs:1.0.3разрешаются, у обоих свежие теги (2026-10-17…20).
По публичным источникам (блоги, не объявления MinIO): сборки образов community edition прекращены в октябре 2025, с декабря 2025 — maintenance mode, в 2026 репозиторий архивирован; исправление CVE-2025-62506 в образ не попало. Варианты оставить MinIO и их цена:
| Вариант | Чем плох |
|---|---|
| старый закреплённый образ | из чистого clone не скачивается — рубрика «3» (стенд из репозитория) не выполняется |
| сборка из исходников архивного репозитория | свой Dockerfile с Go-сборкой, исправлений дальше не будет |
форк pgsty/minio |
сторонний проект, доверие и сопровождение надо проверять |
Сравнение оставшихся:
| SeaweedFS | RustFS | |
|---|---|---|
| Зрелость | с 2015 года, образы публикуются ежедневно | проект моложе, открыт в 2025 |
| Bootstrap bucket и пользователя | weed shell (s3.bucket.create, s3.configure) из того же закреплённого образа |
admin API в стиле MinIO: нужен mc (образ недоступен, см. выше) или свой код подписи |
| Права пользователя API | действия Read / Write / List / Admin на bucket |
IAM-политики в формате AWS, тоньше (s3:PutObject без s3:DeleteObject) |
| Консоль / UI | master, filer, volume, admin UI — не публикуются | консоль на отдельном порту — не публикуется или выключается |
Предложение — SeaweedFS: один процесс weed server -s3 с volume,
bootstrap одноразовым сервисом на том же образе. В design
s3-storage — короткая проверка на стенде до выбора: идемпотентность
создания bucket, запрет анонимного доступа, права пользователя API,
healthcheck, переживание рестарта. Если SeaweedFS провалит проверку —
RustFS. В .claude/rules/settings.md MinIO упомянут только примером
секрета, правило обновляется в том же change.
2. Запись вложения: намерение → объект → готово
- Порядок upload: проверки до чтения → потоковое чтение и проверка
содержимого → строка-намерение
pendingс ключом объекта (commit) →PUTв S3 → строкаready(commit) →201. - Ключ объекта — серверный (
uuid),filenameтолько для показа: ни путь, ни ключ из него не строятся. - Любой объект в bucket, загруженный API, известен БД до PUT.
Сбой после PUT и до второго commit оставляет
pending, а не неучтённый объект: его убирает уборщик после grace period (upload-consistency). Объект без строки возможен только мимо API — это класс расхождений трека 2. - Ответ на вопрос защиты «PUT прошёл, COMMIT нет» — отсюда.
pendingво внешний API не попадает: контракт лабы 4 знает толькоready;GETтакого вложения — 404.
3. /health/ready без S3 — подтверждено 2026-10-20
Отказ S3 не выводит реплики из LB: вложения отвечают 503 unavailable,
текстовые сообщения и история работают. Если включить S3 в готовность,
его заминка разом выключит все реплики, включая текстовый путь
(та же логика, что у таймаута готовности PostgreSQL, balancer.md).
Решение и список критичных зависимостей — в REPORT.md (контракт:
«Какие зависимости критичны, зафиксируйте в отчёте»).
4. Память загрузки
- Тело ≤ 10 MiB:
Content-Lengthбольше лимита — 413 до чтения; безContent-Length— счётчик при чтении, обрыв на 10 MiB + 1. - Сигнатура PNG / JPEG по первым байтам; размеры из заголовка до декодирования, больше 40 млн пикселей — 413.
- Главный риск — не байты, а декодирование: 40 млн пикселей RGB —
около 120 МБ на одну загрузку при лимите реплики 512 МБ. Варианты
для design
attachments: проверка целостности без полного декодирования (PNG — CRC чанков и потоковая распаковка IDAT со счётчиком строк; JPEG — структура маркеров), полное декодирование под семафором,draftдля JPEG. Цена каждого — вupload-memory. - Лимит одновременных загрузок на реплику и сроки чтения тела (HAProxy
и API).
timeout serverLB 10 с рассчитан на запрос к БД, а не на медленную передачу 10 MiB — цепочку таймаутов пересмотреть для пути upload.
5. Учётные данные S3
- root — только bootstrap; API и уборщик его не получают.
- Пользователь API — объекты своего bucket: чтение, запись, удаление (компенсация). Без List и Admin.
- Уборщик / reconciler — свой пользователь: List, чтение, удаление.
- Пароли —
.env(make env_setupгенерирует, как Postgres и Valkey), в приложение — мостамиS3__*. Соответствие имён skeleton (S3_ENDPOINT,S3_REGION,S3_BUCKET,S3_ACCESS_KEY_ID_FILE,S3_SECRET_ACCESS_KEY_FILE,MAX_UPLOAD_BYTES,MAX_IMAGE_PIXELS) — вREPORT.md, как в лабе 3. - API-порт S3 — только
127.0.0.1(console-режимmake run_dev), как Postgres и Valkey; UI и консоль не публикуются вообще.
6. Идемпотентность с attachment_ids
message_request_hash начинает учитывать attachment_ids. Пустой
список не должен менять хэш: иначе ключ, сохранённый версией без
вложений, после make rolling_update давал бы 409 на повтор того же
тела. Порядок элементов массива значим (это JSON-массив), порядок
ключей объекта — нет (контракт).
7. Уборщик — отдельный сервис (подтверждено 2026-10-20)
Фоновая работа в API-репликах запрещена до worker лабы 5 (AGENTS.md,
«Архитектура в двух словах»). Уборщик зависших pending — отдельный
сервис compose на образе API со своей командой и своими S3-правами,
интервал и grace period в настройках. Отвергнута цель Makefile без
расписания: с ней «вечных» объектов нет только при регулярном ручном
запуске. В треке 2 уборщик вырастает в reconciler.
Трек 5: трек 2 «Согласованность двух хранилищ» (подтверждено 2026-10-20)
Почему трек 2.
- Продолжает обязательный пункт «4» (компенсация и очистка): общий код, общие тесты отказов.
- Контракт не расширяется, S3 остаётся во внутренней сети.
- Замеры ложатся на готовый
bench/(наполнение, паспорт, сэмплер,summary.md), как трек 2 лабы 2. - Пригодится в лабе 5: staging-prefix, хвосты worker при доставке at least once.
Почему не трек 1 (presigned upload).
- S3 должен быть доступен клиенту: подпись под внешний адрес, шире поверхность атаки.
- Новые ручки init / complete в
contracts/extensions.openapi.json. - Лимит размера (POST policy
content-length-range) и checksum при complete на SeaweedFS / RustFS не проверены; без них complete читает объект обратно, и выигрыш по трафику API тает. - В лабе 5 загрузка становится асинхронной (202) — flow переделывать.
Гипотезы (до прогонов коммитятся отдельно)
- Линейность. Время обхода растёт линейно по числу объектов, цена на объект от N почти не зависит.
- Батч против точечной сверки. Сверка страницы LIST (до 1000
ключей) одним запросом к БД (
object_key = ANY(...)) дешевлеHEADна каждую строку: запросов N/1000 против N. - Поверхностная против глубокой. Размер из LIST почти бесплатен; SHA-256 требует прочитать каждый объект и упирается в чтение S3 — глубокая сверка выборочная или по требованию.
- Влияние на рабочий трафик. Обход с ограниченной скоростью ухудшает p95 фоновой нагрузки API не больше порога, заданного до прогона.
- Безопасность. Ни одно подтверждённое и ни одно используемое в сообщениях вложение не удаляется при любой гонке с загрузками.
Методика (предварительно)
- Стенд
mtusi-benchс S3 и лимитами из паспорта. N = 10k и 100k объектов; наполнение мимо API (SQL и прямой PUT), граница описана. - Внесённые расхождения, по доле каждого класса: объект без строки,
зависший
pending, строкаreadyбез объекта, другой размер. - Метрики: время по фазам, запросы S3 и PostgreSQL, CPU / RAM reconciler, S3 и PostgreSQL (сэмплер), p95 фоновой нагрузки k6.
- 3 повтора, A/A для отделения эффекта от шума (
make bench_compareили его аналог для профиля).
Ограничения, которые заранее назвать
- Генератор, API, S3 и БД на одном хосте, Docker Desktop — VM.
- Одна нода S3, без репликации: отказ диска или хоста не переживается.
- Строку без объекта не восстановить: байтов нет нигде. Reconciler её находит и помечает, но не «чинит».
Последовательность работ
Этапы 1–6 — changes OpenSpec, каждый проходит /opsx:propose →
/opsx:apply → /opsx:verify → /opsx:archive. Этап 7 — сборка
отчёта, не change. Замеры для отчёта снимаются с закоммиченного кода
(bench.md, «Измеренное состояние — commit»). Отчёт пополняется в
каждом change: evidence и строка в таблице доказательств REPORT.md —
часть «готово». Возможности лаб 2 и 3 (bench_restore, профили
failover и rollout, серии трека 1, проверки отказов) работают после
каждого change.
Сводная таблица
| № | Change | Уровень | Что происходит | Готово, когда |
|---|---|---|---|---|
| 0 | — (подготовка) | — | этот план; выбор трека и S3-сервера | план сохранён 2026-10-20; трек 2, SeaweedFS, решения 3 и 7 подтверждены 2026-10-20 |
| 1 | s3-storage |
3 (+4: bootstrap, права, консоль, приватность) | S3 в стенде, bootstrap, клиент в src/infra/s3/, настройки, все стенды знают о S3 |
bootstrap дважды без ошибок, анонимный GET / LIST → 403, ключ API не может admin-операций, make test-persistence перезапускает и S3 |
| 2 | attachments |
3 (+4: тесты) | миграция, домен attachment, ручки, attachment_ids в сообщениях, тесты |
зелёные make test, test-persistence, test-failover, свой сценарий отказа загрузившей реплики; негативные тесты; evidence исключений переснят |
| 3 | upload-consistency |
4 | намерение до PUT, компенсация, уборщик с grace period, тесты отказов | make failure_checks с отказами S3 и БД посреди загрузки: нет 500, нет неучтённых объектов старше grace period |
| 4 | upload-memory |
4 | лимит загрузок на реплику, сроки тела, профиль uploads |
замер ≥ 10 одновременных загрузок: пик памяти ограничен, механизм объяснён |
| 5 | track2-reconciler |
5 | reconciler: dry-run / apply, классы расхождений, внедрение ошибок, доказательство безопасности | ошибки внесены с обеих сторон, обнаружены, исправлены; повторный запуск находит 0; под загрузками ничего подтверждённого не удалено |
| 6 | track2-reconcile-cost |
5 | гипотезы, профиль стоимости обхода, стратегии, графики | метки в evidence/, выводы по гипотезам и ограничения в REPORT.md |
| 7 | — (отчёт и PR) | 3–5 | сводка REPORT.md, чистый clone, шаблон PR, уборка этого файла |
PR ЛР 4 — БВТ2301 — Сафронов — на 5 |
1. s3-storage — уровень 3, +4
Пункты рубрики.
- «3»: S3 в общем стенде, persistent volume, закреплённая версия, создание приватного bucket описано.
- «4»: bootstrap идемпотентен; отдельные credentials API с ограниченными правами; консоль не в общей сети; проверка приватности вне API.
Стенд.
- Сервис S3: тег с версией и digest индекса (
docker.md), named volume, healthcheck, лимиты CPU / RAM,restart: unless-stopped. - Одноразовый bootstrap (как
migrate): bucket, запрет анонимного доступа, пользователи API и уборщика. Реплики ждут егоservice_completed_successfully. - Окружение по сервисам: root — только bootstrap; ключи API — только
api; LB иmigrateS3-секретов не получают. .env.example,make env_setup(генерация паролей S3), строки вconfig_example.toml.scripts/restart.shперезапускает и S3; стендыbench/(bench.compose.yml),make test_isolated(свой bucket или prefix по имени базы, как ключи Valkey) иmake failure_checks(свой S3) знают о новом сервисе.
Код.
src/infra/s3/: фабрика клиента и глобал по образцуcache/instance.py, срок на каждый вызов, ошибки → доменные исключения (отказ → 503). Библиотека — решение design: aiobotocore (асинхронный, тянет закреплённый botocore) или boto3 в потоке.- Секция
[s3]вSettings, мостыS3__*. /health/ready— по решению 3.
Спеки (дельты). Новая object-storage (bucket, приватность,
права, bootstrap); container-run (S3 в стенде, restart hook);
service-configuration ([s3]); health (S3 не критичен для
готовности); service-logging (ключи и подписи не логируются).
Правила. S3 — в infra.md, docker.md, settings.md; AGENTS.md
(карта кода, таблица команд).
Evidence: evidence/s3/ — bootstrap дважды, анонимные GET и LIST
→ 403, ключ API против admin-операций и чужого bucket, docker compose ps без опубликованных UI-портов, test-persistence с рестартом S3.
2. attachments — уровень 3, +4 (тесты)
Пункты рубрики. Все пункты «3» о вложениях; «4» — негативные тесты.
Код.
- Миграция: таблица вложений (чат, владелец,
filename,content_type, размер, SHA-256, ключ объекта, статус, время) и связь сообщения с вложениями с порядком. Только расширение схемы (migrations.md). - Ручки:
POST /chats/{chat_id}/attachments?filename=…,GET /attachments/{id},GET /attachments/{id}/content(поток из S3, истинныйContent-Type, без redirect,variantтолькоoriginal). - Проверки upload по решению 4; ошибки: 400 (
filename, UUID), 413 (байты, пиксели), 415 (формат, повреждение, подмена MIME), 404 (чужой чат), 503 (S3). - Сообщения:
attachment_ids0–10 уникальныхUuidIn, пустой текст с вложением, чужое / неизвестное / другого чата → 404; история и повтор отдаютattachment_ids; хэш — решение 6. - Драйвер скилла
run-mtusi-messenger: upload / download / SHA-256 и сценарий «остановить реплику, принявшую файл».
Тесты (student-tests/test_attachments.py, маркеры spec):
PNG и JPEG; 413 по байтам и по пикселям (маленький файл с огромными
размерами в заголовке); 415 на обрезанный файл, на текст с
image/png, на JPEG с image/png; filename с /, \, NUL,
управляющими символами — 400; чужое и неизвестное attachment_id,
вложение другого чата — 404; посторонний — 404 на метаданные и
content; ни одна ошибка не 500; идемпотентность с attachment_ids.
Большие и «бомбы» генерируются в тесте, в git не кладутся (README
fixtures).
Свой сценарий отказа. Публичный make test-failover останавливает
реплику, ответившую на первое сообщение, а не на upload. Рубрика
требует остановить именно принявшую файл: upload через LB →
stop-one.sh по её X-Instance-Id → download через другую → тот же
SHA-256.
Переход в лабу 4. Переснять четыре файла исключений сверки на
стенде лабы 4: evidence/cache/hits.md,
evidence/auth/passwords-and-tokens.md,
evidence/replicas/test-persistence.md,
evidence/idempotency/replay-after-restart.md.
Спеки (дельты). Новая attachments; messages (attachment_ids,
пустой текст); idempotency (хэш); data-storage (байты в S3);
student-tests.
Evidence: evidence/attachments/ (smoke, download другим
участником, 404 постороннему, отказ загрузившей реплики),
evidence/tests/.
3. upload-consistency — уровень 4
Пункт рубрики. Прерывание загрузки и отказ между S3 и БД не оставляют вечных неучтённых объектов; механизм с grace period описан.
Код.
- Намерение до PUT (решение 2), компенсация при ошибке после PUT (удаление объекта, без гарантии — её даёт уборщик).
- Уборщик (решение 7):
pendingстарше grace period →DELETEобъекта (идемпотентно, отсутствие — не ошибка) → удаление строки. Grace period больше максимального времени загрузки с запасом на часы; значения — настройки.
Тесты отказов (make failure_checks, новые действия
fault_hook.py): S3 остановлен и заморожен до и во время PUT; отказ
вставки строки после PUT (триггер, как fail-messages); kill реплики
посреди загрузки; обрыв клиента посреди тела. Итог каждого: нет 500,
pending убран уборщиком после grace period, объектов без строки нет.
Спеки (дельты). attachments (сбои загрузки), новая или в
object-storage — уборка.
Evidence: evidence/attachments/consistency.md, вывод
make failure_checks; раздел REPORT.md с порядком записи.
4. upload-memory — уровень 4
Пункт рубрики. Лимиты, таймауты и потоковая обработка не дают одной загрузке занять неограниченную RAM; эксперимент ≥ 10 одновременных загрузок с замером пика памяти.
Код и стенд.
- Лимит одновременных загрузок / декодирований на реплику; что видит
клиент при превышении — решение design (ожидание с таймаутом или
ответ с
Retry-After). - Сроки чтения тела в API и HAProxy, цепочка таймаутов для upload (решение 4).
- Профиль
uploadsстендаbench/: 1 / 10 / 20 / 40 одновременных загрузок по 1 и 10 MiB,memory.peakcgroup реплики и сэмплер, p95, ошибки по кодам. Варианты «без лимита» и «с лимитом».
Гипотеза. Пик памяти реплики ≈ база + K × (буфер тела + декодирование), где K — лимит одновременных загрузок; без лимита пик растёт с конкуренцией до OOM-kill.
Evidence: evidence/uploads/<метка>/, выводы и ограничения в
REPORT.md.
5. track2-reconciler — уровень 5, трек 2
Пункт рубрики. Повторяемый reconciler для orphan / missing объектов и метаданных; ошибки на обеих сторонах; обнаружение и безопасное исправление с dry-run и повторным запуском; свежие и используемые вложения не удаляются.
Код.
- Обход LIST bucket и БД (keyset), классы: объект без строки,
зависший
pending, строкаreadyбез объекта, другой размер. - Режимы
--dry-run(отчёт: класс, ключ, возраст) и--apply; повторный запуск после прерванногоapplyдоводит работу, следующий находит 0. - Безопасность: grace period по времени объекта и строки; перепроверка строки в БД непосредственно перед удалением объекта; объекты, на которые ссылаются сообщения, не удаляются никогда.
- Строка без объекта — что видит API (решение design: метка в БД, ответ content), байты не восстановить.
Внедрение ошибок (fault_hook.py): объект в bucket мимо API,
удалённый объект, удалённая или изменённая строка, обрыв загрузки
посередине.
Доказательство безопасности. Reconciler --apply под
одновременными загрузками и отправками; затем каждое подтверждённое
вложение скачивается с тем же SHA-256.
Evidence: evidence/reconcile/ — dry-run, apply, повтор = 0,
стресс.
6. track2-reconcile-cost — уровень 5, трек 2
Пункт рубрики. Гипотеза, повторяемая методика, результаты и ограничения; измерить стоимость обхода.
Стенд bench/. Профиль reconcile по методике раздела «Трек 5»:
наполнение N объектов с долей расхождений, стратегии (батч против
HEAD, поверхностная против глубокой), фоновая нагрузка k6, сэмплер,
3 повтора и A/A.
Evidence: evidence/reconcile/<метка>/, графики (make bench_plots или его аналог), выводы по гипотезам 1–5 и ограничения в
REPORT.md.
7. Отчёт и PR
REPORT.md: запуск из чистого clone, архитектура и транзакционные границы, соответствие переменных skeleton, таблица доказательств, эксперименты, ответы на вопросы защиты, согласования с преподавателем, ИИ и источники.- Проверка из чистого clone,
make check,make testна собранном образе, шаблон PR. Этот файл удаляется.
Риски
- Декодирование больших изображений в лимите памяти реплики (решение 4) — главный технический риск лабы.
- Совместимость выбранного S3-сервера: идемпотентный bootstrap, права,
поведение при рестарте. Проверяется до выбора в design
s3-storage. - Медленная загрузка 10 MiB против цепочки таймаутов лабы 3
(
timeout server,timeout client, срок запроса к БД). - Доказательство «ничего свежего не удалено» требует настоящих гонок, а не последовательного сценария.
- Объём
bench/: новые профилиuploadsиreconcileне должны ломать прежние (bench_restore,failover,rollout, серии).
Вопросы и решения по ходу changes
Файл вопросов цикла OpenSpec: на каждый change — раздел ### <change>
с подразделами «Решения» (принятые без пользователя, со ссылкой на
design) и «Вопросы» (ждут ответа; ответ дописывается рядом с датой).
При удалении плана открытые вопросы переносятся в REPORT.md.
s3-storage
Решения
Приняты 2026-10-20 в /opsx:propose, подробности — design change
s3-storage.
-
SeaweedFS прошёл пробу на стенде вне репозитория (design, Context), RustFS не понадобился. Проверены: идемпотентность bucket и пользователя, анонимные запросы, права ключа API, healthcheck, рестарт с volume,
kill -9, память, клиент. Образ —chrislusf/seaweedfs:4.48@sha256:4e61d15f…. Командыs3.configureиз решения 1 выше в 4.48 нет, вместо неё IAM-командыs3.user.*иs3.policy*(решение 4). -
Три места, где SeaweedFS по умолчанию не приватен (решения 1, 3):
- без учётных записей S3 открыт анониму → административная пара в окружении сервера с первого старта;
- master, filer и volume слушают все интерфейсы →
-ip.bind=127.0.0.1, в сеть выходит только шлюз S3; - gRPC-порт шлюза без ключа подписи принимает от любого контейнера
учётную запись администратора (воспроизведено) → обязательный
S3_JWT_SIGNING_KEY.
Выключены ещё телеметрия, Iceberg, Lance и встроенный IAM API.
-
Root по решению 5 выше (решение 3). Административную пару хранит только сервер
s3: без неё S3 открыт. Bootstrap работает не ею, аweed shellна loopback сервера с ключом подписи. У API и будущего уборщика административной пары нет. -
Права API — политика
s3:GetObject,s3:PutObject,s3:DeleteObjectна<bucket>/*, у bucket нет владельца (решение 3). Пользователь уборщика появится вupload-consistency. -
Bootstrap — сервис
s3-bootstrapсnetwork_mode: service:s3(решение 4):- сводит состояние к
.env, в том числе новый секрет API; - сам проверяет приватность при каждом запуске;
make s3_check— те же проверки с хоста и из сети (решение 8).
- сводит состояние к
-
Отдельной сети для S3 нет: служебные порты закрыты loopback и ключом подписи (решение 1).
-
Клиент — aiobotocore 3.9.2 (решения 6, 7):
- без повторов, срок на каждый вызов;
- отказ, таймаут и отказ в учётных данных — 503;
- ключи объектов с префиксом имени базы.
Отвергнуты boto3 в потоке, aioboto3, своя подпись, obstore и minio-py.
-
Память S3 (решение 2): лимит 512 МБ,
GOMEMLIMIT=400MiBи-s3.concurrentUploadLimitMB=64. Без них 20 одновременных загрузок по 10 MiB дают OOM-kill. Числа уточняетupload-memory. -
Остановка и перезапуск (решения 1, 2):
stop_grace_period: 20s— плавная остановка SeaweedFS занимает ~15 с, срок зашит в filer; на стенде отказов — 2 с;-master.electionTimeout=1s— перезапуск ~7 с вместо ~24 с.
-
Стенды (решение 9):
test_isolated— S3 рабочего стенда, префиксtest_<db>/, уборка черезfs.rm;failure_checks— свой S3 и проверка готовности без него;bench/— секреты на прогон и фильтр секретов в паспорте; профили лаб 2–3 S3 не запускают, методика прежняя;rolling-update.shbootstrap не запускает: bootstrap, как миграции, только расширяет права.
-
Проверка рестарта без публичного теста (design, Context; решение 9). Публичные
make test,test-persistenceиtest-failoverсLAB=4загружают вложение и доattachmentsкрасные. Поэтому рестарт hook-ом проверяется напрямую:StartedAt, «exists» bootstrap, объект с тем же SHA-256.
Приняты 2026-10-20 в /opsx:apply, подробности — design change
s3-storage, «Уточнения apply».
make start_s3— два шага:up -d --wait s3, затемup --no-deps --exit-code-from s3-bootstrap s3-bootstrap.--waitне ждёт завершения одноразового сервиса (compose v5.5.1), вопреки пробе propose. Так же —run_failures.py.- Bootstrap — режимы
apply,check,cleanup: проверки с хоста и из сети идут между записью проверочного объекта и его удалением. Новый секрет API распознаётся поSignatureDoesNotMatch. - Клиент:
open()читает тело блоками, срок — на каждый блок; ключи в botocore передаются всегда, даже пустые. - Ожидаемо красные шире списка tasks: контракт лабы 4 требует
attachment_idsвMessage, код лабы 3 его не отдаёт — доattachmentsкрасные 32 теста (и 2 ошибки)make student_testчерез LB (вmake test_isolated— 29 и 2) и 5 проверокmake failure_checks. От S3 не зависит. - Дельта
healthсинхронизирована в основной спек в apply, как вscaling-bench: иначе маркер нового сценария — ссылка на неизвестный сценарий в сверке покрытия. rollout_from c50b721— дефект переноса (KNOWN_ISSUES.md): профильrolloutпроверен с--from 5d5d8f9.
Приняты 2026-10-20 в правках по /opsx:verify (tasks.md, группа 7),
подробности — design change s3-storage, «Уточнения apply», п. 8–13.
- Healthcheck S3 ждёт регистрации тома (
/dir/status, непустойDataNodes): первая запись после рестарта — 10–40 мс вместо до 4,8 с при сроке 5 с. Та же проба — вfault_hook.py. tmpfs: [/tmp, /data]уs3-bootstrap: без анонимного volume на каждый контейнер.- Клиент S3: удалённый bucket и отказ в доступе — 503 с
error(«bucket is missing», «denied access»), а не «объекта нет» и не «rejected credentials»;deleteглушит только отсутствующий ключ. Ограничение: HEAD без тела, удалённый bucket уhead—None. make test_isolatedпроверяет уборку префикса (fs.lsпослеfs.rm): код 0weed shellуспеха не значит.make s3_checkберёт порты изnetstatконтейнера S3, а не из фиксированного списка; проверка готовности без S3 — и дляpause.
Вопросы
-
Как в apply добавить строки S3 в рабочий
.env? Агент.envне читает, аmake env_setupсуществующий файл не меняет (правилоsettings.md). Варианты:- (а) пользователь сам переносит блок из
.env.exampleи генерирует секреты, как было с Valkey; design исходит из этого; - (б) агент с согласия пользователя: значения
openssl randпопадут в журнал сессии; - (в) научить
make env_setupдописывать недостающие переменные шаблона со сгенерированными секретами в существующий.env. Это меняет правилоsettings.mdи спекcontainer-runне нарушает: существующие значения не перезаписываются.
Ответ 2026-10-20 (основная сессия, по факту): в рабочей копии лабы 4
.envещё нет. Его создастmake env_setupиз обновлённого.env.exampleвместе с секретами S3, переносить нечего. Для уже существующего.envостаётся (а), как в design; (в) — только по просьбе пользователя. - (а) пользователь сам переносит блок из
-
attachment_idsотсутствует в ответах Message (код лабы 3), и поэтому до changeattachmentsкрасные 32 тестаmake student_testи 5 тестовmake failure_checks(решение 15). Добавлять ли пустой список раньше?Ответ пользователя 2026-10-20: нет, красное до
attachments. Поле приходит целиком вattachments(запрос, ответ, хэш идемпотентности), там же evidence тестов переснимается зелёным. -
Когда чинить
rollout_from c50b721(решение 17,KNOWN_ISSUES.md)?Ответ пользователя 2026-10-20: в change
attachments: он добавляет миграцию, и rollout со старого образа на новую схему — нужное evidence. До тех пор запись остаётся вKNOWN_ISSUES.md.