故障排除

先确定故障层：浏览器、前端、后端、Ollama、提供商插件或部署网络。

快速检查

# App branch and local changes
git status

# Backend process liveness
curl http://localhost:3001/health/live

# Backend dependency readiness (SQLite, schema, and writable data storage)
curl http://localhost:3001/health/ready

# Ollama health
curl http://localhost:11434/api/tags

# Installed Ollama models
ollama list

开发环境中，前端通常运行在 http://localhost:5173，后端运行在 http://localhost:3001。打包的 npx libre-webui 流程在 http://localhost:8080 提供应用。

Libre WebUI 无法启动

检查 Node 和依赖

node --version
npm install
npm run dev

需要 Node.js 22.22 或更新版本。

端口已占用

lsof -i :3001
lsof -i :5173
lsof -i :8080

停止旧进程或配置其他端口。

后端无法写入数据

后端在设置 DATA_DIR 时将数据存储其中，否则使用 backend/data。源码启动从后端目录解析相对 DATA_DIR，而不是 shell 当前目录。因此 DATA_DIR=./data 选择 backend/data，历史支持值 DATA_DIR=./backend/data 选择 backend/backend/data。确保所选目录可写。未设置 DATA_DIR 时，若历史目录是唯一现有存储，Libre 会保留使用。若两个位置都含数据，请停止 Libre、备份两者并主动选择或迁移；Libre 绝不合并或复制分叉数据库。

健康端点有意区分运行中的进程和可用应用：

• 后端能提供 HTTP 时，/health 和 /health/live 返回 200。可选模型提供商不影响存活状态。
• 必需数据库、架构、存储或已注册平台依赖不可用时，/health/ready 返回 503。它不等待可选模型提供商，公共响应省略错误消息和内部详情。
• /health/deep 在受限 Worker 中执行 SQLite 完整性和外键检查，并汇总 Ollama 等可选服务器级提供商探测。可选提供商中断显示警告，不会使必需依赖未就绪。该端点需要当前管理员 Bearer 令牌，不适合频繁编排器探测。

curl -H "Authorization: Bearer $LIBRE_ADMIN_TOKEN" \
  http://localhost:3001/health/deep

浏览器无法访问后端

本地开发中，前端在设置时使用 VITE_API_BASE_URL，否则回退到开发后端。

前端 .env 示例：

VITE_API_BASE_URL=http://localhost:3001/api
VITE_WS_BASE_URL=ws://localhost:3001

VITE_WS_BASE_URL 可选；设置后作为 Chat 和 Work 终端套接字的共享基础。使用绝对 ws: 或 wss: URL；支持 wss://example.com/libre 等路径前缀。不要包含凭据、查询参数或片段。更改 Vite 变量后重启/重建前端。

后端 .env 示例：

CORS_ORIGIN=http://localhost:5173,http://127.0.0.1:5173

通过手机、LAN 或 Tailscale 访问时，不要把手机浏览器指向 localhost；使用笔记本的 LAN 或 Tailscale IP，并以主机绑定运行开发服务器：

npm run dev:host

该命令会在 8080 端口提供前端服务，并将 API 和 WebSocket 流量代理到本地 3001 端口的后端。只需让其他设备能够访问 8080 端口即可。如果在 frontend/.env 中设置了 VITE_API_BASE_URL 或 VITE_WS_BASE_URL，请确保这些 URL 可从其他设备访问，或者删除它们以使用开发服务器代理。

Chat 在反向代理后不流式响应

典型症状是消息成功发送但回复不显示，浏览器控制台报告 WebSocket 连接失败。确认代理允许 WebSocket 升级，且不会关闭长连接。

任一值已配置时，带 Origin 标头的浏览器升级会根据 CORS_ORIGIN 和 BASE_URL 检查。远程部署至少设置一个；都未设置时，为兼容本地开发而保持宽松。Electron 和非浏览器客户端可能省略 Origin，但仍必须先将 Authorization 标头换成短期一次性票据。后端应位于 TLS 之后，并使用与 HTTP API 相同的网络或反向代理访问控制。

公共主机名应在 Libre WebUI 服务中允许对应浏览器源：

services:
  libre-webui:
    environment:
      CORS_ORIGIN: https://chat.example.com
      BASE_URL: https://chat.example.com

以下 nginx 和 Caddy 示例假定代理运行在 Docker 宿主机，而仓库 Compose 配置将 Libre WebUI 发布到 8080。若代理加入 Compose 网络，请使用 libre-webui:3001 作为上游地址。

