準備為 Open WebUI 做出貢獻？讓我們開始吧！🚀

準備好深入 Open WebUI 的開發了嗎？這份全面的指南將指導您快速輕鬆地設置本地開發環境。無論您是經驗老到的開發者還是剛剛開始，我們都會幫助您準備調整前端、增强後端，為 Open WebUI 的未來做出貢獻！讓我們通過簡單、詳細的步驟啟動您的開發環境吧！

前置準備

開始之前，請確保您的系統滿足以下最低要求：

操作系統: Linux（或 Windows 上的 WSL）、Windows 11 或 macOS。(推薦使用以獲得最佳兼容性)
Python: 版本 3.11 或更高。(後端服務須使用)
Node.js: 版本 22.10 或更高。(前端開發須使用)
推薦使用的 IDE: 我們推薦使用類似 VSCode 的 IDE 來進行代碼編輯、調試並訪問集成終端。如果您有喜好的 IDE，隨意使用！
[可選] GitHub Desktop: 如果您對命令行 Git 不太熟悉，建議安裝 GitHub Desktop 以更輕鬆地管理 Git 倉庫。

設置本地開發環境

我們將設置 Open WebUI 的前端（用戶界面）和後端（API 和服務邏輯）。

1. 克隆倉庫

首先使用 git clone 將 Open WebUI 倉庫下載到您的本地機器。這會在您的計算機上創建該項目的本地副本。

打開終端（如果您使用 Windows 且在用 Git Bash，請打開 Git Bash）。
導航至目錄，該目錄是您希望存儲 Open WebUI 項目的地方。
克隆倉庫： 執行以下命令：

git clone https://github.com/open-webui/open-webui.git
cd open-webui

git clone 命令從 GitHub 下載項目文件。cd open-webui 命令則導航到新創建的項目目錄中。

2. 前端設置（用戶界面）

讓我們首先讓用戶界面（您在瀏覽器中看到的）運行起來：

配置環境變量：
- 將示例環境文件複製到 .env：
```
cp -RPp .env.example .env
```
  此命令將 .env.example 文件複製到名為 .env 的新文件中。.env 文件是您為前端配置環境變量的地方。
- 自定義 .env 文件： 使用代碼編輯器（如 VSCode）打開 .env 文件。此文件包含前端的配置變量，例如 API 端點和其他設置。在本地開發中，.env.example 裏的默認設置通常足夠啟動。不過，如果需要，您可以進行自定義。

重要提醒： 如果您要回傳倉庫，請勿提交敏感信息到 .env 文件中。

安裝前端依賴：
- 導航至前端目錄： 如果您尚未位於項目根目錄（open-webui 的目錄），請確保進入該目錄。
```
# 如果您尚未進入項目根目錄，請執行以下命令：
cd open-webui
```
- 安裝所需的 JavaScript 套件：
```
npm install
```
  此命令使用 npm（Node 軟件包管理器）閱讀項目根目錄中的 package.json 文件並下載所有運行前端所需的 JavaScript 庫和工具。根據您的網速，這可能需要幾分鐘。
啟動前端開發服務器：
```
npm run dev
```
此命令啟動前端開發服務器。如果步驟成功完成，通常會顯示服務器正在運行並提供本地的 URL。

🎉 訪問前端： 打開您的網頁瀏覽器並前往 http://localhost:5173。您應該會看到 Open WebUI 的前端正在運行並等待後端可用的消息。不用擔心這個消息！接下來，我們將設置後端。保持這個終端運行——它服務您的前端！

3. 後端設置（API 和服務）

為了更流暢的開發體驗，我們強烈推薦使用單獨的終端窗口來運行前端和後端進程。這樣可以使您的工作流程更有條理，並能更輕鬆地獨立管理應用的每一部分。

為什麼要使用單獨的終端？

