# Хранение и восстановление исходных документов 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>/`. Запись использует 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//` из `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).