准备好为 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。

🎉 访问前端：打开您的网络浏览器并访问 https://: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 文档，网址为 https://:8080/docs。这份文档对于理解后端 API 端点、如何与后端交互以及它期望和返回什么数据都非常有价值。在开发过程中请随时查阅这份文档！

🎉 恭喜！如果您已按照所有步骤操作，您现在应该已在本地运行着前端和后端开发服务器。回到您访问前端的浏览器选项卡（通常是 https://: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（适用于 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 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 仓库上提交一个 issue 来提出您的功能或更改。
- 加入 Open WebUI 社区渠道（如果可用，请查看项目的 README 或网站以获取链接）并在那里讨论您的想法。这有助于确保您的贡献与项目的目标保持一致，并避免在可能不会合并的功能上浪费精力。
为您的工作创建一个单独的分支：切勿直接提交到 dev 分支。始终为正在开发的每个功能或错误修复创建一个新分支。这可以使您的更改隔离，并更易于管理和提交拉取请求。
- 要基于 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
```
频繁提交更改并编写清晰的提交信息：在开发功能或修复错误时，进行小的、逻辑性的提交。编写清晰简洁的提交信息，解释您所做的更改以及原因。良好的提交信息有助于理解更改历史，对于协作至关重要。
- 良好提交信息的示例：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 分支提交一个拉取请求 (PR)。
- 前往 GitHub 上的 Open WebUI 仓库。
- 导航到您的分支。
- 点击“贡献”或“拉取请求”按钮（通常是绿色的）。
- 填写 PR 表单
  - 标题：为您的 PR 提供一个清晰且描述性的标题，总结您的更改（例如，“Fix: 解决了登录表单验证问题”）。
  - 描述：提供您的更改、您正在解决的问题（如果适用）以及任何相关上下文的更详细描述。如果存在任何相关问题，请链接到它们。
- 提交 PR。
项目维护者将审查您的拉取请求，提供反馈，并可能合并您的更改。请对反馈保持响应，并准备好在要求时进行修订。

感谢您阅读这份全面的指南，以及您对贡献 Open WebUI 的兴趣！我们很高兴看到您的贡献，并帮助您成为 Open WebUI 社区的一部分！ 🎉 祝您编程愉快！

先决条件​

设置本地环境​

1. 克隆仓库​

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

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

常见问题排除​

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

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

🔄 热重载不工作​

贡献给 Open WebUI​