Управление ключами API

GPUStack поддерживает аутентификацию с использованием ключей API. Каждый пользователь GPUStack может создавать свои собственные ключи API и управлять ими.

Создать ключ API

Перейдите на страницу Access Control > API Keys.
Нажмите кнопку Add API Key.
Заполните Name, Description и выберите Expiration ключа API.
Выберите Type ключа API:

Сгенерировано автоматически: GPUStack генерирует для вас ключ API.
Пользовательский: укажите собственное значение ключа в поле Key. Это поле является обязательным при выборе Пользовательский. Выберите значение с надежностью пароля, который вам никогда не придется запоминать — см. примечание ниже.

В разделе Access Permissions выберите разрешения для ключа API:

Управление платформой: предоставляет доступ к конечным точкам управления платформой (пользователям, моделям, воркерам и т. д.).
Доступ к модели: Предоставляет доступ к API инференса. При выборе выберите All models или Allowed models, а при выборе Allowed models выберите из списка, к каким моделям этот ключ API может получить доступ.

Если разрешение не выбрано, ключ API не имеет прав доступа. 6. Нажмите кнопку Save. 7. Скопируйте и сохраните ключ в безопасном месте, затем нажмите кнопку Done.

Примечание

Полное значение ключа API отображается только один раз при создании; после этого отображается только замаскированное значение. Пользовательские ключи являются исключением: вы уже знаете их значение.

Пользовательские ключи несут в себе силу, которую вы им придаете.

GPUStack принимает любую строку в качестве пользовательского ключа и не может отличить случайную строку от 123456. Автоматически сгенерированные ключи имеют длину 128 бит из криптографического случайного источника, и ничего более слабого никогда не создается случайно.

Эта разница выходит за рамки очевидных догадок: для аутентификации ключей на шлюзе API, а не на сервере, GPUStack публикует быстрый хеш каждого ключа в конфигурации шлюза, который виден любому, кто может его прочитать, и перемещается в диагностических пакетах. Для пользовательского ключа этот хеш не содержит соли и не зависит ни от чего, кроме секрета, поэтому он имеет одно и то же значение в каждом развертывании — предварительно вычисленная таблица, созданная один раз, работает против всех из них. Случайный ключ не затрагивается, поскольку его поиск в любом случае невозможен, в то время как угадываемый ключ становится дешевым для восстановления в автономном режиме.

По возможности создавайте пользовательские ключи криптографически случайным способом. Если их выбирают вручную, задайте GPUSTACK_GATEWAY_AUTH_ALLOW_CUSTOM_KEYS=false. Тогда каждый запрос с пользовательским ключом, как и раньше, аутентифицируется на сервере, а хэш ключа не публикуется. Шлюзу передаются только идентификатор ключа, факт его существования и срок действия — благодаря этому ключ можно отозвать, даже когда сервер недоступен.

Этот параметр применяется к уже существующим ключам, а не только к новым: его отключение приводит к удалению хэшей пользовательских ключей, созданных во время его включения, при следующем согласовании.

Редактировать права доступа

Перейдите на страницу Access Control > API Keys.
Найдите ключ API, который вы хотите отредактировать.
Нажмите кнопку Edit в столбце Operations.
При необходимости обновите Description.
В разделе Access Permissions настройте выбранные разрешения:

Управление платформой: предоставляет доступ к конечным точкам управления платформой (пользователям, моделям, воркерам и т. д.).
Доступ к модели: Предоставляет доступ к API инференса. При выборе выберите All models или Allowed models, а при выборе Allowed models выберите из списка, к каким моделям этот ключ API может получить доступ.

Нажмите кнопку Save.

Примечание

Изменения вступят в силу в течение одной минуты.

Удалить ключ API

Перейдите на страницу Access Control > API Keys.
Найдите ключ API, который хотите удалить.
Нажмите кнопку Delete в столбце Operations.
Подтвердите удаление.

Отзыв ключа, пока сервер недоступен

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

Шлюз хранит собственную копию принимаемых ключей, что позволяет продолжать инференс при недоступном сервере. Копия хранится в Kubernetes, поэтому её можно редактировать без работающего сервера:

kubectl -n higress-system edit wasmplugin gpustack-llm-ext-auth

Удалите запись ключа из spec.defaultConfig.local_auth. Обычно она находится в keys, где индексом служит ключ доступа — средний сегмент gpustack_<access key>_<secret> у автоматически созданного ключа. В пользовательском ключе такого сегмента нет: найдите в keys числовой user_id владельца или сопоставьте exp со сроком действия ключа.

Если для GPUSTACK_GATEWAY_AUTH_ALLOW_CUSTOM_KEYS установлено значение false, пользовательские ключи вместо этого находятся в refs и индексируются числовым идентификатором ключа, как показано в API.

Ключ, отсутствующий в обоих, уже запрашивает сервер при каждом запросе, поэтому удалять нечего — он перестает работать в тот момент, когда сервер возвращается и обрабатывает удаление.

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

Предупреждение

Это временная мера, а не окончательный отзыв. Через несколько секунд после запуска сервер восстанавливает список из базы данных, поэтому ключ, удалённый только здесь, снова начинает действовать после возвращения сервера. Когда сервер станет доступен, удалите ключ обычным способом.

Примечание

Для редактирования ресурса требуется доступ к кластеру, в котором работает шлюз, а higress-system выше — это пространство имен шлюза по умолчанию — замените свое, если оно было изменено. Изменение базы данных GPUStack напрямую не является поддерживаемой альтернативой и может привести к несогласованности развертывания.

Кто может читать это пространство имен

Этот же ресурс содержит ключ, которым шлюз подписывает внутренние токены удостоверений. Любой, кто может читать ресурсы пространства имён шлюза, способен выпустить такой токен и выдать себя за любого пользователя. Поэтому право чтения этого пространства имён равнозначно полномочиям уровня платформы и должно предоставляться соответственно.

Использовать ключ API

GPUStack поддерживает использование ключа API в качестве токена-носителя.

OpenAI-совместимая конечная точка GET /v1/models возвращает только готовые модели, видимые пользователю и текущему контексту организации. Если ключ API ограничен разрешенными моделями, список дополнительно фильтруется по этим идентификаторам моделей, включая любой префикс организации (например, team-a/qwen3). Это также относится к устаревшей конечной точке GET /v1-openai/models и к ключам, созданным администраторами. Неустановленный или пустой список allowed_model_names не накладывает дополнительных ограничений на модель.

Ниже приведен пример использования Curl:

export GPUSTACK_API_KEY=your_api_key
curl http://your_gpustack_server_url/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GPUSTACK_API_KEY" \
  -d '{
    "model": "qwen3",
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful assistant."
      },
      {
        "role": "user",
        "content": "Hello!"
      }
    ],
    "stream": true
  }'