1. 为什么要在完全离线环境跑 Open WebUIOpen WebUI 是一个可扩展、功能丰富且用户友好的本地部署 AI 平台支持完全离线运行。它本质上是一套跑在你自己机器上的网页聊天前端后端可以接 Ollama 本地模型也可以接任何 OpenAI 兼容接口。对普通用户来说它把「命令行里敲 ollama run」变成了「打开浏览器点几下就能对话」对团队来说它提供了用户分组、模型权限、RAG 文档检索、Pipelines 插件这些能落地的能力。我关注它的核心原因是离线。很多场景下网络并不稳定或者数据根本不允许出内网比如工厂质检报告、医院病历摘要、律所合同比对这些内容一旦上传到外部接口就没法交代。Open WebUI 配合本地 Ollama从模型权重到对话记录全部留在本机磁盘上拔掉网线照样能跑。这一点是云端聊天工具给不了的。适合谁用三类人最合适。第一类是手里有显卡、想给自己搭一个私人 ChatGPT 的开发者第二类是需要给团队内网提供统一 AI 入口的运维或技术负责人第三类是做 AI 应用原型、需要快速验证 RAG 和插件逻辑的产品同学。如果你只是想随便聊两句云端工具更省事但只要你开始在意数据边界、模型可控、长期成本本地部署就是绕不开的一步。这篇会从零交付一套可复制的 Docker 启动配置、模型接入参数和离线验证步骤。我会把踩过的坑直接写进排障章节你照着敲命令就能确认本地 AI 平台是否真的可用。整个流程不依赖任何特殊网络手段全部在本地回环地址内完成。2. 前置准备Docker、Ollama 与 TaoToken 接入参数在启动 Open WebUI 之前先把三样东西理清楚容器运行时、本地模型服务、以及可选的远程模型接入通道。Docker 是基础。Windows 和 macOS 装 Docker DesktopLinux 用官方脚本或包管理器装 docker-ce 即可。装完执行docker version能看到 Client 和 Server 两段输出说明守护进程正常。如果只有 Client 没有 Server多半是没启动服务或当前用户不在 docker 组里。Ollama 负责在本地跑模型。它的默认监听地址是127.0.0.1:11434这个端口后面要填进 Open WebUI 的环境变量。装好后先拉一个小模型验证比如ollama pull qwen2.5:7b再ollama run qwen2.5:7b随便问一句确认模型能出字。这一步别跳过很多人后面连不上其实是 Ollama 本身没跑起来。如果你除了本地模型还想接入更强的云端模型做对比或兜底可以用 TaoToken 这类 OpenAI 兼容通道。它的 API 地址是https://taotoken.net/api在 Open WebUI 里作为「OpenAI 兼容」连接添加即可。注意这里填的是 API 根地址不是网页地址。API Key 在控制台生成模型 ID 按文档里列出的名称填。这样你就有两条腿本地模型保离线远程通道保能力上限。需要提前记下的参数清单参数值用途Ollama 地址http://host.docker.internal:11434容器访问宿主机 OllamaOpen WebUI 端口3000浏览器访问入口数据卷open-webui:/app/backend/data持久化对话与配置OpenAI 兼容 Base URLhttps://taotoken.net/api远程模型接入离线开关HF_HUB_OFFLINE1阻止联网下载把这些准备好后面的命令基本就是填空。我建议你先在纸上或记事本里写下自己的 Ollama 地址和端口避免复制命令时改错。3. 可复制配置Docker 启动与模型接入参数这一节是全文的核心所有命令都可以直接复制。先给最常用的默认配置它会让 Open WebUI 自动连接宿主机的 Ollama。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--add-host这行是关键它让容器内的host.docker.internal指向宿主机。没有它容器里的 Open WebUI 找不到你本机的 Ollama。启动后访问http://localhost:3000第一次进入会让你注册一个管理员账号这个账号只存在本地数据库里。如果你的 Ollama 跑在另一台机器上把地址换成实际 IPdocker run -d -p 3000:8080 \ -e OLLAMA_BASE_URLhttp://192.168.1.50:11434 \ -v open-webui:/app/backend/data \ --name open-webui \ --restart always \ ghcr.io/open-webui/open-webui:main有 NVIDIA 显卡并装了容器工具包的用 CUDA 镜像标签并加上--gpus alldocker run -d -p 3000:8080 --gpus all \ --add-hosthost.docker.internal:host-gateway \ -v open-webui:/app/backend/data \ --name open-webui \ --restart always \ ghcr.io/open-webui/open-webui:cuda只想用远程 OpenAI 兼容接口、不跑本地模型的直接注入 Keydocker run -d -p 3000:8080 \ -e OPENAI_API_KEY你的Key \ -v open-webui:/app/backend/data \ --name open-webui \ --restart always \ ghcr.io/open-webui/open-webui:main如果你希望 Ollama 和 Open WebUI 打包在一个容器里用集成镜像省去单独装 Ollamadocker run -d -p 3000:8080 --gpusall \ -v ollama:/root/.ollama \ -v open-webui:/app/backend/data \ --name open-webui \ --restart always \ ghcr.io/open-webui/open-webui:ollama没有 GPU 就把--gpusall去掉其余不变。容器跑起来后进入「设置 → 连接」可以手动维护模型来源。OpenAI 兼容连接的配置片段如下字段名与界面一致{ enable_openai_api: true, openai_api_base: https://taotoken.net/api, openai_api_key: sk-你的Key, model_ids: [按文档填写的模型ID] }Ollama 连接则填{ enable_ollama_api: true, ollama_base_url: http://host.docker.internal:11434 }保存后点一下刷新模型列表里应该同时出现本地模型和远程模型。如果只想离线把 OpenAI 那段关掉即可不影响本地使用。离线模式还要加一个环境变量防止 HuggingFace 相关组件尝试联网下载export HF_HUB_OFFLINE1在 Docker 里则写成-e HF_HUB_OFFLINE1。这个开关对 RAG 嵌入模型尤其重要否则首次使用文档检索时它会去外网拉模型离线环境下会卡住。4. 验证请求确认本地 AI 平台真的可用配置写完必须验证不然只是「看起来跑起来了」。验证分三层容器活着、模型列表能拉到、对话能出字。第一层看容器状态docker ps --filter nameopen-webui输出里 STATUS 应该是Up开头。如果显示Restarting说明启动就崩了去看日志docker logs --tail 100 open-webui第二层确认 Ollama 从容器内可达。进容器里敲一条 curldocker exec -it open-webui curl http://host.docker.internal:11434/api/tags正常会返回一段 JSON里面列出你本地已拉取的模型名。如果这里报连接拒绝问题一定在 Ollama 地址或网络模式上跟 Open WebUI 本身无关。第三层在浏览器里发一条真实请求。打开http://localhost:3000左上角选一个本地模型输入「用一句话解释什么是本地部署」回车。能正常流式输出就说明整条链路通了。我实测下来7B 级别的模型在消费级显卡上首字延迟通常在一两秒内纯 CPU 会慢一些但也能出结果。再验证一次离线能力把网线拔掉或禁用网络适配器刷新页面重新发一条消息。如果还能正常回答说明模型和前端都在本地闭环没有偷偷依赖外部服务。这一步是很多人忽略的但恰恰是「离线运行」的最终证明。远程通道的验证单独做一次在模型下拉里选 TaoToken 提供的模型发一条消息确认返回正常。这样你就同时拥有了离线兜底和远程增强两种能力。验证模型对话可以直接在模型对话页面里切换对比不需要改任何配置。5. 常见报错排查401、local proxy failed 与 reading choices排障章节按真实报错来写遇到对应关键字直接对号入座。401 Unauthorized。这个几乎都出在远程 OpenAI 兼容连接上。原因有三种Key 填错、Key 前后带了空格、Base URL 写成了网页地址而不是 API 地址。检查openai_api_base是否以/api结尾Key 是否完整。改完保存后要重新点刷新旧连接不会自动重载。local proxy failed / connection refused。这是容器访问不到 Ollama 的典型症状。默认配置下容器和宿主机网络是隔离的127.0.0.1在容器里指向容器自己不是你的电脑。解决办法有两个加--add-hosthost.docker.internal:host-gateway并把地址写成host.docker.internal或者直接用 host 网络模式docker run -d --networkhost \ -v open-webui:/app/backend/data \ -e OLLAMA_BASE_URLhttp://127.0.0.1:11434 \ --name open-webui \ --restart always \ ghcr.io/open-webui/open-webui:mainhost 模式下端口映射参数失效直接访问 8080 即可。Error reading choices / 返回体解析失败。这个报错说明请求发出去了但返回的 JSON 结构不符合 OpenAI 规范。常见于接了一些非标准接口或者模型 ID 填错导致服务端返回了错误对象。先确认模型 ID 与文档完全一致再检查接口是否真的兼容/v1/chat/completions。如果用的是自建服务抓一次返回体看字段名。OAuth 相关报错。如果你配置了单点登录回调地址必须和实际访问地址一致。用localhost注册的应用不能用127.0.0.1登录反之亦然。离线环境一般用不到 OAuth直接本地账号即可。模型列表为空。先确认 Ollama 里有模型ollama list能看到再确认连接开关是打开的最后看容器日志有没有拉取超时。离线环境下如果开了 RAG嵌入模型缺失也会导致部分功能异常记得把HF_HUB_OFFLINE1和本地嵌入模型路径配好。容器反复重启。多半是数据卷权限或端口占用。换一个宿主端口比如-p 3001:8080再试。数据卷损坏的话删掉容器重建卷里的对话记录会保留。排查时记住一个顺序先看容器日志再看容器内 curl最后看浏览器控制台。三层定位下来问题基本跑不掉。6. 长期使用与扩展把本地 AI 平台用起来跑通只是开始真正决定体验的是后续怎么用。Open WebUI 的扩展点不少挑几个最实用的说。RAG 文档检索是高频功能。在对话里用#加文档名就能触发检索前提是先在「工作空间 → 文档」里上传文件。离线环境下嵌入模型要提前准备好否则上传后无法建立索引。文档量大时建议单独挂一块盘存向量数据。Pipelines 插件系统可以注入自定义 Python 逻辑比如内容过滤、多语言翻译、函数调用。它跑在独立进程里通过环境变量PIPELINES_URLS挂载。写插件时注意别把生产数据库直连进去用只读副本或测试库。多模型会话适合做对比评测。同一个问题让本地模型和远程模型各答一遍人工看差异。这个功能在选型阶段特别省事不用来回切页面。长期运行建议配 Watchtower 做镜像更新但离线环境要谨慎更新会拉新镜像。更稳妥的做法是固定镜像标签手动在维护窗口升级。数据卷一定要定期备份open-webui卷里存着所有对话和用户配置丢了很麻烦。如果你要给团队用把 Open WebUI 放在内网反向代理后面配好 HTTPS 和访问控制。用户分组和模型权限在管理面板里设置普通成员只能看到被授权的模型。这样既统一了入口又不会让所有人乱拉模型把显存占满。最后提醒一句离线部署的价值在于可控但可控也意味着你要自己承担模型更新、安全补丁和硬件维护。把它当成一个长期运行的服务来对待而不是装完就忘的玩具。需要长期编码或 Agent 场景的可以了解 Coding Plan只想快速验证模型效果的模型对话入口更直接接入和排障过程中需要生成 Key 的去 API Keys 页面操作即可接入细节以接入文档为准。