进阶 docs.openwebui.com 2026-10-22 19:22:27 · 27 阅读

第9章 Open WebUI 故障排查指南

故障排查

使用本页快速定位对应指南。如果不确定从何入手,请在下表比对当前症状。

快速症状索引

空 "{}" 响应、Markdown 乱码、控制台出现 CORS 错误 查看连接错误指南中的 HTTPS、CORS 或 WebSocket 章节 WebSocket 连接失败(403)或聊天卡住 查看连接错误指南中的 WebSocket 章节 开启工具后助手随机出现空白回复 查看连接错误指南中关于工具调用导致空白回复的内容 Open WebUI 无法连接 Ollama 查看连接错误指南中 Ollama 章节 模型列表加载极慢,或 /api/models 返回 500 查看连接错误指南中模型列表加载章节 间歇性"模型未找到"、模型列表自行清空、出现 ClientConnectorDNSError 查看连接错误指南中关于间歇性域名解析失败的内容 出现 [SSL: CERTIFICATE_VERIFY_FAILED] 查看连接错误指南中的 SSL 章节 登录循环、401 未授权、多副本间 Token 错误 查看扩展性与高可用指南中的登录循环章节 数据库锁死、多实例间数据丢失 查看扩展性与高可用指南中的数据库章节 日志显示 Redis 拒绝发布或订阅消息,实时更新停止 查看性能调优指南中关于每房间 Redis 通道的内容 上传时工作进程崩溃:Child process [pid] died 查看 RAG 指南中工作进程崩溃章节 模型忽略附件知识库 查看 RAG 指南中知识库未生效章节 提示无法读取 内容,或 YouTube 视频无法挂载 查看 RAG 指南中链接与 YouTube 附件章节 执行多次工具调用后中途停止,或达到工具调用限制 (N 次迭代) CHAT_RESPONSE_MAX_TOOL_CALL_ITERATIONS Responses 连接在生成结束或中途变空时异常 查看 Open Responses 指南中偏离格式规范的提供商章节 Responses 连接中,模型回答时仿佛之前的回复未发生 查看 Open Responses 指南中偏离格式规范的提供商章节 NoneType object has no attribute 'encode' 查看 RAG 指南中嵌入错误章节 嵌入时 CUDA 内存溢出 查看 RAG 指南中 CUDA 内存溢出章节 OAuth 重定向循环、CSRF 状态不匹配 查看 SSO 与 OAuth 指南 提示 CSRF Warning! State not equal in request and response 查看 SSO 指南中 CSRF 错误章节 SSO 登录显示"邮箱或密码不正确",日志包含 Unsupported {'app_id'} in header 查看 SSO 指南中提供商添加 ID Token 参数的章节 升级后所有 SSO 用户无法登录,日志显示 UserModel 在 oauth 处有 1 个验证错误 查看 SSO 指南中延迟升级导致账户锁定章节 更改 WEBUI_SECRET_KEY 后开启双因素认证,Open WebUI 拒绝启动 查看双因素认证指南中的要求章节 用户丢失了认证器及恢复码 查看双因素认证指南中丢失认证器恢复章节 TTS 加载卡死,或提示数据集脚本不再受支持 查看音频指南中 TTS 问题章节 Whisper int8 计算类型错误 查看音频指南中语音转文字问题章节 麦克风无法工作(非 HTTPS 环境) 查看音频指南中麦克风章节 实时语音通话失败(语音连接失败,提供商拒绝语音配置) 查看语音模式排查指南 图像未生成,或 ComfyUI 工作流报错 查看图像生成指南 聊天中的图片显示"图片不可用" 查看图像生成指南中的常规问题章节 网络搜索返回空内容或代理错误 查看网络搜索指南 性能缓慢、内存占用高、OOM 崩溃 查看性能与内存指南 编辑模型或知识库权限时容器被 OOM 杀掉(SQLite) 查看性能与内存指南中 SQLite 内存占用章节 提示"The prompt is too long"或上下文长度超限 查看上下文窗口与提示词过长指南 忘记管理员密码 查看重置管理员密码指南 启动时报无此表或表已存在 查看数据库迁移指南 CORS 警告后,Apple Silicon (M1/M2/M3) 上容器启动卡住 查看启动指南中 Apple Silicon 卡死章节 开启 OFFLINE_MODE 后启动未加载嵌入模型 查看启动指南中离线嵌入章节

所有故障排查指南

连接错误 涵盖 HTTPS、CORS、WebSocket、反向代理、Ollama、DNS、SSL、Podman、MCP 性能与内存 涵盖速度调优、数据库优化、基础设施扩展、资源效率 上下文窗口 / 提示词过长 解释为何出现"提示词过长"错误,以及如何通过过滤器管理聊天历史 RAG 涵盖文档摄入、检索质量、嵌入、上传限制、工作进程崩溃 SSO 与 OAuth 涵盖 OIDC、Microsoft、Google、Authentik、Cookie 与会话问题 音频 涵盖语音转文字、文字转语音、麦克风访问、ElevenLabs 扩展性与高可用 涵盖多副本、多工作进程、Redis、共享存储、数据库并发 图像生成 涵盖 OpenAI、ComfyUI、Automatic1111、Gemini 网络搜索 涵盖代理问题、SearXNG、空结果、超时 启动与 Docker 故障 涵盖容器启动卡住、Apple Silicon 模拟、离线模式嵌入失败 重置管理员密码 涵盖 Docker 与本地安装环境的密码重置 数据库迁移 涵盖手动 Alembic 迁移、从升级失败中恢复

开始前

先更新。许多问题已在较新版本中修复。请确保你正在使用最新版本。 检查 ConfigVar。Open WebUI 将部分设置存储在数据库中,其优先级高于环境变量。如果环境变量修改似乎未生效,请参阅环境变量配置页面。

浏览器兼容性

Open WebUI 需要现代浏览器。最低支持版本:

Chrome 111+ (2023年3月) Safari 16.4+ (2023年3月) Firefox 128+ (2024年7月)

如果遇到渲染或功能问题,请确认浏览器满足上述要求。

社区支持

如果按相关指南操作后仍无法解决:

在 GitHub 上搜索现有 Issue 在 Discord 或 Reddit 上提问 赞助商可获得专属支持渠道,响应速度更快 本内容仅供参考,不构成任何担保、保证或合同承诺。Open WebUI 按"原样"提供。请参阅你的许可证以获取适用条款。

评论 (0)