OpenWebUI本地开发指南

原创于 2025-11-12 10:27:57 发布 · 299 阅读

3 ·

CC 4.0 BY-SA版权

文章标签：

#人工智能

AI 专栏收录该内容

86 篇文章

订阅专栏

一、环境准备

操作系统：Linux / macOS / Windows 11（Windows 建议 WSL）
Python ≥ 3.11（后端需要）
Node.js ≥ 22.10（前端需要）

二、获取代码

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

三、前端（frontend）启动

复制并修改环境变量（多数场景默认即可）：

cp -RPp .env.example .env

安装依赖并启动开发：

npm install
# 如遇到版本兼容告警/冲突：
# npm install --force
npm run dev

访问前端开发地址：http://localhost:5173（此时可能提示“等待后端”属正常）。

建议再做一次构建确保产物可编译：

npm run build

四、后端（backend）启动

建议使用独立终端：

# 新开一个终端
cd backend

# 强烈建议使用 Conda 隔离 Python 依赖
conda create --name open-webui python=3.11
conda activate open-webui

# 安装依赖
pip install -r requirements.txt -U

# 启动后端开发脚本
sh dev.sh

后端起完后，可在 http://localhost:8080/docs 打开自动生成的 API 文档。

五、同网设备联调（手机/另一台电脑）

前端仅查看：找出开发主机局域网 IP（如 192.168.1.42），手机浏览器访问 http://192.168.1.42:5173

前后端都要通时，在 backend/dev.sh 加入你的局域网来源到 CORS 白名单并重启后端：

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

windows下指令：

set CORS_ALLOW_ORIGIN=http://localhost:5173;http://localhost:8080;http://192.168.1.42:5173

六、编译成docker镜像

linux脚本：

#!/bin/bash

image_name="open-webui"
container_name="open-webui"
host_port=3000
container_port=8080

docker build -t "$image_name" .
docker stop "$container_name" &>/dev/null || true
docker rm "$container_name" &>/dev/null || true

docker run -d -p "$host_port":"$container_port" \
    --add-host=host.docker.internal:host-gateway \
    -v "${image_name}:/app/backend/data" \
    --name "$container_name" \
    --restart always \
    "$image_name"

docker image prune -f

windows脚本：

set image_name=open-webui
set container_name=open-webui
set host_port=3000
set container_port=8080

docker build -t "%image_name%" .
docker stop "%container_name%" >nul 2>&1
docker rm "%container_name%" >nul 2>&1
docker run -d -p %host_port%:%container_port% ^
    --add-host=host.docker.internal:host-gateway ^
    -v "%image_name%:/app/backend/data" ^
    --name "%container_name%" ^
    --restart always ^
    "%image_name%"

docker image prune -f