nginx

nginx 要求显式转发升级标头。较长读取超时可在模型工作时保持空闲聊天连接。

location /ws {
    proxy_pass http://127.0.0.1:8080;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 3600s;
}

使用 nginx -t 验证配置后重新加载 nginx。

Caddy

Caddy 的 reverse_proxy 原生支持 WebSocket，无需升级标头：

chat.example.com {
    reverse_proxy 127.0.0.1:8080
}

Traefik

Traefik 也默认处理 WebSocket 升级。当其 Docker 提供商与 Libre WebUI 共享网络时，只需常规路由器和服务标签：

labels:
  - 'traefik.enable=true'
  - 'traefik.http.routers.libre-webui.rule=Host(`chat.example.com`)'
  - 'traefik.http.routers.libre-webui.entrypoints=websecure'
  - 'traefik.http.routers.libre-webui.tls=true'
  - 'traefik.http.services.libre-webui.loadbalancer.server.port=3001'

若流连接后又断开，检查 Traefik 前所有代理或负载均衡器的空闲超时。Traefik 自身执行限制时，调整入口点 transport.respondingTimeouts 设置。

未检测到 Ollama

确认 Ollama 正在运行

curl http://localhost:11434/api/tags

配置自定义 Ollama URL

后端 .env：

OLLAMA_BASE_URL=http://localhost:11434

若 Libre WebUI 在 Docker 中运行、Ollama 在宿主机运行，请使用外部 Ollama Compose 文件，或将 OLLAMA_BASE_URL 指向容器可访问的宿主机地址。

模型拉取问题

先从终端拉取

ollama pull gemma4:12b

若终端拉取失败，问题不在 Libre WebUI。

云模型

在模型管理器中使用云筛选器选择 Ollama Cloud 模型。Libre WebUI 会在此流程规范化所需云后缀，受支持云条目无需手动添加 :cloud。

用户无法拉取模型

管理员可禁止普通用户拉取模型。非管理员能浏览模型但不能安装时，请检查管理员设置。

Chat 缓慢或失败

• 使用更小的模型。
• 通过 ollama ps 检查已加载模型。
• 减少上下文长度。
• 对很长响应降低最大令牌数。
• 确认模型能装入 RAM/VRAM。
• 对提供商插件，确认 API 密钥和提供商配额。

OpenAI 图片生成不可用

• 激活内置 OpenAI 提供商。为当前用户保存 API 密钥，或配置可信内置提供商的 OPENAI_API_KEY 环境回退。
• 打开图片生成设置，启用图片生成，并选择公布的 GPT Image 模型。
• 优先使用 gpt-image-2。旧 GPT Image ID 只为兼容现有配置而保留，在上游已弃用。
• 除非运行兼容图片端点，否则保持 OpenAI image_endpoint 覆盖为空。Chat /responses 或 /chat/completions 端点不能处理 Image API 请求。
• 若 OpenAI 在密钥和配额有效时仍拒绝 GPT Image 请求，确认 API 组织有资格使用 GPT Image 模型。

图片可用性使用当前用户保存的凭据或可信内置提供商的环境回退评估。仅保存在另一用户设置中的密钥不会公开图片模型。

提供商端点问题

OpenAI 兼容提供商在错误路径接收请求时，检查 设置 → 插件：

• 为 /chat/completions 载荷选择 Chat Completions，为 /responses 载荷选择 Responses。
• 将 API 根（如 https://provider.example/v1）输入基础 URL。
• 模式使用默认路径时将 API 路径留空，或输入提供商给出的带前导斜杠路径。
• 真正的自定义旧版完整端点有最高优先级；切回基础 URL 和 API 路径时请清除。升级后，仅等于内置清单旧默认值的存储值会自动忽略。自定义端点以 /chat/completions 或 /responses 结尾时，后缀也决定请求格式，防止收到错误载荷。

导入插件 JSON 支持使用 OpenAI Chat Completions、OpenAI Responses、Anthropic 或 Gemini 兼容协议的提供商。若提供商使用专有载荷、流式事件、工具调用或响应格式，需要后端适配器；只更改端点无法翻译协议。

提供商 URL 可使用 HTTP 或 HTTPS。HTTP 在无传输加密时发送凭据和流量，因此仅限可信网络上的自托管网关，并尽可能使用 HTTPS。基础 URL 不能包含查询字符串或片段；相对 API 路径不能含字面或重复编码的遍历段、查询或片段。验证边界内无法稳定的过度编码会被拒绝。

