跳到主要内容

机器人账号

机器人账号是面向自动化任务、CI/CD 作业和服务间访问的非人工身份。每个机器人账号都有独立的令牌、有效期、启用状态，以及细粒度的系统权限和项目权限。

前置条件​

  • 已使用平台管理员账号登录 MatrixHub。
  • 已明确自动化任务所需的最小系统权限和项目权限。
  • 如需让项目权限仅作用于指定项目，请先创建这些项目。

机器人账号列表​

进入 平台设置 -> 机器人账号。列表展示以下信息：

参数描述
用户名账号标识。MatrixHub 会自动在创建时填写的名称前添加 robot$ 前缀。
是否启用账号是否可以进行身份认证和访问资源。
系统权限已配置的平台级权限数量。
覆盖项目数项目权限作用于全部项目还是指定项目，同时展示已配置的项目权限数量。
创建时间机器人账号的创建时间。
有效期剩余展示剩余有效期、永不过期 或 已过期。
描述账号用途或使用场景说明。
操作支持 刷新令牌、编辑、启用/停用 和 删除。

可以使用搜索框按名称筛选机器人账号。

机器人账号列表

创建机器人账号​

  1. 在 机器人账号 页面点击 添加机器人。

  2. 在 基本信息 中填写唯一的名称，并按需填写描述。

  3. 将 过期时间 设置为 永不过期 或 指定天数。选择指定天数时，至少填写 1 天。

  4. 在 系统权限 中，仅选择机器人账号执行任务所需的系统操作权限。

  5. 在 项目权限 中选择项目范围：

    • 覆盖所有项目：所选项目权限作用于所有项目。
    • 选择已有项目：选择一个或多个已有项目，所配置的项目权限仅作用于这些项目。

  6. 在 项目权限明细 中，按需选择模型、数据集、项目成员、项目机器人账号和项目设置相关权限。

  7. 点击 确认。新建的机器人账号会立即启用。

创建机器人账号

创建成功后，MatrixHub 只会显示一次令牌。请立即复制令牌，并将其保存在密钥管理系统或其他安全位置。关闭弹窗后无法再次查看该令牌。

机器人账号令牌

备注

账号的完整用户名为 robot$<名称>。例如，创建时填写 ci-bot，得到的用户名为 robot$ci-bot。

使用机器人账号​

调用 MatrixHub API 时，可以将机器人用户名和令牌作为 HTTP Basic Authentication 凭据。下面的示例用于创建用户，因此机器人账号必须拥有对应的用户管理权限：

curl --request POST 'http://<matrixhub-endpoint>/api/v1alpha1/users' \
  --header 'Content-Type: application/json' \
  --user 'robot$ci-bot:<robot-token>' \
  --data '{
    "username": "example-user",
    "password": "<initial-password>",
    "is_admin": false
  }'

如需通过 Hugging Face CLI 操作模型，请先配置 MatrixHub 端点，再执行 hf auth login，并按提示粘贴由 MatrixHub 自动生成的机器人令牌：

export HF_ENDPOINT="http://<matrixhub-endpoint>"
hf auth login
hf download <project>/<model>

只有在账号已启用、令牌未过期，且分配的权限覆盖当前操作和目标项目时，请求才能成功。

编辑机器人账号​

  1. 找到目标账号，点击 编辑。
  2. 修改描述、有效期、系统权限、项目范围或项目权限。账号名称无法修改。
  3. 点击 确认。权限变更会立即生效。

请遵循最小权限原则，仅授予自动化任务所需的权限和项目范围。

刷新令牌​

  1. 找到目标账号，点击 刷新令牌。

  2. 选择以下任一方式：

    • 保持手动指定开关关闭，点击 刷新令牌，由 MatrixHub 自动生成新令牌。
    • 开启手动指定，输入并确认一个 8–20 个字符的令牌，其中至少包含一个大写字母、一个小写字母和一个数字。

  3. 在成功弹窗中复制新令牌，并更新所有使用该账号的客户端。

刷新机器人账号令牌

刷新令牌后，旧令牌会立即失效。Hugging Face CLI 等仅使用令牌认证的客户端需要使用自动生成的机器人令牌；自定义令牌应配合机器人用户名，通过 HTTP Basic Authentication 使用。

启用、停用或删除账号​

  • 停用：点击 停用 并确认。账号会立即停止认证，但其配置仍会保留。
  • 启用：点击 启用 并确认。如果令牌仍在有效期内，账号可以重新进行身份认证。
  • 删除：点击 删除 并确认。账号及其凭据会被永久删除。
注意

停用、删除机器人账号或刷新其令牌，可能会中断使用该令牌的自动化任务。执行这些操作前，请先更新或停止相关作业。

配置参数​

参数描述
名称必填且不可重复。MatrixHub 会添加 robot$ 前缀后保存并展示；创建后无法修改。
描述可选，用于说明账号用途，最多 50 个字符。
有效期可以设置为 永不过期，或设置不少于 1 天的有效期。过期账号无法进行身份认证。
系统权限用户、镜像仓库、远程同步、项目、机器人账号和清理管理等平台级操作的细粒度权限。
项目范围将所选项目权限作用于 覆盖所有项目 或 选择已有项目。
项目使用 选择已有项目 时，设置权限覆盖的已有项目。
项目权限模型、数据集、成员、项目机器人账号和项目设置操作的细粒度权限。
令牌用于机器人账号身份认证的密钥，仅在创建或刷新令牌成功后完整显示一次。