Misc. bug: web UI unavailable when running the docker server vulkan image

快速结论：该问题出现在使用 Docker/podman 运行 server-vulkan、full-cuda、server-cuda13 等镜像时，Web UI 无法访问，浏览器返回 404 JSON 错误。优先排查镜像是否包含 Web UI 静态资源文件，或尝试手动下载挂载 UI 资源。

问题场景

用户在 Linux 上使用 podman 或 Docker 运行 llama.cpp 的 server-vulkan 镜像（版本 9501），启动容器后通过浏览器访问 http://localhost:10000/ 时，Web UI 不可用，仅返回 JSON 错误。该问题也影响 full-cuda 和 server-cuda13 镜像。

报错原文

{"error":{"message":"File Not Found","type":"not_found_error","code":404}}

原因分析

可能原因：镜像构建过程中未正确打包 Web UI 静态资源文件（如 index.html、bundle.js、bundle.css、loading.html），导致 llama-server 无法提供这些文件。Issue 中用户推测此问题可能关联 PR #22937 引入的变更。

环境排查

确认镜像标签：ghcr.io/ggml-org/llama.cpp:server-vulkan 或其他变体（如 full-cuda、server-cuda13）。
确认 version 信息：version: 9501 (65ef50a0a)（该版本已被撤回）。
确认容器内 /ui 目录是否存在且包含 Web UI 资源文件。
检查容器启动日志中是否有关于静态资源加载的错误。

解决步骤

手动下载 Web UI 资源并挂载到容器（已验证的临时方法）：

mkdir -p ~/.cache/llama.cpp/ui/dist

for f in index.html bundle.js bundle.css loading.html; do
  curl -sfL -o ~/.cache/llama.cpp/ui/dist/$f \
    "https://huggingface.co/buckets/ggml-org/llama-ui/resolve/latest/$f?download=true"
done

然后在 podman/docker run 命令中添加挂载参数并指定路径：

-v ~/.cache/llama.cpp/ui/dist:/ui:ro --path /ui

示例完整命令（基于 Issue 中的 podman 命令）：

podman run -d \
    --pull=newer \
    --name gemma4_12B \
    --device /dev/dri/ \
    --network pasta:--map-guest-addr,10.0.0.1 -p 10000:10000 \
    -v /home/<redacted>/.cache/llama.cpp/:/models \
    -v /home/<redacted>/.cache/llama.cpp:/root/.cache/llama.cpp \
    -v /home/<redacted>/.cache/huggingface/hub/:/root/.cache/huggingface/hub/ \
    -v /home/<redacted>/.cache/llama.cpp/ui/dist:/ui:ro \
    ghcr.io/ggml-org/llama.cpp:server-vulkan \
    -hf unsloth/gemma-4-12b-it-GGUF:Q6_K \
    --port 10000 \
    --host 0.0.0.0 \
    --ctx-size 32768 \
    --batch-size 512 \
    --temp 1.0 \
    --reasoning on \
    --path /ui

升级到包含修复的镜像版本（可优先尝试）：Issue 提到此问题已由 PR #24794 修复。建议拉取最新镜像并重新创建容器，检查是否内置了 Web UI 资源。
注意：根据 Issue 关闭状态，该修复应已合入，升级后可能不再需要手动挂载。
避免使用已撤回版本 9501：如果仍在使用 version 9501，应优先拉取更新版本的镜像。

验证方法

重启容器后，使用浏览器（或 curl）访问 http://localhost:10000/：应返回 llama.cpp Web UI 页面，而不是 JSON 错误。若问题仍存在，请检查容器日志以确认是否还有其他依赖问题。

参考来源

ggml-org/llama.cpp #24107

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。

Misc. bug: web UI unavailable when running the docker server vulkan image