准备为 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 仓库，特别是如果您对命令行 Git 不太熟悉，可以考虑安装 GitHub Desktop。

设置您的本地环境

我们将设置 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 Manager）读取项目根目录中的 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 中，转到 Terminal > New Terminal（或使用快捷键 Windows/Linux 上的 Ctrl+Shift+ 或 macOS 上的 Cmd+Shift+）。这将打开一个新的集成终端面板。
- 导航到 backend 目录： 在这个新终端中，使用 cd backend 命令将目录更改为项目中的 backend 文件夹。这确保所有后端相关命令都在正确的上下文中执行。
现在您在 VSCode 中有两个单独的终端实例：一个用于前端（可能在 open-webui 目录中），一个专门用于后端（在 backend 目录内）。您可以在 VSCode 中轻松切换这些终端，独立管理前端和后端进程。强烈推荐此设置，以获得更清洁、更高效的开发工作流程。

后端设置步骤（在您的后端终端中）：

导航到后端目录：（从前面的步骤，您应该已经在新终端的 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 Package Installer）读取 backend 目录中的 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 (Command Prompt)
# $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 使用。建议至少 4 GB RAM，大型项目或复杂构建可能需要更多。关闭不必要的应用程序以释放 RAM。

⚠️ 端口冲突（前端和后端）

如果您看到与端口相关的错误，如"地址已在使用中"或"端口已绑定"，这意味着您系统上的另一个应用程序已经在使用端口 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）这些命令也会显示使用端口的进程的 PID。
终止冲突进程： 一旦识别出进程 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"、"监视文件更改"或类似的短语。如果您没有看到这些消息，可能存在配置问题。
浏览器缓存： 有时，即使热重载正在工作，浏览器的缓存也可能阻止您看到最新更改。尝试在浏览器中进行硬刷新：
- 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 仓库上开启一个 issue 来提出您的功能或更改。
- 加入 Open WebUI 社区频道（如果可用，请查看项目的 README 或网站获取链接）并在那里讨论您的想法。这有助于确保您的贡献与项目目标一致，并避免在可能不会合并的功能上浪费精力。
为您的工作创建单独的分支： 永远不要直接提交到 dev 分支。 始终为您正在工作的每个功能或错误修复创建一个新分支。这使您的更改保持隔离，并使管理和提交拉取请求更容易。
- 要基于 dev 分支创建新分支（例如，名为 my-feature-branch）：
```
git checkout dev
git pull origin dev # 确保您的本地 dev 分支是最新的
git checkout -b my-feature-branch
```
频繁提交更改并编写清晰的提交消息： 在开发功能或修复错误时进行小的、逻辑性提交。编写清晰简洁的提交消息，解释您做了什么更改以及为什么。好的提交消息使理解更改历史更容易，对协作至关重要。
- 好提交消息的示例：Fix: Corrected typo in documentation for backend setup
- 好提交消息的示例：Feat: Implemented user profile page with basic information display
定期与 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 分支提交拉取请求（PR）。
- 转到 GitHub 上的 Open WebUI 仓库。
- 导航到您的分支。
- 点击"Contribute"或"Pull Request"按钮（通常是绿色的）。
- 填写 PR 表单：
  - 标题： 为您的 PR 提供清晰描述性的标题，总结您的更改（例如，"Fix: Resolved issue with login form validation"）。
  - 描述： 提供更详细的更改描述、您正在解决的问题（如果适用）以及任何相关上下文。如果有相关 issue，请链接到它们。
- 提交 PR。
项目维护者将审查您的拉取请求，提供反馈，并可能合并您的更改。对反馈要有响应，并准备好在请求时进行修订。

感谢您阅读这份综合指南并对为 Open WebUI 做贡献感兴趣！我们很兴奋看到您的贡献，并帮助您成为 Open WebUI 社区的一部分！ 🎉 祝编码愉快！

先决条件​

设置您的本地环境​

1. 克隆仓库​

2. 前端设置（用户界面）​

3. 后端设置（API 和服务器）​

常见问题故障排除​

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

⚠️ 端口冲突（前端和后端）​

🔄 热重载不工作​

为 Open WebUI 做贡献​