Open WebUI 接入 JBB：/v1 地址、模型发现与容器排错

PRE-FLIGHT

准备管理员权限、专用 JBB Key 和一个可用模型 ID

连接配置位于 Open WebUI 的 Admin Settings。先为 Open WebUI 创建独立、低额度 JBB Key；只使用 API Key，不填写账号密码、Session、管理员 Token 或浏览器 Cookie。

Open WebUI 及相关商标归其权利人所有；本页不表示 JBB 与 Open WebUI 存在官方合作、授权、预装或背书。

CONNECTION SETUP

从“Admin Settings → Connections → OpenAI”新增连接

1. 打开 Open WebUI，进入Admin Settings。
2. 选择 Connections → OpenAI。
3. 点击 Add Connection。
4. URL 填写 https://jbbt.pages.dev/v1，末尾不加 /models 或 /chat/completions。
5. API Key 填写 Open WebUI 专用 JBB Key。
6. 先让 Model IDs (Filter) 保持为空，以便 Open WebUI 从 /models 自动发现当前 Key 可见模型。
7. 点击 Save；确认连接开关已启用。
8. 回到聊天页，选择一个实际可用模型，发送一条短测试消息。

官方依据：Open WebUI OpenAI-Compatible Provider Guide。字段名称可能随版本调整，但 URL、API Key、模型发现和过滤逻辑以当前官方说明为准。

FIELD MAP

URL 必须包含 /v1；不要填写完整 endpoint

Connection: OpenAI
URL: https://jbbt.pages.dev/v1
API Key: <YOUR_JBB_API_KEY>
Model IDs (Filter): leave empty for discovery
Enable: ON

MODEL DISCOVERY

先自动发现，再用 Model IDs (Filter) 收窄列表

Open WebUI 保存连接时会使用 Bearer Key 请求 <URL>/models。JBB 的 URL 填写正确后，实际请求路径就是 GET /v1/models。

• 首次连接：过滤器留空，确认模型列表能按当前 Key 的权限自动发现。
• 减少噪音：只把实际使用的精确模型 ID 加入 Model IDs (Filter)。
• 权限边界：过滤器不能让 Key 获得额外模型权限；最终仍以 JBB 当前 Key 的分组和模型授权为准。
• 多连接：Open WebUI 支持多个 OpenAI-compatible 连接；同名模型需要区分时，可使用连接前缀或拆分用途。
• 刷新变化：JBB 模型权限变化后，重新保存或刷新连接；若用了过滤器，还要同步维护 allowlist。

CONNECTION TEST

先做只读模型预检，再发送一条短对话

GET /v1/models 用于验证地址、Bearer 认证和模型可见性；真正的 Chat Completions 测试可能产生少量计费，不要设置无上限重试。

export JBB_API_KEY="<YOUR_JBB_API_KEY>"
curl -sS "https://jbbt.pages.dev/v1/models" \
  -H "Authorization: Bearer $JBB_API_KEY"

$env:JBB_API_KEY = "<YOUR_JBB_API_KEY>"
$Headers = @{ Authorization = "Bearer $env:JBB_API_KEY" }
Invoke-RestMethod -Uri "https://jbbt.pages.dev/v1/models" -Headers $Headers

DOCKER & ENV

公网 JBB 地址不受 localhost 容器边界影响

Open WebUI 的全局 Provider 连接由后端发起。容器里的 localhost 指 Open WebUI 容器自身；只有连接宿主机上的本地模型服务时，才需要考虑 host.docker.internal。JBB 使用公网 HTTPS 域名，不要改成 localhost。

services:
  open-webui:
    environment:
      OPENAI_API_BASE_URL: >-
        https://jbbt.pages.dev/v1
      OPENAI_API_KEY: ${JBB_API_KEY}

• 单连接：OPENAI_API_BASE_URL 与 OPENAI_API_KEY 一一对应。
• 多连接：官方支持复数变量，URL 与 Key 都使用分号分隔，并保持顺序一致。
• 持久配置：这些变量属于 Open WebUI 的持久配置；实例已在 UI 保存过值时，不能假设只改 env 就会覆盖数据库中的现值。
• Key 注入：把真实 Key 放在宿主机 Secret 或 .env，不要写进镜像、Compose 仓库或截图。

环境变量事实来源：Open WebUI Environment Variable Configuration。

TROUBLESHOOTING

按状态码和请求是否到达 JBB 分层排查

• 404
  模型发现或 Chat 路径不存在

  确认 URL 是 https://jbbt.pages.dev/v1，不是站点根地址，也不是已经带 /models 或 /chat/completions 的完整 endpoint。

• 401
  Bearer Key 无效

  重新复制专用 JBB Key，清除首尾空格；不要使用账号密码、Session 或被禁用的 Key。

• 403
  Key 或用户权限不足

  检查 JBB 分组、模型授权与 Open WebUI 管理权限，不要通过扩大管理员权限绕过连接问题。

• 429
  额度或频率限制

  检查额度和限流，停止自动重试；确认后只做一条短请求。

• EMPTY
  连接成功但没有模型

  清空或修正 Model IDs (Filter)，再确认当前 Key 的 /v1/models 真实返回。

• NET
  Open WebUI 后端无法连接

  从 Open WebUI 容器或宿主机测试 JBB HTTPS 域名，并查看后端日志；浏览器能打开站点不等于容器网络一定可达。

容器与前后端网络边界参考 Open WebUI Connection Errors。

KEY HYGIENE

把 Open WebUI 当作独立调用方管理

• 使用独立、低额度 Key，不复用管理员 Key 或其他生产客户端 Key。
• 多用户 Open WebUI 优先使用只允许 inference 的最小权限 Key，不使用 Provider 管理主密钥。
• 真实 Key 只进入 Open WebUI Secret / 环境变量或受控 Admin UI，不写入聊天、代码仓库、网页或工单。
• 定期核对 JBB 调用日志中的时间、Key、模型、状态与 usage；异常时只禁用 Open WebUI 专用 Key。
• 轮换后先更新连接，再撤销旧 Key；避免新旧配置同时长期有效。

FAQ

Open WebUI 接入 JBB 常见问题

• Q1
  URL 要不要带 /v1？

  要。填写 https://jbbt.pages.dev/v1，Open WebUI 再拼接 /models 与 /chat/completions。

• Q2
  可以直接填 /v1/chat/completions 吗？

  不可以。Open WebUI 需要 Base URL；填完整 endpoint 会导致再次拼接路径。

• Q3
  Model IDs (Filter) 应该怎么填？

  首次留空自动发现；需要减少列表时，再加入当前 Key 实际可见的精确模型 ID。

• Q4
  Docker 中需要改成 host.docker.internal 吗？

  不需要。那是访问 Docker 宿主机本地服务的地址；JBB 使用公网 HTTPS 域名。

• Q5
  为什么改了环境变量仍显示旧连接？

  Open WebUI 的 OpenAI 配置属于持久配置。检查 Admin UI 已保存值和数据库配置，不要只看容器 env。

• Q6
  首次测试会扣费吗？

  模型列表预检通常是只读；真正发送 Chat Completions 可能产生费用。使用低额度专用 Key，只发一条短消息。