跳到主要内容

常见问题

本页整理 OPL 数据空间使用过程中最常见的问题与答案。它覆盖部署、更新、容器、身份认证、RAG、音频和模型识别等主题。

常见方向​

为什么我更新镜像后看起来没有任何变化？​

仅仅 docker pull 最新镜像并不会更新正在运行的容器。正确流程通常是：

  1. 拉取新镜像
  2. 停止并删除旧容器
  3. 用相同的数据卷重新启动新容器

如果你使用了持久化卷，数据不会因为替换容器而丢失。

删除容器会不会丢数据？​

只要你正确挂载了数据卷，例如：

-v open-webui:/app/backend/data

你的数据就不会随着容器删除而消失。真正危险的情况，是你把数据写在容器内部而没有挂卷。

为什么重启后总是被登出，或者工具 token 解密失败？​

常见原因是没有设置固定的 WEBUI_SECRET_KEY。如果这个值每次启动都变化：

  • 旧的登录 cookie 会失效
  • 存储在系统中的敏感 token 无法再解密

解决方法：在环境变量中设置稳定、固定的 WEBUI_SECRET_KEY。

为什么我重启后需要重新创建账号，聊天记录也没了？​

通常说明你没有把 /app/backend/data 正确挂载到持久卷，或者之前的数据卷被误删。

为什么创建了新账号却提示需要管理员激活？​

因为第一次创建的账号会自动成为管理员。如果你丢失了那个管理员账号的密码，后续新建账号就需要管理员批准。请参考 重置管理员密码。

为什么 Speech-to-Text / Text-to-Speech 不能用？​

浏览器层面的 STT/TTS 往往依赖 HTTPS。若部署没有配置 HTTPS，很多浏览器会直接限制相关能力。

为什么 OPL 数据空间不内建 HTTPS？​

因为不同部署环境差异极大，统一内建 HTTPS 往往反而限制灵活性。项目更倾向于把 TLS 终止交给用户自己的反向代理或基础设施。

为什么 OPL 数据空间不原生支持每一家 provider 的私有 API？​

OPL 数据空间的核心设计原则是 优先支持标准协议，而不是为每个 provider 的私有接口逐一做特判。这能避免配置和行为不断膨胀，也更利于长期维护。

如果某个 provider 不遵循通用协议，通常推荐通过以下方式接入：

  • 使用 OpenAI 兼容端点
  • 使用中间代理，如 LiteLLM、OpenRouter
  • 使用 Pipe / Function 做桥接

为什么模型自述身份不准确？​

因为 LLM 不能可靠地识别自己是谁。当你问模型“你是什么模型”时，它只是继续生成文本，而不是调用一个系统诊断接口。验证真实模型应以：

  • 模型选择器
  • 管理面板连接配置
  • provider 日志

为准。

为什么 RAG 很差或者看起来完全没起作用？​

一个高频原因是上下文窗口太小。以 Ollama 为例，默认上下文常常只有 2048 token，这对文档检索和网页内容远远不够。通常建议至少提升到 8192，复杂场景更高。

为什么 API 上传文件后立刻加入知识库会报 “The content provided is empty”？​

这是异步处理的时序问题。文件上传接口会先返回文件 ID，而内容抽取和 embedding 是在后台继续完成的。你需要轮询处理状态，等到 completed 后再继续后续操作。

更详细的问答还包括：

  • Docker 与 GPU 支持
  • 为什么推荐使用官方 Docker
  • 为什么直接安装后更容易被系统环境变化影响
  • 反向代理与 TLS 配置思路
  • 推理模型 thinking block 显示为原始文本的原因

如果你遇到的是具体部署故障，也建议直接查阅：