進程隔離： 前端和後端開發服務器是獨立的程序。在單獨的終端中運行它們可以確保彼此不互相干擾，並允許獨立重新啟動或停止進程。
更清晰的日誌和輸出： 每個終端將顯示前端或後端的特定日誌和輸出。這使得調試和監控變得更加容易，因為您不需要篩選交錯的日誌。
減少終端混亂： 在單個終端中混合前端和後端命令可能會令人困惑。分離的終端使命令歷史記錄和活動過程更加有序。
提高工作流程效率： 您可以在一個終端處理前端任務（例如運行 npm run dev），同時在另一個終端管理後端任務（例如啟動服務器或檢查日誌），而無需一直在單個終端內切換上下文。

使用 VSCode 集成終端（推薦）：

VSCode 的集成終端功能使得管理多個終端變得非常容易。以下是如何利用它來分離前端和後端：

前端終端（您可能已經擁有這個）： 如果您按照前端設置步驟操作，您很可能已經在 VSCode 的項目根目錄（open-webui 目錄）中開了一個終端。在這裡，您將運行前端命令（如 npm run dev 等）。如果您尚未位於 open-webui 目錄中，請確保切換到該目錄。
後端終端（開啟一個新終端）：
- 在 VSCode 中，前往 終端 > 新終端（或使用快捷鍵 Ctrl+Shift+ 在 Windows/Linux 上，或者 Cmd+Shift+ 在 macOS 上）。這將打開一個新的集成終端面板。
- 切換到 backend 目錄： 在這個新的終端中，使用 cd backend 命令切換到項目中的 backend 文件夾。這樣可以確保所有後端相關的命令都在正確的上下文中執行。
現在，您在 VSCode 中有兩個獨立的終端實例：一個用於前端（可能位於 open-webui 目錄中），另一個專門用於後端（位於 backend 目錄中）。您可以輕鬆地在這兩個終端之間切換，獨立管理前端和後端過程。這種設置非常推薦，適合更整潔高效的開發工作流程。

後端設置步驟（在您的後端終端中）：

切換到後端目錄：（您應該已經在之前步驟中的 backend 目錄中）。如果尚未切換，運行以下命令：
```
cd backend
```
創建並激活 Conda 環境（推薦）：
- 我們強烈推薦使用 Conda 管理 Python 依賴項並隔離您的項目環境。這避免了與系統上其他 Python 項目的衝突，並確保您擁有正確的 Python 版本和庫。
```
conda create --name open-webui python=3.11
conda activate open-webui
```
  - conda create --name open-webui python=3.11：此命令使用 Python 3.11 創建一個名為 open-webui 的新 Conda 環境。如果您選擇了其他 Python 3.11.x 版本，也可以。
  - conda activate open-webui：此命令激活新創建的 Conda 環境。激活後，終端提示通常會改變以指示您正在 open-webui 環境中（例如，它可能在行首顯示 (open-webui)）。
請確保您在後端終端中激活了環境後再繼續。

(使用 Conda 是可選的，但強烈推薦用於管理 Python 依賴和避免衝突) 如果您選擇不使用 Conda，請確保您使用的是 Python 3.11 或更高版本並繼續下一步，但要注意潛在的依賴衝突。
安裝後端依賴：
- 在您的後端終端中（如果您使用 Conda，請激活 Conda 環境），運行：
```
pip install -r requirements.txt -U
```
該命令使用 pip（Python 包安裝器）來讀取後端目錄中的 requirements.txt 文件。requirements.txt 列出了後端運行所需的所有 Python 庫。pip install 將下載並安裝這些庫到您的活躍 Python 環境中（如果使用 Conda，則到 Conda 環境；否則則到系統範圍的 Python 環境）。-U 標誌確保您獲得最新兼容版本的庫。
啟動後端開發服務器：
- 在您的後端終端中運行：
```
sh dev.sh
```
該命令執行 dev.sh 腳本。此腳本可能包含啟動後端開發服務器的命令。(如果您好奇，可以在您的代碼編輯器中打開並查看 dev.sh 文件以了解執行的具體命令) 後端服務器通常會啟動並在終端中打印一些輸出。

