部署前先了解 Open WebUI 适合什么场景

Open WebUI 是一款常见的本地大模型工具前端，界面接近主流对话产品，适合把 Ollama、本地推理服务或兼容接口统一接入到网页中使用。对于个人用户，它可以作为本地模型聊天入口；对于小团队，它可以用来管理模型、会话、知识库和用户访问；对于 AI 工具学习者，它也是理解本地模型部署链路的入门项目。

使用 Docker 部署的好处是环境隔离、安装简单、迁移方便，不需要手动处理大量依赖。只要主机已经安装 Docker，就可以通过镜像拉取、端口映射和数据目录挂载完成部署。需要注意的是，Open WebUI 本身主要负责界面和管理，模型推理通常仍由 Ollama 或其他后端服务承担，因此部署时要同时规划好模型服务地址。

准备工作与环境检查

开始前建议准备一台 Linux 服务器、Windows Docker Desktop 环境或 macOS 主机。生产环境更推荐 Linux，因为服务常驻更稳定。主机至少预留 2GB 内存给 WebUI，如果还要本机运行大模型，则需要根据模型大小准备更多内存和显存。磁盘方面，Open WebUI 的配置、账号、会话和知识库文件会写入数据目录，建议预留充足空间。

先确认 Docker 是否可用，可执行 docker version 查看客户端和服务端信息，再执行 docker ps 确认当前用户有权限管理容器。如果提示权限不足，可以切换到具备管理权限的用户，或按系统规范配置 Docker 用户组。不要在不清楚来源的脚本中直接执行安装命令，部署前应确认镜像来源、版本标签和网络访问策略。

方式一：使用 Docker 命令一键启动

最常用的部署方式是直接运行官方镜像。基础命令如下：docker run -d --name open-webui -p 3000:8080 -v open-webui:/app/backend/data --restart unless-stopped ghcr.io/open-webui/open-webui:main。这条命令会在后台启动容器，将宿主机 3000 端口映射到容器内部 8080 端口，并创建名为 open-webui 的 Docker 数据卷保存后端数据。

命令中 -d 表示后台运行，--name 用于指定容器名称，便于后续升级和排查；-p 3000:8080 是端口映射，访问地址通常为 https://服务器IP:3000；-v open-webui:/app/backend/data 是数据持久化配置，避免容器删除后会话和设置丢失；--restart unless-stopped 表示系统重启后自动恢复服务，除非你手动停止。

如果 3000 端口已被其他应用占用，可以改成 -p 8088:8080，此时访问地址就是 https://服务器IP:8088。端口选择应避开已有服务，并在防火墙或云主机安全规则中放行对应端口。若只是本机测试，也可以只允许本机访问，减少暴露面。

连接本机 Ollama 的推荐配置

很多用户会把 Open WebUI 与 Ollama 搭配使用。如果 Ollama 安装在宿主机，而 Open WebUI 运行在容器内，容器不能简单地把 localhost 理解为宿主机。Linux 环境可使用如下命令：docker run -d --name open-webui -p 3000:8080 --add-host=host.docker.internal:host-gateway -e OLLAMA_BASE_URL=https://host.docker.internal:11434 -v open-webui:/app/backend/data --restart unless-stopped ghcr.io/open-webui/open-webui:main。

其中 --add-host 用来让容器识别宿主机地址，OLLAMA_BASE_URL 指向 Ollama 服务。启动后进入网页，注册首个管理员账号，再到模型设置中检查是否能读取 Ollama 模型列表。若列表为空，先在宿主机执行 ollama list 确认模型存在，再检查 Ollama 是否监听 11434 端口。

如果 Ollama 也以 Docker 容器运行，建议把两个容器放入同一个 Docker 网络，通过容器名访问服务，这样比使用宿主机地址更清晰。示例思路是先创建网络 docker network create ai-net，再让 Ollama 与 Open WebUI 都加入该网络，并把接口地址设置为 Ollama 容器名加端口。

方式二：使用 Compose 便于长期维护

当部署项较多时，推荐使用 Docker Compose 管理配置。可以创建一个目录，例如 /opt/open-webui，在其中编写 compose 配置，定义镜像、端口、数据卷、环境变量和重启策略。这样后续升级、迁移、排查都会更方便，也能减少命令行参数写错的概率。

