跳到主要内容

📋 常见问题

Sponsored by n8n
n8n
Does your interface have a backend yet? Try n8n

💡 为什么选择 Docker?​

我们理解并非所有人都偏好使用 Docker；然而，这种方式对于我们项目的设计和运营效率至关重要。我们认为项目对 Docker 的承诺是其核心方面，并鼓励那些寻找不同部署方式的人探索由社区驱动的替代方案。

问: 如何定制 logo 和品牌标识？​

答: 您可以通过我们的 企业版授权 定制主题、logo 和品牌标识，从而解锁独特的企业功能。

有关企业解决方案和品牌定制的更多详情，请联系我们的销售团队：📧 [email protected]

问: 为什么需要注册？我的数据会被传送到哪里？​

答: 我们要求您注册为管理员用户以增强安全性。这确保了如果 Open WebUI 暴露给外部访问，您的数据仍然安全。需要注意的是，所有数据都保持在本地。我们不会收集您的数据。当您注册时，所有信息都保存在您的服务器中，绝不会离开您的设备。您的隐私和安全是我们最优先考虑的事项，确保您的数据始终处于您的控制之下。

问: 为什么我的 Docker 容器无法通过 localhost 连接到主机上的服务？​

答: 在 Docker 容器内，localhost 是指容器本身，而不是主机。这种区别对于网络连接来说至关重要。要从容器连接到主机上的服务，您应该使用 DNS 名称 host.docker.internal 而不是 localhost。此 DNS 名称是 Docker 特别识别的，用于促进这种连接，从而有效地将主机视为容器内可访问的实体，绕过通常的 localhost 作用范围限制。

问: 如何让主机上的服务对 Docker 容器可访问？​

答: 如果希望主机上的服务对 Docker 容器可访问，请配置这些服务监听所有网络接口，使用 IP 地址 0.0.0.0 而不是仅限于 127.0.0.1 的 localhost。此配置允许服务接受来自任何 IP 地址的连接，包括 Docker 容器。尤其是在存在潜在外部访问的环境中，需注意这种设置的安全影响。实施适当的安全措施，例如防火墙和身份验证，可以帮助降低风险。

问: 为什么我的 Open WebUI 没有更新？我已经重新拉取/重启容器，但没有变化。​

答: 更新 Open WebUI 不仅仅是拉取新的 Docker 镜像。以下是可能导致您的更新未显示的原因以及确保更新有效的方法：

  1. 更新 Docker 镜像: 使用命令 docker pull ghcr.io/open-webui/open-webui:main 更新 Docker 镜像，但这并不会更新正在运行的容器或其数据。
  2. Docker 卷中的持久数据: Docker 卷独立于容器生命周期存储数据，通过更新保留您的数据（例如聊天记录）。
  3. 应用更新: 确保更新生效的方法是删除现有容器（这不会删除数据卷），并使用更新的镜像和现有卷创建新容器。

这一过程可以更新应用程序，同时保持您的数据安全。

问: 等等，我为什么要删除我的容器？删除后我的数据会丢失吗？​

答: 这是一个常见的顾虑，但只要您正确使用 Docker 卷，删除容器并不会导致数据丢失。原因如下：

  • 卷保留数据: Docker 卷旨在将数据持久化于容器生命周期之外。只要您的数据存储在卷中，它将保持完整，不受容器操作的影响。
  • 安全更新过程: 在更新 Open WebUI 时，删除旧容器并使用更新的镜像创建新容器不会影响存储在卷中的数据。关键是不要通过类似 docker volume rm 的命令明确删除卷。

通过正确的更新步骤——拉取新镜像、删除旧容器但不删除卷，以及使用更新的镜像和现有卷创建新容器——您的应用程序代码会得到更新，同时您的数据保持不变和安全。

问: 我应该使用发行版内置的 Docker 还是官方 Docker 包？​

