❓ 常见问题 (FAQ)
We are hiring! Shape the way humanity engages with intelligence.
Q: 如何自定义徽标 (Logo) 和品牌？
A: 您可以通过我们的**企业版授权 (Enterprise License)** 自定义主题、徽标和品牌，该授权将解锁专属的企业级功能。
有关企业解决方案和品牌自定义的更多详情，请点击此处。
Q: 我的数据会被发送到哪里吗？
A: 不会。除非您明确选择分享数据或连接到外部模型提供商，否则您的数据永远不会被发送到任何地方。Open WebUI 内部的一切都在您的机器或服务器上本地运行并存储，让您始终完全控制自己的数据。我们鼓励您不要只听信我们的说辞：我们的整个代码库都是公开托管的，因此您可以确切地检查一切是如何运行的。如果您发现任何令人担忧的情况，请立即在我们的仓库中向我们报告。
Q: 我可以在外层空间（例如火星及更远的地方）或其他极端环境中使用 Open WebUI 吗？
A: 可以。 Open WebUI 完全自托管，不 依赖持续的互联网连接，因此非常适合云端系统不切实际或无法运行的环境。只要底层硬件能运行支持的运行时，无论位置在哪里，Open WebUI 都能正常工作。
这包括外层空间和地外环境，如航天器、空间站、月球基地以及火星转运或地表栖息地，在这些地方，通信延迟或完全孤立使得外部依赖无法运作。Open WebUI 的离线优先架构确保了即使在极端延迟或完全断网的情况下，模型、工具和数据仍保持在本地且可预测。
同样的原则也适用于严苛的地面环境，包括潜艇、极地研究站、地下设施、物理隔离网络、灾区和移动指挥环境。简而言之，只要您的系统能够启动并自行供电，Open WebUI 就能运行——这是设计使然。
Q: 为什么要求我注册？我的数据被发送到了哪里？
A: 我们要求您注册是为了让您成为管理员用户，以增强安全性。这确保了如果 Open WebUI 暴露于外部访问，您的数据仍能保持安全。请注意，所有内容都保存在本地。我们不收集您的数据。当您注册时，所有信息都保存在您的服务器内，绝不会离开您的设备。您的隐私和安全是我们的首要任务，确保您的数据始终在您的控制之下。
Q: 为什么我的 Docker 容器无法使用 localhost 连接到宿主机上的服务？
A: 在 Docker 容器内部，localhost 指的是容器本身，而不是宿主机。这种区别对于网络连接至关重要。要建立从容器到宿主机上运行服务的连接，您应该使用 DNS 名称 host.docker.internal 而不是 localhost。这个 DNS 名称被 Docker 特别识别以促进此类连接，从而有效地将宿主机视为容器内可达的实体，绕过了通常的 localhost 范围限制。
Q: 如何让宿主机的服务对 Docker 容器可见？
A: 要使宿主机上运行的服务对 Docker 容器可见，请将这些服务配置为监听所有网络接口，使用 IP 地址 0.0.0.0，而不是仅限于 localhost 的 127.0.0.1。此配置允许服务接受来自任何 IP 地址（包括 Docker 容器）的连接。了解此设置的安全影响非常重要，特别是在可能存在外部访问的环境中运行。实施适当的安全措施（如防火墙和身份验证）可以帮助降低风险。
Q: 为什么我的 Open WebUI 没有更新？我已经重新拉取/重启了容器，但没有任何变化。
A: 要更新 Open WebUI，您必须先拉取最新镜像，然后停止并移除现有容器，最后启动一个新容器。仅拉取镜像是不足够的，因为正在运行的容器仍然基于旧版本。
请严格遵循以下步骤：
- 拉取最新镜像：
docker pull ghcr.io/open-webui/open-webui:main - 停止并移除当前容器：
docker stop open-webui
docker rm open-webui - 启动挂载了数据的新容器：
docker run -d -p 3000:8080 -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:main
（注意：如果您的容器或数据卷名称不同，请相应调整命令。）
如需深入了解更新方法（包括像 Watchtower 这样的自动更新），请查看我们的完整**更新指南**。
Q: 等等，为什么要删除容器？我不会丢失数据吗？
A: 在 Docker 中，容器被设计为“可丢弃的”。只有在配置了数据卷 (Volume) 的情况下，您的数据才是安全的。
如果您在运行容器时没有使用 -v open-webui:/app/backend/data 标志（或 Docker Compose 中类似的卷挂载），您的数据将存储在容器内部。在这种特定情况下，删除容器将导致永久性的数据丢失。
请始终确保正确遵循我们的**快速入门指南**，从一开始就设置持久化卷。
当您使用数据卷（在我们的示例中通常命名为 open-webui）时，即使容器被删除，您的数据也是安全的。当您启动新容器并挂载同一个卷时，新版本的应用会自动连接到您的旧数据。
默认数据路径：
在大多数 Linux 系统上，您的卷数据物理存储在：/var/lib/docker/volumes/open-webui/_data。
Q: 我应该使用发行版自带的 Docker 还是官方的 Docker 软件包？
A: 我们建议使用官方的 Docker 软件包而不是发行版自带的版本来运行 Open WebUI。官方 Docker 软件包会频繁更新最新的功能、错误修复和安全补丁，确保最佳性能和安全性。此外，它还支持 host.docker.internal 等重要功能，而这些功能在发行版自带的版本中可能不可用。此功能对于 Docker 容器内的正确网络配置和连接至关重要。
通过选择官方 Docker 软件包，您可以受益于不同环境之间的一致行为、更可靠的故障排除支持以及获取最新的 Docker 进展。广泛的 Docker 社区和资源也与官方软件包更加一致，为您提供丰富的资讯和支持。
运行 Open WebUI 所需的一切（包括您的数据）都保留在您的控制和服务器环境中，这体现了我们对您隐私和安全的承诺。有关安装官方 Docker 软件包的说明，请参考 Docker 官方文档网站上的 安装 Docker 引擎 (Install Docker Engine) 指南。
Q: Docker 是否支持 GPU？
A: Docker 中的 GPU 支持是可用的，但因平台而异。官方在 Windows 上的 Docker 和 Linux 上的 Docker 引擎中提供 GPU 支持。其他平台，如 Linux 版 Docker Desktop 和 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: 我更新/重启后登录失效了，或者我的工具提示“解密令牌错误 (Error decrypting tokens)”？
A: 这是因为您没有在环境变量中设置持久化的 WEBUI_SECRET_KEY。
- 登录失效： 如果没有这个密钥，Open WebUI 每次启动时都会生成一个随机密钥。这会使您之前的会话 Cookie (JWT) 失效，迫使您重新登录。
- 解密错误： 核心机密（如 MCP 工具的 OAuth 令牌或 API 密钥）是使用此密钥加密的。如果密钥在重启时发生变化，Open WebUI 将无法解密它们，从而导致错误。
修复方法： 在 Docker Compose 或环境配置中将 WEBUI_SECRET_KEY 设置为一个固定的、安全的字符串。
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 容器时将其指定为端点。在 Docker 运行命令中使用 -e HF_ENDPOINT=https://hf-mirror.com/ 参数来定义 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: Open WebUI 的 RAG 效果很差或完全不起作用。为什么？
A: 如果您使用的是 Ollama，请注意 Ollama 默认将上下文长度设置为 2048 个 token。这意味着检索到的数据可能因为超出了可用上下文窗口而完全没有被使用。
为了提升 Open WebUI 的检索增强生成 (RAG) 性能，您应该增加上下文长度到一个更大的值（8192+ token），以确保检索到的文档能够有效地为模型的回答做出贡献。
为此，请配置您的 Ollama 模型参数以允许更大的上下文窗口。您可以直接在聊天中或从模型编辑页面检查并修改此设置，从而显著增强 RAG 体验。
Q: Open WebUI 支持 MCP (模型上下文协议) 吗？
A: 是的，Open WebUI 现在包含对 MCP 可流式传输 HTTP (Streamable HTTP) 的原生支持，从而实现了与通过标准 HTTP 传输通信的 MCP 工具的直接、一流集成。对于任何其他 MCP 传输或非 HTTP 实现，您应该使用我们的官方代理适配器 MCPO，获取地址为 👉 https://github.com/open-webui/mcpo。MCPO 提供了一个统一的 OpenAPI 兼容层，将其他 MCP 传输安全且一致地桥接到 Open WebUI 中。这种架构确保了最大的兼容性、严格的安全边界以及在不同环境下可预测的工具行为，同时保持 Open WebUI 与后端无关且易于维护。
Q: 为什么前端被整合进同一个 Docker 镜像中？这不会导致扩展性问题吗？
A: 认为将前端与后端捆绑在一起无法扩展的假设源于对现代单页应用 (SPA) 运行方式的误解。Open WebUI 的前端是一个静态 SPA，这意味着它仅由 HTML、CSS 和 JavaScript 文件组成，与后端没有运行时耦合。由于这些文件是静态的、轻量级的，且不需要单独的服务器，将它们包含在同一个镜像中对扩展性没有影响。这种方法简化了部署，确保每个副本提供的资产完全相同，并消除了不必要的移动部件。如果您愿意，仍可以将 SPA 托管在任何 CDN 或静态托管服务上，并将其指向远程后端，但将两者打包在一起是容器化 SPA 最标准且最实用的方法。
Q: Open WebUI 是否适用于大型组织或企业级部署？
A: 是的，Open WebUI 的架构专为大规模扩展和生产就绪而设计。 它已经深受支持极高用户数量的部署环境的信赖——想想成千上万甚至数十万个席位——被全球的大学、跨国企业和主要机构所使用。
Open WebUI 的无状态、容器优先架构意味着您永远不会被单个服务器瓶颈所束缚。通过水平扩展、灵活的存储后端、外部化身份验证和数据库支持，以及全方位的容器编排兼容性（例如 Kubernetes 或 Docker Swarm），您可以构建强大的高可用集群，以满足最苛刻的企业需求。
配合正确的后端基础设施配置，Open WebUI 将能轻松地从试点项目扩展到任务关键型的全球推广。
Q: 如何在高度可用的大规模生产环境中部署 Open WebUI？
A: 对于有严苛可用性和规模要求的组织，Open WebUI 旨在接入现代生产环境：
- 在负载均衡器后运行多个容器（实例），以实现复原力和最佳性能
- 使用外部数据库和持久化存储，实现可扩展且可靠的数据管理
- 集成企业级身份验证（如 SSO/OIDC/LDAP），实现无缝且安全的登录
- 通过现代日志/指标工具实现可观测性和监控
如果您计划进行高可用、企业级的部署，我们建议查看这个优秀的社区资源：
👉 SRE 的 Open WebUI 高可用部署架构指南 （这为大规模 Open WebUI 架构提供了强有力的技术概览和最佳实践。）
Open WebUI 从设计之初就不仅是为了处理、更是为了在规模化环境下蓬勃发展——服务于全球的大型组织、大学和企业。
Q: Open WebUI 的更新频率是怎样的？（发布计划）
A: 我们的目标是每周发布一次重大版本，并根据需要提供错误修复和次要更新。然而，这并不是一个死板的计划——有些周可能会有多次发布，而有些周可能一次都没有。
要随时了解最新动态，您可以关注我们 GitHub Releases 页面上的发布说明和公告。
Q: 如果发现违反许可证的非合规 Open WebUI 部署，该向哪里举报？
如果您遇到似乎违反 Open WebUI 许可证的 Open WebUI 部署——例如在不允许的情况下移除品牌标识、误导性的白标、商业滥用或任何形式的未经授权再分发——您可以机密地向我们的合规团队报告。
📩 电子邮件： reports@openwebui.com 请包含任何相关的细节（截图、URL、用法描述等），以便我们进行适当的调查。
我们会本着诚信原则审查每一份报告，并谨慎处理所有提交的内容。保护 Open WebUI 生态系统的健康、清晰和完整，有助于我们保持项目的可持续性、公平性以及对每个人的开放可达性。
需要进一步协助？
如果您有任何进一步的问题或疑虑，请访问我们的 GitHub Issues 页面 或我们的 Discord 频道 获取更多帮助和信息。