📋 常见问题
💡 为什么选择 Docker?
我们理解 Docker 可能不是每个人的首选；然而，这种方法对于我们项目的设计和运营效率至关重要。我们将项目对 Docker 的承诺视为一个基本方面，并鼓励寻求不同部署方法的人探索社区驱动的替代方案。
问：如何自定义徽标和品牌？
答：您可以使用我们的 企业许可 自定义主题、徽标和品牌，该许可解锁了独家企业功能。
有关企业解决方案和品牌定制的更多详细信息，请联系我们的销售团队：📧 sales@openwebui.com
问：为什么要求我注册？我的数据会被发送到哪里？
答：我们需要您注册成为管理员用户以增强安全性。这确保了 Open WebUI 即使暴露在外部访问下，您的数据也能保持安全。重要的是要注意，所有内容都保存在本地。我们不收集您的数据。当您注册时，所有信息都保留在您的服务器内，不会离开您的设备。您的隐私和安全是我们的首要任务，确保您的数据始终处于您的控制之下。
问：为什么我的 Docker 容器无法使用 localhost 连接到主机上的服务？
答：在 Docker 容器内部，localhost 指的是容器本身，而不是主机机器。这种区别对于网络至关重要。要从您的容器建立与主机上运行的服务连接，您应该使用 DNS 名称 host.docker.internal 而不是 localhost。Docker 特别识别这个 DNS 名称，以促进此类连接，有效地将主机视为容器内部可访问的实体，从而绕过通常的 localhost 范围限制。
问：如何让我的主机服务可供 Docker 容器访问？
答：要使主机上运行的服务可供 Docker 容器访问，请将这些服务配置为监听所有网络接口，使用 IP 地址 0.0.0.0，而不是仅限于 localhost 的 127.0.0.1。此配置允许服务接受来自任何 IP 地址（包括 Docker 容器）的连接。重要的是要注意此设置的安全隐患，尤其是在可能存在外部访问的环境中操作时。实施适当的安全措施，例如防火墙和身份验证，可以帮助降低风险。
问：我的 Open WebUI 为什么没有更新？我已经重新拉取/重启了容器，但没有任何变化。
答：更新 Open WebUI 不仅仅需要拉取新的 Docker 镜像。以下是为什么您的更新可能没有显示以及如何确保其生效的说明：
- 更新 Docker 镜像：命令
docker pull ghcr.io/open-webui/open-webui:main更新的是 Docker 镜像，而不是正在运行的容器或其数据。 - Docker Volume 中的持久化数据：Docker volume 独立于容器生命周期存储数据，通过更新保留您的数据（例如聊天记录）。
- 应用更新：通过删除现有容器（这不会删除 volume）并使用更新的镜像和附加的现有 volume 创建一个新容器来确保更新生效。
此过程在更新应用程序的同时确保您的数据安全。
问：等等，为什么要删除我的容器？我的数据不会丢失吗？
答：这是一个常见的担忧，但删除容器并不意味着您会丢失数据，前提是您正确使用了 Docker volume。原因如下：
- Volume 保留数据：Docker volume 设计用于在容器生命周期之外持久化数据。只要您的数据存储在 volume 中，无论容器发生什么，它都会保持完整。
- 安全更新过程：更新 Open WebUI 时，删除旧容器并使用更新的镜像创建一个新容器不会影响存储在 volume 中的数据。关键是不要使用
docker volume rm等命令明确删除 volume。
通过遵循正确的更新步骤——拉取新镜像，删除旧容器但不删除 volume，并使用更新的镜像和现有 volume 创建新容器——您的应用程序代码会更新，而您的数据保持不变且安全。
问：我应该使用发行版自带的 Docker 还是官方 Docker 包？
答：我们建议使用官方 Docker 包而非发行版自带的版本来运行 Open WebUI。官方 Docker 包会频繁更新，包含最新的功能、错误修复和安全补丁，确保最佳性能和安全性。此外，它支持重要的功能，例如 host.docker.internal，这可能在发行版自带的版本中不可用。此功能对于 Docker 容器内部正确的网络配置和连接至关重要。
选择官方 Docker 包，您可以受益于跨不同环境的一致行为、更可靠的故障排除支持以及对最新 Docker 进展的访问。更广泛的 Docker 社区和资源也与官方包更一致，为您提供丰富的遇到任何问题时所需的帮助和信息。
运行 Open WebUI 所需的一切，包括您的数据，都由您控制并在您的服务器环境中，这强调了我们对您的隐私和安全的承诺。有关安装官方 Docker 包的说明，请参阅 Docker 官方文档网站上的安装 Docker Engine 指南。
问：Docker 中是否支持 GPU？
答：Docker 中支持 GPU，但这取决于平台。官方支持在 Docker for Windows 和 Linux 上的 Docker Engine 中提供 GPU 支持。其他平台，例如 Linux 和 macOS 上的 Docker Desktop，目前不提供 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 的 volume，或者无意中删除了指定的 Open WebUI volume（在我们的示例中通常命名为 open-webui）。Docker volume 对于跨容器生命周期持久化您的数据至关重要。如果您发现在重启后需要创建新账户，很可能是您在未附加存储数据的现有 volume 的情况下启动了一个新容器。确保您的 Docker 运行命令包含指向正确数据位置的 volume 挂载，以防止数据丢失。
问：我尝试登录但失败了，创建了一个新账户，但现在被告知我的账户需要由管理员激活。
答：这种情况发生在您忘记了首次设置期间创建的初始管理员账户的密码时。第一个账户会自动指定为管理员账户。在无法访问管理员账户的情况下创建新账户将导致需要管理员激活。避免丢失初始管理员账户凭据对于 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 token。这意味着由于检索到的数据不适合可用的上下文窗口，可能没有任何数据被使用。
为了提高检索增强生成 (RAG) 与 Open WebUI 的性能，您应该将上下文长度增加到一个更大的值（8192+ token），以确保检索到的文档能够有效地为模型的响应做出贡献。
为此，请配置您的 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）独立于前端呈现进行演进，从而促进高度模块化的生产环境或分布式工作负载。
总结：Open WebUI 支持 MCP——只要 MCP 工具服务器由 OpenAPI 兼容代理提供服务。此架构决策是经过深思熟虑的，可确保 Open WebUI 保持可扩展、安全和可维护。
需要进一步帮助？
如果您有任何进一步的问题或疑虑，请通过我们的 GitHub Issues 页面 或我们的 Discord 频道 联系我们，以获取更多帮助和信息。