Open WebUI 部署指南新手 5 分钟跑通本地 AI 对话界面【免费下载链接】open-webuiUser-friendly AI Interface (Supports Ollama, OpenAI API, ...)项目地址: https://gitcode.com/GitHub_Trending/op/open-webuiOpen 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-hosthost.docker.internal:host-gateway让容器能访问宿主机上的 Ollama-v open-webui:/app/backend/data把数据挂到具名卷参数说明见下文持久化一节。docker run -d -p 3000:8080 --add-hosthost.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-hosthost.docker.internal:host-gateway -v open-webui:/app/backend/data -e OLLAMA_BASE_URLhttps://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-hosthost.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。没挂卷时数据写在容器内部层容器一删就没了补上挂载后重新登录即可。进阶与收尾可选能力简单带过GPU 加速装好 NVIDIA 驱动和容器工具包后把镜像标签从main换成cuda并在命令里加--gpus all。离线部署环境不通外网时提前把镜像导出导入并设置HF_HUB_OFFLINE1阻止组件联网下载。最后三条运维建议数据卷定期备份webui.db和上传目录丢了账号和会话都找不回来。用 watchtower 之类的工具盯镜像更新重建容器时保留卷挂载。部署到内网多用户环境时配好访问控制和网络隔离别把管理入口直接暴露出去。更多配置项可查 docs/official.md功能实现源码在 backend/open_webui/。【免费下载链接】open-webuiUser-friendly AI Interface (Supports Ollama, OpenAI API, ...)项目地址: https://gitcode.com/GitHub_Trending/op/open-webui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考