将Open WebUI部署到Windows Docker Desktop时TLS证书错误的排查

文章导读
部署 Open WebUI 到 Windows Docker Desktop 遇到 TLS 证书错误,先分清报错发生在哪一层:浏览器访问时报的证书错误,和 docker 命令行报的 TLS 错误,处理路径完全不同。浏览器端报错,绝大多数不是证书内容坏了,而是访问协议与服务实际协议不匹配,或者服务端证书没有被 Windows 信任。docker 命令本身报 x509 unknown authorit
📋 目录
  1. 壹 先分清报错出现的环节
  2. 贰 确实需要 HTTPS 时,在访问层加一层 Caddy
  3. 叁 验证信号和兜底手段
A A

部署 Open WebUI 到 Windows Docker Desktop 遇到 TLS 证书错误,先分清报错发生在哪一层:浏览器访问时报的证书错误,和 docker 命令行报的 TLS 错误,处理路径完全不同。浏览器端报错,绝大多数不是证书内容坏了,而是访问协议与服务实际协议不匹配,或者服务端证书没有被 Windows 信任。docker 命令本身报 x509 unknown authority,则是本地 Docker 客户端上下文或守护进程证书出了问题,跟 Open WebUI 镜像关系不大。

先分清报错出现的环节

  • 浏览器打开 https://localhost:3000 出现 ERR_SSL_PROTOCOL_ERROR:服务端没有启用 TLS,只讲 HTTP,换成 http://localhost:3000 即可。
  • 浏览器出现 NET::ERR_CERT_AUTHORITY_INVALID 或“不是私密连接”:服务端确实有证书,自签或由非公开 CA 签发,但 Windows 不信任,需要导入信任区。
  • docker compose up 阶段输出 certificate signed by unknown authority 或 TLS handshake timeout:先查 docker context 指向,再查代理和镜像源证书。

第一类最常见。Open WebUI 官方镜像通常把 HTTP 服务跑在容器 8080 端口,宿主机映射到 3000 后,直接访问 http://localhost:3000 不涉及证书环节。如果页面上有内容强制跳 https,或你手动写了 https,就会撞上协议不匹配。

# docker-compose.yml 片段
services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    ports:
      - "3000:8080"
    environment:
      - WEBUI_URL=http://localhost:3000
    volumes:
      - open-webui-data:/app/backend/data

WEBUI_URL 要和实际访问地址保持一致,否则应用内部生成的跳转连接可能带错协议或端口。

将Open WebUI部署到Windows Docker Desktop时TLS证书错误的排查

确实需要 HTTPS 时,在访问层加一层 Caddy

如果功能要求 HTTPS 访问,比如浏览器摄像头授权在部分场景要求安全上下文,一个低成本方案是在 Open WebUI 前面加 Caddy 反代。Caddy 会对 localhost 自动签发自签证书,不需要手工生成证书文件。

# Caddyfile,和 docker-compose.yml 同目录
localhost:3443 {
    tls internal
    reverse_proxy open-webui:8080
}
# docker-compose.yml 对应改法
services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    expose:
      - "8080"
    environment:
      - WEBUI_URL=https://localhost:3443
    volumes:
      - open-webui-data:/app/backend/data

  caddy:
    image: caddy:2
    ports:
      - "3443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro

启动后用 https://localhost:3443 访问,浏览器会提示自签不受信任。Caddy 的自签 root CA 写在它自己的数据卷里,用 docker compose exec caddy find /data -name '*.crt' 找到后导出一份,再在 Windows 双击导入“受信任的根证书颁发机构”。Docker Desktop 的 WSL2 后端和 Windows 证书信任机制不互通,容器里生成的证书不会自动出现在 Windows 信任区,必须显式导出导入。

将Open WebUI部署到Windows Docker Desktop时TLS证书错误的排查

验证信号和兜底手段

docker compose logs `--tail`=100 caddy
curl -k https://localhost:3443
curl -v https://localhost:3443 2>&1 | findstr "subject issuer"

curl 输出里 subject 和 issuer 都是 localhost,说明 TLS 链路通了。浏览器不再出现证书错误页,说明信任导入成功。

将Open WebUI部署到Windows Docker Desktop时TLS证书错误的排查

如果 docker 命令本身报 TLS 错误,先执行 docker context ls 确认当前 context 是否指向 desktop-linux。指向残留的远程 context 会让客户端用错误的证书握手,重新 docker context use desktop-linux 后再试。同时检查 Windows 系统时间,时间偏差会造成证书有效期校验失败。

本机调试、不对外提供服务时,HTTP 是成本最低的选择。HTTPS 留给确实需要安全上下文的浏览器功能,不值得为消除一个本地警告引出一整条信任链问题。