核心配置思路包括：服务名设为 open-webui；镜像使用 ghcr.io/open-webui/open-webui:main 或指定稳定版本；端口配置为 3000:8080；数据卷挂载到 /app/backend/data；如需连接 Ollama，则增加 OLLAMA_BASE_URL 环境变量。启动时进入配置目录执行 docker compose up -d，停止服务执行 docker compose down。

Compose 的优势在于配置可读、可备份、可复用。对于团队环境，建议把 compose 文件中的端口、服务地址、版本标签整理成变更记录，但不要把密钥、接口令牌等敏感信息直接公开到共享文档或公共仓库。

数据目录配置与备份要点

Open WebUI 的关键数据位于容器内 /app/backend/data。如果使用命名卷 open-webui，Docker 会自动管理实际存储位置，适合新手；如果希望明确落盘路径，可以改为绑定挂载，例如 -v /opt/open-webui/data:/app/backend/data。绑定挂载便于人工备份和迁移，但要注意目录权限，确保容器进程可以读写。

备份时不要只保存容器本身，更重要的是保存数据卷或绑定目录。建议在升级前先停止容器，再复制数据目录，避免写入过程中产生不完整文件。若使用命名卷，可通过临时容器打包导出；若使用宿主机目录，直接压缩备份即可。恢复时保持挂载路径一致，再重新启动容器。

需要特别提醒的是，聊天记录、上传文件、知识库资料、用户配置都可能包含敏感内容。不要把数据目录随意发送给他人，也不要在无访问控制的共享环境中部署。对外开放服务时，应启用强密码、限制注册策略，并结合反向袋里、访问白名单或内网访问方案进行保护。

镜像拉取、升级与回滚

首次运行时 Docker 会自动拉取镜像，也可以手动执行 docker pull ghcr.io/open-webui/open-webui:main。如果希望稳定，建议关注项目发布说明，选择明确版本标签，而不是长期跟随 main。main 更新快，适合体验新功能；固定版本更适合长期使用环境。

升级的一般流程是：第一步备份数据目录；第二步拉取新镜像；第三步停止并删除旧容器；第四步使用原端口、原环境变量、原数据挂载重新创建容器。示例命令包括 docker stop open-webui、docker rm open-webui、docker pull ghcr.io/open-webui/open-webui:main，然后再次执行启动命令。

如果升级后出现页面异常、模型无法显示或插件不兼容，可以回滚到旧版本镜像。前提是你知道旧版本标签，并且数据备份完整。回滚前最好保留升级后的数据副本，避免新旧版本数据结构差异导致再次恢复困难。

常见问题与排查方法

问题一：浏览器打不开页面。先执行 docker ps 确认容器是否运行，再用 docker logs open-webui 查看日志。如果容器正常，检查端口是否写错、防火墙是否放行、云主机规则是否允许访问。也可以在服务器本机执行 curl https://127.0.0.1:3000 判断服务是否可达。

问题二：端口冲突。若日志或命令行提示端口已被占用，说明宿主机 3000 端口已有其他服务。可以改用 -p 3001:8080 或其他未占用端口。不要修改容器内部 8080，通常只需要调整冒号左侧的宿主机端口。

问题三：连接不到 Ollama。重点检查三处：Ollama 是否运行；容器内访问宿主机地址是否正确；环境变量是否写入到当前容器。修改环境变量后，仅重启旧容器通常不一定生效，建议删除并按新参数重新创建容器，同时保留同一个数据卷。

问题四：数据丢失。多数情况是启动时没有挂载原数据目录，或换了新的卷名。排查时执行 docker inspect open-webui 查看 Mounts 配置，确认挂载目标是否为 /app/backend/data。只要原数据卷或目录还在，通常可以通过重新挂载恢复。

安全边界与实用建议

Open WebUI 部署完成后，首个注册用户通常拥有管理权限，应立即设置强密码，并关闭不必要的开放注册。对公网开放前要评估访问范围，不建议把未加保护的管理后台直接暴露。若接入第三方模型接口，应妥善保存接口密钥，并控制普通用户的使用权限和额度。

在本地大模型工具链中，WebUI、模型服务、数据目录和访问入口是四个关键点。新手可以先用 Docker 命令快速跑通，再改用 Compose 固化配置；个人测试可使用命名卷，长期运行建议使用明确目录并定期备份；升级前先备份，出错后优先看日志和挂载配置。按这个思路部署，Open WebUI 的安装、维护和迁移都会更可控。