Основные понятия
На этой странице объясняются слова, которыми пользуются остальные страницы. Каждый раздел короткий и ведёт на страницу, где тема описана полностью. Краткие определения в одну строку собраны в Глоссарии.
Установка и её службы
Одна установка — это один сервер. На нём работают три службы Arkvory рядом с одной базой данных PostgreSQL:
| Компонент | Назначение |
|---|---|
| API | HTTP-сервер: HTTP API, веб-консоль и реестры контейнеров, Git LFS и npm. Также выполняет правила хранения и физическую очистку. |
| Обработчик (worker) | Фоновые задания: завершает большие загрузки и синхронизирует зеркала. |
| Агент резервного копирования | Резервное копирование по расписанию в хранилище копий. |
| PostgreSQL | Каталог: артефакты, пакеты, версии файлов, учётные записи, ключи и задания. |
Содержимое файлов хранится в локальном каталоге сервера, а не в базе данных. Все компоненты находятся в корне установки (C:\ProgramData\ProAnima\Arkvory в Windows, /opt/proanima-arkvory в Linux). Службы запускаются без вошедшего пользователя и перезапускаются после сбоя или зависания (Самовосстановление).
Установка на одном сервере не обеспечивает высокой доступности. Если сервер остановится, клиенты ждут, а затем продолжают передачи. См. Выбор установки. В Linux два или три сервера можно объединить в кластер высокой доступности.
Репозитории
Репозиторий — это именованное пространство для содержимого. У него свои правила доступа, своя политика хранения (квота и правила хранения) и, при необходимости, источник зеркала. Имя репозитория содержит от 1 до 64 символов: строчные латинские буквы, цифры, - и _; оно начинается с буквы или цифры.
Отдельной команды для создания репозитория нет. Репозиторий появляется, как только группе выдан доступ к его имени или политика сервисной учётной записи его называет. В новой установке уже есть место для первого репозитория — releases. См. Репозитории.
Артефакты
Артефакт — это один сохранённый файл. Он неизменяем: его байты никогда не меняются. У артефакта есть UUID, имя (до 240 символов, без / и \), размер и контрольная сумма SHA-256. Новое содержимое создаёт новый артефакт и никогда не заменяет старый.
Артефакт становится видимым, только когда сервер проверит, что байты совпадают с заявленными размером и SHA-256. Скачивание возвращает те же байты, а контрольная сумма служит строгим ETag. Всё остальное в Arkvory строится на артефактах: версия пакета, версия пути, слой контейнера и объект Git LFS — это артефакты.
Загрузки
Загрузка резервирует будущий артефакт. Вы создаёте сессию загрузки, указывая имя, размер и SHA-256 файла, а также Idempotency-Key, благодаря которому запрос можно безопасно повторять. Затем вы отправляете байты:
- одним запросом — для небольших и средних файлов; или
- частями — для больших файлов. Размер части выбирает сервер: не менее 8 МиБ, а для очень больших файлов он удваивается, чтобы загрузке никогда не требовалось больше 10 000 частей. Часть никогда не превышает 1 ГиБ. У каждой части своя SHA-256, а повторная отправка части безвредна.
Затем вы завершаете загрузку. Сервер проверяет файл целиком и публикует его. Для больших файлов загрузку завершает обработчик в задании завершения, за ходом которого следит клиент; SDK и клиент командной строки выбирают этот способ для файлов от 16 ГиБ. Сессия загрузки существует 7 дней. Прерванная загрузка продолжается с тех частей, которые уже есть на сервере. Наибольший объект — 10 000 ГиБ, если администратор не задал меньшее значение ARKVORY_MAX_OBJECT_BYTES.
Клиент командной строки и SDK делают всё это за вас. См. Передачи и справочник по загрузкам.
Пакеты
Пакет — это архив UPack, который зарегистрировал Arkvory. Его идентичность составляют группа, имя и версия SemVer, например acme / game-server / 1.4.2. Группа входит в идентичность: два пакета с одним именем в разных группах — разные пакеты. Опубликованная версия не меняется; повторная публикация той же версии с другим содержимым отклоняется.
Агент развёртывания запрашивает пакет по точной версии, по диапазону версий, например ^1.4, или по самой новой версии на стадии. Предварительные версии (pre-release) появляются, только если вы их запрашиваете. См. Пакеты.
Файлы по пути
Файл по пути имеет адрес вроде builds/game/1.4/Setup.exe и указывает на артефакт. Когда вы сохраняете по этому пути новые байты, путь получает новую версию (1, 2, 3 и так далее). Прежние версии остаются в истории, и любую из них можно восстановить: восстановление добавляет новую версию со старым содержимым. Повторное сохранение тех же байтов ничего не добавляет.
Путь содержит не более 1024 символов, использует / как разделитель, не содержит пустых сегментов, сегментов . и .., а также символа :. Изменение указывает версию, которую ожидает; если раньше прошло другое изменение, сервер отвечает 409. Для пути, которого ещё нет, укажите 0. См. Файлы по пути и Обычные файлы.
Метки, метаданные, коллекции и вложения
Артефакт можно описать, не трогая его байты:
| Элемент | Правило |
|---|---|
| Метки | До 32 коротких меток, например nightly или tested. |
| Метаданные | До 32 текстовых полей; ключ содержит до 64 символов, значение — до 1024. |
| Коллекции | Именованные наборы, которые группируют артефакты. |
| Вложения | До 32 ссылок из сборки на другие артефакты того же репозитория: манифест, SBOM, подпись, отчёт или любой другой файл. |
Метки, метаданные и коллекции меняются как один набор с версией. У вложений своя версия и своя история.
Стадии и продвижение
Стадия — это контролируемая отметка на сборке, например qa, release или prod. Имя стадии состоит из строчных букв, цифр, ., _ и - (до 32 символов), а у артефакта может быть до 16 стадий. Для изменения стадии нужно отдельное право artifact.promote, и каждое изменение записывается с указанием автора, времени и комментария.
Продвижение публикует сборку в другом репозитории без повторной отправки байтов. copy сохраняет источник; move (перенос) ещё и удаляет сборку из исходного репозитория. Повторное продвижение возвращает уже существующую копию. Поиск по стадии (resolve) находит сборку, на которую указывают стадия и диапазон версий. См. Продвижение.
Учётные записи, группы и права
Люди пользуются учётными записями. У учётной записи есть имя (от 3 до 64 символов) и пароль (от 12 до 128 символов). Учётная запись администратора управляет учётными записями и группами. Учётные записи входят в группы, а группе выдаётся доступ read или write («Чтение и запись») к репозиторию. Права пересчитываются при каждом запросе, поэтому изменение действует сразу.
Автоматизация использует вместо этого сервисную учётную запись. Её политика перечисляет точные действия для каждого репозитория, например upload.create или content.read, а её ключи могут только сужать эту политику. Сервер проверяет каждое действие; скрытая кнопка в консоли защитой не является. См. Учётные записи и доступ и Аутентификация.
Ключи и токены
Каждый запрос содержит учётные данные. Четыре вида вы создаёте сами, один встроен:
| Учётные данные | Для чего | Срок действия |
|---|---|---|
| Сессия консоли | Человек, вошедший по имени и паролю | 12 часов |
| Персональный токен доступа | Скрипты и инструменты одного человека | По умолчанию 90 дней, не более 365 |
| Ключ сервиса | CI/CD и агенты развёртывания | По умолчанию 90 дней, не более 365 |
| Ссылка на скачивание | Передача одного артефакта тому, у кого нет ключа | От 60 секунд до 24 часов (по умолчанию 1 час) |
| Ключ восстановления | Сама установка | Не истекает |
Ключ сервиса выпускается один раз, показывается один раз и становится пригодным к использованию только после активации. Его можно ротировать (выпустить новый, затем вывести из работы старый) и отозвать навсегда. См. Аутентификация.
Владелец и ключ восстановления
Владелец — это первая учётная запись. Он администратор и участник группы arkvory-owners, у которой есть доступ write к releases. Владельца создаёт установщик для Windows; в Linux и Docker вы создаёте его в консоли с помощью ключа восстановления.
Ключ восстановления — это секрет, который установщик записывает в config/bootstrap-token.txt в корне установки. Он может создать первого владельца и учётные записи, управлять сервисными учётными записями и их делегированием, запускать резервное копирование и запрашивать обновления. Средства установки читают его на сервере. Он не предназначен для CI и повседневной работы: храните его на сервере и не копируйте. См. Выбор установки и Безопасность.
Правила хранения, квоты и очистка
Политика хранения принадлежит репозиторию. Она может хранить последние N сборок каждого пакета (или каждого пакета и канала), защищать метки и стадии от удаления, выдерживать минимальный возраст перед удалением чего-либо и задавать квоту с предупреждающим и критическим порогами. Пока администратор её не включит, она выключена. Удаление артефакта сначала логическое: байты остаются на диске в течение защитного срока (по умолчанию 24 часа), а затем физическая очистка освобождает место в фоне, небольшими порциями, не останавливая сервер.
Сервер также оставляет резерв свободного места на диске (по умолчанию 1 ГиБ), который загрузки никогда не используют. См. Хранение.
Резервные копии
Агент резервного копирования копирует базу данных и всё опубликованное содержимое в хранилище копий — каталог на другом диске или в сетевой папке. Одна полная копия — это точка восстановления. Агент проверяет каждую точку, применяет к точкам правила хранения (по умолчанию 7 ежедневных, 4 еженедельных и 6 ежемесячных) и позволяет закрепить точку, чтобы правила хранения её сохранили. Ежедневное расписание выключено, пока администратор не включит его в Расписание и хранение.
Восстановление выполняется командой на сервере. Она записывает данные в пустую базу данных и пустой каталог хранилища. См. Резервные копии.
Зеркала и шлюзы чтения
Зеркало — это копия репозитория только для чтения, которую вторая установка поддерживает, следуя за первой, источником. Зеркало отклоняет изменения и отдаёт скачивания. Если источник потерян, оператор отсоединяет зеркало, и оно становится обычным репозиторием; переключение выполняется вручную и не является автоматическим переключением на зеркало (failover). См. Зеркала.
Шлюз чтения — это дополнительный процесс API на том же хранилище, который отвечает только на GET и HEAD. Узел записи и шлюзы делят общий бюджет пропускной способности для скачиваний. См. Шлюзы чтения.
Что читать дальше
- Быстрый старт: установите Arkvory и загрузите первый файл.
- Учётные записи и доступ: люди, группы, токены и ключи сервиса.
- Обзор API: правила, которые нужны любой интеграции.
- Глоссарий: краткие определения всех терминов.