11 KiB
Хранение и восстановление исходных документов OpenAPI
Эта инструкция описывает текущую реализацию Community. Контракт HTTP см. в Admin API, параметры — в runtime-config.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. Увеличение 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 с прежним ключом и отсутствие дубликатов.
Существующая команда восстановления изменяет данные назначения:
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.