模型刷新将包括 /responses 在内的已知操作后缀替换为 /models。激活、显式刷新和已保存连接覆盖使用当前用户的端点和 API 密钥。保存或移除该用户 API 密钥以及重置连接覆盖也会刷新列表；无关生成参数不会。发现 ID 按用户存储，绝不覆盖共享插件 JSON。提供商不支持推导路由时，在插件 model_map 中手动配置模型 ID。

提供商请求有意不跟随 HTTP 重定向，包括模型发现、Chat、Work、图片、嵌入和文字转语音。请配置最终目标 URL，而不是重定向 URL。此安全失败行为可防止授权标头跳到未验证目标。

Work 报告运行中提供商路由改变时，在完成设置更新后开始新运行。Work 有意在下一次提供商请求前停止，防止先前工具状态重放到不同模式、端点或 API 密钥身份验证边界。

请求来自后端，因此后端在容器内运行时 localhost 指 Libre WebUI 容器，而不会自动指向宿主机。Compose 或 Kubernetes 部署应使用网关服务 DNS，例如 http://ai-gateway:8080/v1。只有容器运行时提供该宿主机别名时才使用 http://host.docker.internal:8080/v1。即使名称解析到私有地址，HTTP 流量也是明文。

图片模型可用性、端点覆盖和 API 密钥也为当前用户解析。图片请求似乎使用其他账户设置时，确认请求以预期用户身份验证。

还应遵守以下安全和所有权规则：

• 以管理员身份登录才能更改提供商路由。插件定义和连接字段由实例管理；普通用户仍可保存生成设置、凭据和自己的激活状态。
• 使用旧版 endpoint 或 api_url 覆盖时，输入完整 API 端点 URL，包括操作路径（如 https://provider.example/v1/chat/completions）。仅在 base_url 中输入 API 根，并配合 api_mode 和可选 api_path。
• 接受绝对 HTTP 和 HTTPS 端点。HTTP 只用于可信网络上的自托管网关，否则 API 密钥、提示词和响应无传输加密。
• 空覆盖使用插件定义内置端点。显式格式错误或不安全覆盖会拒绝；Libre WebUI 不会悄然把请求发送到内置提供商端点。
• 只有未遮蔽内置定义保留可信根端点、身份验证字段、能力端点与选择器和路由变量默认值时，才使用部署环境密钥。导入定义、复用内置 ID 的可写定义和管理员保存的自定义路由需要同一账户保存凭据。只有环境密钥时，Libre WebUI 有意报告提供商不可用并跳过发现。
• 升级前自定义定义会隔离，因为旧版本未记录管理员来源。以管理员身份重新导入 JSON，再让每位用户重新激活。直接编辑已批准插件 JSON 会再次隔离；使用管理员安装或更新流程记录源路径和定义哈希。
• 保存的凭据绑定到输入时有效的路由、身份验证契约、定义和源。更改端点或定义后，重新保存账户凭据。旧版未绑定凭据只在完全匹配的锚定内置路由上自动迁移。
• 导入插件可将 api_url 用作旧版完整操作 URL 别名。两字段都有值时 endpoint 优先。模型发现位于其他位置时，在 models_endpoint 设置完整模型列表 URL；它会验证且不跟随重定向。
• 保存端点和凭据后激活插件。激活从完整端点推导 /models URL，并使用激活用户凭据发现，除非设置 models_endpoint。保存或重置连接字段也会刷新发现。请求会等待发现完成后再重新加载插件列表。激活按账户划分，其他用户必须分别激活同一共享插件。
• 在 设置 → 插件 中选择提供商并选择 刷新模型 明确检查目录。模型表只读，显示当前账户配置或发现的 ID。暂时发现失败会保留之前目录，或在没有旧结果时使用插件回退 model_map，因此检查完成本身不证明远程端点健康。
• 自动发现需要 OpenAI 兼容 data 模型 ID 数组。成功目录按用户存储，不更改共享插件 JSON。普通激活在发现不可用时保留用户旧目录。更改或重置连接字段会先清除过期目录，因此失败刷新使用插件现有 model_map；必要时在插件 JSON 配置回退模型 ID。
• 图片模型可用性、端点覆盖和 API 密钥也按当前用户解析。若图片请求似乎使用其他账户设置，请验证请求身份。
• 若升级后的非管理员账户曾存储路由值，对该插件使用 重置。被忽略旧值会清除，防止以后角色变化时激活。保存或重置路由也会清除该账户发现模型，防止旧目录跟随旧路由。
• 请求来自后端。Libre WebUI 在容器中运行时，localhost 指容器，而不是宿主机。
• 提供商请求不跟随重定向。直接配置最终验证操作 URL。

