Клиенты и протоколы
У Arkvory одно хранилище и одна модель доступа, но к ним ведут несколько путей. Каждый путь — это клиент или протокол, который инструмент уже знает. Все они сохраняют данные как артефакты Arkvory. Поэтому одни и те же права, квоты, проверки SHA-256, правила хранения, резервные копии и зеркала действуют независимо от того, каким путём вы пользуетесь.
На этой странице перечислены все способы работы с Arkvory, их назначение и принимаемые ими учётные данные. Используйте её, чтобы выбрать подходящий инструмент для задачи.
Обзор
| Способ | Адрес | Для чего | Учётные данные |
|---|---|---|---|
| Веб-консоль | https://arkvory.example/console/ | Просмотр репозиториев, загрузка и скачивание в браузере, управление пользователями, ключами и резервными копиями | Вход по имени пользователя и паролю или ключом сервиса |
Командная строка arkvoryctl | /api/v1 | Скрипты CI, возобновляемые загрузки и скачивания, файлы по пути, продвижение, резервные копии | Ключ из файла или переменной окружения (передаётся как Bearer) |
| TypeScript SDK | /api/v1 | Собственные инструменты на TypeScript или JavaScript в Node.js или браузере | Ключ из функции обратного вызова (передаётся как Bearer) |
| REST API | /api/v1/... | Интеграции на любом языке | Только Authorization: Bearer <ключ> |
| Реестр контейнеров (OCI) | /v2/ | Docker, Podman, Buildx, containerd, чарты Helm, артефакты ORAS | Basic, где ключ служит паролем (docker login), или Bearer |
| Git LFS | /lfs/<репозиторий> | Большие файлы репозитория git, блокировка файлов для Unity и Unreal | Basic, где ключ служит паролем (помощник учётных данных git), или Bearer |
| Реестр npm | /npm/<репозиторий>/ | Реестры с областью действия (scoped registries) в Unity Package Manager, npm publish и npm install | Bearer (_authToken в .npmrc, token в .upmconfig.toml) или Basic _auth |
| Обычные файлы по пути | /api/v1/repositories/<репозиторий>/raw/<путь> | Один запрос через curl -T или PowerShell | Только Authorization: Bearer <ключ> |
| Вебхуки | URL вашего получателя | Запуск развёртывания или задания при изменении репозитория | HMAC-подпись каждого запроса |
Маршруты под /v2, /lfs и /npm следуют спецификациям своих протоколов. Они не входят в документ OpenAPI для /api/v1 и сообщают об ошибках в формате, которого ждут их клиенты.
Учётные данные
Каждый запрос требует учётных данных, кроме публичных проверок работоспособности. Arkvory принимает такие виды:
| Вид | Как выглядит | Откуда берётся | Типичное применение |
|---|---|---|---|
| Персональный токен доступа | pat_... | Создаётся пользователем в консоли. Область read или read-write. Истекает (по умолчанию через 90 дней, не более чем через 365). | Разработчики: Unity, git, Docker на рабочей станции |
| Ключ сервиса | arkvory_... | Выдаётся для сервисной учётной записи, с точным перечнем действий для каждого репозитория, ключом восстановления или делегированным ключом оператора | CI/CD, агенты развёртывания, серверы сборки |
| Файловый ключ | любой секрет | Файл ключей сервера (ARKVORY_KEYS_FILE), с правом read или write на репозиторий; ключ владельца также администрирует | Владелец установки, прежние интеграции |
| Сессия | dps_... | Вход в консоль; действует 12 часов | Интерактивная работа в консоли |
| Ссылка на скачивание | URL с ?token= | Создаётся для одного артефакта; от 60 секунд до 24 часов | Передача одного файла тому, у кого нет ключа |
Протоколы различаются только тем, как передают ключ:
/api/v1, CLI, SDK и обычные файлы используютAuthorization: Bearer <ключ>./v2,/lfsи/npmпринимают также HTTP Basic. Имя пользователя не проверяется. Паролем служит ключ Arkvory. Именно так передают учётные данныеdocker login, помощники учётных данных git и_authв npm.- Персональный токен только для чтения никогда не меняет данные. Он всё равно может скачивать объекты Git LFS, потому что пакетный запрос (batch) Git LFS для скачивания — тоже
POST.
Как создать токены и ключи: Учётные записи и ключи. Подробности о заголовках: Аутентификация.
Какой способ выбрать
| Задача | Рекомендуемый способ |
|---|---|
| Загрузить артефакт сборки из CI и продолжить загрузку после сбоя сети | arkvoryctl upload или arkvoryctl put |
| Опубликовать пакет UPack из CI | arkvoryctl packages publish |
| Развернуть на сервере «самый новый релиз 1.4» | arkvoryctl packages download --range ^1.4 --stage release |
| Поместить небольшой или средний файл по пути из shell-скрипта, ничего не устанавливая | Обычные файлы через curl -T или PowerShell |
| Хранить образы контейнеров или чарты Helm | Образы контейнеров |
| Хранить текстуры, модели и уровни игры вне хоста git | Git LFS |
| Делиться пакетами Unity между проектами | Пакеты Unity и npm |
| Создать собственный инструмент или веб-интерфейс | TypeScript SDK |
| Интегрироваться из Python, Go, C# или другого языка | REST API |
| Осмотреться, управлять пользователями, ключами и резервными копиями | Веб-консоль |
Практические правила:
- Большие файлы (много гигабайт): используйте
arkvoryctlили SDK. Они загружают файл по частям и продолжают после прерывания. Один запросPUT(обычные файлы, объекты Git LFS, публикация npm, слой Docker) после сбоя начинается заново с нулевого байта. - Инструмент уже знает протокол: используйте этот протокол. Docker, git и Unity не требуют дополнительного ПО.
- Машина только читает: дайте ей токен только для чтения или ключ сервиса с действиями только на чтение.
Общие правила
HTTPS. Используйте HTTPS для каждого клиента. CLI и SDK отказываются работать по обычному HTTP, кроме loopback-адресов (localhost, 127.0.0.1, [::1]). Docker требует доверенного сертификата. Git отправляет ключ с каждым запросом. См. HTTPS.
Одно хранилище. Слой образа, объект Git LFS, архив npm и обычный файл — всё это артефакты. Они учитываются в квотах репозиториев и в ёмкости установки. При сохранении их проверяют по SHA-256. Они входят в резервные копии.
Шлюзы чтения и зеркала. Шлюз чтения принимает только GET и HEAD. Зеркало — это копия репозитория только для чтения в другой установке.
| Способ | На шлюзе чтения | На зеркале |
|---|---|---|
/api/v1, CLI, SDK | Только чтение | Чтение; изменения отклоняются (409 mirror_read_only) |
| Реестр контейнеров | Pull | Pull; push отклоняется |
| Git LFS | Не поддерживается (пакетный запрос — это POST) | Clone и fetch; push и блокировки отклоняются |
| Реестр npm | Установка и поиск | Установка и поиск; публикация отклоняется |
| Обычные файлы | GET и HEAD | GET и HEAD |
См. Шлюзы чтения и Зеркала.