Open WebUI连接内网vLLM：容器网络、账户、模型列表与持久化

两个容器不是同一个localhost

Open WebUI负责账户、会话和界面，vLLM负责模型推理。WebUI容器里的127.0.0.1指向WebUI自己，不是宿主机，也不是vLLM容器。因此不能把浏览器能访问的localhost:8000直接填进容器后端。本文用专用Docker网络与容器名称解析，适合单机内网试验。

前提是已有经过验证的模型目录、NVIDIA容器环境和足够显存。示例沿用Qwen3-8B与vLLM 0.18.0，模型目录为/srv/models/qwen3-8b。没有这些条件应先完成模型服务教程，不把安装界面当成模型部署成功。

建立网络与独立服务

docker network create ai-ui-test
docker volume create ai-ui-data
docker run -d --name ai-ui-vllm --network ai-ui-test \
  --gpus all --shm-size 8g \
  -v /srv/models/qwen3-8b:/model:ro \
  vllm/vllm-openai:v0.18.0 /model \
  --served-model-name qwen3-8b --max-model-len 4096 \
  --max-num-seqs 2 --gpu-memory-utilization 0.85
docker logs ai-ui-vllm

没有-p映射推理端口，服务仅在专用Docker网络中可访问。仍应核对主机上谁有Docker管理权限，因为这些人员可以进入网络。生产环境为推理服务设置API密钥，并以秘密配置传递，示例的无密钥方式只用于本机链路验证。

启动WebUI并保存运行镜像

docker pull ghcr.io/open-webui/open-webui:main
docker image inspect ghcr.io/open-webui/open-webui:main \
  --format '{{index .RepoDigests 0}}'
docker run -d --name ai-ui --network ai-ui-test \
  -p 127.0.0.1:8080:8080 \
  -e ENABLE_OLLAMA_API=false \
  -e OPENAI_API_BASE_URL=http://ai-ui-vllm:8000/v1 \
  -e OPENAI_API_KEY=local-test \
  -v ai-ui-data:/app/backend/data \
  ghcr.io/open-webui/open-webui:main
docker logs ai-ui

main是初次获取入口，不应作为长期不变的版本号。记录上一步摘要，后续把镜像参数替换为该摘要，避免同一命令下次部署得到另一版本。新版许可与品牌要求应按所选发布版核对，不能假设所有历史版本条件相同。

首次在本机打开http://127.0.0.1:8080，完成初始账户设置。若从另一台电脑访问，可通过受控SSH隧道或内网反向代理，不直接改成公网无认证暴露。首个管理员账户创建后立即检查注册策略、默认权限和用户配额。

检查接口、模型与流式响应

在后台连接设置核对http://ai-ui-vllm:8000/v1，刷新模型列表，选择qwen3-8b进行普通问答。容器通信出错时从WebUI容器内部检查DNS与API，宿主机curl成功并不能证明容器能连接。

docker exec ai-ui python -c \
  "import urllib.request; print(urllib.request.urlopen('http://ai-ui-vllm:8000/v1/models').read().decode())"

测试一条较长回答，确认逐步显示而不是最后一次出现。若代理增加缓冲、超时过短或连接被断开，界面可能看起来停住。分别量推理服务、WebUI和浏览器路径，避免一上来更换模型。

持久化与回滚不能只保留模型

ai-ui-data保存账户和会话等应用状态，升级前停写并备份卷，核对备份可恢复。模型服务不负责这些数据。演练删除测试容器后，用同一个卷与同一个镜像摘要重建，确认账户、会话与连接配置仍在；不要执行docker volume rm清理已有数据。

界面中的联网搜索、文档上传与工具功能涉及额外数据流，未审核前不要全部开启。上传内容可能被存入向量库或日志，数据清理要覆盖这些位置。员工离职时先禁用账户再按制度处理会话，不只重置聊天页面。

故障顺序与正式接入

模型列表为空先核对/v1和服务名称，再检查容器网络；401检查API密钥是否一致；回答重复或特殊token异常检查聊天模板；重启后账户消失检查数据卷挂载。停止ai-ui和ai-ui-vllm只停止服务，保留卷与权重。

正式服务增加TLS、访问控制、注册审核、网关限流和备份恢复，先完成最小闭环再开放人员使用。参考：Open WebUI官方快速开始。

账户与连接配置的上线检查

管理员先建立两个普通测试账户，分别登录并创建会话，验证彼此不能看到对方记录。共享模型不等于共享聊天历史；管理员可见范围、用户默认角色、注册入口与删除权限需要明确。关闭不需要的注册方式，普通账户不拥有模型连接修改权。密码恢复方式也应在开放员工使用前验证，不能等管理员离职才发现唯一账户无法交接。

连接配置同时可能来自环境变量和后台持久化设置。已有数据卷时，后台保存的值可能继续生效，重启并不一定让新的环境变量覆盖旧值。排障先在界面查看实际连接，再对照容器环境，不反复重建容器试运气。避免在截图、聊天和日志中显示真实API密钥；使用只允许访问指定模型的密钥，并制定更换步骤。

文档上传的存储和隐私边界

即便只搭聊天界面，也应确认是否开放附件。用户上传文档后，原件、解析结果、索引和会话可能分别保存，删除聊天不一定清除所有副本。管理员用一份带唯一测试标记的假资料检查上传、检索、删除和备份恢复路径，记录实际保存位置与保留周期，不使用真实个人数据试验。

如果启用检索，嵌入模型和生成模型是两条服务链，不能因为聊天正常就认定附件检索也正常。先验证文档解析，再检查候选片段与引用。普通用户不能配置任意外部连接或任意本地目录，工具执行功能需要独立审批。

接入反向代理后的体验验收

在内网反向代理上配置HTTPS、认证策略、上传大小与流式超时，测试短问答、长输出和浏览器关闭。检查移动端与不同浏览器，确认流式过程中不会把原始协议事件显示为正文。代理访问日志只保留必要元数据，不能默认记录完整请求体。

为团队准备故障提示：模型维护、请求排队、配额用尽和连接失败应区分，不全部显示成密码错误。管理员升级前导出运行配置并备份数据卷，用两个测试账户核对历史记录恢复。跨版本数据库迁移可能不可逆，回滚不能只换旧镜像而不恢复匹配的数据副本。