XHub 客户使用与管理手册

English | 简体中文 · 文档首页

本手册面向平台管理员、组织与团队管理员，以及使用模型的开发者。先按安装指南启动服务，再按下面的流程配置工作空间。文中的页面路径属于 Web 控制台，默认端口为 3000；应用请求发送到网关，默认端口为 4000。

1. 建立第一个工作空间

由平台管理员完成初始配置：

图 1：先建立模型与访问范围，再发放密钥、测试和核对调用。下面的步骤对应这四个阶段。

1. 在 /login 登录。本地 Compose 配置的初始账号为 admin@xhub.local / admin-pass-1234，对外开放前在个人资料中修改密码。
2. 打开 Models + Endpoints（/models-and-endpoints），先添加供应商凭证，再添加模型部署，核对公开模型名、上游模型 ID、操作能力、API 地址和价格。
3. 在 /organizations 创建组织，在 /teams 创建团队并设置模型范围和预算。未指定其他管理员时，创建者成为首位团队管理员。
4. 在 /users 创建账号，填写邮箱及至少八位的密码，选择团队和团队角色。已有账号通过团队成员管理按邮箱加入。
5. 按需在 /projects 创建项目，用于区分应用或费用归属。
6. 在 /api-keys 创建该团队范围内的个人或服务虚拟密钥。
7. 在 /playground 测试可用模型，再通过应用调用；在 /usage 确认用量，在 /logs 查看请求详情。

平台管理权限与推理权限分别判断。平台管理员使用个人推理入口，也需要加入团队。

2. 正确接入模型

多个部署可以使用同一个公开模型名，让路由在多个上游之间选择，而应用保持相同的模型名称。

第一步：添加模型供应商

打开“模型供应商”，添加供应商。本例选择 Custom Openai，名称填 company-newapi；地址与 API Key 只填在供应商连接中。普通 Chat 模型的供应商目录 ID 留空。截图中的地址和遮挡密钥为虚构示例，不要直接使用。

第二步：添加模型部署

保存供应商后，打开“模型管理 → 添加模型”。先选择供应商，再填写供应商确认可用的上游模型 ID、对外模型名称、上游协议和价格。截图是尚未选择供应商的初始状态：第二步置灰时，先完成第一步。不要在模型里重复填写地址、密钥，也不用编辑 model_list。点击图片可查看原图。

NewAPI 的完整字段说明、实际调用验证，以及当前未实现的 Suno 接入开发工作，见自定义供应商接入指南。

保存对话部署后，平台管理员可以运行测试连接。服务端使用已保存的供应商凭据和部署 ID，发送一个最小的真实英文对话请求。该测试不支持媒体部署，也不经过网关密钥额度、路由、冷却和网关用量记账；但供应商仍可能执行请求并收费。测试成功只说明这次探测通过，不能代表流式、工具、图片、异步操作或应用的完整生产请求一定可用。

3. 分配管理员

账号角色、组织角色和团队角色是独立的授权，同一个人可以同时拥有多个角色。

只有平台管理员能够创建账号。创建账号不会发送邀请邮件；密码找回当前通过管理员直接重置，不提供邮件重置链接。团队管理员不能重置平台管理员或组织管理员的密码。修改密码会使旧会话失效，用户需要重新登录。

不能移除或降级最后一名团队管理员，先指定接任者再调整成员关系。详细接口规则见开发者权限参考。

4. 管理模型范围和预算

资源按 组织 → 团队 → 项目 组织。团队作为共享访问边界，项目用于区分边界内的应用。

图 3：权限范围示意，不是控制台截图。项目和密钥只能继承或收窄模型范围，不能增加团队未授权的模型。

• 团队决定模型范围。团队模型列表为空，表示这一层不施加限制。
• 项目或密钥的模型列表为空，表示继承上级；非空列表只能进一步收窄，不能授予上级范围之外的模型。
• 项目预算不能超过团队预算。
• 停止团队访问应使用封禁功能。清空模型列表不会禁用团队。

例如，团队允许 chat-a 和 chat-b，项目收窄为 chat-a，该项目密钥只能继续使用 chat-a，不能通过密钥配置恢复 chat-b。

预算检查使用已记录的支出和可用的热状态支出，不会提前预占请求费用。因此，并发请求、长时间流式调用和异步任务可能超出预算。设置预算时保留余量，并结合供应商账单监控。

5. 创建与管理虚拟密钥

打开虚拟密钥 → 创建新密钥，每个应用使用容易识别的名称。创建前检查模型范围、密钥类型、最大预算、RPM/TPM、重置预算、路由模板、有效期和自动轮换。当前创建表单已有 RPM/TPM，不是只能在编辑已有密钥时设置。额度留空表示共享属主的上级剩余容量，不会绕过上级限制。生成的密钥保存在环境变量或密钥管理系统中，不要放进文档截图。

通过 API 创建或更新密钥时，duration 使用正整数加 s、m、h 或 d，例如 30m、12h、7d。空字符串表示不限期；零、负数、格式错误和溢出值会被拒绝。

应用使用 XHub 虚拟密钥。供应商密钥用于 XHub 连接上游；主密钥用于初始化或应急管理；会话令牌用于控制台登录。虚拟密钥不授予控制台管理权限。

6. 从应用发起调用

先打开 /models-and-endpoints/mine（My models）确认当前账号可用的模型，在卡片上选择 Use in Playground 进入测试。已有模型部署不代表当前账号自动获得访问权限，仍需核对团队成员关系与模型范围。

图 4：从可用模型卡片进入 Playground。截图中的模型、价格与能力标签来自演示配置，不构成所有模型的支持承诺。点击截图可查看原图。

先在调试台检查调用，再接应用