Chat 使用错误提供商或显示不可用

同一模型 ID 可同时存在于 Ollama 和多个插件。当前 Chat 会话和默认模型偏好设置同时保存所选提供商和原始模型 ID，因此同名条目是独立选择。

• 选择器显示提供商不可用时，重新激活或安装确切插件，并确认模型映射仍含已保存模型 ID。
• 提供商或模型被主动移除时，明确选择替代项。Libre WebUI 不会把精确保存选择重定向到另一提供商的同名模型。
• 旧会话和偏好设置可能没有提供商元数据。由于 Libre WebUI 无法推断原提供商，这些记录继续使用旧版按名称路由。模型选择器显示“未记录提供商”。重新选择所需 Ollama 或插件条目，为以后请求固定。
• 角色条目仍标记 persona:<id>。新选择角色会记录 Ollama 为后端提供商；没有提供商元数据的历史角色会话保持兼容。

Work 问题

Work 缺失或报告运行时不可用

Work 需要当前已验证且拥有 Work 访问权限的账户——管理员，或管理员从设置中的用户管理选项卡向所有用户开放后任一活跃用户。容器运行时必须可供 Libre WebUI 后端访问：

docker info
docker version

默认 Docker 后端应确认 Docker 运行，且运行 Libre WebUI 的操作系统用户可调用已配置 WORK_DOCKER_COMMAND。通过 npx 安装 Libre WebUI 不会安装 Docker。运行时缺失时，其余应用仍可用，Libre WebUI 不会回退到在宿主机执行模型命令。

仓库 Compose 文件通过挂载宿主机 Docker 套接字启用 Work。Kubernetes 上使用 Helm 值 work.enabled=true 启用原生 Pod/PVC 运行时；不要挂载节点运行时套接字。Compose 部署仍报告 Runtime unavailable 时，Work 页面指出具体原因：

消息	原因和修复
The "docker" CLI is not installed…	自定义映像没有 docker-cli。使用官方映像，或将 WORK_DOCKER_COMMAND 指向 CLI。
No Docker daemon is reachable…	移除了套接字挂载，或宿主机守护进程停止。恢复 Compose 挂载并启动 Docker。
The Docker socket is mounted but…cannot open	套接字组与容器不同。在 .env 中设置 DOCKER_GID 并重新创建容器。
Work 屏幕/音频以 WebSocket 1006 关闭，并记录 screen is unreachable	容器化后端在连接自身的回环地址。Docker Desktop 上使用随附的 WORK_DOCKER_PUBLISHED_HOST=host.docker.internal；原生 Docker Engine 上还需把 WORK_PREVIEW_BIND 设为非公开的 Docker 网桥网关，然后重新创建 Libre WebUI。

应通过容器读取套接字组，因为 macOS 宿主机报告值与容器所见不同：

echo "DOCKER_GID=$(docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
  alpine stat -c '%g' /var/run/docker.sock)" >> .env
docker compose up -d --force-recreate

该套接字授予等同 root 的 Docker 宿主机控制权；参阅 Work：隔离工作区了解部署影响。

模型不支持工具

Work 需要支持工具的聊天模型。对 Ollama，选择已安装且报告能力含 tools 的模型。对插件模型：

• 确认聊天或补全插件活跃。
• 确认所选模型在插件配置模型列表中。
• 确认当前管理员有可用 API 密钥。
• 确认提供商为该确切模型支持工具调用。

Libre WebUI 不会悄然把失败 Work 运行路由到其他提供商。

Work 请求返回 HTTP 429

实例达到任务或活跃运行时准入限制。默认情况下，Libre WebUI 允许整个实例两个活跃容器任务、每用户一个。运行预览也占用运行时容量。等待其他操作完成，停止未使用预览，或让操作员审核 WORK_MAX_ACTIVE_RUNTIMES_* 和 WORK_MAX_TASKS_* 设置。

软件包安装或网络访问失败