📄 探索 API 文件說明: 當後端運行後，您可以在網頁瀏覽器中訪問自動生成的 API 文件說明，地址為 http://localhost:8080/docs。此文件說明對於理解後端 API 端點、如何與後端交互以及期望獲得和返回的數據非常重要。請在開發過程中隨時保留此文件說明！

🎉 恭喜！ 如果您已完成所有步驟，現在應該在本地運行前端和後端開發服務器。返回您之前訪問前端的瀏覽器標籤（通常是 http://localhost:5173）。刷新頁面。 現在應該能夠在瀏覽器中看到完整的 Open WebUI 應用程序，並已連接到本地後端！

常見問題排查

以下是一些您在設置或開發過程中可能遇到常見問題的解決方案：

💥 "FATAL ERROR: Reached Heap Limit"（前端）

此錯誤通常出現在前端開發過程中，表示 Node.js 在構建過程中內存不足，特別是在處理大型前端應用程序時。

解決方案: 增加 Node.js 的堆內存大小。這樣可以為 Node.js 提供更多的內存。您有以下選項：

使用 NODE_OPTIONS 環境變量（推薦用於開發過程）：
- 這是一種臨時的方式來增加當前終端會話的內存限制。在您的前端終端中運行 npm run dev 或 npm run build 之前，設置 NODE_OPTIONS 環境變量：
```
export NODE_OPTIONS="--max-old-space-size=4096" # 用於 Linux/macOS (bash, zsh)
# set NODE_OPTIONS=--max-old-space-size=4096 # 用於 Windows (命令提示符)
# $env:NODE_OPTIONS="--max-old-space-size=4096" # 用於 Windows (PowerShell)
npm run dev
```
  選擇適合您的操作系統和終端的命令。4096 代表 4GB 的內存。若需要，您可以嘗試進一步增加該值（例如，8192 代表 8GB）。該設置僅適用於當前終端會話中執行的命令。
修改 Dockerfile（適用於 Docker 環境）：
- 如果您使用的是 Docker，可以在 Dockerfile 中永久設置 NODE_OPTIONS 環境變量。這在 Docker 環境中分配內存時非常有用，示例如下：
```
ENV NODE_OPTIONS=--max-old-space-size=4096
```
- 分配足夠的 RAM: 無論採用哪種方法，請確保您的系統或 Docker 容器可用的 RAM 足夠多以供 Node.js 使用。至少建議 4GB 的 RAM，對於較大的項目或複雜的構建可能需要更多。關閉不必要的應用程序以釋放 RAM。

⚠️ 端口衝突（前端與後端）

如果出現與端口相關的錯誤，例如 "Address already in use" 或 "Port already bound"，這表明您的系統上已有其他應用程序使用了端口 5173（前端默認端口）或 8080（後端默認端口）。一個端口一次只能供一個應用程序使用。

解決方案:

確認衝突進程: 您需要找出使用您所需端口的應用程序。
- Linux/macOS: 打開新終端，使用 lsof 或 netstat 命令：
  - lsof -i :5173（或 :8080 用於後端端口）
  - netstat -tulnp | grep 5173（或 8080）這些命令將列出使用指定端口的進程 ID (PID) 和進程名稱。
- Windows: 以管理員身份打開命令提示符或 PowerShell，並使用 netstat 或 Get-NetTCPConnection：
  - netstat -ano | findstr :5173（或 :8080） (命令提示符)
  - Get-Process -Id (Get-NetTCPConnection -LocalPort 5173).OwningProcess (PowerShell) 這些命令也將顯示使用該端口的進程 ID。
