准备为 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 目录），请确保你在那里。
```
# If you are not in the project root, run:
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 中，转到终端 > 新建终端（或使用 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 包安装器) 读取 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" # For Linux/macOS (bash, zsh)
# set NODE_OPTIONS=--max-old-space-size=4096 # For Windows (Command Prompt)
# $env:NODE_OPTIONS="--max-old-space-size=4096" # For Windows (PowerShell)
npm run dev
```
  选择适合你的操作系统和终端的命令。4096 表示 4GB 内存。如果需要，你可以尝试进一步增加此值（例如，8192 表示 8GB）。此设置仅适用于在当前终端会话中运行的命令。
修改 Dockerfile（用于 Dockerized 环境）
- 如果你在使用 Docker，可以在你的 Dockerfile 中永久设置 NODE_OPTIONS 环境变量。这对于 Dockerized 环境中的一致内存分配非常有用，如下面的原始指南示例所示
```
ENV NODE_OPTIONS=--max-old-space-size=4096
```
- 分配足够的内存： 无论采用哪种方法，请确保你的系统或 Docker 容器有足够的内存供 Node.js 使用。建议至少 4 GB 内存，对于大型项目或复杂构建可能需要更多。关闭不必要的应用程序以释放内存。

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

如果你看到与端口相关的错误，例如“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) 这些命令也会显示使用该端口的进程的 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 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 文件夹。查看代码、配置文件和文档，了解项目是如何组织的。
从小贡献开始： 如果你是该项目的新手，可以考虑从小处开始贡献，例如
- 改进文档： 修复错别字，澄清解释，为文档添加更多细节。
- 修复 Bug： 解决已报告的 Bug 或问题。
- 小的 UI 改进： 改进样式，修复小的布局问题。这些较小的贡献是熟悉代码库和贡献流程的好方法。
优先讨论较大更改： 如果你计划实现一个重要的新功能或进行实质性更改，强烈建议先与项目维护者或社区讨论你的想法。 你可以通过以下方式进行：
- 在 GitHub 仓库上开启一个 Issue 来提出你的功能或更改建议。
- 加入 Open WebUI 社区频道（如果可用，请查看项目的 README 或网站以获取链接）并在那里讨论你的想法。这有助于确保你的贡献符合项目的目标，并避免在可能不会被合并的功能上浪费精力。
为你的工作创建一个单独的分支： 绝不要直接提交到 dev 分支。 对于你正在进行的每一个功能或 Bug 修复，都要创建一个新的分支。这能使你的更改隔离，并更容易管理和提交拉取请求 (Pull Request)。
- 基于 dev 分支创建一个新分支（例如命名为 my-feature-branch）
```
git checkout dev
git pull origin dev # Ensure your local dev branch is up-to-date
git checkout -b my-feature-branch
```
频繁提交更改并编写清晰的提交消息： 在开发功能或修复 Bug 时，进行小的、有逻辑的提交。编写清晰简洁的提交消息，解释你做了哪些更改以及原因。良好的提交消息有助于更容易理解更改历史，并且对于协作至关重要。
- 一个好的提交消息示例：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)： 完成工作、测试完毕（如果适用）并准备贡献你的更改后，向 Open WebUI 在 GitHub 上的仓库的 dev 分支提交一个拉取请求 (PR)。
- 前往 Open WebUI 在 GitHub 上的仓库。
- 导航到你的分支。
- 点击“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​