新 Work 任务使用 Docker 桥接网络，使生成项目可下载软件包并启动预览。检查 Docker DNS、代理配置、注册表可用性和 活动 中的命令输出。Libre WebUI 不会把宿主机 SSH 密钥、云凭据、浏览器配置或 Docker 套接字挂载到任务容器。

Work 预览无法启动

• 确保服务器在 WORK_PREVIEW_PORT（默认 4173）上绑定 0.0.0.0。
• 将可选命令留空，自动检测 package.json 的 dev 脚本或纯 index.html，包括单个嵌套应用。
• Work 报告多个应用或没有受支持入口点时，在可选命令字段输入项目明确开发命令。命令从 /workspace 启动；嵌套应用使用 cd <app-directory> && ...。
• 展开错误详情检查启动输出。
• 启动需要容器的其他命令前停止现有预览。

预览 URL 使用动态分配环回端口。因此浏览器和 Libre WebUI 后端需要运行在同一计算机。连接远程后端的浏览器无法访问其环回预览，HTTPS 页面也可能将纯 HTTP 预览作为混合内容阻止。

工作区文件无法打开或保存

Work 文件 API 接受最多 2 MB 的 UTF-8 文本文件。文件在打开后发生变化时，保存前重新加载，避免覆盖新版本。格式化仅支持少于 100,000 个字符、4,000 行的兼容文件类型；大文件暂停语法高亮，以保持编辑响应。

未保存编辑作为草稿保存在当前浏览器中，不能替代保存到持久工作区。

任务或预览已停止

停止运行、停止预览或重启 Libre WebUI 会停止一次性容器进程，但保留任务命名工作区卷。重新打开任务并重启预览。删除任务不同：确认后永久移除任务和工作区。

登录与注册问题

首位用户不是管理员

只有全新数据库中创建的第一个账户成为管理员。现有数据库保留当前用户和角色。

JWT 错误

生产环境设置稳定密钥：

JWT_SECRET=replace-with-a-long-random-secret

更改 JWT_SECRET 会使现有会话失效。

Turnstile 阻止注册

只有两个密钥都存在时才启用 Turnstile：

TURNSTILE_SITE_KEY=...
TURNSTILE_SECRET_KEY=...

注册突然失败时，确认站点密钥与域名匹配，且密钥有效。

OAuth 重定向失败

在提供商控制台和后端 .env 中设置回调 URL：

BASE_URL=https://your-domain.example
GITHUB_CALLBACK_URL=https://your-domain.example/api/auth/oauth/github/callback
HUGGINGFACE_CALLBACK_URL=https://your-domain.example/api/auth/oauth/huggingface/callback

文档聊天问题

Libre WebUI 接受最大 10 MB 的 PDF、Office（DOCX/PPTX/XLSX）、Markdown、HTML、代码和 CSV 文件。

若搜索可用但语义检索不可用：

1. 安装 nomic-embed-text 等嵌入模型。
2. 在设置中启用嵌入。
3. 从文档设置或 API 重新生成嵌入。

ollama pull nomic-embed-text

禁用嵌入时，关键词搜索仍可用。

构件预览问题

对于游戏或交互式 HTML，请让模型生成单个完整、独立的 HTML 文件，其中内联 CSS 和 JavaScript。

若构件需要键盘输入：

• 先单击预览区域。
• 使用“打开”按钮在独立浏览器标签页中运行。
• 不要依赖响应中未包含的本地文件。

Libre WebUI 可以捆绑常见 index.html + CSS + JavaScript 代码块，但独立 HTML 仍是最可靠输出。

Docker 问题

容器无法访问 Ollama

Ollama 不在同一 Compose 堆栈中时，使用外部 Ollama Compose 文件：

docker compose -f docker-compose.external-ollama.yml up -d

数据不持久

挂载持久数据卷，必要时设置 DATA_DIR。使用 DATA_DIR 或 Docker 模式时，加密密钥存储在持久存储中。

重置本地数据

先停止应用，然后备份并删除当前数据目录。默认开发数据位于 backend/data。

cp -R backend/data backend/data.backup
rm -rf backend/data

重启后端并创建新账户。

仍未解决？

提交 Issue，并提供：

• Libre WebUI 版本和 Commit
• 安装方式
• 操作系统
• Node.js 版本
• Ollama 版本
• Work 问题中的 Docker 版本和 docker info 结果
• 故障附近的后端日志
• 浏览器控制台错误
• 使用的确切模型或提供商
• 任务或预览失败时的 Work 活动输出