根本原因是Open WebUI容器内localhost无法访问vLLM容器，需将OPENWEBUI_BASE_URL改为http://vllm-server:8000、vLLM启动加--host 0.0.0.0、移除ports映射、验证curl连通性及DNS解析。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您启动了 vLLM 和 Open WebUI 两个独立容器，但浏览器能打开 http://localhost:7860 却无法加载对话、反复提示“连接后端失败”或日志中出现 ConnectionRefusedError，则极可能是 Open WebUI 容器内无法访问 vLLM 服务。根本原因在于：Open WebUI 默认配置的 OPENWEBUI_BASE_URL=http://localhost:8000 在容器环境中指向自身，而非 vLLM 所在容器。以下是解决此问题的步骤：
一、修正 OPENWEBUI_BASE_URL 为 Docker 内部服务名
Open WebUI 容器必须通过 Docker 自定义网络中的服务别名访问 vLLM 容器，而非使用 localhost。Docker Compose 会自动为每个 service 创建 DNS 解析记录，前提是它们处于同一网络。
1、打开 docker-compose.yml 文件，确认 vLLM 服务已定义明确的服务名称（例如 vllm-server）。
2、在 Open WebUI 的 environment 配置块中，将 OPENWEBUI_BASE_URL 的值由 http://localhost:8000 改为 http://vllm-server:8000（其中 vllm-server 必须与 vLLM service 名称完全一致）。
3、确保两个 service 均声明了相同的 network（如 default 或自定义 bridge 网络），且未设置 network_mode: host。
二、验证 vLLM 容器是否监听 0.0.0.0 而非 127.0.0.1
vLLM 默认绑定到 127.0.0.1 时，仅接受来自本容器内部的请求，外部容器无法连接。必须强制其监听所有接口，才能被同网络内其他容器访问。
1、检查 vLLM 启动命令中是否包含 --host 0.0.0.0 参数（或等效配置）。
2、若使用 docker-compose.yml，需在 vLLM service 的 command 字段末尾添加：--host 0.0.0.0。
3、重启 vLLM 容器后，进入其内部执行 curl -v http://localhost:8000/health，确认返回 200；再从 Open WebUI 容器内执行 curl -v http://vllm-server:8000/health，也应返回 200。
三、显式暴露 vLLM API 端口并禁用宿主机端口映射干扰
虽跨容器通信不依赖宿主机端口映射，但若错误地将 vLLM 的 8000 端口映射到宿主机（如 ports: ["8000:8000"]），可能触发防火墙策略或 SELinux 限制，间接阻断容器间通信。
1、在 vLLM service 的 docker-compose.yml 中，**删除或注释掉 ports 配置项**。
2、仅保留 expose: ["8000"]（可选，仅作文档说明用途，不影响实际通信）。
3、确保 Open WebUI service 中未配置 depends_on 的健康检查误判逻辑（如 condition: service_healthy），避免因 vLLM 启动慢导致 Open WebUI 过早退出。
四、使用 curl 从 Open WebUI 容器内直连 vLLM 地址进行诊断
该方法绕过 Open WebUI 应用层逻辑，直接验证底层网络连通性与 HTTP 可达性，是定位通信链路中断点的最可靠手段。
1、执行 docker exec -it <openwebui_container_name> sh 进入 Open WebUI 容器。
2、在容器内运行：curl -v http://vllm-server:8000/health。
3、若返回 HTTP/1.1 200 OK，则网络与服务可达；若报 Failed to connect、Connection refused 或 timeout，则说明服务名解析失败、vLLM 未运行、或端口未监听 0.0.0.0。
五、强制指定 Docker 自定义网络并验证 DNS 解析
当默认 bridge 网络存在配置残留或命名冲突时，显式创建并绑定专用网络可彻底规避 DNS 解析异常。
1、执行 docker network create llama-net 创建新网络。
2、在 docker-compose.yml 的顶层 networks 字段中声明该网络，并在 vLLM 与 Open WebUI 两个 service 的 networks 下均加入 llama-net。
3、进入 Open WebUI 容器后执行 nslookup vllm-server，确认返回的是 Docker 内部 IP（如 172.20.0.x），而非 127.0.0.11 或解析失败。
