身份验证系统（基于数据库）#

Added in version 3.0: 基于数据库的身份验证系统，默认启用。

Xinference 内置了一套基于数据库的身份验证与授权系统。它将用户、权限、API Key 和刷新令牌存储在本地 SQLite 数据库中，并支持在运行时通过 REST 接口创建和管理用户与 API Key——无需重启服务器。

从 v3.0 开始，该系统默认启用 —— 全新部署的 Xinference 开箱即需要身份验证。

备注

早期版本提供了一个更简单的、基于内存的 --auth-config JSON 系统。该系统已被移除；本文描述的基于数据库的系统是唯一的身份验证模式。

启用与禁用#

身份验证由 XINFERENCE_AUTH_ADVANCED 环境变量控制：

  • 未设置，或设置为 1 / true / yes（大小写不敏感）中的任意一个：启用（默认行为）。

  • 0 / false / no 之一（不区分大小写）：禁用——Xinference 将 完全不启用身份验证，所有接口无需登录或 API Key 即可访问。

# Default: authentication enabled
xinference-local -H 0.0.0.0

# Disable authentication entirely
export XINFERENCE_AUTH_ADVANCED=false
xinference-local -H 0.0.0.0

初始管理员账号#

启用身份验证后首次启动时，用户表为空，Xinference 不会 自动创建管理员账号。首次运行的初始化由两个无需鉴权的接口完成：

  • GET /v1/admin/setup/status：在尚无任何账号时返回 {"needs_setup": true, "initialized": false}。

  • POST /v1/admin/setup：根据给定的 username 和 password 创建第一个管理员账号（拥有所有权限）。

curl -X POST "<endpoint>/v1/admin/setup" \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "choose-a-strong-password"}'

Web UI 会自动引导这一流程：首次打开时会重定向到初始化页面，要求输入新管理员的用户名和密码，随后跳转到登录页面。

一旦已有账号存在， /v1/admin/setup 将永久拒绝创建第二个账号——第一次成功的调用即获胜。如果实例在完成初始化之前就暴露在不受信任的网络中，最先访问该接口的人将成为管理员。如果那个人不是你，拥有部署环境 shell 访问权限的运维人员可以通过 xinference-reset-auth-password 夺回控制权（参见 重置丢失的管理员密码）。

重置丢失的管理员密码#

如果管理员密码丢失——或者首次初始化被他人抢先——拥有运行 RESTful API 的机器 shell 访问权限的运维人员可以在不登录的情况下，直接对认证数据库重置管理员密码：

xinference-reset-auth-password --username admin

该命令会提示输入新密码（也可以通过命令行参数 --password 提供），更新该管理员的密码，并吊销该用户当前有效的刷新令牌，使所有残留会话立即失效。它只对已经拥有 admin 权限的用户生效，并读取 XINFERENCE_AUTH_DB_PATH 指定的数据库（可用 --db-path 覆盖）。运行 xinference-reset-auth-password --help 查看所有选项。

密钥与存储位置#

系统需要一个 JWT 签名密钥、一个加密密钥（用于加密静态存储的 API Key），以及一个数据库文件。这三者都可以通过环境变量覆盖；如果不设置，Xinference 会在首次运行时自动生成并持久化到 XINFERENCE_HOME （默认是 ~/.xinference）下：

用途

环境变量

默认位置

JWT 签名密钥

XINFERENCE_AUTH_JWT_SECRET_KEY

<XINFERENCE_HOME>/auth/jwt_secret_key（自动生成）

API Key 加密密钥

XINFERENCE_AUTH_ENCRYPTION_KEY

<XINFERENCE_HOME>/auth/encryption_key（自动生成）

用户/API Key 数据库

XINFERENCE_AUTH_DB_PATH

<XINFERENCE_HOME>/auth/auth.db

自动生成的密钥只会写入一次，并在后续重启时复用，因此已签发的 JWT 和已加密的 API Key 在重启后仍然可用。在分布式部署（supervisor + worker）中，请确保所有运行 RESTful API 的进程共享同一个 XINFERENCE_HOME（或者设置相同的显式环境变量），以便它们使用相同的密钥和数据库。

权限#

Xinference 定义了以下接口权限：

  • models:list: 获取模型列表和信息的权限。

  • models:read: 使用模型的权限。

  • models:write：启动和停止模型的权限。

  • models:register：注册和取消注册自定义模型的权限。

  • keys:create：创建 API Key 的权限（为自己创建；若与 keys:manage 结合，也可为他人创建）。

  • keys:manage：列出、更新、删除以及查看任意用户 API Key 的权限。

  • users:manage：创建、更新、删除用户以及管理其权限的权限。

  • cache:list / cache:delete：列出/删除已缓存模型文件的权限。

  • virtualenv:list / virtualenv:delete：列出/删除单个模型虚拟环境的权限。

  • logs:list：查看集群日志的权限。

  • monitor:view：查看监控面板的权限。

  • admin：管理员拥有上述所有权限。