終止衝突進程: 一旦識別了進程 ID (PID)，可以停止使用該端口的應用程序。終止進程時請小心，尤其是不確定它是什麼時。
- Linux/macOS: 使用 kill 命令：kill <PID>（替換 <PID> 為實際進程 ID）。如果進程未能通過 kill 停止，您可以使用 kill -9 <PID>（強制停止），但請謹慎使用。
- Windows: 以管理員身份在命令提示符或 PowerShell 中使用 taskkill 命令：taskkill /PID <PID> /F（替換 <PID> 為進程 ID）。/F 標誌表示強制終止。
或者，更改端口（高級選項）：
- 如果無法終止衝突進程（例如，它是您需要的系統服務），您可以配置 Open WebUI 使用不同的前端和/或後端端口。這通常需要修改配置文件。
  - 前端端口: 查看前端文件說明或配置文件（通常是 vite.config.js 或類似文件），了解如何更改開發服務器端口。如果前端使用環境變量設置端口，可能還需要調整 .env 文件。
  - 後端埠號： 檢查 dev.sh 腳本或後端配置檔案以檢視後端埠號的設置方式。您可能需要修改啟動命令或配置檔案以更改後端埠號。如果更改了後端埠號，您可能需要更新前端的 .env 檔案以指向新的後端 URL。

🔄 熱更新無法正常工作

熱更新（或稱熱模組替換 - HMR）是一個非常棒的開發功能，當您對代碼進行更改時，它會自動刷新瀏覽器。如果它無法正常工作，可能會大幅降低您的開發效率。

故障排除步驟：

確認開發伺服器正在執行： 確認前端的 npm run dev 和後端的 sh dev.sh 分別在各自的終端中執行，並且沒有報錯。檢查終端輸出中的消息以確認伺服器正在執行並處於“監視模式”或“開發模式”。如果有錯誤，請先解決它們。
檢查監視模式/HMR 消息： 當啟動開發伺服器時，它通常會在終端中打印出消息，表明熱更新或監視模式已啟用。查找類似於 "HMR enabled"、"watching for file changes" 的短語。如果未看到相關消息，可能是配置有問題。
瀏覽器快取： 有時候，瀏覽器的快取可能會阻止您看到最新的更改，即使熱更新正在工作。嘗試進行強制刷新：
- Windows/Linux： Ctrl+Shift+R
- macOS： Cmd+Shift+R
- 或者清除瀏覽器快取，或者在私密/無痕瀏覽窗口內打開前端。
前端依賴問題： 過期或損壞的前端依賴可能會影響熱更新。嘗試刷新前端依賴：
- 在前端終端中執行：
```
rm -rf node_modules && npm install
```
  此命令將刪除存儲依賴的 node_modules 資料夾，然後重新安裝依賴。這可以解決因損壞或過期的包引起的問題。
後端需重啟（針對後端更改）： 熱更新通常最適合前端代碼更改（UI、樣式、組件）。但對於後端代碼的重大更改（尤其是伺服器邏輯、API 端點或依賴的修改），可能需要手動重啟後端伺服器（在終端中停止 sh dev.sh 並重新執行該命令）。對後端更改的熱更新通常不太可靠或未自動配置。
IDE/編輯器問題： 在少數情況下，您的 IDE 或代碼編輯器可能會阻止代碼修改被開發伺服器正確檢測。嘗試重啟 IDE 或確認文件是否正確保存。
配置問題（進階）： 如果以上步驟均未解決，可能是前端或後端開發伺服器設置中的更複雜配置問題。檢查項目文檔、配置檔案（例如前端的 vite.config.js、後端伺服器配置檔案），或者向 Open WebUI 社群或維護者尋求幫助。

參與 Open WebUI 開發

我們熱烈歡迎您對 Open WebUI 的貢獻！您的幫助對於讓這個項目變得更好非常珍貴。下面是一個簡短的指南，幫助您順利而有效地參與貢獻流程：

