使用 Docker 和持久化存储部署 Open WebUI

适用范围与验证声明

本文面向 Linux Docker Engine，以及已经独立安装的 Ollama 后端，提供部署参考和功能自检方法。本站尚未完成 Open WebUI 与 Ollama 的完整部署实测。官方资料核验日期为 2026 年 10 月 10 日；命令经过静态检查，不代表镜像启动、模型推理、TLS 或恢复已实际通过。

Open WebUI 是界面，Ollama 负责运行模型。排错前记录 docker version、ollama --version 和所选 WebUI 发布版本。下方示例采用 Docker bridge 网络，不是 host 网络；Docker Desktop、rootless Docker 和自定义网络可能不同。使用支持 host-gateway 的受支持 Docker 版本。Docker 官方指出低于 28.0.0 的版本存在 localhost 发布端口可能被同一二层网络主机访问的限制，不能把回环绑定当成跨版本绝对隔离，参见端口发布说明。

资源、持久化与安全边界

本文没有可靠依据给出统一的 CPU、内存、磁盘硬性最低值。界面资源取决于并发、上传和启用功能；Ollama 则要另按模型大小、量化和上下文估算。磁盘需容纳镜像、应用数据和模型。能运行 Web 界面的服务器，不一定能承担模型推理。

保留 /app/backend/data 数据卷和固定 WEBUI_SECRET_KEY。升级前备份数据，密钥单独安全保管，并在副本上验证恢复。不要为解决连接问题删除数据卷。完成管理员初始化后关闭非必要注册；未初始化的界面不要直接公开。对外提供有访问控制的 HTTPS 界面，不公开原始 Ollama API。

第 1 步：确认 Ollama 前置条件

按照官方 Linux 安装与服务说明准备已经运行的 Ollama。本文不安装 Ollama，也不替读者选择硬件适用模型。在 Ollama 所在主机检查版本与已有模型：

ollama --version
ollama list
curl --fail --silent --show-error --max-time 10 http://127.0.0.1:11434/api/tags

本机接口正常时返回包含 models 数组的 JSON。空数组和连接失败是两回事：没有模型时，先核对资源与下载条件，再按官方流程获取合适模型；下文使用已经存在的模型自检。若服务使用不同地址，应检查已经批准的实际地址。已有服务运行时，不要再重复启动一个 ollama serve。

第 2 步：先确定安全的网络路径

bridge 容器里的 127.0.0.1 指向该容器，不是 Linux 宿主机。--add-host=host.docker.internal:host-gateway 只是增加到宿主地址的名称映射，不会修改 Ollama 的监听接口。Ollama 默认只监听宿主机回环地址的 11434 端口，因此第 4 步示例有前提：Ollama 必须确实可从该 bridge 网络到达。

执行示例前，与主机管理员核对监听地址和访问限制。仅允许必要来源访问的、容器可达的宿主私有接口，与公网接口不是同一方案。没有这样的安全路径就先停止，参照官方连接排错和Ollama 网络说明。不要直接设置全接口监听或开放公网 11434。私有地址本身也不能替代访问控制。

其他拓扑需分别处理：Ollama 也是容器时可用共享私有网络与服务名；远程后端需要受保护的私有路径；Linux host 网络会改变端口映射及隔离边界，不能只把 bridge 命令加上 host 参数就认为等价。本文不提供通用的防火墙或监听修改命令。下文检查可达性，并不能单独证明网络安全。

第 3 步：准备数据卷与固定密钥

使用已获准管理 Docker 的账号。Docker 管理权限具有高权限影响，不要为了快捷随意授予。先确认客户端和服务端都可用：

docker version
docker volume create open-webui
openssl rand -hex 32

预期分别是：版本输出包含有响应的 Server；数据卷返回 open-webui；随机密钥为 64 位十六进制字符串。通过编辑器将密钥保存到私有 open-webui.env，内容为 WEBUI_SECRET_KEY=<你生成的密钥>。必须替换占位值，限制为部署所有者可读，并排除版本控制、截图及共享日志。Docker 管理者仍可查看容器环境，环境文件不能向他们隐藏密钥。重建、升级继续保留同一值。

第 4 步：启动界面容器

官方 main 标签会滚动变化，适合体验。生产应选择已审查、架构适用的发布版本，记录版本或摘要，升级前阅读变更。本文未实测某个固定版本。官方快速入门说明了镜像选择。

下方是条件性的启动参考：仅在第 2 步网络前提和私有环境文件均准备好后使用。先确认容器名和端口没有被其他部署使用，不要盲目删除原容器或数据卷。

docker run -d \
  -p 127.0.0.1:3001:8080 \
  --add-host=host.docker.internal:host-gateway \
  -e OLLAMA_BASE_URL=http://host.docker.internal:11434 \
  --env-file ./open-webui.env \
  -v open-webui:/app/backend/data \
  --name open-webui --restart always \
  ghcr.io/open-webui/open-webui:main

