Files
crank/docs/artifact-storage-operations.md
T
bsodfather ad23cd9a46
CI / Rust Checks (pull_request) Successful in 24m43s
CI / UI Checks (pull_request) Successful in 6s
CI / Community Image Smoke (pull_request) Successful in 9m5s
CI / Frontend E2E (pull_request) Successful in 12m43s
CI / Deploy (pull_request) Skipped
fix(import): подтвердить обязательные гарантии второго эпика
2026-10-10 13:25:05 +03:00

129 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Хранение и восстановление исходных документов OpenAPI
Эта инструкция описывает текущую реализацию Community. Контракт HTTP см.
в [Admin API](admin-api.md#openapi-preview-upload), параметры — в
[runtime-config.md](runtime-config.md), обновление схемы — в [migrations.md](migrations.md).
## Корень и ограничения
`CRANK_STORAGE_ROOT` — абсолютный путь, по умолчанию `/var/lib/crank/storage`.
Admin API открывает его при запуске и закрепляет файловый дескриптор. Корень
и внутренние каталоги должны принадлежать пользователю процесса и иметь права
`0700`; опубликованные blobs — `0400`. Символьные ссылки, чужие владельцы,
небезопасные права и hard links отклоняются. В Compose именованный том
`artifact_storage` монтируется в этот путь, а `artifact-storage-init`
подготавливает права. Не заменяйте root symlink и не исправляйте проблему
прав рекурсивным `chmod 777`.
Production upload — `multipart/form-data` с единственным полем `file`, UTF-8
YAML/JSON, непустой файл до 262144 bytes включительно. Расширение и MIME
должны согласовываться; для YAML/JSON допустим `application/octet-stream`.
Это фиксированный предел текущего импортёра, не отдельная переменная окружения.
Дополнительные лимиты normalizer и external reference chain описаны в
[openapi-import.md](openapi-import.md). Увеличение HTTP proxy body limit
не увеличивает предел импортёра. Не передавайте документ через JSON `{document}`.
Физический blob адресуется только SHA-256: `sha256/<первые 2 hex>/<digest>`.
Запись использует private temp, file fsync, публикацию без перезаписи и
fsync каталога. Чтение проверяет digest до возврата bytes. PostgreSQL хранит
workspace-scoped ownership и references; один физический digest может
принадлежать нескольким workspace. Наличие файла не предоставляет права
другому workspace. Preview не создаёт Operations; Apply создаёт их одной
транзакцией и сохраняет неизменяемый результат для точного повторного запроса.
## Резервное копирование и восстановление
Сохраняйте согласованный комплект PostgreSQL, **всего** artifact storage,
Compose, runtime configuration и используемой ревизии образов. Дамп БД
без тома не восстанавливает исходники и snapshots; отдельно взятый том
не восстанавливает ownership и immutable plans. Конфигурация и исходники
могут содержать секретные данные: закрытые права, шифрование копии и ограниченный доступ.
Перед ручным снимком остановите mutating traffic и процессы `admin-api`/
`mcp-server`, включая фоновые reconciliation workers; затем получите дамп
PostgreSQL и архив тома. Не удаляйте named volume. Копируйте комплект на другой
хост и проверяйте SHA256SUMS. Возобновляйте процессы после получения снимка.
`scripts/deploy-community.sh` создаёт комплект `backups/<UTC>/` из
`postgres.dump`, `artifacts.tar.gz`, `runtime.env`, `docker-compose.yml`,
`SHA256SUMS` и проверяет миграцию копии перед обновлением. Дамп и архив
получаются последовательно; при продолжающихся записях это **не** доказательство
атомарного снимка БД+файлов. Для строгой согласованности оператор должен
организовать окно без записей. Скрипт сохраняет пять последних локальных
комплектов, поэтому внешняя копия обязательна до следующего обновления.
Проверяйте восстановление на изолированном стенде с matching image revision,
БД и томом: контрольные суммы, compatibility check, `/ready`, чтение
сохранённого source, повтор Apply с прежним ключом и отсутствие дубликатов.
Существующая команда восстановления изменяет данные назначения:
```sh
CRANK_RESTORE_CONFIRM=restore ./scripts/restore-community.sh DEPLOY_DIR BACKUP_DIR
```
Перед её выполнением сохраните текущее состояние и убедитесь, что выбрано
нужное назначение. Не откатывайте только приложение после миграции схемы:
используйте совместимый forward image либо проверенное восстановление комплекта.
## Очистка и восстановление claims
Координатор запускается в Admin API, проходит Recovery до Sweep и ограничивает
каждый тик: 4096 traversal syscalls, 32 candidates, 32 mutation attempts,
deadline 30 секунд. Период — 15 минут. Grace финальных/detached blobs — 24 часа,
lease claim — 5 минут; cleanup temp — после часа с отдельными лимитами
512 scans / 16 deletes. Это константы текущей версии, не конфигурационные ручки.
Referenced source действующего ImportPlan не является orphan. Старые upload jobs
и detached references очищаются по жизненному циклу; нельзя освобождать место
ручным удалением digest из storage, пока БД ссылается на него.
Sweep сначала помещает eligible blob в quarantine. Recovery проверяет обе
канонические локации и только после подтверждённого отсутствия переводит БД
в `unavailable`. Неопределённая мутация/fsync/commit сохраняет claim для
повторной попытки; перезапуск начинает bounded cycle заново. Старый worker
не может финализировать новый fencing token. При сбое диска/БД восстановите
ресурс, затем наблюдайте последующие тики; не сбрасывайте claim вручную в idle.
Legacy read — только из явно настроенного доверенного корня с проверками
containment и digest. Это read compatibility, не автоматическая миграция,
перезапись или удаление старых файлов. URL документа не выбирает корень.
## Диагностика и границы доказательств
Используйте canonical `X-Request-ID` и `X-Trace-ID` из ответа для сопоставления
с диагностикой. Ошибки не должны включать raw source, credentials или пути.
Reconciliation пишет фиксированные classification counters в события
`admin.artifact_reconciliation.tick` / `failed`; это безопасные категории,
а не реестр digest/workspace/token. `/ready` проверяет доступность PostgreSQL,
но не подтверждает целостность каждого blob: verified read проверяет конкретный файл.
Для проверки фоновой очистки смотрите последовательность событий
`admin.artifact_reconciliation.tick`: `cycle_completed=true` означает завершённый
проход, `recovery_completed=false` — Recovery ещё продолжается. Несколько тиков
с `retryable=true`, ростом `recovery_retryable`, `registration_retryable` или
`mutation_retryable` требуют проверки доступности БД, свободного места и ошибок
fsync/permissions. Событие `admin.artifact_reconciliation.failed` содержит
категорию `backend` или `deadline`; сопоставьте её с журналами БД и хоста.
После восстановления ресурса убедитесь, что следующие тики завершают цикл без
retryable. Предел candidates/mutation attempts может означать продолжение
ограниченного прохода, а не сбой.
В текущей версии эти значения — поля структурированных событий, а не
Prometheus gauge размера очереди. Runtime не публикует точное число оставшихся
blobs: не считайте один незавершённый тик доказательством утечки. Для Compose
отберите события из журнала Admin API командой
`docker compose logs --since 2h admin-api`; фильтруйте по фиксированным именам
событий. Не включайте raw source или digest в диагностические выгрузки.
Внешние ссылки выключены по умолчанию. Разрешение задаёт оператор allowlist;
автономный комплект требует подготовки и согласованной поддержки загрузки,
а не произвольного доступа к файловой системе. Документ не может разрешить
себе сеть. Изменённое удалённое содержимое требует нового preview.
Автоматические проверки находятся в `crank-artifacts/tests`, registry
`artifact_sources`/`artifact_reconciliation`, Admin API `reconciliation/tests`
и `openapi_import`, UI `openapi*.spec.js`. Они проверяют конкретные сбои и
состояния; успешный CI не доказывает отсутствие любых аппаратных сбоев,
потерь данных при произвольном порядке backup или утечек по времени.
Reference performance, длительная эксплуатация и человеческая приёмка
выполняются отдельно по [acceptance-test-plan.md](acceptance-test-plan.md).