1. 打开调试台（/playground），先在选择模型中选择公开模型，再选择该模型支持的客户调用接口。选择有效之前，接口选择器与发送按钮不会开放。
2. 展开连接设置，发送前检查请求连接。供应商认证仍保存在模型供应商中；不要把供应商密钥填进应用调用示例。
3. 输入英文测试提示词，例如 Reply with the word ready.。点击发送会执行真实请求，可能产生供应商费用。截图是尚未选择模型的初始界面，不是调用成功的证明。
4. 使用查看调用代码检查当前操作的示例。外部应用使用网关地址和有权限的 XHub 虚拟密钥，不使用控制台地址或供应商密钥。

通过 pip install openai 安装 OpenAI Python 客户端，设置虚拟密钥和公开模型名：

export XHUB_API_KEY="YOUR_XHUB_VIRTUAL_KEY"
export XHUB_MODEL="YOUR_PUBLIC_MODEL_NAME"

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["XHUB_API_KEY"],
    base_url="http://localhost:4000/v1",
)
response = client.chat.completions.create(
    model=os.environ["XHUB_MODEL"],
    messages=[{"role": "user", "content": "Hello, XHub!"}],
)
print(response.choices[0].message.content)

部署到其他环境时替换网关地址。3000 端口是控制台，误用时可能得到 HTML，而不是 API 响应。其他操作需要核对部署能力，并使用对应的受支持接口。

7. 配置请求路由

在 /route-templates 管理模板，操作账号需要具有目标范围的管理权限。可绑定范围的选择顺序为 密钥 → 团队 → 组织；三者都未选择时，使用内置平台设置及模型管理默认部署分配。清除选择后恢复继承；选中的模板整体替换上级模板，不逐字段合并。项目和账号没有单独的模板绑定。

图 5：从左向右查找最近的模板绑定；清除密钥绑定后，会继续使用团队或更上层的选择。

支持同一公开模型的部署故障切换，也可配置跨公开模型或路由组的通用错误、上下文超限与供应商内容策略回退链。模板不能扩大模型权限或绕过预算，本地护栏拦截不会触发供应商内容策略回退。完整字段与继承语义见路由参考。回退只发生在响应字节输出前，可用 disable_fallbacks:true 按请求关闭；固定续传、原生异步任务创建和 Responses background 请求不会换模型重放。

8. 查看用量、费用和日志

在 /usage 查看趋势和维度统计，在 /logs 查看单次调用。可见范围随账号角色与权限变化。排查请求时保留响应头中的 x-litellm-call-id。平台管理员可通过 GET /audit 查看管理审计记录。

1. 在选择时间范围中选中刚才请求所在的时间段。时间段内没有数据，不代表请求免费。
2. 按权限选择全局用量、组织用量、团队用量或用户用量。全局视图可使用按用户筛选缩小范围；比较费用前，先确认两边时间段和权限维度一致。
3. 先看成本与用量指标：核对请求总数、成功/失败请求、总计令牌和支出；再切换模型活动、密钥活动或端点活动定位对应维度。
4. 打开日志找到单次请求，对照响应中的调用 ID 核查状态、耗时、用量和费用。汇总图表本身不能解释某一次调用为何失败。

截图显示本地开发环境已有记录，不是价格报价或服务质量承诺。中英文截图使用同一视图，其他请求运行时记录值可能变化。点击截图可打开完整原图。

• 请求保存价格快照，后续调价不会改变该次请求的已记录费用；缺少价格快照的记录可能按当前价格重算，并标记为 recomputed。
• 网关响应缓存命中不产生上游费用；供应商的提示词缓存命中仍可能收费。
• 失败或中断的请求可能显示本地零费用，但供应商仍可能收费。上游缺少用量时可能估算，价格缺失需要进一步核查。
• 用户、密钥、团队、项目和组织费用是同一批调用的不同维度，不能相加，否则重复计算。
• 使用 Redis 时 RPM/TPM 是共享分钟计数；未使用 Redis 时是进程内滑动窗口。运行多个网关进程应配置共享状态。

请求/响应内容存储由 general_settings.store_prompts_in_spend_logs 控制，可选择开启。范围内的管理员可查看保存的内容。根据业务数据要求决定是否开启，并通过运维流程设置留存；该开关本身不提供自动加密或留存策略。

计价参考解释单价单位、价格快照和结算；运行行为参考解释缓存、幂等、流式和任务边界。

9. 成员离职与访问回收

1. 必要时先指定新的团队管理员。
2. 移除成员的团队关系，个人密钥仍保留；新请求重新检查当前归属、密钥范围和计费授权，已记录用量保留原调用归属。
3. 吊销或轮换该成员掌握的服务密钥。服务密钥不属于成员，离职后不会自动失效。
4. 单独移除组织管理员授权。需要完整停用账号时，由平台管理员禁用账号。

10. 常见问题排查

调用受支持的供应商内容生成任务时，后续查询使用创建任务时的同一虚拟密钥和供应商路由。任务定位记录有效期为七天。XHub 尚无通用的媒体取消、回调或下载流程。

11. 部署运维与升级

外部访问地址、环境变量密钥和 Docker 配置见安装指南。升级前备份 PostgreSQL 和部署配置，并在独立数据库验证恢复。

提交缺陷或准备修改代码时，记录受影响的操作、公开模型名、调用 ID、预期结果和已脱敏日志。开发者从代码与 AI 编程指南开始定位。

供应商均由管理员显式创建：选择提供商后填写对应凭据字段。系统不会自动安装中转供应商。手动价格刷新及已启用的定时刷新默认读取 https://api.modelink.ai/v1/market/models；XHUB_PRICE_FEED_URL 可覆盖默认源。失败保留当前目录，人工覆盖独立管理。