Open WebUI 安装部署完整指南3 条路线从零搭建 AI 聊天平台【免费下载链接】open-webuiUser-friendly AI Interface (Supports Ollama, OpenAI API, ...)项目地址: https://gitcode.com/GitHub_Trending/op/open-webui如果你装过 Open WebUI——一个支持 Ollama、OpenAI API 等后端的开源 AI 聊天平台多半被这类问题劝退过依赖装不全、容器连不上 Ollama、端口被占导致页面打不开。这篇文章先走最短路径让 Open WebUI 在一条命令后几分钟内跑起来再覆盖 Docker Compose、手动部署、Kubernetes 三条路线。读完你能独立部署、接入模型并会自己排查高频故障。先认识一下它凭什么值得你花时间全离线可用不依赖外部服务数据不出本机适合对隐私敏感的场景多后端兼容Ollama、OpenAI 兼容 APIOpenAI / Groq / Mistral 等都能接交互能力完整Markdown、LaTeX、语音输入、文件上传、RAG 检索开箱即用插件化扩展Functions / Tools 机制可以在管理后台直接加功能不用改代码目录结构一句话版backend/是 Python FastAPI 后端负责 API 和业务逻辑src/是 SvelteKit 前端构建后由后端托管根目录的 docker-compose.yaml 和 Dockerfile 负责容器化部署。最短路径一条命令先跑起来前提是机器上装了 Docker 和 Docker Compose。三条命令git clone https://gitcode.com/GitHub_Trending/op/open-webui cd open-webui克隆仓库并进入项目目录后面所有命令都在这里执行。docker compose up -d这一条命令同时拉起 Ollama 和 Open WebUI 两个容器并把模型数据和 WebUI 数据挂到命名卷里做持久化。首次运行要构建/拉取镜像等几分钟。# 打开浏览器访问 open http://localhost:3000 # macOSLinux 直接手动打开该地址首次访问会引导你创建管理员账户——第一个注册的用户自动成为管理员。看到聊天界面部署这一半就算成了。剩下的按你的场景补细节。动手前硬件与软件清单项目最低配置推荐配置CPU双核四核及以上内存4GB8GB存储10GB 可用20GB SSD模型文件会占不少系统Windows 10/11、macOS 12、LinuxUbuntu 22.04 LTS按部署方式分两组预装Docker 路线Docker Engine Docker Compose 插件docker compose version能出版本号即可手动路线Python 3.11、Node.js 18.13 ~ 22.x、Git三条部署路线按场景挑一条想省心选路线 A要改源码或二次开发选路线 B多副本、要高可用再考虑路线 C。路线 ADocker Compose 一键部署推荐大多数人最短路径已经跑通的就是这条路这里把 docker-compose.yaml 逐行看懂方便你改配置services: ollama: volumes: - ollama:/root/.ollama # Ollama 模型库持久化删容器不丢模型 image: ollama/ollama:latest restart: unless-stopped open-webui: image: ghcr.io/open-webui/open-webui:main volumes: - open-webui:/app/backend/data # WebUI 数据卷数据库、上传文件都在这 depends_on: - ollama # 先起 Ollama 再起 WebUI ports: - 3000:8080 # 宿主机 3000 → 容器内 8080 environment: - OLLAMA_BASE_URLhttp://ollama:11434 # 容器间用服务名互访 - WEBUI_SECRET_KEY # 留空时首次启动自动生成 restart: unless-stopped volumes: ollama: {} open-webui: {}几个变体N 卡加速用docker compose -f docker-compose.gpu.yaml up -d只接 OpenAI API、完全不需要 Ollama 时用docker compose -f docker-compose.api.yaml up -d它会把 Ollama API 端口 11434 额外映射出来供其他客户端使用。路线 B手动部署想改源码再走这条手动部署就是前端构建 后端启动两件事git clone https://gitcode.com/GitHub_Trending/op/open-webui cd open-webui # 后端依赖需要 Python 3.11建议先建虚拟环境 cd backend pip install -r requirements.txt cd .. # 前端依赖与构建Node 18.13 ~ 22.x npm install npm run build # 产物在 build/由后端直接托管 # 启动后端自动生成密钥、执行数据库迁移、拉起 uvicorn cd backend ./start.sh # Windows 用 start_windows.bat启动后访问http://localhost:8080手动部署默认端口是 8080不是 3000。日常开发模式可以换成npm run dev加cd backend ./dev.sh两者都带热重载。路线 CKubernetes企业生产场景生产环境直接用官方镜像ghcr.io/open-webui/open-webui:main写 Deployment Service Ingress 即可数据卷对应一个 PVC。项目提供 Helm Chartchart 来源与values.yaml参数见官方文档适合要自动扩缩容和高可用的团队。细节不在这里展开。接入模型让它真正能聊连接 Ollama确认 Ollama 在跑ollama ps进入 WebUI管理设置 → Ollama → Add Ollama Instance填 API 地址——容器部署填http://ollama:11434手动部署填http://localhost:11434远程服务器填http://服务器IP:11434原理顺带说一句WebUI 前端并不直连 Ollama请求都走后端/ollama路由转发到OLLAMA_BASE_URL所以这个地址配错是连不上 Ollama的头号原因。连接 OpenAI API管理设置 → OpenAI API → Add OpenAI Instance填 API 密钥sk-...和 Base URL官方是https://api.openai.com/v1兼容服务填对应地址保存后模型列表里就会出现对应模型安全侧有两个开关值得知道都在 backend/open_webui/config.py 中定义、可被环境变量覆盖ENABLE_SIGNUP True # 是否允许新用户自助注册 ENABLE_API_KEY_ENDPOINT_RESTRICTIONS False # 是否限制 API Key 可调用的接口 API_KEY_ALLOWED_ENDPOINTS [] # 允许 API Key 访问的端点白名单多人共享的实例建议关闭自助注册、给 API Key 设端点白名单。部署体检四步确认一切就绪打开http://localhost:3000能登录、能创建账户模型页面能看到已连接的 LLM 列表Ollama 的或 OpenAI 的发一条你好能收到流式回复上传一个 TXT/PDF 文件用 RAG 提问能引用文件内容任何一步不对先看日志docker logs -f open-webui # Docker 部署手动部署没有守护日志uvicorn 的输出直接打在启动它的终端窗口里滚到最上方找报错。踩坑急救包1. WebUI 提示无法连接 Ollama→ 可能原因容器内的127.0.0.1指向容器自己不是宿主机OLLAMA_BASE_URL指错了。 → 修复docker exec -it open-webui env | grep OLLAMA_BASE_URL # 确认应为 http://ollama:11434compose 内部网络 # 若 Ollama 在宿主机且网络隔离改用 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:main # 注意--networkhost 时访问地址变为 http://localhost:80802. 页面打不开提示 3000 端口被占用→ 可能原因宿主机 3000 已被其他程序占用。 → 修复lsof -i :3000 # 查看占用者 # 换个端口在项目根目录 .env 里加一行 OPEN_WEBUI_PORT3001 docker compose up -d3. 升级后启动报数据库迁移错误→ 可能原因版本间有 alembic 迁移未执行。 → 修复# Docker 部署 docker exec -it open-webui alembic upgrade head # 手动部署 cd backend alembic upgrade head更完整的问题清单见仓库里的 TROUBLESHOOTING.md。走向生产备份、定制与插件备份所有数据数据库db.sqlite3、上传文件都在open-webui数据卷里备份即备份卷docker run --rm -v open-webui_open-webui:/data -v $PWD/backup:/backup alpine \ sh -c tar czf /backup/open-webui-backup.tgz -C /data .恢复就是把上面的tar czf换成tar xzf /backup/open-webui-backup.tgz -C /data再跑一遍。手动部署直接备份backend/data目录。自定义主题项目自带static/custom.css把内容替换成自己的样式即可覆盖默认外观也可以配置WEBUI_CUSTOM_CSS_URL指向外部样式地址改完重启生效。插件Functions / Tools / Pipelines 不用装包——在管理后台直接编写、保存即生效RAG 检索增强、函数调用都靠它扩展。接下来跑通之后值得往下摸的方向多模态模型接入、RAG 知识库的深度使用、以及用插件生态把内部工具接进聊天流。遇到问题优先翻 TROUBLESHOOTING.md社区反馈入口是仓库的 Issues 页面和官方 Discord地址见项目 README。附录命令速查操作Docker 部署手动部署启动docker compose up -dcd backend ./start.sh停止docker compose down在启动终端 CtrlC或pkill -f uvicorn看日志docker logs -f open-webui直接看 uvicorn 所在终端输出更新docker compose pull docker compose up -dgit pull npm run build ./backend/start.sh备份docker run --rm -v open-webui_open-webui:/data -v $PWD/backup:/backup alpine sh -c tar czf /backup/open-webui-backup.tgz -C /data .直接复制backend/data目录【免费下载链接】open-webuiUser-friendly AI Interface (Supports Ollama, OpenAI API, ...)项目地址: https://gitcode.com/GitHub_Trending/op/open-webui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考