故障排查
使用本页可以快速找到与你问题对应的指南。如果不确定从哪里开始，请先在下表中按症状定位。
快速症状索引
| 你看到的问题 | 跳转到 |
|---|---|
聊天返回空的 "{}"、Markdown 乱码、控制台出现 CORS 错误 | 连接错误 → HTTPS/CORS/WebSocket |
WebSocket connection failed: 403 或聊天卡住 | 连接错误 → WebSocket |
| Open WebUI 无法连接 Ollama | 连接错误 → Ollama |
模型列表加载极慢 / /api/models 返回 500 | 连接错误 → 模型列表加载 |
[SSL: CERTIFICATE_VERIFY_FAILED] | 连接错误 → SSL |
| 多副本场景下登录循环、401 Unauthorized、跨副本 token 错误 | 扩缩容与高可用 → 登录循环 |
database is locked、不同实例之间数据忽隐忽现 | 扩缩容与高可用 → 数据库 |
上传时 worker 崩溃：Child process [pid] died | RAG → Worker 崩溃 |
| 模型忽略已附加的知识库 | RAG → 知识库不生效 |
Agent 在多次工具调用后中途停止 / Tool-call limit reached (N iterations). | CHAT_RESPONSE_MAX_TOOL_CALL_ITERATIONS |
NoneType object has no attribute 'encode' | RAG → 嵌入错误 |
| 嵌入时出现 CUDA out of memory | RAG → CUDA OOM |
| OAuth 重定向循环、CSRF state 不匹配 | SSO 与 OAuth |
CSRF Warning! State not equal in request and response | SSO → CSRF 错误 |
TTS 一直加载、Dataset scripts are no longer supported | 音频 → TTS 问题 |
Whisper 报 int8 compute type 错误 | 音频 → STT 问题 |
| 麦克风不能用（非 HTTPS） | 音频 → 麦克风 |
| 图像无法生成、ComfyUI workflow 报错 | 图像生成 |
| Web Search 返回空内容或代理错误 | Web Search |
| 性能慢、RAM 占用高、OOM 崩溃 | 性能与内存 |
| 编辑模型/知识库权限时容器被 OOM kill（SQLite） | 性能与内存 → SQLite 在受限容器中的内存占用 |
| "The prompt is too long" / context length exceeded | 上下文窗口 / Prompt Too Long |
| 忘记管理员密码 | 重置管理员密码 |
启动时出现 no such table 或 table already exists | 数据库迁移 |
全部故障排查指南
| 指南 | 涵盖内容 |
|---|---|
| 连接错误 | HTTPS、CORS、WebSocket、反向代理、Ollama、SSL、Podman、MCP |
| 性能与内存 | 速度调优、数据库优化、基础设施扩缩容、资源效率 |
| 上下文窗口 / Prompt Too Long | 为什么会出现 “prompt is too long” 以及如何用过滤器管理聊天历史 |
| RAG | 文档导入、检索质量、嵌入、上传限制、worker 崩溃 |
| SSO 与 OAuth | OIDC、Microsoft、Google、Authentik、cookie 与会话问题 |
| 音频 | Speech-to-Text、Text-to-Speech、麦克风访问、ElevenLabs |
| 扩缩容与高可用 | 多副本、多 worker、Redis、共享存储、数据库并发 |
| 图像生成 | OpenAI、ComfyUI、Automatic1111、Gemini |
| Web Search | 代理问题、SearXNG、空结果、超时 |
| 重置管理员密码 | Docker 与本地安装的密码重置 |
| 数据库迁移 | 手动 Alembic 迁移、升级失败后的恢复 |
开始之前
- 先更新。 很多问题会在较新的版本中修复。请先确认你正在使用最新版本。
- 检查 ConfigVar。 Open WebUI 会把部分设置存到数据库中，并且这些设置优先级高于环境变量。如果你发现修改 env var 后似乎没有生效，请参阅 环境变量配置。
浏览器兼容性
Open WebUI 需要现代浏览器。最低支持版本：
- Chrome 111+ (2023 年 3 月)
- Safari 16.4+ (2023 年 3 月)
- Firefox 128+ (2024 年 7 月)
如果你遇到渲染或功能问题，请先确认浏览器满足这些要求。
社区支持
如果按照对应指南排查后仍然卡住：
- 在 GitHub 搜索现有 issues
- 在 GitHub Discussions 提问
- 赞助支持 可使用专属支持渠道，响应更快