故障排查与疑难解答
利用本页面快速锁定您所遭遇的问题。如果您不确定从何入手，可以通过下方的快速现象索引进行比对。
故障现象快速索引
| 您所看到的故障现象 | 快速排障指南入口 |
|---|---|
返回空的 "{}" 响应、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 → 进程异常崩溃专项排查 |
| 模型完全无视挂载好的知识库内容，答非所问 | RAG → 知识库失效专项排查 |
报错 NoneType object has no attribute 'encode' | RAG → 向量模型报错排查 |
| 执行向量化（Embedding）时抛出 CUDA 显存溢出错误 | RAG → CUDA OOM 显存溢出排查 |
| OAuth 重定向无限循环、CSRF 状态校验不一致 | 单点登录 SSO 与 OAuth |
登录报错 CSRF Warning! State not equal in request and response | 单点登录 SSO → CSRF 报错排查 |
语音朗读（TTS）无限加载或失效，日志报错 Dataset scripts are no longer supported | 语音与音频 → TTS 专项排查 |
语音输入（STT）Whisper 报错 int8 compute type | 语音与音频 → STT 专项排查 |
| 麦克风无法正常调用（非 HTTPS 环境安全策略拦截） | 语音与音频 → 麦克风权限排查 |
| 图像生成无响应，或 ComfyUI 工作流报错 | 图像生成故障排查 |
| 联网搜索（Web Search）返回空内容，或代理服务器配置失败 | 联网搜索故障排查 |
| 系统响应极度卡顿、物理 RAM 爆满或遭遇系统级内存溢出（OOM）崩溃 | 性能与内存优化指南 |
| 报错 "The prompt is too long" 提示词上下文超长限限制 | 排障：上下文超长解决方案 |
| 忘记了管理员（Admin）账 号的超级密码 | 重置管理员密码指南 |
系统启动时报错 no such table 或 table already exists | 数据库迁移与表修复 |
所有故障排除专题指南
| 专题指南 | 覆盖的具体故障与配置范畴 |
|---|---|
| 连接错误排查 | HTTPS 配置、CORS 跨域、WebSocket 握手、反向代理、Ollama 连通性、SSL 证书自签、Podman/MCP 部署 |
| 性能与内存优化 | 系统响应提速、数据库调优、集群扩展策略、服务器资源效能优化 |
| 上下文窗口管理 | 上下文超限报错的底层原理，及如何优雅配置 Filter 过滤器自动裁剪会话历史 |
| 检索增强生成 (RAG) | 文档切段与解析质量、向量化报错、文件导入上限、Worker 进程崩溃排查 |
| 单点登录 (SSO) & OAuth | OIDC、微软、谷歌、Authentik 接入配置，及 Cookie / 会话 Session 问题定位 |
| 语音与音频 | 语音输入（STT）、语音朗读（TTS）、麦克风设备权限、ElevenLabs 语音合成接入 |
| 集群部署与高可用 | 多副本部署、多 Workers 并发、Redis 缓存会话管理、共享存储与数据库高并发并发 |
| 图像生成 | OpenAI DALL-E、ComfyUI、Automatic1111 及 Gemini 图像生成故障定位 |
| 联网搜索 | 网络代理配置、SearXNG 接入报错、搜索结果为空与网络超时处理 |
| 重置管理员密码 | 针对 Docker 挂载卷或本地 Python pip 部署环境下的管理员密码重置 |
| 数据库手动迁移 | Alembic 表结构迁移指南，及如何从失败的数据库结构升级中恢复 |
💡 在开始排障之前
- 优先升级系统：大量的已知 Bug 都在最新的发布版本中得到了妥善解决。请首先确保您的 Open WebUI 已更新至最新的稳定版。
- 确认 PersistentConfig 覆盖：Open WebUI 将大部分全局配置存储在数据库中，这比操作系统环境变量具有更高的优先级。如果您修改了系统环境变量但在网页中未见成效，请参阅 环境变量配置 - PersistentConfig 注意事项 说明页面。
🌐 浏览器兼容性要求
Open WebUI 依托大量先进的现代 Web APIs。您使用的浏览器必须满足以下最低版本要求：
- Chrome 111+ (2023年3月发布)
- Safari 16.4+ (2023年3月发布)
- Firefox 128+ (2024年7月发布)
如果遭遇网页渲染错乱或按钮交互无响应，请首先确保您的浏览器符合上述标准。
👥 获取社区官方技术支持
如果在参考了对应的排障指南后依然无法解决问题：
- 检索 GitHub Issues 列表 确认是否已有类似报告；
- 前往 Discord 官方群组 或 Reddit 社区 发帖讨论；
- 赞助支持我们 的用户可以访问专属的支持通道，以获得更快速的官方排障响应。