第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 指南中知识库未生效章节
提示无法读取
所有故障排查指南
连接错误 涵盖 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 按"原样"提供。请参阅你的许可证以获取适用条款。