学习 Open WebUI 源码（一）：本地开发部署

官方文档：Open WebUI Development Guide

系统要求：Linux or Mac

• Python 3.11+ (本机版本： 3.12.9)

• Nodejs 22.10+（本机版本：22.14.0）

0. 环境准备

# 1.使用 conda 创建 Python 虚拟环境
conda create -n open-webui python=3.11
conda activate open-webui
# 2.使用 nvm 安装 22.14.0
nvm install 22.14.0
nvm use 22.14.0

1. 克隆 github 仓库

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

2.前端设置

# 1.创建 .env 文件
cp -RPp .env.example .env
# 2.安装依赖
npm install 
# 3.运行 web 服务
npm run dev

一切顺利的话，打开浏览器在地址栏中输入 http://your.ubuntu.server:5173

但这个时候仍不能使用，Open WebUI 运行需要后端的支持

3.后端设置

# 1.进入 backend 文件夹
cd backend
# 2.安装依赖
pip install -r requirements.txt -U
# 3.启动
sh dev.sh

刷新浏览器，happy coding ~

如果不 happy 就继续往下看

4.踩坑

1. npm install 失败

   网上一堆教程，切换淘宝源(npm install --registry=https://registry.npm.taobao.org)，如果有代理就设置代理(npm config set proxy http://your.proxy.com:port && npm config set https-proxy http://your.proxy.com:port && npm install)

   我遇到的问题是下载 onnxruntime 失败

   #1.默认安装依赖只有一个 loading，先切换日志等级到 verbose
   npm install --verbose
   #2.查看是哪一个依赖安装失败,然后在 package.json 中注释/删掉后安装其他依赖，最后再手动安装出问题的依赖

2. 后端运行成功后，前端依然无法访问，打开浏览器控制台，发现出现了跨域访问问题

   # 1. 打开 open-webui/backend/open-webui/main.py:737 修改代码
   WEBUI_DEV_ORIGIN="your.webui.fontend.address:5173" # 改成真实前端运行地址
   app.add_middleware(
       CORSMiddleware,
       allow_origins=[WEBUI_DEV_ORIGIN], # 添加这一行
       allow_credentials=True,
       allow_methods=["*"],
       allow_headers=["*"],
   )
   # 顺手解决静态资源跨域访问问题
   # main.py:1194
   static_app = StaticFiles(directory=STATIC_DIR) # 定义 static_app
   static_app = CORSMiddleware(
       static_app,
       allow_origins=[WEBUI_DEV_ORIGIN],
       allow_credentials=True,
       allow_methods=["*"],
       allow_headers=["*"],) # 使用 CORS 中间件包裹
   ​
   app.mount("/static", static_app, name="static") # 挂载到 app 上

   这个时候刷新页面，应该就可以正常使用了，如果还有问题，那就打开 ChatGPT/DeepSeek/Copilot 一步一步解决即可