A: 我们推荐使用官方 Docker 包，而不是分发版的 Docker 包来运行 Open WebUI。官方 Docker 包会频繁更新，提供最新的功能、错误修复和安全补丁，以确保最佳性能和安全性。此外，它支持像 host.docker.internal 这样的重要功能，而这些功能可能在分发版中不可用。此功能对于 Docker 容器内的网络配置和连接至关重要。

选择官方 Docker 包，您可以在不同环境中获得一致的行为、更可靠的故障排除支持，以及获取 Docker 最新技术的机会。更广泛的 Docker 社区和资源也更贴合官方包，为您提供丰富的信息和支持，以解决遇到的问题。

运行 Open WebUI 所需的一切，包括数据，都在您的控制和服务器环境内，强调了我们对隐私和安全的承诺。有关安装官方 Docker 包的说明，请参考 Docker 官方文档站点上的 安装 Docker 引擎 指南。

Q: Docker 是否支持 GPU？​

A: Docker 中提供了 GPU 支持，但支持情况因平台而异。官方支持的 GPU 功能在 Windows 平台的 Docker 和 Linux 平台的 Docker Engine 中可用。其他平台，例如 Linux 和 MacOS 上的 Docker Desktop，目前尚不支持 GPU。这一限制对于需要 GPU 加速的应用程序来说至关重要。为获得最佳体验并使用 GPU 功能，我们建议在官方支持 GPU 集成的平台上使用 Docker。

Q: 为什么 Open WebUI 强调使用 Docker？​

A: 使用 Docker 的决定源于其能够确保一致性、隔离依赖关系，并简化不同环境下的部署。Docker 最大程度地减少了兼容性问题，并简化了启动 WebUI 的流程，无论底层系统如何。这是项目维护者的战略选择，利用这些优势，同时承认 Docker 具有一定的学习曲线，但在部署和维护方面的优势显著。我们理解并非所有人都偏好 Docker；然而，这种方法是我们项目设计和运行效率的核心。我们将项目对 Docker 的承诺视为一个基本方面，并鼓励那些寻找不同部署方法的人探索社区驱动的替代方案。

Q: 为什么在我的部署中语音转文本 (STT) 和文本转语音 (TTS) 功能不起作用？​

A: 在您的部署中，语音转文本 (STT) 和文本转语音 (TTS) 服务的功能可能需要 HTTPS 才能正常运行。现代浏览器会执行安全措施，限制某些功能（包括 STT 和 TTS）仅在安全的 HTTPS 连接下工作。如果您的部署未配置为使用 HTTPS，这些服务可能无法按预期运行。确保您的部署能够通过 HTTPS 访问可以解决这些问题，启用 STT/TTS 功能。

Q: 为什么 Open WebUI 不包含内置的 HTTPS 支持？​

A: 尽管我们理解集成 HTTPS 支持的全能解决方案的需求，但我们认为这种方法无法充分满足我们用户群的多样化需求。在项目中实现 HTTPS 功能可能会限制其灵活性，并可能不符合所有用户的特定需求或偏好。为了确保每个人都能根据他们的独特环境定制设置，我们将 HTTPS 终端的实现交由用户负责其生产部署。这一决定允许更大的适应性和定制性。虽然我们不提供设置 HTTPS 的官方文档，但社区成员可能会在请求时提供指导，分享基于他们经验的见解和建议。

Q: 我更新/重启/安装了一些新软件，现在 Open WebUI 无法正常工作了！​

A: 如果您的 Open WebUI 在更新或安装新软件后无法启动，很可能是由于直接安装方法引起的，特别是如果您未为后端依赖项使用虚拟环境。直接安装可能对系统环境的变化（例如更新或新安装）比较敏感，这可能改变现有依赖项。为了避免冲突并确保稳定性，我们建议使用虚拟环境来管理后端的 requirements.txt 依赖项。这将您的 Open WebUI 依赖项与其他系统包隔离，最大程度地减少此类问题。

Q: 我更新/重启后，现在登录不起作用了，我不得不创建一个新账户，而且所有聊天记录都消失了。​

