Модули
Пакет модуля добавляет в Arkvory новую функцию. Arkvory устанавливает только пакеты, подпись которых он может проверить. Команды этой страницы выполняются на хосте установки: от root в Linux или от администратора в Windows. Консоль и HTTP API не умеют устанавливать модули и доверять ключам, поэтому украденная учётная запись администратора консоли не позволит запустить код на сервере.
Службы заново проверяют установленные модули и загружают их при каждом запуске. Модуль работает только после того, как вы его включите.
Arkvory Pro
Arkvory Pro — дополнительный набор платных подписанных модулей ProAnimaStudio для бесплатного ядра Arkvory. Pro 0.1.0 работает с Arkvory 0.6.3 на Windows/Linux x64. Пакеты модулей и лицензию получают у ProAnimaStudio; модули устанавливаются отдельно от ядра. См. установку и лицензии.
- Дедупликация хранит общие чанки один раз и переиспользует их в разных объектах. Общий каталог согласует сборку мусора с публикацией, чтением и резервным копированием.
- Дельта-передачи используют содержимое, уже доступное совместимому клиенту, и передают недостающие данные или патчи. Комплект содержит серверные модули хранения и передачи, а также клиентский модуль дельты. Экономия зависит от данных и клиента; обычное HTTP-скачивание автоматически не становится дельта-передачей.
- Лицензирование управляет платной записью и оптимизациями. При истечении или недоступности лицензии существующие данные остаются читаемыми; новые загрузки переходят в хранилище ядра и на обычную передачу. Квота Pro считает логические данные Pro, включая принятые незавершённые загрузки, без скидки за дедупликацию. Поле updatesUntil лицензии ограничивает право на новые сборки модулей.
Модули загружаются при старте служб; установки Docker Compose их не загружают. Перед обновлением сохраните копию метаданных и данных модулей. При первом внедрении общего каталога остановите старые пишущие API/worker: смешанная работа старых и новых писателей не поддерживается. Восстанавливайте данные и состояние лицензии вместе, дождитесь восстановления и проверьте новую загрузку в Pro перед возвратом обычной записи.
Восстановление большого каталога может быть долгим: на приёмочном стенде запись при 4 млн чанков и уже восстановленном общем каталоге стала доступна через 32 минуты 43 секунды без перезапуска. Это не гарантия времени восстановления и не замер пропускной способности на 4 ТБ. Проверка HA на одном физическом хосте не заменяет проверку fencing и доменов отказа вашей площадки. Pro не меняет условия лицензии ядра.
Возможности модулей и сторонние плагины
Подписанные модули ProAnimaStudio могут добавлять хранилища, протоколы передачи и HTTP-маршруты, получать службы фоновой работы, ограниченных вычислений и согласованной очистки данных согласно своим ролям. Бесплатным модулям не нужна лицензия на платные функции; платные объявляют свои лицензионные требования. Каждый пакет должен соответствовать extension API ядра и пройти проверку подписи и целостности.
Установка и выполнение сторонних плагинов в этом выпуске недоступны. Можно вести список доверенных ключей авторов, но добавление ключа не включает установку плагинов. Интерфейс модулей не является песочницей для произвольного кода.
Установить пакет
Скопируйте файл пакета
arkvory-module-<id>-<version>.tgzна хост.Проверьте его и прочитайте условия:
bashsudo arkvory module install /root/arkvory-module-sample-1.0.0.tgz --root /opt/proanima-arkvoryКоманда показывает модуль, его роли, данные, которые он хранит, ключ подписи и SHA-256 пакета, а затем условия модуля. Пока ничего не меняется.
Установите его:
bashsudo arkvory module install /root/arkvory-module-sample-1.0.0.tgz --root /opt/proanima-arkvory --yes
Arkvory отклоняет пакет, если:
| Причина | Код в сообщении |
|---|---|
| Подпись сделана не ключом модулей ProAnimaStudio, или манифест изменён | unknown_key, wrong_key_class, signature_invalid |
| Файла нет, он изменён или не указан в манифесте | file_missing, file_mismatch, file_unlisted |
| В архиве есть ссылки, устройства, пути за пределами пакета или имена, различные лишь регистром | link_entry, special_entry, unsafe_path, case_collision |
В архиве есть нативное дополнение (.node) | native_addon |
| Модулю нужна другая версия Arkvory | module_incompatible |
| ProAnimaStudio отозвала эту версию | module_revoked и версия-замена |
| Нет действующего списка отзыва (см. ниже) | stale_revocations |
Ограничения: 1 ГиБ на пакет, 256 МиБ на файл, 4096 файлов. Пакет больше отклоняется до чтения его данных.
Версия, уже установленная с теми же байтами, остаётся как есть. Та же версия с другими байтами отклоняется.
Включить и загрузить модуль
Установленный модуль выключен, пока вы его не включите. Службы загружают модули только при запуске.
Добавьте модуль в файл модулей (
ARKVORY_MODULES_FILE, см. Переменные окружения). Настройки модуля указываются вconfig:json{ "format": 1, "modules": { "sample": { "enabled": true } } }Если модуль хранит файлы, утвердите размер его каталога данных в
resources, например"resources": { "dataMiB": 512, "dataFiles": 10000 }рядом сenabled. Этот размер заменяет тот, который запрашивает пакет. См. Каталог данных модуля.Перезапустите службы, как описано в разделе Применить изменение.
Проверьте модуль от имени глобального администратора:
GET /api/v1/system/modulesпоказывает его сrunning: trueиhealth.statusokв API и на каждом шлюзе чтения.
Подписанные модули выполняются в API, шлюзе чтения, worker и агенте резервного копирования согласно объявленным ролям. Каждый процесс выдаёт только службы своей роли, перечисленные модулем в uses. Маршруты требуют службу routes. В Docker Compose модули пока не загружаются.
Хранилища модулей регистрируются как <module>.<name> и участвуют в выборе хранилища новых загрузок. Если экземпляр перестаёт принимать записи, новые загрузки направляются в default. Ядро проверяет полные байты перед публикацией результата сборки из частей. Очистка данных модулей ждёт завершения активных чтений, снятия всех закреплений резервных копий и открытия барьера копирования. Вычисления выполняются в ограниченных потоках; подписки подтверждают события после успешного обработчика и могут повторить доставку после ошибки.
Прежде чем служба импортирует хоть какой-то код модуля, она снова проверяет пакет:
- Изменять каталог установки,
modules/, набор модулей, список отзыва и его каталог может только root (в Windows — SYSTEM и Administrators) или владелец каталога установки. Установка так и настраивает права. Файл, который может изменить другая учётная запись, и ссылка внутри пакета отклоняются (access_unsafe,access_link). - Подпись, каждый файл и версия Arkvory — так же, как их проверяет
module install. - Список отзыва. Отозванная версия никогда не загружается. Истёкший список или его отсутствие модуль не останавливают.
Модуль, который не прошёл проверку, не загружается; остальные модули и Arkvory продолжают работу. GET /api/v1/system/modules показывает его с running: false:
health.status | Значение | Коды |
|---|---|---|
failed | Пакет отклонён, или его код не загрузился или не запустился | file_mismatch, unknown_key, module_incompatible, access_unsafe, config_invalid, start_failed и другие |
revoked | ProAnimaStudio отозвала эту версию | причина из списка отзыва |
unavailable | Каталога пакета нет на хосте | module_unavailable |
Упавший модуль снимает Arkvory с готовности (/health/ready отвечает 503 с module_failed), только если он нужен другому включённому модулю. Модуль, который хранит байты опубликованных файлов (данные layout), не снимает никогда: Arkvory продолжает отдавать его данные и пишет новые загрузки в своё хранилище вместо хранилища модуля. Журнал записывает module.refused и module.failed с кодом в errorCode.
Чтобы восстановить изменённый или пропавший пакет, установите его заново. Все службы установки должны видеть одни и те же модули, включённые и выключенные: шлюз чтения или worker с другими модулями не готов (module_plan_mismatch). Установите те же пакеты на хосте каждого шлюза чтения.
Каталог данных модуля
Модуль, который хранит собственные индексы, кеши или состояние, получает каталог на томе данных: module-data/<id>/ в каталоге хранилища файлов default. Его часть data предназначена для резервного копирования, часть cache — нет. Arkvory учитывает каждую запись в утверждённом размере, в МиБ и в файлах, для обеих частей вместе. Запись сверх него отклоняется (module_quota_exceeded), а модуль продолжает работать. Без утверждённого размера модуль может только читать. Действует и резерв тома. На шлюзе чтения модуль читает те же файлы и не может их изменить.
Логическая копия читает байты опубликованных объектов через установленный модуль в роли backup; она не копирует каталог модуля, кеши и внутреннее состояние координации как образ файловой системы. Сохраняйте модули источника установленными и доступными для чтения до завершения копирования. Восстановление с --to-default-storage возвращает эти объекты как обычные blobs ядра без исходного модуля и платной лицензии; предусмотрите место под полный логический размер. Секреты установки сохраняйте отдельно; перед возобновлением платной записи выполните процедуру восстановления лицензии. Удаление модуля не удаляет каталог его данных; не удаляйте файлы, на которые ссылаются опубликованные объекты.
Перед переходом на extension API 0.7.0 остановите все старые процессы API и worker, записывающие данные модулей. Новые писатели используют общий учёт квоты через PostgreSQL coordinator установки; временные файлы тоже входят в квоту. Смешанная запись старыми и новыми процессами не поддерживается. После сбоя Arkvory при необходимости перестраивает учёт и удаляет временные каталоги нового протокола только после получения блокировки прежнего владельца в БД. Старые временные файлы автоматически не удаляются и продолжают занимать квоту; разбирайте их отдельно при остановленных писателях. Процессы backup имеют только доступ на чтение.
Маршруты модулей
Модуль может добавить маршруты HTTP под своим префиксом /api/ext/<id>/v<major>/, например /api/ext/sample/v1/. Arkvory проверяет каждый запрос до того, как выполнится код модуля:
| Проверка | Как для /api/v1 |
|---|---|
| Учётные данные | Те же ключи, сессии и токены; маршрут открыт любому вошедшему клиенту или только глобальному администратору |
| Права | Право, которое маршрут называет, на репозиторий из его пути, например content.read или upload.create: сервисному ключу нужно это право, учётной записи — право чтения или записи |
| Тело запроса | Предел размера маршрута, пределы загрузки, сроки и полоса сервера |
| Файлы | Выдаёт сам Arkvory: ETag, Range, If-Range, 304, очередь скачиваний и полоса скачивания |
Ошибки — в формате ошибок API. Модуль не видит учётных данных и других заголовков. Шлюз чтения обслуживает маршруты чтения модуля, а на остальные отвечает read_only.
Каждый модуль описывает свои маршруты документом OpenAPI, и Arkvory сверяет их при запуске модуля. Модуль, маршруты которого нарушают правила, не запускается и ничего не обслуживает; Arkvory продолжает работу. GET /api/v1/system/modules показывает его с running: false и health.status failed:
| Код | Значение |
|---|---|
routes_invalid | Маршрут нарушает правила, например путь вне префикса модуля или изменение, открытое любому вошедшему клиенту |
openapi_invalid | Документа OpenAPI нет или он неверен |
openapi_route_mismatch | У маршрута нет операции в документе или у операции нет маршрута |
transfer_invalid | Модуль предлагает протокол передачи, который ему предлагать нельзя |
Документы маршрутов:
| Адрес | Кто может читать | Содержимое |
|---|---|---|
GET /api/ext/openapi.json | Любой вошедший клиент | Маршруты всех модулей, которые выполняет эта служба, с операциями, доступными вызывающему |
GET /api/v1/system/modules/{id}/openapi | Глобальный администратор | Маршруты одного модуля |
/api/v1/openapi.json маршрутов модулей не перечисляет никогда. Модуль вида transfer может предложить другой способ передачи файлов: GET /api/v1/capabilities перечисляет его в transfer. Клиент пользуется им, только если у него есть подходящее расширение; иначе он передаёт файлы как обычно.
Обновить, закрепить, понизить версию
Установите файл новой версии с --yes. Предыдущий пакет остаётся на хосте до следующего изменения модулей.
| Задача | Команда |
|---|---|
| Оставить установленную версию | sudo arkvory module pin sample 1.0.0 --root … |
| Снова разрешить другие версии | sudo arkvory module pin sample --unpin --root … |
| Установить более старую версию | sudo arkvory module install <file> --downgrade --yes --root … |
Закреплённый модуль отклоняет любую другую версию, пока вы не снимете закрепление. Версия старше установленной или удалённой, пакет которой ещё лежит на хосте, требует --downgrade.
Проверить установленные модули
sudo arkvory module list --root /opt/proanima-arkvoryКоманда заново проверяет каждый установленный пакет так же, как это делают службы перед загрузкой: подпись, каждый файл и архив. У каждого модуля одно состояние:
| Состояние | Что значит |
|---|---|
ok | Пакет цел |
refused: <code> | Файл изменён, добавлен или заменён ссылкой (file_mismatch, file_unlisted, link_entry и другие) |
revoked (<reason>) | ProAnimaStudio отозвала эту версию. read path only значит, что её данные остаются доступными для чтения |
Отклонённый пакет никогда не используется. Чтобы восстановить его, установите файл пакета ещё раз.
Удалить модуль
sudo arkvory module remove sample --root /opt/proanima-arkvoryМодуль уходит из установки, а его пакет остаётся на хосте до следующего изменения модулей. Модуль, который хранит байты опубликованных файлов (данные layout), удалить нельзя: Arkvory отказывает с module_owns_data, чтобы его данные не стали нечитаемыми.
Список отзыва
ProAnimaStudio публикует подписанный список отозванных версий модулей. У каждого списка есть номер, и Arkvory никогда не принимает список с номером меньше, чем у сохранённого. Пакет модуля может нести более новый список: Arkvory сохраняет его при установке пакета. На хосте без доступа к хабу сохраните файл списка сами:
sudo arkvory module revocations /root/module-revocations.json --root /opt/proanima-arkvoryКаждый список подписан со сроком действия: по умолчанию 90 дней, не больше 180. module install и module pin <id> <version> требуют действующего списка; с истёкшим списком или без списка они отказывают с stale_revocations. Пакет, который несёт действующий список, тоже подходит. Чтобы продолжить всё равно, добавьте --allow-stale-revocations: Arkvory выведет предупреждение и запишет решение в modules/audit.jsonl. Истёкший список никогда не останавливает установленные модули: они продолжают работать, их данные остаются читаемыми; версию останавливает только запись об отзыве. Список с большим номером всегда заменяет сохранённый, даже если он уже истёк.
Когда ProAnimaStudio меняет ключ подписи модулей, один релиз содержит оба ключа, а следующий список подписывается новым ключом; старый ключ убирает только более поздний релиз. Обновление до этого релиза отклоняется, пока хост хранит список, подписанный старым ключом: сначала сохраните действующий список. sudo arkvory module check-revocations --root … показывает, доверяет ли этот релиз ключу сохранённого списка.
Доверять автору плагинов
Плагины вашей команды или другого автора подписаны ключом автора. Добавьте ключ в список доверия хоста до установки таких плагинов. Список доверия принадлежит хосту: службы читают его, но не могут изменить.
Получите у автора файл открытого ключа (
.pub, формат minisign), а его отпечаток — по другому каналу.Покажите ключ и сверьте отпечаток:
bashsudo arkvory module trust add /root/acme.pub --label "Acme platform team" --plugins "op-acme-*" --root /opt/proanima-arkvoryДобавьте его с
--yes.
| Параметр | Что значит |
|---|---|
--label | Чей это ключ; обязателен |
--plugins | Id плагинов, которые ключ может подписывать, через запятую: точный id или префикс с *. По умолчанию op-* |
--expires | Время UTC, например 2027-01-31T00:00:00Z. После него ключ не принимается для новых установок |
--allow-in-process | Разрешает плагинам этого ключа работать внутри процесса Arkvory. Такой код получает все права службы |
Id плагинов всегда начинаются с op-. Ключ плагинов никогда не подписывает модули ProAnimaStudio, а ключи ProAnimaStudio никогда не подписывают плагины op-. Ключ, который хост уже знает под другим id или как ключ другого вида, отклоняется (duplicate_key). Подписи должны быть с предварительным хешированием, как по умолчанию в текущих версиях minisign; старые подписи отклоняются с signature_algorithm.
sudo arkvory module trust list --root … показывает ключи, которым вы доверяете. sudo arkvory module trust remove <key id> --root … удаляет ключ.
Этот выпуск ведёт список доверия; плагины устанавливает следующий выпуск.
После прерывания
Каждое изменение набора модулей записывается в журнал обновлений. Если команда остановилась на полпути, следующая команда развёртывания отказывает с Interrupted deployment. Выполните sudo arkvory recover --root …: она вернёт прежний набор модулей. До этого отказывает каждая команда модулей, которая что-то меняет, включая module trust и module revocations.
Время жизни запроса модуля
Маршрут использует права вызывающего до конца ответа, включая поток. Отмена или завершение отзывают права и закрывают ресурсы чтения. Служба upload-read читает подтверждённые части незавершённой загрузки с проверкой владельца, upload.read, диапазона и отмены. Модуль может снять предложение передачи во время работы. Следующие запросы возможностей его не содержат; маршруты и начатые передачи сохраняются. Клиент может кешировать старое предложение, поэтому маршрут проверяет каждую операцию.
Восстановление производного кеша
Подписанные модули могут объявить derived-cache (extension API 0.9.0). API и worker строят и читают неизменяемые поколения, reader только читает; backup службу не получает. Права на источник проверяются при каждом запросе. Одобренный бюджет ресурсов модуля общий для legacy data/cache и удерживаемых поколений. Промах кеша требует повторного вычисления или fallback.
Потеря PostgreSQL-сессии не доказывает остановку файлового I/O. Reservations неопределённых owner и persisted reader references остаются учтёнными. Сначала примените миграции этой версии ядра. Перед recovery остановите все участвующие хосты и подтвердите завершение процессов и I/O либо докажите остановку точной инкарнации owner и невозможность её возобновления; недоступные хосты требуют fencing. Получите точный UUID owner из диагностики и запишите доказательство. PID, таймаут и отсутствие DB-lock недостаточны.
На доверенном хосте с настроенным ARKVORY_DATABASE_URL выполните команду ниже собранными пакетами этой версии ядра. Флаг подтверждает физическую остановку; активный owner lock всё равно запрещает recovery. Без подтверждения действий нет. Затем возобновите reconciliation и проверьте очистку: само подтверждение не освобождает квоту немедленно. Это обслуживание хоста, не право модуля или удалённого CLI.
node scripts/recover-derived-cache.mjs --owner UUID --confirm-owner-stoppedСлужебное состояние модуля
Extension API 0.10.0 добавляет ограниченный атомарный регистр для подписанных модулей. Он сохраняется при переключении HA, но не входит в переносимые логические копии. После restore выполните явную процедуру повторной инициализации модуля; чтение и восстановление объектов должны оставаться доступными. Регистр отделён от хранилища объектов и не сбрасывается переустановкой модуля.
Модуль передачи может временно снять свой протокол и восстановить его после успешной проверки политики без перезапуска Arkvory. Каждый запрос по-прежнему проверяется по текущей политике модуля.
API расширений 0.12.0 позволяет подписанному модулю хранилища задать лимит логических байтов. Ядро учитывает полные размеры объектов и принятых незавершённых загрузок во всех репозиториях, без скидки за дедупликацию. При исчерпании лимита новые загрузки идут в основное хранилище; принятые сохраняют назначение, объекты остаются доступны для чтения. Счётчик освобождается только после очистки.
Общий каталог ресурсов
Extension API 0.13.0 предоставляет подписанным модулям общий каталог ресурсов. Файлы защищены, пока на них ссылаются загрузки или зависимые ресурсы. Только очистка ядра освобождает владельцев-загрузки. Физическое удаление ждёт завершения чтения и резервного копирования; при ошибке зависимости сохраняются для повтора.
Перед первым обновлением модуля с этим каталогом остановите все старые процессы API и worker. Не смешивайте старых и новых писателей. После логического восстановления очистка закрыта до успешной проверки всех рецептов, файлов и зависимостей модулем. Восстановите отсутствующие или повреждённые данные до возобновления очистки.