Skip to main content

准备好为 Open WebUI 贡献了吗？让我们开始吧！🚀

很高兴您能参与 Open WebUI 的开发！这份详尽的指南将引导您快速、轻松地搭建 本地开发环境。无论您是经验丰富的开发人员还是刚起步的新手，我们都将助您做好准备，以便调整前端、增强后端并为 Open WebUI 的未来做出贡献！让我们通过简单、详细的步骤让您的开发环境运行起来！

先决条件​

在开始之前，请确保您的系统满足以下最低要求：

  • 操作系统： Linux (或 Windows 上的 WSL)、Windows 11 或 macOS。(推荐以获得最佳兼容性)
  • Python： 版本 3.11 或更高。(后端服务所需)
  • Node.js： 版本 22.10 或更高。(前端开发所需)
  • IDE (推荐)： 我们推荐使用 VS Code 等 IDE 进行代码编辑、调试和集成终端访问。如果您有自己喜欢的 IDE，也可以随意使用！
  • [可选] GitHub Desktop： 为了更轻松地管理 Git 仓库，特别是如果您不太熟悉命令行 Git，可以考虑安装 GitHub Desktop。

搭建本地环境​

我们将同时搭建 Open WebUI 的前端（用户界面）和后端（API 和服务器逻辑）。

1. 克隆仓库​

首先，使用 git clone 将 Open WebUI 仓库下载到您的本地机器。这将在您的计算机上创建项目的本地副本。

  1. 打开您的终端（如果您在 Windows 上并使用 Git Bash，请打开 Git Bash）。
  2. 导航到您想要存储 Open WebUI 项目的目录。
  3. 克隆仓库： 运行以下命令：
git clone https://github.com/open-webui/open-webui.git
cd open-webui

git clone 命令从 GitHub 下载项目文件。cd open-webui 命令随后将您带入新创建的项目目录。

2. 前端设置 (用户界面)​

让我们先让用户界面（您在浏览器中看到的内容）运行起来：

  1. 配置环境变量：

    • 将示例环境文件复制到 .env：

      cp -RPp .env.example .env

      此命令将 .env.example 文件复制为一个名为 .env 的新文件。.env 文件是您为前端配置环境变量的地方。

    • 自定义 .env：在您的代码编辑器（如 VS Code）中打开 .env 文件。此文件包含前端的配置变量，例如 API 端点和其他设置。对于本地开发，.env.example 中的默认设置通常足以启动。但是，如果需要，您可以对其进行自定义。

重要提示： 如果您要向仓库贡献代码，请勿将敏感信息提交到 .env。

  1. 安装前端依赖项：

    • 导航到前端目录： 如果您尚未处于项目根目录（open-webui 目录），请确保您在那里。

      # 如果您不在项目根目录，请运行：
      cd open-webui

    • 安装所需的 JavaScript 包：

      npm install

      这将安装 package.json 中列出的所有前端依赖项。

      注意：根据您的 Open WebUI 版本，您可能会看到兼容性警告或错误。如果是这样，只需运行：

      npm install --force

      某些设置需要这样来绕过版本问题。

  2. 启动前端开发服务器：

    npm run dev

    此命令启动前端开发服务器。如果步骤执行成功，通常会指示服务器正在运行并提供一个本地 URL。

    🎉 访问前端： 打开您的 Web 浏览器并访问 http://localhost:5173。您应该会看到一条消息，指出 Open WebUI 的前端正在运行并等待后端可用。现在先不用担心该消息！接下来让我们设置后端。保持此终端运行 —— 它正在为您的前端提供服务！

2.5: 构建前端 (推荐)​

一旦您验证了前端开发服务器 (npm run dev) 运行正常，并且可以在 http://localhost:5173 看到 Open WebUI，最佳实践是同时也构建前端资源。此步骤模拟生产环境，可以帮助捕捉开发期间未显示的构建时错误。

在同一个前端终端中：

npm run build
  • 此命令生成优化后的、生产就绪的前端构建版本，并将静态文件放在 build 目录中。
  • 如果构建成功完成（没有错误），您就准备好了！如果有错误，请在继续之前解决它们。
  • 在本地开发中，您不需要对 build 目录做更多操作，但构建可以确保您的代码在生产或部署期间不会出错。

3. 后端设置 (API 和服务器)​

我们 要求 您为前端和后端进程使用单独的终端实例。这可以保持您的工作流井然有序，并更轻松地独立管理应用程序的各个部分。

使用 VS Code 集成终端：

