Open WebUI 部署完整指南小白 3 分钟跑通自托管 AI 聊天界面【免费下载链接】open-webuiUser-friendly AI Interface (Supports Ollama, OpenAI API, ...)项目地址: https://gitcode.com/GitHub_Trending/op/open-webui本地已经跑着 Ollama或者手里有一把 OpenAI 兼容的 API key但想要的界面、团队共享、数据不出内网都得自己搭。Open WebUI 就是干这个的一个可完全离线运行的自托管 AI 聊天前端Ollama 和 OpenAI 兼容接口开箱即用聊天、知识库、多用户权限全带齐。这篇指南带你从空机器走到团队可用的页面。 起步前环境自检硬件底线与系统要求跑起来它本身不吃硬件吃硬件的是后面的模型服务但最低门槛摆在这里操作系统Linux / macOS / WindowsWSL2装好 Docker Engine 或 Docker Desktop内存 8GB 起磁盘预留 10GB 以上——镜像首次启动会下载 embedding 和语音识别模型端口宿主机放一个 3000可改给 Web 界面用想源码方式本地跑Python 3.11 Node.js 22依赖清单见 pyproject.toml开发脚本在 backend/dev.shGPU 用户多装一个东西NVIDIA 显卡想走 CUDA 加速先确认宿主机装了 NVIDIA 驱动和 Container Toolkit否则:cuda镜像的--gpus all参数会直接报错。没有 GPU 也别纠结CPU 路线完全能跑只是本地向量化和转写会慢一些。️ 选择部署路线四条路线对比表路线用什么适合谁代价官方 main 镜像 外部模型服务ghcr.io/open-webui/open-webui:main已装 Ollama或直接用 OpenAI API要自己告诉它模型服务在哪官方 cuda 镜像:cuda--gpus allNVIDIA 显卡本地跑 RAG / 语音转写需要 Container Toolkit镜像更大官方 ollama 一体镜像:ollama全新机器想一个容器全搞定Ollama 被捆在镜像里不能单独升级源码本地运行git clone https://gitcode.com/GitHub_Trending/op/open-webui要改代码、做二次开发自己装 Python 3.11、Node 22 和全部依赖推荐结论多数人选main 镜像 外部 Ollama镜像最轻模型服务升级、换模型互不牵连出问题时排查面最小。机器是全新空白、又懒得单独装 Ollama 的直接上:ollama一体镜像省掉一半步骤。 首次跑通从 0 到可访问最快的一条 docker run 命令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-p 3000:8080把容器内的 8080 映射到宿主机 3000-v open-webui:/app/backend/data把数据库和上传文件放进持久卷这一条绝对不能省--add-host让容器能摸到宿主机上的 Ollama。验证服务是否就绪终端执行curl http://localhost:3000/health返回{status:true}即服务就绪。浏览器打开http://localhost:3000注册的第一个账号自动成为管理员。一键接入内置 Ollama用一体镜像的话命令里多挂一个卷存 Ollama 的模型docker run -d -p 3000:8080 \ -v ollama:/root/.ollama -v open-webui:/app/backend/data \ --name open-webui --restart always \ ghcr.io/open-webui/open-webui:ollama启动后在界面里拉取模型WebUI 会自动发现不需要再配连接地址。⚙️ 最常用配置所有开关都是环境变量完整清单看 backend/open_webui/env.py。日常高频的就这几个变量解决什么问题OLLAMA_BASE_URL模型服务不在宿主机时指定它真正的地址OPENAI_API_KEY/OPENAI_API_BASE_URL接入 OpenAI 或任意兼容 API 的服务WEBUI_SECRET_KEY会话签名的钥匙生产环境必须自己固定OFFLINE_MODE断网部署禁止启动时去 Hugging Face 拉模型DATA_DIR数据落盘位置默认/app/backend/dataDATABASE_URL从默认 SQLite 切到 PostgreSQL默认值在 backend/open_webui/config.py 附近定义指向你自己的 OllamaOllama 装在另一台机器、或容器内摸不到宿主机时在docker run里加环境变量即可-e OLLAMA_BASE_URLhttp://host.docker.internal:11434 \ -e OPENAI_API_KEY你的密钥 \ -e WEBUI_SECRET_KEY一段足够长的随机字符串断网环境关掉模型下载内网、机房这类连不上外网的场景加-e OFFLINE_MODEtrue它会把HF_HUB_OFFLINE置 1启动时不再尝试下载也不会弹更新检查。 跑起来之后能做什么把私有文档变成能问答的知识库上传合同、白皮书、产品手册它替你切成小块、向量化、存进向量库镜像里预装了 all-MiniLM-L6-v2 embedding 模型。之后提问时先检索相关段落再让模型作答答案带引用来源。加载器覆盖 pdf、docx、网页等格式实现在 backend/open_webui/retrieval/loaders/。注意换 embedding 模型后旧文档要重新向量化不然检索会对不上。多模型切换与团队协作同一窗口顶部切换本地小模型、OpenAI 或任意兼容服务对话历史各存各的。频道和文件夹把群聊、专题归档账号分角色谁能看哪个知识库、用哪个模型都可以按组授权——多个人共用一台服务时这就是你不用自己写权限系统的理由。挂上工具让它动手干活除了聊天它还能调用工具接入 MCP 工具服务器或者写自定义函数和 Pipeline 插件框架在 backend/open_webui/utils/plugin.py。比如让它查日历、调内部接口、生成文件模型负责决策工具替你执行。️ 踩坑清单现象前端一直报连不上 Ollama原因容器内的127.0.0.1指向容器自己不是宿主机Ollama 在宿主机上时自然摸不到解法按首次跑通的命令带上--add-hosthost.docker.internal:host-gateway或者干脆用 host 网络此时端口回到 8080docker 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:main现象容器删了重建账号和聊天记录全没了原因漏挂-v open-webui:/app/backend/dataSQLite 数据库webui.db生成在容器层里容器没了数据就没了解法卷挂载写进启动命令当成固定习惯已经中招的话趁容器没删先docker cp把/app/backend/data拷出来现象重启或升级后会话集体失效、多实例互踢原因WEBUI_SECRET_KEY没固定每次启动随机生成旧签名全部作废解法生成一段长随机值写死在配置或 secrets 管理里多实例共用同一个值 想更进一步用 Docker Compose 做生产编排仓库根目录的 docker-compose.yaml 现成可用ollama 和 open-webui 两个服务卷、端口、依赖关系都配好了一条命令起全栈docker compose up -d要接 OpenTelemetry 监控的看 docker-compose.otel.yaml配合环境变量ENABLE_OTELtrue导出链路和指标。安全与多节点登录默认开启WEBUI_AUTHtrue对外暴露前再叠上强密码策略ENABLE_PASSWORD_VALIDATION反代层终结 HTTPS安全边界参考 docs/SECURITY.md单节点 SQLite 够用的时候就别动数据库要水平扩展再切DATABASE_URL到 PostgreSQL用户数据和上传文件放共享存储容器编排上 K8s 的官方提供 Helm 方式镜像里已内置/health健康检查探针直接对着打服务起来只是开始最快见效的一步是把团队最常翻的那份文档丢进知识库用本地模型试一次问答再决定要不要接更强的模型。【免费下载链接】open-webuiUser-friendly AI Interface (Supports Ollama, OpenAI API, ...)项目地址: https://gitcode.com/GitHub_Trending/op/open-webui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考