返回容器 ID 只证明创建请求成功，不证明应用或模型后端可用。界面映射到宿主回环的 3001 端口。若在远程服务器部署，电脑浏览器的 localhost 不是服务器；使用批准的安全隧道或下文 HTTPS 入口，不要改成无保护的公网端口。

第 5 步：分层验证，直到真正获得回复

先检查容器和本机 HTTP：

docker ps -a --filter name=open-webui
docker logs --tail=100 open-webui
curl --fail --silent --show-error --max-time 20 -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3001/

预期容器持续运行，日志没有致命启动循环，本机页面返回合理的成功 HTTP 响应。通过批准的路径打开浏览器页面。首页响应不能证明后端或推理正常；分享日志前须脱敏。

若所选镜像包含 Python，可在容器内检查 Ollama 模型接口，不下载模型：

docker exec -i open-webui python - <<'PY'
import json, urllib.request
with urllib.request.urlopen('http://host.docker.internal:11434/api/tags', timeout=10) as response:
    data = json.load(response)
if not isinstance(data.get('models'), list):
    raise SystemExit('Unexpected model-list response')
print([model.get('name') for model in data['models']])
PY

输出已有模型名称列表，说明该容器可达这个后端；[] 表示未返回模型。拒绝连接、超时或名称解析失败，应检查服务、路由、监听和访问限制。镜像没有 python 时，此检查不适用；不要为了检查往生产容器临时安装工具，改在界面检查连接并查对应版本文档。仅按批准的实际拓扑调整诊断地址。

随后在受保护的界面创建管理员，核对注册和访问策略，进入管理设置检查 Ollama 连接。菜单名称可能随版本变化；确认连接 URL 正确、模型选择器出现已有模型。持久化的应用设置可能与环境变量不同，需检查实际值。选择模型，发送一条简短测试消息，并看到完整的助手回复。模型列表空时先查连接与后端模型；模型存在却无回复时查后端日志、内存/加速资源，再查代理的流式响应或 WebSocket。不要以删除数据解决这些问题。

可选：核对后端实际响应

在 Ollama 主机执行前，把 EXISTING_MODEL_NAME 换成模型列表中的准确名称。请求会实际推理并消耗资源；没有现成适用模型就跳过，不强制下载。stream:false 时应核对完整返回中的 message.content 和 done:true，不能只看 HTTP 成功。推理模型可能耗时或包含单独的思考数据。

curl --fail --silent --show-error --max-time 120 \
  http://127.0.0.1:11434/api/chat \
  -H 'Content-Type: application/json' \
  -d '{"model":"EXISTING_MODEL_NAME","messages":[{"role":"user","content":"Reply with a short greeting."}],"stream":false}'

超时不自动等于安装失败。主机 API 测试成功也不能替代 WebUI 中的完整聊天。接口依据：模型列表、聊天请求。

第 6 步：Caddy HTTPS 配置参考

以下是 Caddyfile 语法，不是 shell 命令，也不是本站实测成功的 HTTPS 配置。前提是 Caddy 与 Docker 在同一宿主机、能访问 3001，读者拥有替换后的域名，DNS 指向正确主机，证书验证所需路径和端口可用。若 Caddy 也在容器，其回环地址指向自身，上游路径需另行设计。添加站点前备份并审查现有配置，不能覆盖其他站点。

openwebui.example.com {
    reverse_proxy 127.0.0.1:3001
}

在审查后的配置文件中替换示例域名。这几行没有全部注释，确实声明站点。仅在自己的测试或部署主机，先校验完整目标文件，再按授权流程重载：

caddy validate --config ./Caddyfile --adapter caddyfile

校验成功不等于 DNS、证书签发、认证或模型流式回复成功。参照Caddy 命令文档和自动 HTTPS 前提。批准重载后，检查实际 HTTPS 域名、证书、登录策略和完整聊天；保持原始模型 API 私有。

常见故障与恢复边界

• 容器退出：先查日志、Docker 服务权限、镜像架构、环境文件及名称/端口冲突。
• 宿主模型列表正常，容器不可达：查实际网络模式、网关映射、Ollama 监听与来源限制。
• 模型选择器为空：区分连接失败与后端空模型列表，核对已保存的连接 URL。
• 有模型却无回复：查资源和后端日志，再查界面/代理链路；首页正常不是终点。
• 升级后异常：保留数据卷及密钥；使用经过核验的备份和审查后的恢复方案，优先在副本测试，不用破坏性清理代替排错。

用户侧完整成功条件是：持久化界面运行、受保护的浏览器入口、正确后端可达、模型可选择、实际回复完成。本文提供检查方法，并不声明本站已实际完成上述全部验证。