📋 常见问题
💡 为什么选择 Docker？
我们理解 Docker 可能不是所有人的偏好；然而，这种方法是我们项目设计和运行效率的核心。我们将项目对 Docker 的承诺视为一个基本方面，并鼓励那些寻求不同部署方法的人探索社区驱动的替代方案。
Q: 如何定制标志和品牌？
A: 您可以使用我们的企业许可证来定制主题、标志和品牌，该许可证可解锁专属企业功能。
有关企业解决方案和品牌定制的更多详细信息，请通过以下方式联系我们的销售团队：📧 sales@openwebui.com
Q: 为什么我需要注册？我的数据发送到哪里去了？
A: 我们要求您注册成为管理员用户以增强安全性。这确保了如果 Open WebUI 暴露于外部访问，您的数据仍然安全。重要的是，所有数据都保留在本地。我们不收集您的数据。当您注册时，所有信息都保留在您的服务器上，从不离开您的设备。您的隐私和安全是我们的首要任务，确保您的数据始终在您的控制之下。
Q: 我的 Docker 容器为什么无法使用 localhost 连接到主机上的服务？
A: 在 Docker 容器内部，localhost 指的是容器本身，而不是主机。这种区别对于网络连接至关重要。要从容器连接到主机上运行的服务，您应该使用 DNS 名称 host.docker.internal 而不是 localhost。Docker 特别识别此 DNS 名称，以方便此类连接，有效地将主机视为容器内部可访问的实体，从而绕过通常的 localhost 作用域限制。
Q: 如何让我的主机的服务可供 Docker 容器访问？
A: 要使主机上运行的服务可供 Docker 容器访问，请将这些服务配置为监听所有网络接口，使用 IP 地址 0.0.0.0，而不是仅限于 localhost 的 127.0.0.1。此配置允许服务接受来自任何 IP 地址（包括 Docker 容器）的连接。了解此设置的安全隐患非常重要，尤其是在可能存在外部访问的环境中操作时。实施适当的安全措施，例如防火墙和身份验证，有助于减轻风险。
Q: 我的 Open WebUI 为什么没有更新？我已经重新拉取/重启了容器，但没有任何变化。
A: 更新 Open WebUI 不仅仅是拉取新的 Docker 镜像。以下是您的更新可能没有显示的原因以及如何确保它们生效：
- 更新 Docker 镜像：命令
docker pull ghcr.io/open-webui/open-webui:main会更新 Docker 镜像，但不会更新正在运行的容器或其数据。 - Docker 卷中的持久化数据：Docker 卷独立于容器生命周期存储数据，在更新过程中保留您的数据（如聊天记录）。
- 应用更新：通过删除现有容器（不会删除卷）并使用更新后的镜像和已连接的现有卷创建新容器，确保您的更新生效。
此过程在更新应用程序的同时保证您的数据安全。
Q: 等等，我为什么要删除我的容器？我不会丢失数据吗？
A: 这是一个普遍的担忧，但删除容器并不意味着您会丢失数据，前提是您正确使用了 Docker 卷。原因如下：
- 卷保留数据：Docker 卷旨在将数据持久化在容器生命周期之外。只要您的数据存储在卷中，无论容器发生什么，它都会保持完整无损。
- 安全更新过程：更新 Open WebUI 时，删除旧容器并使用更新后的镜像创建新容器不会影响存储在卷中的数据。关键是不要使用像
docker volume rm这样的命令明确删除卷。
通过遵循正确的更新步骤——拉取新镜像，删除旧容器而不删除卷，并使用更新后的镜像和现有卷创建新容器——您的应用程序代码得到更新，而您的数据保持不变且安全。
Q: 我应该使用发行版自带的 Docker 还是官方 Docker 包？
A: 我们建议使用官方 Docker 包而不是发行版自带的版本来运行 Open WebUI。官方 Docker 包会频繁更新，包含最新功能、错误修复和安全补丁，确保最佳性能和安全性。此外，它还支持重要的功能，例如 host.docker.internal，这可能在发行版自带的版本中不可用。此功能对于 Docker 容器内的正确网络配置和连接至关重要。
选择官方 Docker 包，您可以受益于不同环境之间的一致行为、更可靠的故障排除支持以及对最新 Docker 进步的访问。更广泛的 Docker 社区和资源也与官方包更一致，为您提供丰富的信息和支持，以解决您可能遇到的任何问题。
运行 Open WebUI 所需的一切，包括您的数据，都将保持在您的控制和服务器环境中，这强调了我们对您隐私和安全的承诺。有关安装官方 Docker 包的说明，请参阅 Docker 官方文档网站上的安装 Docker Engine 指南。
Q: Docker 中是否支持 GPU？
A: Docker 中支持 GPU，但具体情况因平台而异。官方地，Docker for Windows 和 Linux 上的 Docker Engine 提供 GPU 支持。其他平台，例如 Docker Desktop for Linux 和 MacOS，目前不提供 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 个令牌。这意味着检索到的数据可能根本没有被使用，因为它不适合可用的上下文窗口。
为了提高 Open WebUI 中检索增强生成 (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 保持可扩展、安全和可维护。
Q: Open WebUI 的更新频率如何？（发布计划）
A: 我们目标是每周发布主要版本，并根据需要提供错误修复和次要更新。然而，这并非严格的时间表——有些周可能会发布多个版本，而有些周可能根本没有。
要获取最新信息，您可以关注我们的 GitHub 发布页面上的发布说明和公告。
需要进一步协助？
如果您有任何其他问题或疑虑，请访问我们的 GitHub Issues 页面或我们的 Discord 频道以获取更多帮助和信息。