调用者只能授予自己拥有的权限——例如，只拥有 users:manage 权限的用户不能将 admin 权限授予他人。

备注

早期版本使用更细粒度的权限范围名称： models:start 和 models:stop （现为 models:write），以及 models:add / models:unregister （现为 models:register）。携带旧名称的令牌和 API Key 仍然可用——服务器会透明地将它们映射到新的权限范围——但该兼容映射已被弃用，将在未来版本中移除。授予权限时请使用新名称。

使用#

启用身份验证后，所有用法保持不变，只是在开始阶段增加了登录步骤，或改用 API Key 进行鉴权。

基于用户名-密码的使用方式#

使用命令行登录：

xinference login -e <endpoint> --username <username> --password <password>

使用 Python SDK 登录：

from xinference.client import Client
client = Client('<endpoint>')
client.login('<name>', '<pass>')

对于 Web UI 的用户，在打开 Web UI 时，将首先跳转到登录页面。登录后，就可以正常使用Web UI 的功能。

基于 Api-Key 鉴权的使用方式#

对于命令行用户，仅需在所要运行的命令上新增 --api-key 或 -ak 选项即可。

xinference launch <other options> --api-key <your_api_key>

对于 Python 客户端用户，在客户端对象初始化时传入 api_key 参数即可，就像 OPENAI 客户端那样。

from xinference.client import Client
client = Client('<endpoint>', api_key='<your_api_key>')

当然，Xinference 也与 OPENAI Python 客户端的使用方式完全兼容。

from openai import OpenAI
client = OpenAI(base_url="<xinference endpoint>" + "/v1", api_key="<your_api_key>")
client.models.list()

对于 HTTP 请求，在请求头中传递 Authorization: Bearer api-key。

curl --request GET \
  --url "<xinference endpoint>" \
  --header "Authorization: Bearer <your_api_key>"

管理用户和 API Key#

以拥有 users:manage 和/或 keys:manage 权限的用户登录后（初始的 admin 账号同时拥有这两项权限），即可通过 /v1/admin 下的 REST 接口管理用户和 API Key，例如：

# Create a new user
curl -X POST "<endpoint>/v1/admin/users" \
  -H "Authorization: Bearer <admin_access_token>" \
  -H "Content-Type: application/json" \
  -d '{"username": "alice", "password": "s3cret!", "permissions": ["models:list", "models:read"]}'

# Create an API key for the current user
curl -X POST "<endpoint>/v1/admin/keys" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-key"}'

其他受支持的接口还包括：列出/更新/删除用户（/v1/admin/users、 /v1/admin/users/{user_id}）、修改用户密码（/v1/admin/users/{user_id}/password），以及列出、更新、删除和查看 API Key（/v1/admin/keys、 /v1/admin/keys/{key_id}、 /v1/admin/keys/{key_id}/reveal）。

通过 Web UI 管理#

以上所有功能也可以通过 Web UI 中的专属页面完成：

  • 用户管理：创建、更新、禁用和删除用户，并编辑其权限（需要 users:manage）。

  • API Key 管理：创建、更新、删除和查看 API Key 明文，并可选地按模型限制访问范围（管理自己的 Key 需要 keys:create，管理其他用户的 Key 需要 keys:manage）。

  • 安全设置：查看和调整防暴力破解配置（登录 / API Key 失败频率限制），并解封被封禁的 IP 或 Key（需要 admin）。详情参见 审计日志与安全。

  • 审计中心：浏览记录的 API 活动（需要 admin）。参见 审计日志与安全。

Http 状态码#

添加了以下两种 HTTP 状态码：

  • 401 Unauthorized: 登录信息或者令牌验证失效。

  • 403 Forbidden: 没有足够的权限访问接口。

对于命令行、SDK 或 Web UI 用户，在遇到授权和权限问题时，会有明确的信息提示。

行为说明#

权限变更无需重新登录即可生效#

路由的权限检查会在每次请求时从数据库读取用户**当前**的权限，而不是使用登录时固化在 JWT 中的权限。授予或撤销权限会在用户下一次 API 调用时立即生效——无需重新登录。这一点适用于基于 JWT 的浏览器会话；API Key 一直以来也是实时读取权限的。

可配置的访问令牌有效期#

访问令牌的有效期默认为 30 分钟，可以通过 XINFERENCE_ACCESS_TOKEN_EXPIRE_MINUTES 环境变量覆盖：

export XINFERENCE_ACCESS_TOKEN_EXPIRE_MINUTES=10

更短的有效期可以缩小令牌被盗用的时间窗口。刷新令牌的有效期为 7 天，目前尚不可配置。

反馈#

该功能处于实验阶段。欢迎通过 GitHub issues 或者 Telegram 群组 提供反馈和建议。