Импорт и миграция
Arkvory загружает существующие данные собственным инструментом импорта подготовленного файлового каталога через публичный API и SDK. Инструмент не подключается к другим хранилищам и не переносит их пользователей, права и метаданные. Полная миграция рабочего объёма 4 ТБ не выполнялась.
Импорт каталога
npm run import -- DIRECTORY [--apply] [--replace-assets]Реализация: scripts/import.mjs; npm script подключает .env, если файл существует. Принимается ровно один каталог; неизвестные флаги отклоняются.
Опись (dry run)
По умолчанию ничего не отправляется: инструмент рекурсивно обходит каталог, потоково вычисляет SHA-256 и печатает JSONL-опись {path,size,sha256,kind}. path — относительный путь с разделителем /, size — десятичная строка, kind — upack для файлов .upack, иначе asset.
Отказывает для symlinks (включая сам источник), нештатных файлов и небезопасных путей: пустых сегментов, ./.., символа : и путей длиннее 1024 символов. Первое нарушение останавливает запуск. На время переноса исходный каталог должен быть неизменяемым. Имена каталогов/файлов не следует использовать для секретов: пути попадают в опись/журнал оператора.
Применение
--apply использует переменные окружения:
| Переменная | Значение |
|---|---|
ARKVORY_BASE_URL | Адрес API; по умолчанию http://127.0.0.1:8080. SDK допускает HTTPS либо HTTP на loopback |
ARKVORY_TOKEN_FILE | Обязательный файл с Bearer-ключом |
ARKVORY_REPOSITORY | Целевой репозиторий; по умолчанию releases, формат [a-z0-9][a-z0-9_-]{0,63} |
ARKVORY_IMPORT_JOURNAL | Обязательный журнал; открывается на дозапись с правами 0600 |
Файл ключа и журнал должны находиться вне импортируемого каталога. Ключу нужны права загрузки, регистрации пакетов, чтения и изменения assets и чтения содержимого в целевом репозитории.
Порядок для файла: SHA-256 → детерминированный Idempotency-Key из repository/path/hash → multipart upload с продолжением принятых частей и завершением → регистрация UPack или привязка asset к относительному пути → полное скачивание опубликованного артефакта → сверка size/SHA-256 → строка журнала {path,id,size,sha256,verifiedAt} и fsync. В stdout печатается {path,id,status:"verified"}.
Повтор идентичного source path/hash/repository использует прежнюю сессию и продолжает с принятых частей. Журнал является отчётом; не используется как основание пропустить проверку: каждый запуск заново хеширует и сверяет все файлы. Истёкшая cancelled-сессия требует новой операции с осознанно изменённой идентичностью импорта, не подмены descriptor.
.upack регистрируется как пакет; прочие файлы привязываются к относительному asset path. По умолчанию существующий другой asset не перезаписывается, запуск останавливается. --replace-assets разрешает атомарную замену только с проверкой текущей ревизии; старый blob остаётся в истории. Изменённую версию UPack перезаписать нельзя.
Descriptor получает имя файла и label imported; других метаданных инструмент не придумывает. Метаданные и права источника переносятся отдельно: annotations API с проверкой ревизий, сервисные ключи и группы доступа. Секреты передаются из файла, не через argv и не выводятся. Передачи последовательны, память bounded; собственного расписания и ограничения полосы у инструмента нет, действуют серверные лимиты ключа. Проверка скачиванием удваивает сетевой трафик — учесть это в окне миграции.
Перенос рабочего объёма (ожидает стенда)
- Снять read-only инвентаризацию источника: пакеты, пути, ревизии, metadata, права и пользователей. Зафиксировать версии клиентов и сценарии, которые должны работать после переноса.
- Подготовить экспорт без перепаковки и контролируемую опись исходных хешей. Пути проверить на коллизии регистра и ограничения Arkvory.
- Прогнать малый пилот: обычные, пустые, большие файлы, prerelease/build metadata, nested groups, пользовательские поля манифеста. Сопоставить исходные и целевые права. Прерывать процессы и повторять перенос.
- Перенести основной объём вне пиков, сверить журнал и независимую опись. Клиенты переводятся на native API, SDK или
arkvoryctl. - Остановить запись в источник, перенести финальную дельту, сверить byte counts/hash, метаданные, права и рабочие клиентские сценарии.
- Переключать клиентов только после стендовых HA/restore/client проверок и согласованного окна.
- При откате сначала остановить запись в Arkvory, инвентаризировать появившуюся дельту и перенести её обратно. Источник не удалять до завершения периода наблюдения.
Резервное копирование до реализации online backup
Остановить API/worker и отключить автоматический перезапуск. Снять согласованный PostgreSQL dump и полную копию storage root вместе со storage-id, parts и staging. Не копировать только blobs, теряя БД. Секреты/конфигурацию хранить отдельно с ограниченными правами. Зафиксировать версии сервиса, PostgreSQL и схемы БД.
Восстанавливать сначала в изолированную чистую среду: БД, соответствующий storage root, конфигурация; затем offline npm run scrub, проверки pending/available и sample downloads. Реплика не заменяет независимый backup: ошибки/удаления также реплицируются. Автоматический backup/restore runner и испытание восстановления 4 ТБ остаются открытыми задачами: BACKUP_RECOVERY.
В перспективе
Инструменты миграции из внешних репозиториев артефактов (например, ProGet) могут быть добавлены позднее: чтение источника через его API, перенос метаданных и сопоставление прав. Совместимость протоколов при этом не возвращается (ADR 0045).