📋 FAQ

Sponsored by Open WebUI

The top banner spot is reserved for Emerald+ Enterprise sponsors

💡 为什么选择 Docker？

我们理解 Docker 可能不是每个人的首选；然而，这种方法是我们项目设计和运营效率的核心。我们将项目对 Docker 的承诺视为一个基本方面，并鼓励那些寻求不同部署方法的用户探索社区驱动的替代方案。

问：如何自定义徽标和品牌？

答： 您可以使用我们的 企业许可证 自定义主题、徽标和品牌，这将解锁独家企业功能。

有关企业解决方案和品牌定制的更多详细信息，请联系我们的销售团队：📧 sales@openwebui.com

问：为什么要求我注册？我的数据被发送到哪里？

答： 我们要求您注册成为管理员用户以增强安全性。这确保如果 Open WebUI 暴露于外部访问，您的数据仍然保持安全。重要的是要注意，一切都保存在本地。我们不收集您的数据。当您注册时，所有信息都保留在您的服务器内，永远不会离开您的设备。您的隐私和安全是我们的首要任务，确保您的数据始终在您的控制之下。

问：为什么我的 Docker 容器无法使用 localhost 连接到主机上的服务？

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

问：如何使主机的服务对 Docker 容器可访问？

答： 要使主机上运行的服务对 Docker 容器可访问，请配置这些服务监听所有网络接口，使用 IP 地址 0.0.0.0，而不是仅限于 localhost 的 127.0.0.1。这种配置允许服务接受来自任何 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 包？

答： 我们建议使用官方 Docker 包而不是发行版打包版本来运行 Open WebUI。官方 Docker 包经常更新最新功能、错误修复和安全补丁，确保最佳性能和安全性。此外，它支持 host.docker.internal 等重要功能，这在发行版打包版本中可能不可用。此功能对于 Docker 容器内的正确网络配置和连接至关重要。

通过选择官方 Docker 包，您可以在不同环境中获得一致的行为、更可靠的故障排除支持，以及访问最新的 Docker 进展。更广泛的 Docker 社区和资源也更符合官方包，为您可能遇到的任何问题提供丰富的信息和支持。

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

问：Docker 中是否支持 GPU？

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

问：为什么 Open WebUI 强调使用 Docker？

答： 使用 Docker 的决定源于它确保一致性、隔离依赖项和简化跨不同环境部署的能力。Docker 最小化兼容性问题并简化了 WebUI 启动和运行的过程，无论底层系统如何。这是项目维护者利用这些优势的战略选择，承认虽然 Docker 有学习曲线，但部署和维护的优势是显著的。我们理解 Docker 可能不是每个人的首选；然而，这种方法是我们项目设计和运营效率的核心。我们将项目对 Docker 的承诺视为一个基本方面，并鼓励那些寻求不同部署方法的用户探索社区驱动的替代方案。

问：为什么我的部署中语音转文字 (STT) 和文字转语音 (TTS) 不工作？

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

问：为什么 Open WebUI 不包含内置的 HTTPS 支持？

答： 虽然我们理解对包含 HTTPS 支持的一体化解决方案的渴望，但我们认为这种方法无法充分满足我们用户群体的多样化需求。在项目内直接实施 HTTPS 可能会限制灵活性，并可能不符合所有用户的特定要求或偏好。为了确保每个人都能根据其独特环境定制设置，我们将 HTTPS 终止的实施留给用户进行生产部署。这个决定允许更大的适应性和定制。虽然我们不提供设置 HTTPS 的官方文档，但社区成员可能会根据请求提供指导，分享基于他们经验的见解和建议。

问：我更新/重启/安装了一些新软件，现在 Open WebUI 不再工作了！

答： 如果您的 Open WebUI 在更新或安装新软件后无法启动，这可能与直接安装方法有关，特别是如果您没有为后端依赖项使用虚拟环境。直接安装对系统环境的变化很敏感，例如更改现有依赖项的更新或新安装。为了避免冲突并确保稳定性，我们建议使用虚拟环境来管理后端的 requirements.txt 依赖项。这将您的 Open WebUI 依赖项与其他系统包隔离，最小化此类问题的风险。

问：我更新/重启后登录不再工作，我必须创建一个新账户，所有聊天都消失了。

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

问：我尝试登录但无法登录，创建了一个新账户，现在被告知我的账户需要管理员激活。

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

问：为什么 Open WebUI 无法启动并出现 SSL 错误？

答： 您在启动 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

问：Open WebUI 的 RAG 效果很差或完全不工作。为什么？

答： 如果您使用 Ollama，请注意 Ollama 默认将上下文长度设置为 2048 个标记。这意味着检索到的数据可能都不会被使用，因为它们无法适应可用的上下文窗口。

要改善检索增强生成（RAG）与 Open WebUI 的性能，您应该增加上下文长度到更大的值（8192+ 个标记），以确保检索到的文档能够有效地为模型的响应做出贡献。

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

问：Open WebUI 是否支持 MCP（模型上下文协议）？

答： 是的，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 保持可扩展、安全和可维护。

问：Open WebUI 多久更新一次？（发布计划）

答： 我们的目标是每周发布主要版本，根据需要提供错误修复和小更新。但是，这不是严格的时间表——有些周可能有多个发布，而其他周可能没有。

要保持信息更新，您可以关注我们 GitHub 发布页面 上的发布说明和公告。

需要进一步帮助？

如果您有任何进一步的问题或担忧，请访问我们的 GitHub 问题页面 或我们的 Discord 频道 获取更多帮助和信息。