# 故障排查常见问题
SUMMARY: Synapse 常见问题的解决方案 — 认证、网络、数据、部署。

故障排查常见问题
Synapse 常见问题的解决方案。
无法登录
症状
-  返回 401
- "Invalid email or password"
解决方案
1. 确认邮箱正确 — 区分大小写
2. 检查密码 — 至少 6 个字符
3. 若无账户请先注册：
4. （如已配置 SMTP）通过 Web UI 重置密码
丢失了 Mind Key
症状
- 无法访问记忆
- Mind Key 已删除或丢失
解决方案
Mind Key 无法找回。你必须：
1. 登录获取 JWT：
2. 列出 Mind：（用 JWT）
3. 创建新 Mind：
4. 保存新的 Mind Key
5. （可选）删除旧 Mind：
旧 Mind 中的数据将丢失，除非你能找到 Mind Key。
API 调用返回 401
症状
- 所有 API 调用返回 401 Unauthorized
- "Mind Key fehlt oder ungültig"
解决方案
1. 确认请求头格式：
2. 检查 Mind Key 是否以  开头（不是 ，那是 JWT）
3. 直接测试：
   [CODE BLOCK]
4. Mind Key 可能已被吊销 — 创建新 Mind
参见 Authentication。
API 调用返回 404
症状
- 404 Not Found
- "Route not found"
解决方案
> [!CRITICAL]
> 不要猜测端点路径。只有  中列出的路径才存在。
1. 检查有效端点：
2. 逐字符对比 URL — 区分大小写，无尾斜杠
3. 检查 HTTP 方法 —  与  是不同的
API 调用返回 429
症状
- 429 Too Many Requests
- "Rate limit exceeded"
解决方案
1. 改用头部认证（无限制）：
   [CODE BLOCK]
2. 如果必须用 ，请等待  秒
参见 限速。
记忆搜索返回零结果
症状
-  返回空
- 确知有记忆存在
解决方案
1. 确认记忆存在：
2. 检查搜索语法 — FTS5 有特定语法
3. 尝试更简单的查询 — 用  而非 
4. 概念查询用语义搜索：
参见 FTS5 搜索。
记忆未持久化
症状
- POST /memory 返回成功
- GET /memory/recall 看不到它们
解决方案
1. 确认使用相同的 Mind Key — 不同 key = 不同 Mind
2. 检查响应 — POST 应返回 
3. 改用 GET /memory（JSON 列表）代替 /memory/recall（文本）
4. 检查过滤条件 —  或  可能将它们隐藏
Claude Desktop 中看不到工具
症状
- Claude Desktop 显示 0 个工具
- 没有 🔌 图标
解决方案
1. 完全重启 Claude Desktop（Cmd+Q）
2. 确认配置文件为有效 JSON
3. 检查已安装 Node.js 18+
4. 手动运行 MCP：
5. 查看日志：
参见 MCP 故障排查。
Synapse 离线
症状
- 无法访问 synapse.schaefer.zone
- curl 超时
解决方案
1. 检查你的网络 — 试试其他网站
2. 检查 Synapse 健康：
3. 等待 — 可能是临时故障或部署中
4. 查看状态页（如有）
自托管请检查 Docker 容器状态与数据库连接。
数据库错误
症状
- 500 Internal Server Error
- "Database connection failed"
解决方案
自托管：
1. 检查 PostgreSQL 是否运行：
2. 检查环境变量 DATABASEURL
3. 检查迁移：
4. 检查磁盘空间：
托管版本：联系支持。
Webhook 未触发
症状
- 已注册 Webhook 但未收到回调
- URL 没有 POST 请求到达
解决方案
1. 确认 URL 可达：
2. 检查事件过滤 —  匹配所有记忆事件
3. 测试 Webhook：
4. 检查 Webhook 是否启用：
5. 验证 SSL — Synapse 要求 Webhook URL 使用有效 HTTPS
参见 Webhooks API。
Cron 任务未运行
症状
- 已创建 Cron 任务但不触发
-  不更新
解决方案
1. 检查调度语法 — 必须是有效的 5 字段 cron 或整数秒
2. 确认端点被允许 — 必须是 http(s)，无私有 IP
3. 检查任务是否启用：
4. 等待下一个计划时间 — cron 不是即时的
参见 Cron 与调度器。
需要更多帮助？
1. 查看现有文档：<https://synapse.schaefer.zone/docs>
2. 搜索文档：
3. 提交 issue：<https://gitlab.com/schaefer-services/synapse/-/issues>
4. 联系：参见  页面
下一步
- 错误与错误处理
- API 常见问题
- MCP 故障排查