Open WebUI 的关键部署难点不在于启动 Web 页面而在于处理容器、持久化目录和模型服务之间的边界。Web 服务运行在容器内时127.0.0.1指向容器自身不会自动指向 Linux 宿主机上的 Ollama。若忽略这一点界面可以正常打开模型列表却可能为空。下面采用 Docker Compose 部署 Open WebUI并将其连接到宿主机上的 Ollama。数据写入独立 Docker 卷便于升级和备份浏览器访问端口使用仓库文档中的3000容器内部服务端口为8080。对话工作区包含会话导航、模型选择和消息交互区域。一、组件与数据流这套部署包含三个主要部分Open WebUI 前端与后端官方容器镜像同时提供浏览器界面和后端服务。Ollama负责加载本地模型并提供推理接口默认监听11434。持久化数据卷挂载到容器的/app/backend/data保存数据库、上传文件及应用配置。浏览器请求先到达宿主机的3000端口再映射至容器内的8080。Open WebUI 通过OLLAMA_BASE_URL请求模型服务浏览器 │ ▼ Linux 主机:3000 │ ▼ Open WebUI 容器:8080 │ ▼ host.docker.internal:11434 │ ▼ 宿主机 Ollama仓库同时包含前端、后端、容器构建文件和环境变量示例。若只做常规自托管部署不需要从源码构建前端。仓库包含 Dockerfile、环境变量示例、后端代码和故障排查文档。二、服务器准备准备一台能够运行 Docker 的 64 位 Linux 服务器。使用本地模型时内存、磁盘和计算资源还要满足所选模型的要求Open WebUI 本身不决定模型能够以何种速度运行。检查系统和可用空间uname-mcat/etc/os-releasefree-hdf-huname -m用于确认处理器架构df -h用于检查 Docker 数据目录所在文件系统是否有足够空间。模型文件通常比 Web 应用数据占用更多磁盘因此不能只按容器镜像大小规划容量。服务器应已安装 Docker Engine并支持docker compose子命令docker--versiondockercompose versiondockerinfo如果第一条命令提示找不到docker需要先完成 Docker Engine 安装。不要在 Docker 尚未安装时继续执行 Compose 命令否则应用配置本身还没有机会被读取。三、确认 Ollama 可访问1. Ollama 与 Open WebUI 位于同一台服务器先从宿主机检查 Ollamacurlhttp://127.0.0.1:11434该请求的目的不是测试 Open WebUI而是确认宿主机的11434端口已有服务响应。若这里连接失败应先处理 Ollama 的安装、启动或监听地址问题。Docker 在 Linux 上不会始终自动创建host.docker.internal。后面的 Compose 配置通过extra_hosts:-host.docker.internal:host-gateway将该名称映射到宿主机网关因此容器内应使用http://host.docker.internal:11434不能在容器配置中直接使用http://127.0.0.1:11434因为那会请求 Open WebUI 容器自身。2. Ollama 位于另一台服务器将OLLAMA_BASE_URL设置为实际模型服务器地址。模型服务器还必须允许部署主机访问并应通过防火墙限制来源。不要为了排障直接把推理端口开放给所有网络。四、创建部署目录建立独立目录避免配置文件散落在管理员家目录sudomkdir-p/opt/open-webuisudochown$USER:$USER/opt/open-webuicd/opt/open-webui目录中保存 Compose 文件和非敏感部署参数。应用运行数据不直接写入该目录而是保存在 Docker 卷open-webui中。创建.envOPEN_WEBUI_IMAGEghcr.io/open-webui/open-webui:main OPEN_WEBUI_PORT3000 OLLAMA_BASE_URLhttp://host.docker.internal:11434这里使用仓库快速启动示例中的:main标签。该标签会随项目更新而变化适合跟随主线版本但不能保证两次拉取得到相同镜像。需要可重复部署时应将OPEN_WEBUI_IMAGE改为项目发布页提供的明确版本标签或镜像摘要。若 Ollama 位于另一台服务器只修改OLLAMA_BASE_URL不要删除变量名。五、编写 Docker Compose 配置创建compose.yamlservices:open-webui:image:${OPEN_WEBUI_IMAGE}container_name:open-webuirestart:alwaysports:-${OPEN_WEBUI_PORT}:8080extra_hosts:-host.docker.internal:host-gatewayenvironment:OLLAMA_BASE_URL:${OLLAMA_BASE_URL}volumes:-open-webui:/app/backend/datavolumes:open-webui:name:open-webui几个配置项直接影响后续运维ports将宿主机的3000映射到容器内固定的8080。restart: always使容器在 Docker 服务重启后自动拉起。extra_hosts解决 Linux 容器访问宿主机 Ollama 的名称解析问题。OLLAMA_BASE_URL决定模型列表和聊天请求发往何处。/app/backend/data是必须持久化的目录。删除容器不会删除命名卷但删除卷会造成应用数据丢失。先让 Compose 完成变量展开并检查 YAMLcd/opt/open-webuidockercompose config输出中应能看到实际镜像、3000:8080端口映射、数据卷和OLLAMA_BASE_URL。如果出现变量为空的警告检查.env是否与compose.yaml位于同一目录。六、拉取镜像并启动执行cd/opt/open-webuidockercompose pulldockercompose up-ddockercomposepspull单独执行便于区分镜像下载错误与容器启动错误。up -d让服务在后台运行而ps用来确认容器是否处于运行状态以及端口是否已经发布。查看启动日志dockercompose logs--tail200open-webui日志中不应持续出现数据库无法写入、端口占用或连接配置解析失败。首次启动可能包含初始化过程不能只凭容器刚进入运行状态就判定全部功能可用。七、配置防火墙与访问范围如果只允许管理网络访问可按实际网段设置来源地址ADMIN_CIDR192.0.2.0/24sudoufw allow from$ADMIN_CIDRto any port3000proto tcpsudoufw status192.0.2.0/24只是文档示例网段部署时必须替换为真实管理网段。若服务器前面还有独立防火墙或反向代理也要同步检查对应规则。不建议直接把管理界面长期暴露在不受限制的网络中。需要使用域名时可在前面配置反向代理和 TLS并只让反向代理访问3000。此时还可以把端口映射调整为仅监听本机ports:-127.0.0.1:${OPEN_WEBUI_PORT}:8080修改后运行docker compose up -d使配置生效。八、启动验收先从服务器本机检查 HTTP 响应curl-Ihttp://127.0.0.1:3000dockerport open-webuidockercomposeps验收时至少检查以下现象curl能收到 HTTP 响应而不是Connection refused。docker port显示容器8080已映射到配置的宿主机端口。浏览器可以打开http://服务器地址:3000。页面完成初始化后能够进入登录或初始化界面。模型选择区域能够读取 Ollama 提供的模型。发送测试消息后日志中没有持续出现模型服务连接错误。欢迎界面可用于确认前端静态资源和后端页面路由已经能够访问。还应观察部署前后的 CPU、内存、网络与磁盘 I/O。界面可访问只说明 Web 服务已响应不能证明本地模型具有足够资源。资源曲线应结合模型加载和生成请求的时间点进行判断。九、备份与恢复Open WebUI 的重点备份对象是/app/backend/data。为了避免备份期间数据库继续写入先停止容器再复制数据cd/opt/open-webuidockercompose stopBACKUP_DIR$HOME/open-webui-backup-$(date%Y%m%d-%H%M%S)mkdir-p$BACKUP_DIRdockercpopen-webui:/app/backend/data$BACKUP_DIR/datacpcompose.yaml .env$BACKUP_DIR/dockercompose startdocker cp会把容器内的data目录复制到时间戳目录。备份完成后应检查文件是否存在find$BACKUP_DIR-maxdepth2-typef|headdu-sh$BACKUP_DIR恢复前应停止并删除现有容器重新创建空数据卷再把备份内容复制回/app/backend/data。恢复操作会覆盖当前数据执行前要额外保留当前卷的副本cd/opt/open-webuidockercompose downdockervolumermopen-webuidockervolume create open-webuidockercompose createdockercp$BACKUP_DIR/data/.open-webui:/app/backend/datadockercompose up-d恢复后重新执行 HTTP、登录、模型列表和对话测试。若容器因文件权限问题无法启动可通过日志确认具体路径不要直接对整个数据目录执行宽松的全局写权限。十、升级与回滚使用:main时升级过程会获取当前主线镜像cd/opt/open-webuidockercompose pulldockercompose up-ddockercompose logs--tail200open-webui升级前应完成数据备份并记录当前镜像摘要dockerinspect open-webui\--format{{.Config.Image}} {{.Image}}镜像标签可能不变但镜像 ID 会改变因此只记录:main不足以支持精确回滚。生产环境更适合在.env中固定发布版本或镜像摘要。发生兼容问题时将OPEN_WEBUI_IMAGE改回升级前记录的镜像摘要然后重新创建容器cd/opt/open-webuidockercompose pulldockercompose up-d如果新版本已经迁移了数据库仅回退镜像未必足够还应恢复升级前的数据备份。十一、常见故障排查1.docker: command not found原因通常是 Docker Engine 未安装或者当前终端环境找不到 Docker 可执行文件。检查command-vdockerdocker--version安装完成后还要确认 Docker 服务正在运行并重新打开终端会话。2. 页面可以打开但模型列表为空先验证宿主机 Ollamacurlhttp://127.0.0.1:11434再从 Open WebUI 容器测试宿主机名称是否已经注入dockerexecopen-webui getent hosts host.docker.internaldockerinspect open-webui\--format{{range .Config.Env}}{{println .}}{{end}}重点核对OLLAMA_BASE_URL是否为http://host.docker.internal:11434。如果 Ollama 位于其他服务器则检查目标地址、监听接口和网络访问规则。3.3000端口已被占用查找占用进程sudoss-lntp|grep:3000可以停止冲突服务也可以修改.env中的OPEN_WEBUI_PORT。容器内部端口仍保持8080只调整宿主机端口即可。4. 容器反复重启查看状态和最近日志dockercomposepsdockercompose logs--tail300open-webuidockerinspect open-webui\--formatstatus{{.State.Status}} exit{{.State.ExitCode}} error{{.State.Error}}常见原因包括数据目录不可写、环境变量格式错误、磁盘已满或镜像与已有数据不兼容。5. 重建容器后历史数据消失检查挂载是否存在dockerinspect open-webui\--format{{range .Mounts}}{{println .Type .Name .Destination}}{{end}}dockervolume inspect open-webui正常情况下应看到命名卷挂载到/app/backend/data。如果此前启动命令遗漏了该挂载数据可能只写在已删除容器的可写层中。6. 离线环境中持续出现外部下载请求仓库文档给出的离线变量是HF_HUB_OFFLINE1。可加入 Composeenvironment:OLLAMA_BASE_URL:${OLLAMA_BASE_URL}HF_HUB_OFFLINE:1修改后运行dockercompose up-d离线模式不会自动提供模型和相关资源。需要预先准备的文件仍应在断网前下载并验证。十二、目录与配置清单部署完成后的关键对象如下对象位置或名称作用Compose 配置/opt/open-webui/compose.yaml定义容器、端口、环境变量和数据卷部署变量/opt/open-webui/.env保存镜像、访问端口和 Ollama 地址应用数据/app/backend/data容器内持久化目录Docker 卷open-webui在容器重建后保留应用数据Web 访问端口3000宿主机对外或对反向代理提供服务容器服务端口8080Open WebUI 容器内部端口Ollama 默认端口11434本地模型服务接口不要把.env、数据备份和数据库文件放进公开仓库。即使当前.env只包含内部地址后续也可能加入访问凭据。参考资料Open WebUI 项目仓库Open WebUI 安装文档Open WebUI 更新文档Open WebUI 故障排查文档Open WebUI 安全公告Docker Engine 安装文档Docker Compose 文档Ollama 项目仓库项目当前代码包含多个时期和组件对应的许可条款。部署、修改或再分发前应以仓库中的LICENSE、LICENSE_HISTORY和LICENSE_NOTICE为准不能仅根据早期许可证名称判断当前全部代码的适用条件。