# 故障排查常见问题

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. **直接测试**：
   ```bash
   curl -H "Authorization: Bearer mk_YOUR_KEY" \
        https://synapse.schaefer.zone/memory/recall
   ```
4. **Mind Key 可能已被吊销** — 创建新 Mind

参见 [Authentication](/docs/getting-started/authentication)。

## API 调用返回 404

### 症状

- 404 Not Found
- "Route not found"

### 解决方案

> [!CRITICAL]
> 不要猜测端点路径。只有 `GET /endpoints` 中列出的路径才存在。

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. **改用头部认证**（无限制）：
   ```bash
   # 不要这样做
   curl ".../memory/recall?key=mk_..."
   
   # 推荐做法
   curl -H "Authorization: Bearer mk_..." .../memory/recall
   ```
2. 如果必须用 `?key=`，请等待 `Retry-After` 秒

参见 [限速](/docs/api/rate-limits)。

## 记忆搜索返回零结果

### 症状

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

### 解决方案

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

参见 [FTS5 搜索](/docs/concepts/fts5-search)。

## 记忆未持久化

### 症状

- 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 故障排查](/docs/mcp/troubleshooting)。

## 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](/docs/api/webhooks)。

## Cron 任务未运行

### 症状

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

### 解决方案

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

参见 [Cron 与调度器](/docs/api/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` 页面

## 下一步

- [错误与错误处理](/docs/api/errors)
- [API 常见问题](/docs/faq/api-faq)
- [MCP 故障排查](/docs/mcp/troubleshooting)