Open‑WebUI多租户模式部署

知识分享

2026-08-12 11:40

23 阅读

Open-WebUI 的多租户模式可以理解为：在同一套服务里，为不同团队或用户创建相互隔离的聊天空间、模型权限和 API 密钥配置。
本文要解决的是，在部署多租户模式后，如何让每个租户使用外部中转 API（也就是第三方大模型接口网关）的密钥，而不是直接绑定官方 Key。
整个过程不需要改代码，主要靠环境变量和后台配置完成。
读完本文，你可以独立部署一套支持多租户的 Open-WebUI，并让不同租户分别绑定各自的中转 API 密钥。

部署前需要准备的三样东西

开始之前，先确认你的服务器满足以下条件：

一台可运行 Docker 的服务器，建议至少 2 核 4G 内存，系统推荐 Ubuntu 22.04 或 Debian 12。
已安装 Docker 和 Docker Compose 插件，安装命令可参考官方文档。
一个可用的外部中转 API 地址，包含 Base URL 和对应的 API Key。如果中转平台给你多个 Key，最好提前整理成表格，方便后续分配给不同租户。

另外，Open-WebUI 多租户模式需要启用用户管理功能。
也就是说不建议用 WEBUI_AUTH=false 这种免登录模式，否则无法区分租户。

启用多租户并配置外部中转 API

Open-WebUI 从较早版本开始就内置了多租户基础能力，默认每个注册用户都可以拥有独立的聊天历史和模型设置。
你不需要额外安装插件，只需要通过环境变量把默认的 OpenAI API 地址指向你的中转服务，并允许用户自己填写密钥即可。

用 Docker Compose 部署时，创建一个 docker-compose.yml 文件，内容如下：

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    container_name: open-webui
    ports:
      - "3000:8080"
    environment:
      - OPENAI_API_BASE_URL=https://你的中转地址/v1
      - OPENAI_API_KEY=你的默认中转Key
      - ENABLE_OLLAMA_API=false
      - WEBUI_AUTH=true
      - WEBUI_SECRET_KEY=请换成随机长字符串
    volumes:
      - ./data:/app/backend/data
    restart: always

保存后执行：

docker compose up -d

这里的关键是 OPENAI_API_BASE_URL。
把它设置成中转平台的地址后，Open-WebUI 会默认把所有模型请求都走这个网关。OPENAI_API_KEY 你可以填一个主要 Key，作为平台级默认密钥。

启动后访问 http://服务器IP:3000，注册第一个账号。
注意，第一个注册的账号会自动成为管理员。

让每个租户单独绑定自己的中转密钥

如果你希望租户 A 用 Key A，租户 B 用 Key B，而不是共用平台默认 Key，需要这样配置：

用管理员账号登录，点击左下角头像进入「管理员面板」。
在「设置」->「通用」里，找到 OPENAI_API_BASE_URL 对应的连接配置，确认连接 ID 是 openai。
开启「允许用户修改 API 密钥」选项（不同版本叫法略有差异，类似 Allow User API Key 或「用户可自定义密钥」）。
让普通用户登录后，在「设置」->「模型」->「OpenAI API」中，把自己的中转 Key 填入「API Key」输入框，并保存。

完成以上操作后，该用户后续请求都会使用他自己填写的 Key，而不会用到平台默认 Key。
管理员可以在「管理员面板」->「用户」中查看每个用户的状态，但不会看到明文密钥。

如果你需要按团队隔离，建议为每个团队创建独立用户，并在中转平台上分别生成对应的子 Key。
这样在 Open-WebUI 里，每个团队各用一组密钥，相互不影响。

多租户对接中转 API 时的避坑清单

在实际部署中，以下几个问题最容易踩坑：

中转地址末尾是否带 /v1。Open-WebUI 兼容 OpenAI 接口格式，Base URL 通常需要包含 /v1。如果写错，会出现连接失败或 404 错误。以中转平台接入文档为准。
不要把所有用户都塞到同一个 Key 下。如果中转平台按 Key 做限流或计费，共用 Key 会导致一个用户刷爆额度，其他人全部受影响。建议每个租户单独一个 Key，并在中转平台设置额度上限。
某些模型名称在中转平台可能被映射。比如你填 gpt-4o，但中转平台实际映射到 gpt-4o-2024-11-20。这种情况下，Open-WebUI 可能报错「Model Not Found」。解决办法是在管理员面板的模型管理里，手动添加与中转平台一致的模型 ID。
Docker 容器内访问宿主机中转服务。如果你的中转 API 跑在宿主机上，不能写 http://localhost:8080，而要写 http://host.docker.internal:8080（Linux 需要额外加 extra_hosts: - "host.docker.internal:host-gateway"）。
更新版本后配置项可能变化。Open-WebUI 更新很快，部分环境变量名称会变。建议部署时使用较新的稳定版镜像，并定期查看官方 Release 说明。

验证多租户密钥是否生效

部署完成后，建议按以下流程做一次完整验证：

新建一个测试用户，登录后在其「设置」中填入一个特殊的测试 Key（比如你手动在中转平台创建的一个低额度 Key）。
发送一条聊天消息，比如“你好”，然后在中转平台的后台日志或请求记录里，查看这个用户请求对应的 Key 是否正是你填的那个测试 Key。
再换一个用户，填入另一个 Key，重复上述操作。
检查用户 A 和用户 B 的聊天记录互相不可见（Open-WebUI 多租户下每个用户数据天然隔离，只要不共用账号就行）。

如果在请求日志里看到的是平台默认 Key，说明「允许用户自定义 API 密钥」没有开启，或者用户填入的 Key 没有保存成功。
重新检查管理员设置，并让用户退出重新登录后再试。

关于中转密钥管理的一点补充建议

多租户模式下，密钥管理的核心是「一租户一 Key，平台只兜底」。
建议你在中转平台上为每个租户创建独立子 Key，并设置可用的模型范围、额度上限和过期时间，不要把主 Key 给用户使用。
当某个租户额度异常或出现盗用风险时，你可以单独禁用该子 Key，不影响其他租户。

如果你正在处理 Open-WebUI多租户模式部署，对接外部中转API密钥管理的需求，建议先按本文步骤完整执行，再根据自己的环境和中转平台规则做微调。
遇到报错时，优先检查 Base URL、模型 ID 和用户密钥配置三个位置，多数问题都能在这些环节解决。

如果你的服务器性能紧张，或者想要更稳定的网络线路来跑中转服务，可以考虑选用具备正规 IDC 资质的云服务商，比如泽御云这类提供云服务器和带宽资源的平台，具体配置和价格以官网控制台为准。
部署类问题欢迎继续翻阅本站其他实操教程。

中转业务遇到风控封禁上游账号，快速切换备用上游流程

大模型中转慢请求堆积，连接池、读写超时全套参数调优