Open WebUI 用 Docker 起不来（镜像拉不动、端口被占、页面打不开、数据丢）

你会遇到什么

你照着教程在 Docker 里部署 Open WebUI：docker pull ghcr.io/open-webui/open-webui 拉到一半转圈直到超时；或者容器终于起来了，浏览器打开 localhost:3000 却连接被拒、一直转圈；或者报 port is already allocated 根本创建不了容器。

还有一个更隐蔽的：能用了几天，删掉容器重建，账号、历史会话、知识库全没了。

四类表现（镜像拉不动 / 端口冲突 / 页面打不开 / 数据丢）根因各不相同，下面逐条拆。

本文路径：快速修复（30 秒一段命令）→ 一步步排查（可跳读）→ 原理与变体（症状/原因/证据）。赶时间直接跳到「快速修复」。

为什么会这样

先说结论：这四条路各自有一个固定断点——镜像走错源、宿主端口被占、启动需要等 2-3 分钟、数据没挂卷。

断点 1：镜像源。 Open WebUI 官方镜像在 ghcr.io，国内直连拉取不稳定。本机实测（2026-09-24，WSL2 Ubuntu + Docker 29.1.3）：ghcr.io 直连在 25 秒限时内没拉完（只完成了部分层，进程超时退出）；换南京大学镜像 ghcr.nju.edu.cn 后用 3 分 24 秒拉完，镜像 1.66GB。

断点 2：宿主端口。 -p 3000:8080 里的 3000 是宿主端口，全局唯一。被别的进程或容器占了，docker 直接拒绝启动：实测报 failed to bind host port 0.0.0.0:3000/tcp: address already in use。

断点 3：启动耗时。 容器状态 Up 不等于页面可用。Open WebUI 首次启动要在容器内准备 embedding 模型（日志里可见 all-MiniLM-L6-v2），本机实测从 docker run 到首次 HTTP 200 用了 154 秒——这期间浏览器就是连接被拒/转圈。很多人在这两分钟里以为装坏了，反复删容器重来，反而永远起不来。

断点 4：数据卷。 /app/backend/data 里放着 webui.db（账号、会话）、uploads/（上传文档）、vector_db/（RAG 向量库）。不挂 -v，这些都在容器的可写层，docker rm 即丢。实测 docker inspect：不挂卷的容器 Mounts 为空数组；挂了卷的容器重建后 webui.db 仍在（647168 → 684032 字节）。

确定性推论：拉不动先换源；端口报错先看谁占着；"起不来"先看日志是不是还在启动（没报 Traceback 就是等）；删容器前先确认 docker inspect 能看到挂载。

一步步来

1. 镜像拉不动 → 换国内 ghcr 镜像前缀 — 必做（官方源直连慢是常态）

docker pull ghcr.nju.edu.cn/open-webui/open-webui:main

实测 3 分 24 秒完成（1.66GB）。拉不动时也可以先开代理拉一次缓存、之后用国内前缀启动。

2. 端口被占 → 先定位占用者，再换端口 — 必做（宿主端口全局唯一）

docker ps | grep 3000        # 是不是旧容器占着
ss -tlnp | grep 3000         # 是不是宿主进程占着

旧容器：docker rm -f <名字>；宿主进程：停掉或直接用别的宿主端口（-p 3001:8080）。

3. 容器 Up 但页面打不开 → 看日志区分"启动中"和"崩了" — 排查（90% 是还没启动完）

docker ps --filter name=open-webui
docker logs --tail 50 open-webui

日志在刷 Installing external dependencies / 模型加载 = 还在启动，等到首次出现 GET / HTTP/1.1" 200 再用浏览器；日志有 Traceback 才是真崩了。想确认进度，用命令轮询：

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3000/

4. 数据不能丢 → 必须挂 volume — 必做（删容器是常规操作）

docker inspect open-webui --format '{{json .Mounts}}'

输出里要有 "Destination":"/app/backend/data"。升级镜像的正确姿势：docker rm -f open-webui 后用同一条 docker run 重建——卷还在，数据还在。

5. 想连本机 ollama → 按场景指到宿主 — 按场景

容器里的 localhost 是容器自己；连宿主机 ollama 要指 host.docker.internal，见 Open WebUI 连不上 Ollama。

怎么确认修好了

• docker ps 里状态是 Up；
• curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:3000/ 返回 200（首次要等 2-3 分钟）；
• docker inspect open-webui --format '{{json .Mounts}}' 能看到挂到 /app/backend/data 的卷；
• docker exec open-webui ls /app/backend/data 里有 webui.db。

其它环境的表现

• Docker Desktop（Windows/macOS）：端口映射后浏览器开 http://localhost:3000 即可；镜像源同理可用；本条目未在该形态下复现（本机是 WSL2 + 引擎直装）。
• docker compose：把 ports、volumes、image 三段照上面写；端口冲突看 compose 内左侧值是否重复。

症状

# 形态 1：镜像拉取超时
Error response from daemon: ... context deadline exceeded (Client.Timeout exceeded while awaiting headers)

# 形态 2：宿主端口被占
docker: Error response from daemon: failed to set up container networking:
failed to bind host port 0.0.0.0:3000/tcp: address already in use

# 形态 3：容器 Up 但浏览器打不开（启动未完成，最常见）
（浏览器）This site can't be reached / 连接被拒绝

# 形态 4：删容器重建后账号、会话、知识库清空
（页面）回到首次注册引导

原因

镜像源慢（ghcr.io 直连）、宿主端口被占用、首次启动需 2-3 分钟准备 embedding 模型、数据目录 /app/backend/data 没有挂到 volume——四个断点分别对应上面四种形态。

解法

1. 换国内镜像前缀：ghcr.nju.edu.cn/open-webui/open-webui:main（实测 3 分 24 秒拉完）；
2. 端口冲突先 docker ps / ss -tlnp 定位，旧容器删掉或换宿主端口；
3. 页面打不开先 docker logs 看是不是还在启动，等首次 200（本机实测冷启动 154 秒）；
4. 一律加 -v open-webui:/app/backend/data，重建容器不丢数据；
5. 连不上 ollama 另见 open-webui-ollama-connect。

相关 canonical

按「前置 → 同根 / 同域 / 相关」读：

• 前置（先排除）：
• Docker daemon 连不上（daemon 没起，谈不上下载/启动）
• 同根 / 相邻：
• docker pull 失败 / 镜像加速（镜像源类问题的通用排查）
• 端口被占用 port is already allocated（端口断点的通用形态）
• 同域（Open WebUI）：
• 连不上 Ollama
• RAG 知识库检索不生效
• 忘记管理员密码