129 lines
11 KiB
Markdown
129 lines
11 KiB
Markdown
# Хранение и восстановление исходных документов 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).
|