{"title":"故障排查常见问题","slug":"troubleshooting","category":"faq","summary":"Synapse 常见问题的解决方案 — 认证、网络、数据、部署。","audience":["human","llm"],"tags":["faq","troubleshooting","problems","solutions"],"difficulty":"beginner","updated":"2026-06-27","word_count":406,"read_minutes":2,"lang":"zh","translated":true,"requested_lang":"zh","content_markdown":"\n# 故障排查常见问题\n\nSynapse 常见问题的解决方案。\n\n## 无法登录\n\n### 症状\n\n- `POST /login` 返回 401\n- \"Invalid email or password\"\n\n### 解决方案\n\n1. **确认邮箱正确** — 区分大小写\n2. **检查密码** — 至少 6 个字符\n3. 若无账户请先注册：`POST /register`\n4. （如已配置 SMTP）通过 Web UI 重置密码\n\n## 丢失了 Mind Key\n\n### 症状\n\n- 无法访问记忆\n- Mind Key 已删除或丢失\n\n### 解决方案\n\nMind Key 无法找回。你必须：\n\n1. 登录获取 JWT：`POST /login`\n2. 列出 Mind：`GET /minds`（用 JWT）\n3. 创建新 Mind：`POST /minds`\n4. 保存新的 Mind Key\n5. （可选）删除旧 Mind：`DELETE /minds/:id`\n\n**旧 Mind 中的数据将丢失**，除非你能找到 Mind Key。\n\n## API 调用返回 401\n\n### 症状\n\n- 所有 API 调用返回 401 Unauthorized\n- \"Mind Key fehlt oder ungültig\"\n\n### 解决方案\n\n1. **确认请求头格式**：`Authorization: Bearer mk_...`\n2. **检查 Mind Key 是否以 `mk_` 开头**（不是 `eyJ`，那是 JWT）\n3. **直接测试**：\n ```bash\n curl -H \"Authorization: Bearer mk_YOUR_KEY\" \\\n https://synapse.schaefer.zone/memory/recall\n ```\n4. **Mind Key 可能已被吊销** — 创建新 Mind\n\n参见 [Authentication](/docs/getting-started/authentication)。\n\n## API 调用返回 404\n\n### 症状\n\n- 404 Not Found\n- \"Route not found\"\n\n### 解决方案\n\n> [!CRITICAL]\n> 不要猜测端点路径。只有 `GET /endpoints` 中列出的路径才存在。\n\n1. **检查有效端点**：`curl https://synapse.schaefer.zone/endpoints`\n2. **逐字符对比 URL** — 区分大小写，无尾斜杠\n3. **检查 HTTP 方法** — `GET /memory` 与 `POST /memory` 是不同的\n\n## API 调用返回 429\n\n### 症状\n\n- 429 Too Many Requests\n- \"Rate limit exceeded\"\n\n### 解决方案\n\n1. **改用头部认证**（无限制）：\n ```bash\n # 不要这样做\n curl \".../memory/recall?key=mk_...\"\n \n # 推荐做法\n curl -H \"Authorization: Bearer mk_...\" .../memory/recall\n ```\n2. 如果必须用 `?key=`，请等待 `Retry-After` 秒\n\n参见 [限速](/docs/api/rate-limits)。\n\n## 记忆搜索返回零结果\n\n### 症状\n\n- `GET /memory/search?q=...` 返回空\n- 确知有记忆存在\n\n### 解决方案\n\n1. **确认记忆存在**：`GET /memory/recall`\n2. **检查搜索语法** — FTS5 有特定语法\n3. **尝试更简单的查询** — 用 `?q=docker` 而非 `?q=docker+swarm+deployment`\n4. **概念查询用语义搜索**：`GET /memory/semantic-search?q=...`\n\n参见 [FTS5 搜索](/docs/concepts/fts5-search)。\n\n## 记忆未持久化\n\n### 症状\n\n- POST /memory 返回成功\n- GET /memory/recall 看不到它们\n\n### 解决方案\n\n1. **确认使用相同的 Mind Key** — 不同 key = 不同 Mind\n2. **检查响应** — POST 应返回 `{ \"id\": \"mem_...\", \"status\": \"stored\" }`\n3. **改用 GET /memory**（JSON 列表）代替 /memory/recall（文本）\n4. **检查过滤条件** — `?category=` 或 `?tag=` 可能将它们隐藏\n\n## Claude Desktop 中看不到工具\n\n### 症状\n\n- Claude Desktop 显示 0 个工具\n- 没有 🔌 图标\n\n### 解决方案\n\n1. **完全重启 Claude Desktop**（Cmd+Q）\n2. **确认配置文件为有效 JSON**\n3. **检查已安装 Node.js 18+**\n4. **手动运行 MCP**：`npx -y synapse-mcp-api@latest`\n5. **查看日志**：`~/Library/Logs/Claude/mcp.log`\n\n参见 [MCP 故障排查](/docs/mcp/troubleshooting)。\n\n## Synapse 离线\n\n### 症状\n\n- 无法访问 synapse.schaefer.zone\n- curl 超时\n\n### 解决方案\n\n1. **检查你的网络** — 试试其他网站\n2. **检查 Synapse 健康**：`curl https://synapse.schaefer.zone/health`\n3. **等待** — 可能是临时故障或部署中\n4. **查看状态页**（如有）\n\n自托管请检查 Docker 容器状态与数据库连接。\n\n## 数据库错误\n\n### 症状\n\n- 500 Internal Server Error\n- \"Database connection failed\"\n\n### 解决方案\n\n自托管：\n\n1. **检查 PostgreSQL 是否运行**：`docker ps | grep postgres`\n2. **检查环境变量 DATABASE_URL**\n3. **检查迁移**：`npm run migrate:check`\n4. **检查磁盘空间**：`df -h`\n\n托管版本：联系支持。\n\n## Webhook 未触发\n\n### 症状\n\n- 已注册 Webhook 但未收到回调\n- URL 没有 POST 请求到达\n\n### 解决方案\n\n1. **确认 URL 可达**：`curl -X POST your-url -d '{}'`\n2. **检查事件过滤** — `memory.*` 匹配所有记忆事件\n3. **测试 Webhook**：`POST /webhooks/:id/test`\n4. **检查 Webhook 是否启用**：`GET /webhooks/:id`\n5. **验证 SSL** — Synapse 要求 Webhook URL 使用有效 HTTPS\n\n参见 [Webhooks API](/docs/api/webhooks)。\n\n## Cron 任务未运行\n\n### 症状\n\n- 已创建 Cron 任务但不触发\n- `next_run` 不更新\n\n### 解决方案\n\n1. **检查调度语法** — 必须是有效的 5 字段 cron 或整数秒\n2. **确认端点被允许** — 必须是 http(s)，无私有 IP\n3. **检查任务是否启用**：`GET /cron`\n4. **等待下一个计划时间** — cron 不是即时的\n\n参见 [Cron 与调度器](/docs/api/cron)。\n\n## 需要更多帮助？\n\n1. **查看现有文档**：\n2. **搜索文档**：`GET /docs/search?q=your+question`\n3. **提交 issue**：\n4. **联系**：参见 `/support` 页面\n\n## 下一步\n\n- [错误与错误处理](/docs/api/errors)\n- [API 常见问题](/docs/faq/api-faq)\n- [MCP 故障排查](/docs/mcp/troubleshooting)\n","content_html":"

故障排查常见问题

\n

Synapse 常见问题的解决方案。

\n

无法登录

\n

症状

\n\n

解决方案

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

丢失了 Mind Key

\n

症状

\n\n

解决方案

\n

Mind Key 无法找回。你必须：

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

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

\n

API 调用返回 401

\n

症状

\n\n

解决方案

\n
    \n
  1. 确认请求头格式：Authorization: Bearer mk_...
    2. \n
  2. 检查 Mind Key 是否以 mk_ 开头（不是 eyJ，那是 JWT）
    3. \n
  3. 直接测试：
    curl -H "Authorization: Bearer mk_YOUR_KEY" \\\n     https://synapse.schaefer.zone/memory/recall
    4. \n
  4. Mind Key 可能已被吊销 — 创建新 Mind
    5. \n
\n

参见 Authentication。

\n

API 调用返回 404

\n

症状

\n\n

解决方案

\n
不要猜测端点路径。只有 `GET /endpoints` 中列出的路径才存在。
    \n
  1. 检查有效端点：curl https://synapse.schaefer.zone/endpoints
    2. \n
  2. 逐字符对比 URL — 区分大小写，无尾斜杠
    3. \n
  3. 检查 HTTP 方法 — GET /memory 与 POST /memory 是不同的
    4. \n
\n

API 调用返回 429

\n

症状

\n\n

解决方案

\n
    \n
  1. 改用头部认证（无限制）：
    # 不要这样做\ncurl ".../memory/recall?key=mk_..."\n\n# 推荐做法\ncurl -H "Authorization: Bearer mk_..." .../memory/recall
    2. \n
  2. 如果必须用 ?key=，请等待 Retry-After 秒
    3. \n
\n

参见 限速。

\n

记忆搜索返回零结果

\n

症状

\n\n

解决方案

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

参见 FTS5 搜索。

\n

记忆未持久化

\n

症状

\n\n

解决方案

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

Claude Desktop 中看不到工具

\n

症状

\n\n

解决方案

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

参见 MCP 故障排查。

\n

Synapse 离线

\n

症状

\n\n

解决方案

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

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

\n

数据库错误

\n

症状

\n\n

解决方案

\n

自托管：

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

托管版本：联系支持。

\n

Webhook 未触发

\n

症状

\n\n

解决方案

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

参见 Webhooks API。

\n

Cron 任务未运行

\n

症状

\n\n

解决方案

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

参见 Cron 与调度器。

\n

需要更多帮助？

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

下一步

\n\n","urls":{"html":"/docs/faq/troubleshooting","text":"/docs/faq/troubleshooting?format=text","json":"/docs/faq/troubleshooting?format=json","llm":"/docs/faq/troubleshooting?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}