Учётные записи и доступ

В Arkvory есть четыре вида учётных данных. Люди входят по паролю. Их собственные инструменты используют персональные токены доступа. Системы CI и агенты развёртывания используют ключи сервиса. Программа установки создаёт ещё один ключ — ключ восстановления — для настройки и аварийных случаев. Сервер проверяет каждый запрос по тем учётным данным, с которыми он пришёл.

Кто что может

Учётные данные	Кто создаёт	Срок действия	Администрирование	Доступ к репозиториям
Сессия по паролю	Вход	12 часов	Пользователи и группы, если учётная запись — администратор	Чтение или запись по каждому репозиторию — через группы
Персональный токен доступа	Вы, из сессии по паролю	По умолчанию 90 дней, не более 365	Никогда	Ваши группы, при желании только чтение
Ключ сервиса	Ключ восстановления или оператор с делегированными правами	По умолчанию 90 дней, не более 365	Только то, что делегировал владелец	Политика сервисной учётной записи, суженная ключом
Ключ восстановления	Программа установки	Пока вы его не замените	Пользователи, группы, сервисные учётные записи, резервные копии	Чтение и запись в releases

Три момента легко упустить:

• Учётная запись администратора управляет пользователями и группами. Она не даёт доступа к файлам. К файлам доступ только через права групп.
• Ключ сервиса создаёт ключ восстановления или ключ оператора, а не сессия по паролю. Администратор, вошедший по паролю, не может создавать сервисные учётные записи.
• Персональный токен или ключ сервиса никогда не могут создавать пользователей, группы и другие токены.

Владелец и ключ восстановления

Первая учётная запись — владелец. Он администратор. В Windows его создаёт мастер установки. В Linux и Docker вы создаёте его в консоли с помощью ключа восстановления, как описано в разделе Веб-консоль.

Владелец входит в группу arkvory-owners, у которой есть доступ на запись в репозиторий releases. Для любого другого репозитория выдайте группе доступ сами. См. Группы и доступ к репозиториям.

Ключ восстановления — это файл config/bootstrap-token.txt в каталоге установки. Прочитать его может только администратор сервера. Не копируйте его в CI и на клиентские компьютеры. Его читают средства установки и обновления, поэтому не удаляйте его. См. Безопасность.

Создание пользователей

Пользователей создают только администраторы. Имя состоит из 3–64 символов: букв, цифр, ., _ или -. Пароль содержит от 12 до 128 символов. В одной установке может быть не больше 1000 учётных записей.

В консоли:

1. Войдите как администратор и откройте раздел Пользователи и доступ.
2. Разверните Создать пользователя.
3. Введите Имя пользователя и Пароль. Отметьте Администратор только для тех, кто управляет пользователями.
4. Нажмите Создать пользователя.

В таблице Учётные записи перечислены учётные записи. Кнопка Отключить блокирует учётную запись: её сессии сразу завершаются, а персональные токены перестают работать, пока вы не нажмёте Включить. Чтобы задать пользователю новый пароль, разверните Сменить пароль. Это завершает сессии учётной записи и отзывает все её персональные токены.

В API эти операции вызывает сессия администратора или ключ восстановления: createUser, updateUser и listUsers.

curl -X POST "$ARKVORY/api/v1/users" \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"anna","password":"a long password here","administrator":false}'

await client.administration.users.create('anna', 'a long password here', false);

У arkvoryctl нет команд для учётных записей. Используйте консоль или API.

Самостоятельная регистрация по умолчанию выключена. Администратор сервера включает её переменной ARKVORY_ALLOW_REGISTRATION=true (см. Переменные окружения). После этого на карточке входа появляется Регистрация. У новой учётной записи нет доступа ни к одному репозиторию, пока администратор не добавит её в группу. Самостоятельная регистрация прекращается на 900 учётных записях, поэтому 100 мест остаются для администраторов.

Группы и доступ к репозиториям

Люди получают доступ через группы. У группы есть участники и для каждого репозитория один уровень доступа:

Уровень в консоли	Значение
Чтение	Просмотр и скачивание
Чтение и запись	Всё, что даёт чтение, а также загрузка, публикация, изменение метаданных, продвижение и восстановление

У репозитория нет отдельного шага создания. Он появляется, как только его имя указано в выданном доступе или в политике сервисной учётной записи. Имя состоит из строчных латинских букв, цифр, - и _, начинается с буквы или цифры и содержит не больше 64 символов. См. Репозитории.

В консоли откройте Пользователи и доступ:

