故障排查常见问题

Synapse 常见问题的解决方案。

无法登录

症状

• POST /login 返回 401
• "Invalid email or password"

解决方案

1. 确认邮箱正确 — 区分大小写
2. 检查密码 — 至少 6 个字符
3. 若无账户请先注册：POST /register
4. （如已配置 SMTP）通过 Web UI 重置密码

丢失了 Mind Key

症状

• 无法访问记忆
• Mind Key 已删除或丢失

解决方案

Mind Key 无法找回。你必须：

1. 登录获取 JWT：POST /login
2. 列出 Mind：GET /minds（用 JWT）
3. 创建新 Mind：POST /minds
4. 保存新的 Mind Key
5. （可选）删除旧 Mind：DELETE /minds/:id

旧 Mind 中的数据将丢失，除非你能找到 Mind Key。

API 调用返回 401

症状

• 所有 API 调用返回 401 Unauthorized
• "Mind Key fehlt oder ungültig"

解决方案

1. 确认请求头格式：Authorization: Bearer mk_...
2. 检查 Mind Key 是否以 mk_ 开头（不是 eyJ，那是 JWT）
3. 直接测试：

   curl -H "Authorization: Bearer mk_YOUR_KEY" \
        https://synapse.schaefer.zone/memory/recall

4. Mind Key 可能已被吊销 — 创建新 Mind

参见 Authentication。

API 调用返回 404

症状

• 404 Not Found
• "Route not found"

解决方案

1. 检查有效端点：curl https://synapse.schaefer.zone/endpoints
2. 逐字符对比 URL — 区分大小写，无尾斜杠
3. 检查 HTTP 方法 — GET /memory 与 POST /memory 是不同的

API 调用返回 429

症状

• 429 Too Many Requests
• "Rate limit exceeded"

解决方案

1. 改用头部认证（无限制）：

   # 不要这样做
   curl ".../memory/recall?key=mk_..."
   
   # 推荐做法
   curl -H "Authorization: Bearer mk_..." .../memory/recall

2. 如果必须用 ?key=，请等待 Retry-After 秒

参见 限速。

记忆搜索返回零结果

症状

• GET /memory/search?q=... 返回空
• 确知有记忆存在

解决方案

1. 确认记忆存在：GET /memory/recall
2. 检查搜索语法 — FTS5 有特定语法
3. 尝试更简单的查询 — 用 ?q=docker 而非 ?q=docker+swarm+deployment
4. 概念查询用语义搜索：GET /memory/semantic-search?q=...

参见 FTS5 搜索。

记忆未持久化

症状

• POST /memory 返回成功
• GET /memory/recall 看不到它们

解决方案

1. 确认使用相同的 Mind Key — 不同 key = 不同 Mind
2. 检查响应 — POST 应返回 { "id": "mem_...", "status": "stored" }
3. 改用 GET /memory（JSON 列表）代替 /memory/recall（文本）
4. 检查过滤条件 — ?category= 或 ?tag= 可能将它们隐藏

Claude Desktop 中看不到工具

症状

• Claude Desktop 显示 0 个工具
• 没有 🔌 图标

解决方案

1. 完全重启 Claude Desktop（Cmd+Q）
2. 确认配置文件为有效 JSON
3. 检查已安装 Node.js 18+
4. 手动运行 MCP：npx -y synapse-mcp-api@latest
5. 查看日志：~/Library/Logs/Claude/mcp.log

参见 MCP 故障排查。

Synapse 离线

症状

• 无法访问 synapse.schaefer.zone
• curl 超时

解决方案

1. 检查你的网络 — 试试其他网站
2. 检查 Synapse 健康：curl https://synapse.schaefer.zone/health
3. 等待 — 可能是临时故障或部署中
4. 查看状态页（如有）

自托管请检查 Docker 容器状态与数据库连接。

数据库错误

症状

• 500 Internal Server Error
• "Database connection failed"

解决方案

自托管：

1. 检查 PostgreSQL 是否运行：docker ps | grep postgres
2. 检查环境变量 DATABASE_URL
3. 检查迁移：npm run migrate:check
4. 检查磁盘空间：df -h

托管版本：联系支持。

Webhook 未触发

症状

• 已注册 Webhook 但未收到回调
• URL 没有 POST 请求到达

解决方案

1. 确认 URL 可达：curl -X POST your-url -d '{}'
2. 检查事件过滤 — memory.* 匹配所有记忆事件
3. 测试 Webhook：POST /webhooks/:id/test
4. 检查 Webhook 是否启用：GET /webhooks/:id
5. 验证 SSL — Synapse 要求 Webhook URL 使用有效 HTTPS

参见 Webhooks API。

Cron 任务未运行

症状

• 已创建 Cron 任务但不触发
• next_run 不更新

解决方案

1. 检查调度语法 — 必须是有效的 5 字段 cron 或整数秒
2. 确认端点被允许 — 必须是 http(s)，无私有 IP
3. 检查任务是否启用：GET /cron
4. 等待下一个计划时间 — cron 不是即时的

参见 Cron 与调度器。

需要更多帮助？

1. 查看现有文档：https://synapse.schaefer.zone/docs
2. 搜索文档：GET /docs/search?q=your+question
3. 提交 issue：https://gitlab.com/schaefer-services/synapse/-/issues
4. 联系：参见 /support 页面

下一步

• 错误与错误处理
• API 常见问题
• MCP 故障排查