VS Code 的集成终端功能使管理多个终端变得极其简单。以下是如何利用它来实现前后端分离：

  1. 前端终端（您可能已经有了）： 如果您按照前端设置步骤操作，您可能已经在 VS Code 中打开了一个位于项目根目录（open-webui 目录）的终端。这是您运行前端命令（npm run dev 等）的地方。如果还没在 open-webui 目录，请确保接下来的步骤在此目录下。

  2. 后端终端（打开一个新终端）：

    • 在 VS Code 中，转到 终端 > 新终端（或使用快捷键 Ctrl+Shift+ Windows/Linux 或 Cmd+Shift+ macOS）。这将打开一个新的集成终端面板。
    • 导航到 backend 目录： 在这个 新 终端中，使用 cd backend 命令切换到项目内的 backend 文件夹。这确保所有与后端相关的命令都在正确的上下文中执行。

    现在您在 VS Code 中拥有两个独立的终端实例：一个用于前端（通常在 open-webui 目录中），另一个专门用于后端（在 backend 目录中）。您可以在 VS Code 内轻松地在这些终端之间切换，以独立管理您的前端和后端进程。强烈建议采用此设置，以获得更整洁、更高效的开发工作流。

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

  1. 导航到后端目录：（在上一步中，您应该已经在 新 终端中处于 backend 目录了）。如果不是，请运行：

    cd backend

  2. 创建并激活 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：此命令创建一个名为 open-webui 的新 Conda 环境，使用 Python 3.11 版本。如果您选择了不同的 Python 3.11.x 版本也可以。
      • conda activate open-webui：此命令激活新创建的 Conda 环境。一旦激活，您的终端提示符通常会更改以指示您处于 open-webui 环境中（例如，它可能在行首显示 (open-webui)）。

    在继续之前，请确保在后端终端中激活了环境。

    (使用 Conda 是可选的，但强烈建议用于管理 Python 依赖项和避免冲突。) 如果您选择不使用 Conda，请确保您使用的是 Python 3.11 或更高版本并继续下一步，但请注意潜在的依赖冲突。

  3. 备选方案：创建并激活 Python venv：

    如果您更喜欢使用 Python 内置的 venv 模块而不是 Conda，请按照以下步骤操作：

    • 创建虚拟环境： 
      python3 -m venv venv
    • 激活虚拟环境：
      • Linux/macOS: 
        source venv/bin/activate
      • Windows: 
        .\venv\Scripts\activate

    一旦激活，您的终端提示符应显示 (venv)。您现在可以继续安装依赖项。

  4. 安装后端依赖项：

    • 在您的 后端 终端中（如果您使用 Conda，请确保已激活环境），运行：
    pip install -r requirements.txt -U

    此命令使用 pip（Python 包安装程序）读取 backend 目录中的 requirements.txt 文件。requirements.txt 列出了后端运行所需的所有 Python 库。pip install 将这些库下载并安装到您的活动 Python 环境中（如果您使用 Conda 环境，则安装到该环境中，否则安装到系统范围的 Python 环境中）。-U 标志确保您获得库的最新兼容版本。

  5. 启动后端开发服务器：

    • 在您的 后端 终端中，运行：
    sh dev.sh

    此命令执行 dev.sh 脚本。此脚本可能包含启动后端开发服务器的命令。(如果您感兴趣，可以在代码编辑器中打开并查看 dev.sh 文件以查看正在运行的确切命令。) 后端服务器通常会启动并向终端打印一些输出。

    📄 探索 API 文档： 一旦后端运行起来，您可以在 Web 浏览器中访问自动生成的 API 文档，地址为 http://localhost:8080/docs。这些文档对于了解后端 API 端点、如何与后端交互以及它预期和返回的数据非常有用。在开发时请随身携带这些文档！

🎉 恭喜！ 如果您按照所有步骤操作，您现在应该已经在本地运行了前端和后端开发服务器。回到您访问前端的浏览器标签页（通常是 http://localhost:5173）。刷新页面。 您现在应该可以在浏览器中看到完整的 Open WebUI 应用程序正在运行，并已连接到您的本地后端！

从另一台设备测试 (手机、平板电脑等)​

想从您的手机或同一 Wi-Fi 下的另一台电脑打开您的开发实例吗？

  1. 找到您开发机器的局域网 IP，例如 192.168.1.42。
  2. 仅前端 (快速检查)：
    • 保持后端在 localhost。
    • 从您的手机访问 http://192.168.1.42:5173。
  3. 全栈 (前端 + 后端)：

    • 在 backend/dev.sh 中 将您的局域网地址添加到 CORS 列表，例如：

      export CORS_ALLOW_ORIGIN="http://localhost:5173;http://localhost:8080;http://192.168.1.42:5173"

    • 重启后端 (sh dev.sh)。