A: 此问题通常出现在创建 Docker 容器时没有为 /app/backend/data 挂载一个卷，或者指定的 Open WebUI 卷（通常在我们示例中命名为 open-webui）被意外删除。Docker 卷对于在容器生命周期中保存数据至关重要。如果您发现需要在重启后创建一个新帐户，那么很可能是启动了一个新的容器，但没有附加保存数据的现有卷。请确保您的 Docker 运行命令包含指向正确数据位置的卷挂载参数，以防数据丢失。

Q: 我尝试登录却失败了，创建了一个新账户，现在系统提示我的账户需要管理员激活。​

A: 这种情况发生在您忘记了首次设置时创建的初始管理员账户的密码。第一个账户会自动被设置为管理员账户。没有访问管理员账户就创建新账户，将导致需要管理员激活。避免丢失初始管理员账户的凭证对于无缝访问和管理 Open WebUI 至关重要。请参阅 重置管理员密码 指南以了解恢复管理员账户的操作说明。

Q: 为什么 Open WebUI 无法启动并出现 SSL 错误？​

A: 您在启动 Open WebUI 时遇到的 SSL 错误可能是由于 SSL 证书缺失或 huggingface.co 配置错误造成的。为解决此问题，您可以设置一个 HuggingFace 的镜像，例如 hf-mirror.com，并在启动 Docker 容器时将其指定为终端节点。使用 -e HF_ENDPOINT=https://hf-mirror.com/ 参数在 Docker 运行命令中定义 HuggingFace 镜像地址。例如，您可以按照以下方式修改 Docker 运行命令：

docker run -d -p 3000:8080 -e HF_ENDPOINT=https://hf-mirror.com/ --add-host=host.docker.internal:host-gateway -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:main

Q: 为什么 RAG（检索增强生成）在 Open WebUI 中效果不好或完全无法工作？​

A: 如果使用 Ollama，请注意 Ollama 默认将上下文长度设置为 2048 个标记。这意味着检索到的数据可能完全无法使用，因为它无法适配可用的上下文窗口。

为了提升检索增强生成（RAG）性能，应将上下文长度增加到更大的值（8192+ 个标记），以确保检索的文档能够有效地为模型的响应提供支持。

为此，请配置您的 Ollama 模型参数，以允许更大的上下文窗口。您可以直接在聊天中或通过模型编辑页面检查并修改此设置，以显著提升 RAG 体验。

Q: 在 Open WebUI 中是否支持 MCP（模型上下文协议）？​

A: 是的，Open WebUI 官方支持 MCP 工具服务器——但只能通过与 OpenAPI 兼容的代理 （openapi-servers）进行，以确保最佳的兼容性、安全性和可维护性。

要连接 MCP（以及其他后端协议），我们提供了专门构建的代理实现，地址为：👉 https://github.com/open-webui/mcpo

此设计选择基于几个核心原则：

  • 📘 标准优先：OpenAPI 是 RESTful 服务定义和契约驱动服务互操作性的事实标准。通过通过 OpenAPI 对齐集成，我们实现了可重现的、基于架构的行为，并可跨升级和部署稳定运行。
  • 🔒 安全模型隔离：通过代理集成 MCP 可允许我们将后端协议行为沙盒化并隔离，减少攻击面，并启用边界级别的审计、身份验证和可观察性。
  • ⚙️ 协议抽象：通过统一的 OpenAPI 架构支持异构后端（例如 MCP），使 Open WebUI 在执行时能够保持对后端无关，同时维持可预测的运行时行为。
  • ⛓️ 解耦的部署拓扑：基于代理的架构允许工具服务器（如 MCP）独立于前端演示进行演化，促进高度模块化的生产环境或分布式工作负载。

总结：MCP 是支持的——只要 MCP 工具服务器由与 OpenAPI 兼容的代理作为前端提供支持。此架构选择是经过深思熟虑的，旨在确保 Open WebUI 的可扩展性、安全性和可维护性。

需要更多帮助？​

如果您有其他问题或顾虑，请前往我们的 GitHub 问题页面 或加入我们的 Discord 频道 寻求更多帮助和信息。