了解項目結構： 花點時間熟悉項目的目錄結構，特別是 frontend 和 backend 資料夾。查看代碼、配置檔案和文檔，了解項目是如何組織的。
從小型貢獻開始： 如果您是項目的新手，建議先從一些小型貢獻開始，例如：
- 改進文檔： 修正錯別字、澄清說明、向文檔中添加更多內容。
- 修復漏洞： 解決已報告的漏洞或問題。
- 小型 UI 強化： 改進樣式、修正輕微佈局問題。這些小型的貢獻能讓您熟悉代碼庫和貢獻流程。
先討論大的更改： 如果您計劃實施重大新功能或進行大幅度修改，強烈建議您先與項目維護者或社群討論您的想法。 您可以通過以下方式進行：
- 在 GitHub 儲存庫上開設問題來提議您的功能或更改。
- 加入 Open WebUI 的社群頻道（如果有，請查看項目的 README 或網站上的鏈接），在其中討論您的想法。這樣可以確保您的貢獻符合項目的目標，避免在可能不被合併的功能上浪費精力。
為您的工作創建單獨分支： 切勿直接提交到 dev 分支。 為每個功能或漏洞修復創建新的分支。這種方式可以讓您的更改保持隔離，並使提交 Pull Request 更加方便管理。
- 要基於 dev 分支創建新分支（例如命名為 my-feature-branch）：
```
git checkout dev
git pull origin dev # 確保本地 dev 分支是最新的
git checkout -b my-feature-branch
```
頻繁提交變更並撰寫清晰的提交訊息： 在開發功能或修復錯誤時，請進行小而有邏輯的提交。撰寫清晰且簡明的提交訊息，解釋您進行了哪些變更以及原因。良好的提交訊息可以更容易理解變更歷史，是協作的關鍵。
- 良好的提交訊息範例：Fix: 修正後端設置文件中的文檔拼寫錯誤
- 良好的提交訊息範例：Feat: 實現了顯示基本資訊的使用者個人資料頁面
定期與 dev 分支保持同步： 在您的分支工作時，定期與 dev 分支的最新變更保持同步，以減少後續合併衝突的可能性：
```
git checkout dev
git pull origin dev
git checkout my-feature-branch
git merge dev
```
在進行 git merge 步驟時解決任何合併衝突。
在推送之前執行測試（如果可用）： 雖然本指引未詳細介紹 Open WebUI 的具體測試程序，但在推送您的程式碼之前執行任何可用的測試是個良好的習慣。檢查專案文檔或 package.json（前端）及後端文件中的測試相關命令（例如，npm run test，pytest 等）。執行測試有助於確保您的變更未引入回歸問題或破壞現有功能。
提交拉取請求（PR）： 完成您的工作後（已測試，如果適用），準備將您的變更提交到 GitHub 上 Open WebUI 儲存庫的 dev 分支中。
- 訪問 GitHub 上的 Open WebUI 儲存庫。
- 導航到您的分支。
- 點擊 “Contribute” 或 “Pull Request” 按鈕（通常是綠色的）。
- 填寫 PR 表格：
  - 標題： 為您的 PR 提供清晰的描述性標題，概述您的變更（例如，“Fix: 解決登入表單驗證問題”）。
  - 描述： 提供更詳細的變更描述，解釋您解決的問題（若有）以及其他相關上下文。如果有相關問題，請連結。
- 提交 PR。
專案維護者將審查您的拉取請求，提供反饋，並可能合併您的變更。請積極回應反饋，並準備根據要求進行修訂。

感謝您閱讀本綜合指南並對 Open WebUI 的貢獻感到興趣！我們期待看到您的貢獻並幫助您成為 Open WebUI 社群的一部分！ 🎉 祝編程愉快！

前置準備​

設置本地開發環境​

1. 克隆倉庫​

2. 前端設置（用戶界面）​

3. 後端設置（API 和服務）​

常見問題排查​

💥 "FATAL ERROR: Reached Heap Limit"（前端）​

⚠️ 端口衝突（前端與後端）​

🔄 熱更新無法正常工作​

參與 Open WebUI 開發​