Понятия

Инстанс

Одна установка xvii на одном домене. У него один сервер control plane (сервисы платформы, PostgreSQL, Caddy) и сколько угодно нод для приложений. Аккаунты людей существуют в рамках инстанса; у инстанса есть суперпользователи (администрируют его) и пользователи.

Команды

Всё принадлежит какой-то команде: деплои, приложения, секреты, мониторы, ключи. У каждого человека есть личная команда; общая работа идёт в командах с участниками:

Роль	Может
viewer	видеть ресурсы команды
developer	создавать, деплоить и менять их; читать и менять незащищённые окружения
admin	ещё защищённые окружения, участников, токены команды, настройки
owner	ещё удалить команду и менять владельцев

Участников приглашают по имени аккаунта или почте, а тех, у кого аккаунта ещё нет, — одноразовой ссылкой-приглашением.

Проекты и окружения

Проект объединяет то, что относится к одному делу, во всех сервисах: алиас pages, приложение, его базу и секреты, мониторы, проект в errors, сайт в analytics. У проекта есть окружения, для начала production и preview; можно добавить ещё. Окружение может быть защищённым: менять то, что в нём задеплоено или хранится, могут только администраторы.

инстанс
└── команда               участники с ролями, лимиты
    └── проект            общий для всех сервисов
        └── окружение     production, preview, …
            └── ресурс    деплой, приложение, набор секретов, монитор, …

home показывает проект по всем сервисам на одной странице.

Ключи доступа и вход

Паролей нет. Люди входят в id по ключам доступа (passkeys), и один ключ работает на весь инстанс. Панели перенаправляют в id; CLI использует код устройства, который вы подтверждаете в браузере. Потерянное устройство восстанавливают одноразовой ссылкой для входа от суперпользователя.

Токены

Для скриптов и CI есть API-токены (xv_…), личные или командные:

Scope	Позволяет
`read`	читать
`deploy`	читать и деплоить (деплои pages, релизы приложений)
`write`	всё, что может владелец

Токен можно ограничить отдельными сервисами и одним проектом; у него есть срок жизни (по умолчанию 90 дней).

xvii tokens create gitlab-ci --scope deploy --ttl 30d

Задачам CI в GitLab и GitHub хранимые токены вообще не нужны: правило доверия в проекте позволяет задаче обменять свой OIDC-токен на краткоживущий. См. Деплой из CI.

Лимиты и планы

Суперпользователи задают планы (наборы лимитов вроде pages.storage или apps.memory) и назначают их командам, с переопределениями для отдельных команд. Администраторы команды могут ограничить проект внутри лимитов команды. Сервисы говорят, какой лимит остановил действие: «план Free команды разрешает 100 деплоев». См. Лимиты.

Ноды

Серверы, на которых работают приложения. Агент ноды сам подключается к control plane, так что нода может стоять где угодно. Нода бывает нодой инстанса (общая для команд, с квотами памяти) или собственной нодой команды. Она обслуживает трафик своих приложений сама (edge) или через control plane (relay). См. Ноды.

События и активность

Каждое изменение через любой API записывается в журнал сервиса (кто, что, команда, IP) и уходит в notify как событие. home показывает активность всех сервисов; notify доставляет события, на которые люди подписались. См. События.