故障排查
按症状对号入座。大多数问题按顺序做三步就能定位：重启应用 → 看报错原文 → 查日志。
桌面端启动失败 / 后端起不来
桌面端内嵌本地后端（sidecar），启动时会做健康检查（最长等 60 秒），超时未就绪会进入错误页。
- 先彻底退出再重启：桌面端是托盘常驻，关窗口不等于退出。右键托盘图标选「退出」，再重新启动。
- 检查是否装了杀毒软件拦截：本地后端只监听 127.0.0.1 回环地址，若被安全软件误拦，放行后重启。
- 看后端日志：打开
%APPDATA%\psb-desktop\logs\backend.log，拉到最后看报错行（错误页也会提示这个路径）。 - 仍不行：带上 backend.log 最后几十行走支持渠道反馈。
模型连不上
先分清你用的是哪条通道——三条通道报错各走各的，不会互相兜底。
本地模型（Ollama）
- 确认 Ollama 在运行：浏览器访问
http://localhost:11434，能看到 "Ollama is running" 才算活着。 - 确认模型已拉取：命令行执行
ollama list，没有就先ollama pull <模型名>（如qwen2.5:0.5b）。 - Pro 会员可在「设置 → AI 设置」用模型管家自动检测、安装与拉取，不用碰命令行。
BYOK 自填 Key
- 报「请填 key」：去「设置 → AI 设置」对应厂商卡片填入 API Key 并保存。
- 报厂商侧错误（欠费、Key 失效等）：错误会原文透传，去对应厂商控制台核实余额与 Key 状态；改完 Key 后重试。
- BYOK 只认你自己填的 Key，不会回落到平台账户——别把「平台模型暂不可用」当成该去填 Key 的信号。
平台按量（☁️ 系统模型）
- 报「余额不足」：余额耗尽，按指引去云端充值页充值；免费模型每日 10 次耗尽后也是同类提示，次日重置。
- 报「平台模型暂不可用」：平台侧临时故障或该模型上游波动，换一款模型或稍后再试（免费上游模型漂移较快，属正常现象）。
- 不确定模型死活：先在对话里发一句「你好」测试，再怀疑配置。
知识图谱构建失败
- 大库构建本身耗时较长，期间界面会显示进度；构建失败会出现失败横幅，里面带原因。
- 构建状态是落库的：重启应用会自动从中断点续建，不会从头再来。
- 反复失败的常见原因是构建模型不可用：先把当前选型换成一个对话里验证过能用的模型，再重新触发构建。
- 自动续建连续两次被打断后会标记为失败，需要手动重新触发（防止崩溃循环）。
更新问题
- 安装版：启动约 10 秒后自动检查更新，之后每 6 小时检查一次；下载过程有实时百分比提示，下完按提示重启即可。
- 便携版不支持自动更新：会提示去官网下载新版，下载后整体替换程序文件即可（数据在同级
data\目录，不受影响）。 - 更新异常排查：看更新日志
%APPDATA%\psb-desktop\logs\updater.log，里面有每次检查、下载、报错的记录。 - 更新/重装不会动数据目录——数据从不放在安装目录里。
日志在哪里
Windows 安装版统一在 %APPDATA%\psb-desktop\logs\ 下：
| 文件 | 内容 |
|---|---|
updater.log | 自动更新：检查、下载进度、失败原因 |
backend.log | 内嵌后端：启动、报错堆栈 |
反馈问题时附上对应日志的最后几十行，处理会快很多。
网页版 / 自托管
- 云端网页版异常：先刷新并重新登录；全站不可达一般是服务侧问题，稍后再试。
- 自托管：确认容器存活（
docker compose ps）、看后端日志（docker compose logs backend）；健康检查接口/health；更多见自托管部署。
注意事项
- 别从终端命令行启动桌面包来调日志，直接用桌面图标或开始菜单启动，日志写在上面表格里的文件。
- 反馈问题时附上：版本号（「设置 → 桌面端」可见）、操作系统、报错原文、日志片段。
- 以下行为是有意设计而非故障：余额不足拦截、免费额度每日重置、手动选型后不做跨模型回退（报当前模型的错）。
FAQ
重启后图谱构建会从头再来吗？ 不会，构建状态落库，重启自动从断点续建。
更新会把我的数据冲掉吗？ 不会。数据目录独立于安装目录，自动更新只替换程序文件。
「平台模型暂不可用」是要我填 Key 吗？ 不是。这是平台通道的提示，表示平台侧临时不可用，稍后重试或换模型即可。