1. Разверните Создать группу, введите имя в поле Группа доступа (от 2 до 64 букв, цифр, ., _ или -) и нажмите Создать группу.
2. Разверните Участники групп, выберите группу и учётную запись, затем нажмите Добавить в группу. Кнопка Убрать из группы убирает учётную запись из группы.
3. Разверните Доступ к репозиториям, выберите группу, введите имя в поле Репозиторий, выберите уровень в поле Доступ и нажмите Сохранить доступ. Кнопка Убрать доступ отнимает доступ.

Таблица под формами показывает для каждой группы списки Участники и Права. Удаление участника или права действует со следующего запроса учётной записи. Файлы остаются на месте.

В одной установке может быть не больше 100 групп, 10 000 членств и 10 000 прав доступа.

В API это операции createAccessGroup, addGroupMember, removeGroupMember, setGroupGrant и removeGroupGrant:

curl -X PUT "$ARKVORY/api/v1/access-groups/$GROUP_ID/grants/builds" \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"access":"write"}'

await client.administration.groups.setGrant(groupId, 'builds', 'write');

Права

За двумя уровнями — чтением и записью — стоят 24 действия над репозиторием. Ключ сервиса называет эти действия по одному. arkvoryctl doctor и GET /api/v1/auth/permissions показывают действия, которые есть у текущих учётных данных, по каждому репозиторию.

Действие	Название в консоли	Что разрешает
repository.read	Просмотр репозиториев	Список репозиториев и просмотр собственных прав. Доступа к файлам нет.
artifact.list	Список артефактов	Список и поиск артефактов, чтение списка стадий и журнала продвижения
artifact.read	Просмотр артефактов	Сведения об одном артефакте, его стадии и история продвижения
content.read	Скачивание файлов	Скачивание байтов, создание ссылок на скачивание, поиск пакета для скачивания
upload.create	Создание загрузок	Начало загрузки
upload.read	Просмотр загрузок	Чтение состояния и частей собственной загрузки
upload.write	Передача данных	Передача байтов собственной загрузки
upload.complete	Завершение загрузок	Завершение собственной загрузки, запуск задания завершения
upload.cancel	Отмена загрузок	Отмена собственной загрузки
job.read	Просмотр заданий	Чтение собственного задания завершения
package.read	Просмотр пакетов	Список пакетов UPack и поиск версии
package.publish	Публикация пакетов	Регистрация загруженного архива как пакета
asset.read	Просмотр файловых ссылок	Чтение путей к файлам, их истории и версий
asset.write	Назначение файловых ссылок	Назначение артефакта текущим содержимым пути
asset.restore	Восстановление файлов	Восстановление прежней версии пути
annotation.read	Просмотр метаданных	Чтение меток, метаданных, коллекций и вложений
annotation.write	Изменение метаданных	Изменение меток, метаданных, коллекций и вложений
artifact.promote	Продвижение артефактов и стадии	Добавление и удаление стадий, продвижение в репозиторий
reference.write	Управление связями	Добавление и удаление собственной внешней ссылки на артефакт
audit.read	Просмотр аудита	Чтение аудита каталога репозитория
artifact.delete	Удаление артефактов	Проверка и удаление артефактов, предварительный просмотр и применение правил хранения
storage.read	Просмотр политики и объёма	Чтение политики хранения, занятого объёма и настроек очистки
storage.manage	Настройка хранения	Изменение политики хранения и настроек очистки, их запуск
diagnostics.read	Просмотр диагностики	Чтение событий хранилища

Как уровни группы соответствуют действиям:

• Чтение даёт repository.read, artifact.list, artifact.read, content.read, package.read, asset.read и annotation.read.
• Запись даёт всё, что даёт чтение, а также upload.create, upload.read, upload.write, upload.complete, upload.cancel, job.read, package.publish, asset.write, asset.restore, annotation.write, artifact.promote, reference.write и audit.read.
• Ни один уровень группы не даёт artifact.delete, storage.read, storage.manage и diagnostics.read. Удаление артефактов и управление хранилищем доступны ключам сервиса, в которых эти действия названы явно. См. Хранение.

Зеркало — это копия другого репозитория только для чтения (Зеркала). Любое действие, которое его изменяет, отклоняется с ошибкой 409 mirror_read_only, какие бы права ни были выданы.

Пароли и сессии

Чтобы войти, заполните поля Имя пользователя и Пароль на карточке Подключение к репозиторию. Сессия длится 12 часов. Кнопка Отключиться завершает её.

