📋 FAQ
💡 為什麼選擇 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 映像。以下是您的更新可能未顯示的原因以及如何確保更新生效：
- 更新 Docker 映像: 執行命令
docker pull ghcr.io/open-webui/open-webui:main可更新 Docker 映像，但並不會更新正在運行的容器或其數據。 - Docker 卷中的持久數據: Docker 卷獨立於容器的週期，存儲並保留數據（例如聊天歷史記錄），即使更新也不受影響。
- 應用更新: 確保您的更新生效，需刪除現有的容器（這不會刪除卷）並用更新後的映像和現有的卷重新創建新容器。
此流程可在保留數據的同時更新應用程式。
問: 等一下，為什麼要刪除我的容器？我不會丟失數據嗎？
答: 這是一個常見的疑慮，但如果您正確使用 Docker 卷，刪除容器並不等於丟失數據。以下是原因：
- 卷保留數據: Docker 卷旨在持久化數據，即使容器的生存週期結束，也不受影響。只要數據存儲在卷中，就會保持不變，無論容器發生什麼。
- 安全的更新流程: 在更新 Open WebUI 時，刪除舊容器並使用新映像創建一個新容器，並不會影響存儲在卷中的數據。關鍵是在過程中不使用諸如
docker volume rm等命令顯式刪除卷。
按照正確的更新步驟——拉取新映像、刪除舊容器（不刪除卷），並使用更新的映像和現有卷創建新容器，您的應用代碼將被更新，而數據仍然保持不變且安全。
問: 我應該使用發行版預打包的 Docker 還是官方的 Docker 套件？
A: 我們建議使用官方 Docker 套件來執行 Open WebUI，而非使用發行版包裝的版本。官方 Docker 套件定期更新最新功能、錯誤修復和安全補丁，以確保最佳性能和安全性。此外，它支持像 host.docker.internal 等重要功能，這些功能可能在發行版包裝版本中無法使用。此功能對於適當的網絡配置和 Docker 容器內的連接性至關重要。
選擇官方 Docker 套件，您可以享受不同行環境中的一致性行為、更可靠的故障排除支持以及最新 Docker 技術的訪問。更廣泛的 Docker 社區和資源也更契合官方套件，為您可能遇到的任何問題提供豐富的信息和支持。
您運行 Open WebUI 所需的一切，包括您的數據，都保留在您的控制範圍內和您的伺服器環境中，這強調了我們對隱私和安全的承諾。有關安裝官方 Docker 套件的指導，請參閱 Docker 官方文檔網站上的安裝 Docker 引擎指南。
Q: Docker 中是否支持 GPU？
A: Docker 中的 GPU 支持是可用的，但取決於平台。官方提供了 Windows 平台的 Docker 和 Linux 平台的 Docker Engine 的 GPU 支持。而其他平台，如 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: 與 Open WebUI 的 RAG 表現非常糟糕或者完全無法工作。為什麼？
A: 如果您使用的是 Ollama，請注意 Ollama 默認將上下文長度設置為 2048 個 tokens。這意味著檢索到的數據可能完全未被使用，因為它不適合可用的上下文窗口。
為了提高與 Open WebUI 的檢索增強生成（RAG）的性能，您應該 將上下文長度增加到更大的值（8192+ tokens），以確保檢索到的文檔能夠有效地為模型的響應做出貢獻。
為此，請配置您的 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 Issue 頁面 或 Discord 頻道 以獲取更多幫助和信息。