企业官网建设流程全解析

Open WebUI 本地部署 3 分钟跑通：完全离线的多模型 AI 对话界面

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

公司内网完全断网，却要在周五前给团队一个能切换模型、能传文档的对话界面，还不能写一行前端代码。Open WebUI 本地部署解决的就是这件事。它是一个自托管的 AI 对话 Web 界面：对话记录、上传文件、向量数据全部落在本地 Docker 卷里，不经过任何第三方服务。边界讲清楚：它不做模型推理，模型服务（Ollama 或 OpenAI 兼容 API）得你自备，它负责界面、RAG 检索（检索增强生成，即让模型先查你的文档再回答）和存数据。跑起来后浏览器打开 3000 端口，顶部是模型下拉框，左侧是对话列表，底部是输入框，你注册的第一个账号自动成为管理员。

🚀 3 条路径让 Open WebUI 跑起来

最快路径是仓库根目录的 compose 文件，一条命令起两个容器：Ollama（跑模型的运行时）和 Open WebUI（对话界面）。

git clone https://gitcode.com/GitHub_Trending/op/open-webui cd open-webui docker compose up -d

启动后访问 http://localhost:3000，注册账号即可对话，无需额外配置。端口映射 3000 到容器内 8080，Ollama 地址OLLAMA_BASE_URL已指向容器内 http://ollama:11434，都定义在 docker-compose.yaml。

没有 Docker 就换 pip 路径，前置条件是 Python 3.11：

pip install open-webui open-webui serve

启动后服务地址是 http://localhost:8080，注意比 Docker 路径多一个 80。

第三条路径适合 compose 用不了的环境：官方镜像有:ollama标签，单容器内置 Ollama，同时干两件事。

docker run -d -p 3000:8080 -v open-webui:/app/backend/data ghcr.io/open-webui/open-webui:ollama

验证方式同样是打开 http://localhost:3000。OLLAMA_BASE_URL、OPENAI_API_KEY等全部环境变量集中在 backend/open_webui/config.py，想调参数先翻它。

🎯 接 Ollama 与 OpenAI 兼容 API 的两种方式

compose 启动后，Open WebUI 已通过OLLAMA_BASE_URL指向容器内的 Ollama，但 Ollama 容器里还没有模型。进容器拉一个：

docker compose exec ollama ollama pull llama3.2

拉完，页面顶部下拉框里就出现 llama3.2。选中它发一句话，模型逐字流式返回，全程不离开内网。有多台 Ollama 实例时，用OLLAMA_BASE_URLS配多个分号分隔的地址，它们会同时出现在同一个下拉列表里。

第二种方式是 OpenAI 兼容 API：启动容器时传入OPENAI_API_BASE_URL和OPENAI_API_KEY，vLLM、LM Studio、OpenRouter 都只是改个 URL。已有推理集群、不想再跑 Ollama 的团队走这条，改完不用动一行代码。

📚 把文档读进对话：RAG 检索三步实操

第一步，让文档进来。新建对话后把 PDF 直接拖进输入区，或先传到左侧知识库让它向量化。系统用内置嵌入模型（默认 sentence-transformers/all-MiniLM-L6-v2）完成分块和嵌入，数据落在本地向量库。

第二步，提问。问"总结这份文档并列出关键数据"，回答会带出文档里的具体内容。输入框里敲#能检索整个文档库，也能把网页 URL 拉进上下文。

第三步，认清边界。RAG 只做"检索加引用"，不会重新训练或微调你的模型。检索引擎在 backend/open_webui/retrieval/，支持 9 种向量库后端可选（ChromaDB、PGVector、Qdrant、Milvus 等）。

🔍 部署后最常见的 4 个问题自查

现象：页面提示 Server connection error，模型列表为空。原因：容器内的 localhost 不指向宿主机，容器够不到 Ollama。解法：compose 方式已默认处理好；单独 docker run 时加--network=host（此时端口变成 8080）或显式设置OLLAMA_BASE_URL。请求如何被后端转发，TROUBLESHOOTING.md 有原理说明。

现象：对话生成到一半断开。原因：Ollama 响应超时默认 300 秒（5 分钟），CPU 上跑大模型来不及算完。解法：调大AIOHTTP_CLIENT_TIMEOUT（单位秒）再启动容器，或换更小的模型。

现象：容器重建后，对话和上传文件全没了。原因：没挂数据卷，数据写进了容器内部文件系统。解法：运行命令里保留-v open-webui:/app/backend/data，官方 README 明确警告了这一步。

现象：完全离线的机器上，首次启动迟迟完不成初始化。原因：默认嵌入模型首次使用需要从 Hugging Face 下载，断网就卡住。解法：先在联网机器上预热，把模型缓存搬进离线环境，具体缓存位置见官方文档。

🔩 跑起来之后的 4 个定制点

想备份或迁移数据：记录、上传文件、向量数据都在 open-webui 卷（容器内 /app/backend/data）里，把卷快照或整个搬到新机器即可原样恢复。

想改快捷键：定义在 src/lib/shortcuts.ts，直接改那里。

想加自定义 Tools 或 Filters：用 Python 写，放到 backend/open_webui/tools/ 下注册，目录里的 builtin.py 和 knowledge_fs.py 可以当样例读。

想换向量数据库：选择由VECTOR_DB环境变量控制，9 种后端实现在 backend/open_webui/retrieval/vector/dbs/ 下，改值重启即可。

🧭 接下来做什么

Open WebUI 本质是一个跑在浏览器里的本地模型调度台：界面它负责，模型你负责。两个可执行的下一步：先读一遍内置工具的写法，弄清 Tools 的注册模式；再回到管理页接第二个模型，或注册一个你自己的工具。

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