故障排查
用这个页面快速找到最贴近你问题的排障指南。如果你还不知道该从哪里开始，就先用下面的症状表定位。
常见症状速查
| 现象 | 前往 |
|---|---|
返回空 "{}"、Markdown 乱码、控制台出现 CORS 报错 | 连接错误 → HTTPS/CORS/WebSocket |
WebSocket connection failed: 403 或聊天卡住 | 连接错误 → WebSocket |
| OPL 数据空间无法连接 Ollama | 连接错误 → Ollama |
模型列表加载极慢，或 /api/models 返回 500 | 连接错误 → 模型列表加载 |
[SSL: CERTIFICATE_VERIFY_FAILED] | 连接错误 → SSL |
| 多副本环境出现登录循环、401 或 token 异常 | 扩缩容与高可用 → 登录循环 |
| 某个组织正常，另一个组织缺 provider 或功能 | 管理作用域 |
| 新用户进入了错误组织，或租户数据看起来错位 | 组织维护 |
| 上线或迁移时启动后进入维护模式 | 组织维护 |
database is locked，或多实例间数据异常丢失 | 扩缩容与高可用 → 数据库 |
上传文档时 worker 崩溃：Child process [pid] died | RAG → Worker 崩溃 |
| 模型忽略了已绑定的知识库 | RAG → 知识库未生效 |
NoneType object has no attribute 'encode' | RAG → Embedding 错误 |
| 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 问题 |
Whisper 报 int8 compute type 错误 | 音频 → STT 问题 |
| 麦克风不能用（非 HTTPS） | 音频 → 麦克风 |
| 图片无法生成，或 ComfyUI 工作流报错 | 图像生成 |
| 网页搜索返回空内容或代理错误 | 网页搜索 |
| 性能慢、内存高、OOM 崩溃 | 性能与内存 |
| “The prompt is too long” / 超出上下文长度 | 上下文窗口 / Prompt 过长 |
| 忘记管理员密码 | 重置管理员密码 |
启动时报 no such table 或 table already exists | 数据库迁移 |
全部排障指南
| 指南 | 覆盖内容 |
|---|---|
| 连接错误 | HTTPS、CORS、WebSocket、反向代理、Ollama、SSL、Podman、MCP |
| 性能与内存 | 性能调优、数据库优化、扩缩容基础设施、资源效率 |
| 上下文窗口 / Prompt 过长 | 为什么会出现“prompt 太长”，以及如何借助 filter 管理聊天历史 |
| RAG | 文档导入、检索质量、embedding、上传限制与 worker 崩溃 |
| SSO 与 OAuth | OIDC、Microsoft、Google、Authentik、Cookie 与 session 问题 |
| 音频 | 语音转文本、文本转语音、麦克风访问、ElevenLabs |
| 扩缩容与高可用 | 多副本、多 worker、Redis、共享存储、数据库并发 |
| 维护教程 | 面向租户的上线、备份、存储、修复与迁移准备 |
| 图像生成 | OpenAI、ComfyUI、Automatic1111、Gemini |
| 网页搜索 | 代理问题、SearXNG、空结果、超时 |
| 重置管理员密码 | Docker 与本地安装的密码重置方法 |
| 数据库迁移 | Alembic 手动迁移与升级失败恢复 |
排查前先确认
- 先更新。 很多问题在新版本里已经修复，先确认你在用的不是旧版本。
- 确认 PersistentConfig。 OPL 数据空间会把部分设置写入数据库，它们会覆盖环境变量。如果你改了 env 却看起来没生效，请先看 环境变量配置。
- 先确认是不是作用域问题。 在组织化部署中，故障可能只发生在某个选中组织里，而不是整个实例。
- 先确认是否处于维护态。 在组织感知的上线或迁移中，启动迁移和修复流程可能会让实例暂时进入维护模式。不要把它误判成普通宕机，先看 组织维护。
浏览器兼容性
OPL 数据空间需要现代浏览器。最低支持版本：
- Chrome 111+（2023 年 3 月）
- Safari 16.4+（2023 年 3 月）
- Firefox 128+（2024 年 7 月）
如果你遇到渲染或功能问题，先确认浏览器版本满足要求。
社区支持
如果按对应指南排查后仍然没有解决：