Чтобы сменить свой пароль, используйте Сменить свой пароль на той же карточке. Введите Текущий пароль и Новый пароль. Все ваши сессии и персональные токены прекращают действовать, поэтому вам придётся войти снова и создать новые токены. Администратор может сбросить пароль другой учётной записи, не зная старого.

Сервер замедляет подбор паролей:

• С одного сетевого адреса можно сделать 10 попыток входа подряд, затем ещё по одной каждые 15 секунд.
• После многих неверных паролей для одной учётной записи она ждёт всё дольше — до 2 минут. В это время отказ получает даже правильный пароль. Ответ — 429 rate_limited с заголовком Retry-After.
• За обратным прокси-сервером администратор указывает прокси в ARKVORY_TRUSTED_PROXIES. Иначе у всех людей будет один общий адрес.

В API операция login обменивает имя и пароль на bearer-сессию, а changeOwnPassword меняет пароль:

curl -X POST "$ARKVORY/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"name":"anna","password":"a long password here"}'

Персональные токены доступа

Персональный токен доступа — это ключ для ваших собственных инструментов: скрипта на вашем компьютере, arkvoryctl или SDK. Он действует от вашего имени и с теми репозиториями, которые доступны вашим группам.

Токены создаёт только сессия по паролю. Токен не может создать другой токен и не имеет прав администратора.

1. Войдите с паролем.
2. На карточке Подключение к репозиторию разверните Персональные токены доступа.
3. Введите Название токена. Выберите Срок действия: 30 дней, 90 дней или 365 дней.
4. Выберите Доступ: Только чтение или Чтение и запись. Токен только для чтения отклоняет любое изменение с ошибкой 403 read_only_token.
5. Нажмите Создать токен, затем Скопировать токен. Токен показывается один раз. Он начинается с pat_.

В таблице для каждого токена указаны Префикс, Создан, Истекает, Использован и Состояние: Активен, Истёк или Отозван. Чтобы остановить токен, нажмите Отозвать токен и подтвердите кнопкой Отозвать. Клиенты, которые его используют, сразу теряют доступ.

У учётной записи может быть до 50 активных токенов. Администратор может просмотреть и отозвать токены любой учётной записи операциями listAccountTokens и revokeAccountToken.

В API у токена есть имя и, по желанию, срок действия (не более 365 дней от текущего момента) и область действия scope:

curl -X POST "$ARKVORY/api/v1/auth/tokens" \
  -H "Authorization: Bearer $SESSION" \
  -H "Content-Type: application/json" \
  -d '{"name":"laptop","scope":"read-write","expiresAt":"2027-01-31T00:00:00Z"}'

const created = await client.identity.createToken('laptop', { scope: 'read-write' });
console.log(created.token); // shown once

Значение scope по умолчанию в API — read-write. Консоль заранее выбирает Только чтение.

Передайте токен в arkvoryctl через закрытый файл. См. Командная строка.

Сервисные учётные записи и ключи для CI

Сервисная учётная запись — это идентичность инструмента, а не человека. У неё есть политика: репозитории и действия, которые ей разрешены. У сервисной учётной записи есть ключи. У ключа тоже есть свой список репозиториев и действий. Действующие права — это пересечение двух списков, по каждому действию отдельно. Пустая политика не даёт доступа к файлам.

Сервисным доступом управляют с помощью ключа восстановления или ключа оператора, которому владелец делегировал права. В консоли:

1. Нажмите Отключиться, если вы вошли. Затем откройте Подключиться ключом сервиса или автоматизации, вставьте ключ восстановления в поле Ключ сервиса и нажмите Подключиться.
2. Откройте раздел Сервисный доступ. Он виден только для ключа восстановления и ключей операторов.

Создание учётной записи и политики

1. В разделе Сервисный доступ разверните Создать сервисный аккаунт.
2. Введите Имя аккаунта (от 3 до 64 букв, цифр, ., _ или -).
3. В блоке Права на репозитории нажмите Добавить репозиторий и введите имя в поле Репозиторий.
4. Заполните права. Кнопки Набор для чтения и Набор для публикации задают типовые наборы, Снять права снимает их, а в списке Отдельные права перечислены все действия. Нажмите Убрать репозиторий, чтобы убрать репозиторий.
5. Нажмите Создать сервисный аккаунт.

Два типовых набора:

