OpenWebUI入门本身也不难,依然是需要依赖一些基础的硬件配置,部署完成就可以实现可视化管理满足用户的需求,当然也可以使用我们官网的一键部署免费试用很适合新手！
一、OpenWebUI 简介
OpenWebUI 是一款开源免费的 AI 模型可视化管理工具，专为 Ollama、OpenAI API 等模型运行器设计，提供直观的 Web 操作界面。其核心优势包括多模型兼容、内置 RAG 检索增强功能、用户权限管理、全平台适配(Windows/Linux/macOS)及离线运行能力，无需复杂命令行操作即可实现 AI 模型的部署、管理与交互，兼顾新手入门与企业级应用需求，是本地 AI 部署的首选可视化工具。
二、部署前置配置要求
(一)基础配置(满足核心功能运行)
操作系统：Windows 10/11 64 位、Ubuntu 20.04+、macOS 12+(无中文路径限制);
处理器：双核 CPU(推荐四核及以上，提升并发处理能力);
内存：≥8GB(运行单模型基础需求，多模型同时运行需 16GB+);
存储：机械硬盘预留≥20GB 空间(含工具安装包 + 基础模型存储);
软件依赖：Docker 20.10+(推荐部署方案)或 Python 3.11(手动部署专用，避免 3.12 + 版本)、Git;
网络要求：首次部署需联网下载镜像 / 依赖，后续支持离线运行。
(二)推荐配置(平衡性能与稳定性)
操作系统：与基础配置一致;
处理器：四核八线程 CPU(如 Intel i5/Ryzen 5 及以上);
内存：≥16GB(支持多模型并行加载，减少卡顿);
存储：SSD 预留≥50GB 空间(提升模型加载与文件读写速度);
软件依赖：Docker 24.0+、Git，NVIDIA 用户额外安装 CUDA 12.1+(启用 GPU 加速);
硬件增强：NVIDIA 显卡(显存≥6GB，支持 CUDA 加速，大幅提升模型推理速度)。
星宇智算官网支持免费部署立马安装！点击下方立即试用!
(三)企业级配置(多用户 / 高清场景)
操作系统：Ubuntu 22.04 LTS 或 Windows Server 2022;
处理器：八核十六线程 CPU(如 Intel i7/Ryzen 7 及以上);
内存：≥32GB(支持 10 人以上同时访问，多模型高负载运行);
存储：NVMe SSD≥100GB(适配大尺寸模型存储与高速读写);
软件依赖：Docker Compose/Kubernetes(集群部署)、CUDA 12.4+、cuDNN 8.9.x;
硬件增强：NVIDIA 显卡(显存≥12GB，如 RTX 3060/4070.支持 TensorRT 优化)。
三、详细部署与使用教程
(一)推荐方案：Docker 部署(适配 90% 用户，简单高效)
安装 Docker 环境
安装完成后，终端输入docker –version验证是否成功。
Windows：下载 Docker Desktop 并安装，启用 WSL2 功能(需重启电脑);
macOS：通过官网下载 Docker Desktop，Apple Silicon 用户需确保系统版本≥12.5;
Linux(Ubuntu)：执行以下命令安装：
sudo apt update && sudo apt install docker-ce docker-ce-cli containerd.io
sudo systemctl start docker && sudo systemctl enable docker
sudo usermod -aG docker $USER # 无需sudo运行Docker
拉取 OpenWebUI 镜像
完整版镜像(含预捆绑模型，推荐)：
docker pull ghcr.io/open-webui/open-webui:main
轻量版镜像(体积更小，首次使用自动下载模型)：
docker pull ghcr.io/open-webui/open-webui:main-slim
NVIDIA GPU 加速版(需提前安装 CUDA)：
docker pull ghcr.io/open-webui/open-webui:cuda
启动容器
关键参数说明：-p 3000:8080映射端口，-v实现数据持久化，–restart always设置开机自启。
基础启动(CPU 版，本地访问)：
docker run -d -p 3000:8080 -v open-webui:/app/backend/data –name open-webui –restart always ghcr.io/open-webui/open-webui:main
GPU 加速启动(NVIDIA 显卡)：
docker run -d -p 3000:8080 –gpus all -v open-webui:/app/backend/data –name open-webui –restart always ghcr.io/open-webui/open-webui:cuda
单用户模式(跳过登录，仅本地使用)：
docker run -d -p 3000:8080 -e WEBUI_AUTH=false -v open-webui:/app/backend/data –name open-webui –restart always ghcr.io/open-webui/open-webui:main
访问与初始化
启动成功后，浏览器访问http://localhost:3000.首次打开需注册管理员账户(数据本地存储，无隐私泄露风险)，完成后即可进入主界面。
(二)备选方案：Python 手动部署(低资源环境)
安装依赖环境
安装 Python 3.11(官网下载对应系统版本);
安装 Node.js 22.10+(前端编译依赖);
克隆项目仓库：
git clone https://github.com/open-webui/open-webui.git
cd open-webui
配置后端环境
# 进入后端目录
cd backend
# 安装依赖
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
# 解决跨域问题(本地测试必备)
sed -i ‘s/CORS_ALLOW_ORIGIN = os.environ.get(“CORS_ALLOW_ORIGIN”,”*”).split(“;”)/CORS_ALLOW_ORIGIN = os.environ.get(“CORS_ALLOW_ORIGIN”,”http://localhost:5173″).split(“;”)/g’ open_webui/config.py
配置前端环境
# 返回项目根目录
cd ..
# 复制配置文件
cp .env.example .env
# 安装前端依赖
npm install
# 启动前端开发服务
npm run dev
启动服务
Windows：双击backend/start_windows.bat启动后端;
Linux/macOS：执行sh backend/start.sh启动后端;
浏览器访问http://localhost:5173即可使用。
(三)基础使用流程
连接模型：在主界面进入 “设置”，选择模型提供者(如 Ollama)，填写模型地址(本地默认http://localhost:11434);
模型下载：在 “模型库” 中选择所需模型(如 llama3)，点击下载即可自动部署;
交互体验：在聊天界面输入问题，可调整温度、最大 tokens 等参数，支持文件上传、RAG 检索等功能;
用户管理：管理员可在 “控制台” 添加用户、分配权限，适合多用户共享环境。
四、常见问题 FAQ
Docker 容器无法连接本地 Ollama?
原因：容器内localhost指向自身，而非主机。解决方案：启动命令添加–add-host=host.docker.internal:host-gateway，模型地址填写http://host.docker.internal:11434.
模型下载缓慢或失败?
原因：默认从国外服务器下载。解决方案：改用国内镜像(如hf-mirror.com)手动下载模型，放置到~/.ollama/models目录;或在 Docker 启动时添加代理环境变量。
启动报错 “Python 版本不兼容”?
原因：使用 Python 3.12 + 或 3.10 以下版本。解决方案：卸载当前 Python，安装 3.11 版本，重新配置环境。
GPU 加速未生效，仍使用 CPU?
原因：CUDA 版本不匹配或未安装 GPU 版镜像。解决方案：确认 CUDA 版本≥12.1.拉取cuda标签镜像，启动命令添加–gpus all参数。
浏览器提示跨域错误?
原因：后端 CORS 配置限制。解决方案：按手动部署步骤修改config.py文件，或在启动命令中添加-e CORS_ALLOW_ORIGIN=”*”(Docker 部署)。
忘记管理员密码?
解决方案：删除 Docker 数据卷(docker volume rm open-webui)后重启容器，重新注册;手动部署需删除backend/data目录下的数据库文件。
all-MiniLM-L6-v2 模型下载失败?
原因：Hugging Face 访问受限。解决方案：从 hf-mirror 下载模型到本地，修改backend/open_webui/retrieval/utils.py，将model_repo_path改为本地路径。
部署后外部设备无法访问?
原因：默认仅监听本地端口。解决方案：Docker 启动时将端口映射改为-p 0.0.0.0:3000:8080.确保防火墙开放 3000 端口。
