Open WebUI 部署指南：新手 5 分钟跑通本地 AI 对话界面-平芜编程栈

Open WebUI 部署指南：新手 5 分钟跑通本地 AI 对话界面

【免费下载链接】open-webuiUser-friendly AI Interface (Supports Ollama, OpenAI API, ...)项目地址: https://gitcode.com/GitHub_Trending/op/open-webui

Open WebUI 是一个自托管的 AI 对话界面，支持接入 Ollama 和 OpenAI API 兼容的模型服务。它解决的问题很直接：本地大模型往往只提供一个 API，而 Open WebUI 给它配上一个带网页端、可多人使用、能完全离线运行的对话界面。刚接触本地大模型的个人用户，以及需要在内网做私有部署的团队，都可以用这份指南完成安装与部署。

部署前检查

开始之前，先花两分钟确认下面几项，能省掉后面大部分的排查时间。

需要确认什么	为什么需要	怎么确认
容器运行时是否可用	Docker 是推荐的安装方式，装不了它就只能走 Python 环境	终端运行`docker --version`，能看到版本号即可
目标端口是否空闲	端口被占用时容器起不来，服务无法访问	用`netstat -tlnp`或`ss -tlnp`查看 3000、8080 是否已被占用
磁盘剩余空间	镜像、模型文件和数据都要落地，空间不足会在中途失败	用`df -h`查看挂载数据卷的目录所在分区
Ollama 服务是否在运行	Open WebUI 本身不产生回复，模型调用都依赖它	终端运行`ollama list`，能看到模型列表才算正常
机器是否装了 NVIDIA 驱动	想用 GPU 加速，驱动和容器工具包缺一不可	运行`nvidia-smi`，能看到显卡信息即可

安装方式怎么选

方式	适用场景	特点
Docker 容器	新手、服务器、生产环境	一条命令拉镜像就能跑，数据靠卷挂载保存，升级时重建容器即可
Python pip	已有 Python 环境、不想装容器	直接装到本机解释器里，端口和环境都依赖本机配置
源码构建	要改代码、参与开发	克隆仓库后本地构建，部署前需要额外装前端依赖

新手建议直接用 Docker；机器上已经有 Python 环境的话，走 pip 也足够用。

分步部署

第 1 步：确认 Docker 可用

目的：确认容器运行时能正常工作，装错版本后面全白费。

命令：查看 Docker 版本。

docker --version

预期结果：终端输出类似Docker version 2x.x.x, build xxx。看不到版本号就先把 Docker 装好再往下走。

第 2 步：拉取 Open WebUI 镜像

目的：把镜像提前下到本地，避免启动时边下载边等待，也方便离线机复用。

命令：拉取官方主版本镜像。

docker pull ghcr.io/open-webui/open-webui:main

预期结果：出现下载进度并最终提示完成；镜像已存在时会提示 layer 已就绪，两种情况都算通过。

第 3 步：启动容器

目的：把服务跑起来，同时把端口映射和数据保存一次配好。

命令：运行容器。其中-p 3000:8080把容器内 8080 端口暴露到宿主机 3000；--add-host=host.docker.internal:host-gateway让容器能访问宿主机上的 Ollama；-v open-webui:/app/backend/data把数据挂到具名卷，参数说明见下文持久化一节。

docker run -d -p 3000:8080 --add-host=host.docker.internal:host-gateway -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:main

预期结果：命令返回容器 ID；浏览器打开http://localhost:3000，能看到登录页和聊天界面，部署就算成功。如果想在 Python 环境里跑，沿用第 3 步同样的端口逻辑，改用下面两条命令：

pip install open-webui python -m open_webui

启动后访问http://localhost:8080，看到同样的界面即可。

第 4 步：接入 Ollama

目的：让 Open WebUI 找到模型服务，否则界面里没有任何模型可选。

命令：Ollama 和容器部署在同一台机器上、且第 3 步用了默认参数时，不需要额外操作。Ollama 在别的机器上时，重新建容器时加一个-e OLLAMA_BASE_URL参数指向远程地址，比如：

docker run -d -p 3000:8080 --add-host=host.docker.internal:host-gateway -v open-webui:/app/backend/data -e OLLAMA_BASE_URL=https://your-ollama-server.com --name open-webui --restart always ghcr.io/open-webui/open-webui:main

也可以登录后在 Settings 页面直接填写服务地址，效果一样。

预期结果：模型列表里出现 Ollama 上的模型，选中后能发出第一条对话。

第 5 步：确认数据落盘

目的：验证聊天记录和配置确实写进了数据卷，而不是只存在容器里。

命令：沿用第 3 步的卷挂载配置，重启容器后检查卷里生成的文件。

docker restart open-webui docker volume inspect open-webui

预期结果：卷内能看到vector_db、webui.db和上传目录；重启完成后再打开网页，之前的会话还在。

接入与持久化

后端服务怎么接

Open WebUI 自己不跑模型，它负责界面，推理交给后端模型服务。接入方式就两个：启动时通过环境变量OLLAMA_BASE_URL指定 Ollama 地址，或者用 OpenAI 兼容 API 时在界面 Settings 里填 Base URL 和 API Key。容器场景下，--add-host=host.docker.internal:host-gateway是关键，它保证容器内能用这个主机名访问宿主机的服务。

数据怎么保存

-v open-webui:/app/backend/data这一项挂载决定了一切：聊天记录、用户账号、上传的文件都存在这个卷里。删掉容器重建，数据不动；反过来，如果没做这步挂载，容器一删数据全丢。需要迁移或备份时，直接对整个数据卷做备份即可。

验证清单

逐项打勾，全部通过才算部署完成：

浏览器打开http://localhost:3000，能看到登录页和聊天界面
能完成注册/登录，创建第一个账号
模型列表里出现了 Ollama 的模型
发出一条消息，能看到流式回复
数据卷中已有webui.db和上传目录
重启容器后，之前的会话依然存在

常见问题

Q1：页面能打开，但发消息一直转圈或提示连接失败。现象描述：界面正常，模型调用超时。解法：多数是 Ollama 没在运行，或OLLAMA_BASE_URL填错。先确认ollama list能正常输出，再检查配置里的地址和端口；容器连宿主机场景要确认第 3 步的--add-host参数没有漏掉。

Q2：容器起不来，提示端口已被占用。现象描述：启动报错，或访问时连到的是别的程序。解法：换外部端口即可，沿用第 3 步命令，仅把-p 3000:8080替换为-p 8080:8080，访问地址跟着换成http://localhost:8080。

Q3：模型列表是空的。现象描述：能登录，但下拉框里没有任何模型。解法：先确认 Ollama 端本身有模型（ollama list），再检查服务地址配置。地址对了还是空的话，看容器日志排查网络。

Q4：重启容器后聊天记录不见了。现象描述：升级或重建容器后会话全丢。解法：检查启动参数里是否带了-v open-webui:/app/backend/data。没挂卷时数据写在容器内部层，容器一删就没了，补上挂载后重新登录即可。