Набор	Действия
Набор для чтения	repository.read, artifact.read, artifact.list, content.read, package.read, asset.read, annotation.read
Набор для публикации	Набор для чтения, а также upload.create, upload.read, upload.write, upload.complete, upload.cancel, job.read, package.publish, asset.write, annotation.write

Ни один набор не включает продвижение, восстановление и удаление. Для задания продвижения добавьте artifact.promote. Агенту развёртывания, который только скачивает, для arkvoryctl нужен набор для чтения. Для обычного HTTP-скачивания пакета по имени достаточно одного content.read.

В политике может быть не больше 64 репозиториев, а в установке — не больше 1000 сервисных учётных записей. У сохранённой политики есть версия. Если за это время её изменил кто-то другой, консоль показывает конфликт и сохраняет ваш черновик: нажмите Обновить аккаунт и примените изменение снова. Кнопка Отключить аккаунт блокирует все ключи учётной записи. Передачи, которые уже идут, могут завершиться.

Выпуск, сохранение и активация ключа

1. Откройте учётную запись и её раздел Сервисные ключи.
2. Разверните Выпустить ключ. Введите Имя ключа. Задайте срок в поле Срок действия (местное время, необязательно) или оставьте его пустым — тогда ключ действует 90 дней. Максимальный срок — 365 дней.
3. Сузьте права, если ключу нужно меньше, чем учётной записи. Нажмите Выпустить ключ.
4. Окно Сохраните новый секрет показывает секрет один раз. Нажмите Скопировать секрет и сохраните секрет в хранилище секретов вашей системы CI. Секрет начинается с arkvory_.
5. Отметьте Секрет сохранён и нажмите Активировать ключ.

Неактивированный ключ бесполезен и истекает через 15 минут. Пока вы его не активируете, он отображается как Ожидает активации. У учётной записи может быть одновременно 3 активных ключа и 2 ожидающих. Состояния ключа: Ожидает активации, Активен, Отозван и Истёк. В разделе Сведения о ключе указаны id и права ключа.

Если ответ потерян до того, как вы скопировали секрет, сервер не покажет его снова. Отзовите ключ и выпустите другой.

В API ключ восстановления сначала создаёт учётную запись, затем выпускает ключ. Заголовок Idempotency-Key (от 1 до 128 букв, цифр, ., _, : или -) делает повторный запрос безопасным, но повтор не возвращает секрет. Ключ активирует себя сам, вызвав activateServiceKey:

curl -X POST "$ARKVORY/api/v1/service-accounts" \
  -H "Authorization: Bearer $RECOVERY_KEY" -H "Content-Type: application/json" \
  -d '{"name":"ci-prod","bindings":[{"resource":{"kind":"repository","id":"releases"},"actions":["repository.read","artifact.read","artifact.list","content.read","package.read","upload.create","upload.read","upload.write","upload.complete","job.read","package.publish","asset.read","asset.write"]}]}'

curl -X POST "$ARKVORY/api/v1/service-accounts/$ACCOUNT_ID/keys" \
  -H "Authorization: Bearer $RECOVERY_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: ci-prod-2026-10" \
  -d '{"name":"pipeline-2026","bindings":[{"resource":{"kind":"repository","id":"releases"},"actions":["content.read","package.read","artifact.read"]}]}'

curl -X POST "$ARKVORY/api/v1/auth/activate-key" -H "Authorization: Bearer $NEW_SECRET"

Те же шаги в SDK:

const account = await root.administration.services.create('ci-prod', bindings);
const issued = await root.administration.credentials.issue(account.id, requestId, {
  name: 'pipeline-2026',
  bindings,
});
if (!issued.secret) throw new Error('Lost response: revoke the key and issue another');
await saveToSecretStore(issued.secret);
await new ArkvoryClient(url, () => issued.secret ?? '').identity.activateKey();

Передайте активированный ключ заданию через ARKVORY_TOKEN_FILE или ARKVORY_TOKEN. См. пример для CI.

Ротация и отзыв

Ротируйте ключ до истечения срока, без перерыва в работе:

1. Рядом с ключом нажмите Ротировать. Форма заполнена правами старого ключа. Их можно только сохранить или сократить.
2. Выпустите новый ключ, сохраните его секрет и активируйте его.
3. Переключите задания на новый секрет.
4. Нажмите Отозвать у старого ключа.

Активация нового ключа ограничивает срок старого ещё не более чем 24 часами, чтобы забытый старый ключ не остался в силе. Отзыв необратим и требует ввести имя ключа. Новые запросы с этим ключом отклоняются сразу. Передачи, которые уже идут, могут завершиться. В API это операции rotateServiceKey и revokeServiceKey.

Кнопка Журнал действий у учётной записи показывает, кто и когда выпускал, активировал, ротировал и отзывал ключи. Секретов в нём нет. Сервер хранит последние 100 000 событий по всем учётным записям.

Делегированное администрирование

В повседневной работе не используйте ключ восстановления. Владелец может передать часть управления сервисами ключу оператора, а ключ восстановления держать вне сети.

1. С помощью ключа восстановления создайте для оператора сервисную учётную запись с пустой политикой, выпустите для неё ключ и активируйте его.
2. Откройте Сервисные ключи этой учётной записи и нажмите Делегирование управления у ключа.
3. Разверните Новое делегирование. Введите ID целевого аккаунта — учётную запись, которой будет управлять оператор.
4. Отметьте Административные действия и задайте Предельные права на репозитории — потолок, то есть максимум, который оператор может выдать в репозиториях.
5. Нажмите Сохранить делегирование.

Семь действий:

Действие	Название в консоли	Оператор может
service-account.read	Просмотр аккаунтов	Видеть учётную запись
service-account.manage	Включение и отключение аккаунтов	Включать и отключать её
policy.read	Просмотр политик	Читать её политику
policy.manage	Изменение политик	Заменять её политику
credential.read	Просмотр ключей	Просматривать список её ключей
credential.manage	Выпуск, ротация и отзыв ключей	Выпускать, ротировать и отзывать её ключи
service-audit.read	Просмотр журнала сервиса	Читать её журнал действий

Правила:

• Всё, что задаёт оператор, не должно выходить за потолок. Выпущенный им ключ истекает не позже его собственного ключа.
• Оператор может выпускать ключи для целевой учётной записи, поэтому относитесь к делегированию как к доверию ко всему, что разрешает потолок.
• Оператор не может управлять собственной учётной записью и не может делегировать дальше. Учётная запись не может быть одновременно целью и оператором.
• Снятие делегирования кнопкой Снять делегирование не отзывает ключи, которые оператор уже активировал. Отзовите их сами.
• Оператор видит свои назначения в разделе Мои права управления.

Делегирование задаёт только ключ восстановления. Операции API: listServiceDelegations, setServiceDelegation и removeServiceDelegation.

Аудит

Администраторы могут читать журнал безопасности установки: входы и неудачные попытки, регистрации, смену и сброс паролей, изменения пользователей, групп и прав, создание и отзыв токенов. В каждой записи указаны время, субъект, вид учётных данных, адрес клиента, цель и результат (success, failure или denied). Паролей и секретов в журнале нет. Сервер хранит записи 365 дней или до 1 000 000 записей — в зависимости от того, что наступит раньше.

В консоли для этого журнала нет экрана. Читайте его через API с сессией администратора или ключом восстановления. На странице по умолчанию 50 записей, не больше 100; сначала идут новые. Передайте значение next как after, чтобы получить следующую страницу.

curl -H "Authorization: Bearer $ADMIN_KEY" "$ARKVORY/api/v1/security/audit?limit=20"

const page = await client.administration.security.audit({ limit: 20 });

Журнал действий сервисной учётной записи ведётся отдельно. См. Выпуск, сохранение и активация ключа.

Если владелец потерял доступ

Если никто не может войти как администратор, воспользуйтесь ключом восстановления:

1. Прочитайте ключ на сервере: config/bootstrap-token.txt в каталоге установки. Это может сделать только администратор сервера.
2. В консоли откройте Подключиться ключом сервиса или автоматизации, вставьте ключ в поле Ключ сервиса и нажмите Подключиться.
3. Откройте Пользователи и доступ. Разверните Сменить пароль, выберите учётную запись, введите Новый пароль и нажмите Сменить пароль. Если учётная запись отображается как отключённая, нажмите Включить.
4. Войдите с новым паролем.

Можно также создать нового администратора кнопкой Создать пользователя, отметив Администратор.

Форма Создать первого владельца работает только пока в установке нет учётных записей. Позже используйте ключ восстановления, чтобы чинить учётные записи, а не начинать заново.

Если сам ключ восстановления потерян, администратор сервера заменяет SHA-256 ключа в config/keys.json и перезапускает API. См. Безопасность.

Связанные страницы

• Веб-консоль
• Репозитории
• Командная строка (arkvoryctl)
• Аутентификация и справочник API: Учётные записи и вход, Сервисные учётные записи и ключи
• Безопасность