{"title":"Synapse 架构","slug":"architecture","category":"concepts","summary":"Synapse 的构建方式 — Fastify、PostgreSQL、FTS5、向量嵌入、MCP Server。","audience":["human","llm"],"tags":["architecture","design","components"],"difficulty":"intermediate","updated":"2026-06-27","word_count":268,"read_minutes":1,"lang":"zh","translated":true,"requested_lang":"zh","content_markdown":"\n# Synapse 架构\n\nSynapse 是一个多租户记忆 API，基于 Fastify、带 FTS5 的 PostgreSQL，以及可选的用于语义搜索的向量嵌入服务构建。\n\n## 高层架构\n\n```\n┌──────────────────────────────────────────────────────────┐\n│ 客户端 │\n├──────────────┬──────────────┬──────────────┬─────────────┤\n│ LLM Agent │ Web 浏览器 │ MCP 客户端 │ Webhooks │\n│ (curl/SDK) │ (人类) │ (Claude 等) │ (外部) │\n└──────┬───────┴──────┬───────┴──────┬───────┴──────┬──────┘\n │ │ │ │\n └──────────────┴──────────────┴──────────────┘\n │\n ▼\n ┌───────────────────────────────┐\n │ Synapse API (Fastify) │\n │ port 12800 │\n │ - REST 端点 │\n │ - 认证 (Mind Key / JWT) │\n │ - 限速 │\n │ - 静态文件服务 │\n └───────────────┬───────────────┘\n │\n ┌───────────────┼───────────────┐\n ▼ ▼ ▼\n ┌─────────────┐ ┌─────────────┐ ┌─────────────┐\n │ PostgreSQL │ │ Embeddings │ │ MCP Server │\n │ + FTS5 │ │ Service │ │ (独立服务) │\n │ │ │ (可选) │ │ port 13100 │\n │ - memories │ │ │ │ │\n │ - tasks │ │ - 生成 │ │ - 79 个工具 │\n │ - chat │ │ 向量嵌入 │ │ - stdio/SSE │\n │ - scripts │ │ │ │ - WebSocket │\n └─────────────┘ └─────────────┘ └─────────────┘\n```\n\n## 核心组件\n\n### 1. Synapse API（Fastify）\n\n主 HTTP 服务器。负责处理：\n\n- REST 端点（`/memory`、`/chat`、`/mind/tasks` 等）\n- 认证（Agent 用 Mind Key，人类用 JWT）\n- 限速（仅 `?key=` 认证）\n- 静态文件服务（`/human`、`/docs` 等 Web UI）\n- Webhook 派发\n\n基于 **Fastify 5** 构建，注重性能。生产环境运行在端口 12800。\n\n### 2. 带 FTS5 的 PostgreSQL\n\n主数据存储。使用 PostgreSQL 及 FTS5 扩展进行全文搜索。\n\n**关键表：**\n\n| 表 | 用途 |\n|-------|---------|\n| `users` | 用户账户 |\n| `minds` | Mind 范围（每个 Mind 有一个 Mind Key） |\n| `memories` | 记忆记录，附带 FTS5 虚拟表 |\n| `tasks` | 任务管理 |\n| `chat_messages` | 聊天记录 |\n| `scripts` | 持久化脚本 |\n| `webhooks` | Webhook 注册 |\n| `cron_jobs` | 定时任务 |\n| `variables` | 键值存储 |\n| `audit_log` | 审计日志 |\n\n**FTS5** 可在所有记忆内容上实现亚毫秒级全文搜索。详见 [FTS5 搜索](/docs/concepts/fts5-search)。\n\n### 3. Embeddings 服务（可选）\n\n为支持语义搜索，Synapse 会为记忆内容生成向量嵌入。这些向量与记忆一起存储，用于相似度搜索。\n\n- 提供方：可配置（OpenAI、本地模型等）\n- 作为 `vector` 列存储在 `memories` 表中\n- 由 `/memory/semantic-search` 端点使用\n- 详见 [语义搜索](/docs/concepts/semantic-search)\n\n### 4. MCP Server（独立服务）\n\nSynapse MCP Server 作为独立进程运行（端口 13100）。它：\n\n- 通过 Model Context Protocol 暴露 79 个工具\n- 支持 stdio、HTTP/SSE 和 WebSocket 传输\n- 将 MCP 工具调用转换为 Synapse API 调用\n- 多租户：每个会话使用一个 Mind Key\n\n### 5. Browser 代理（独立服务）\n\n为支持浏览器自动化，独立的基于 Playwright 的服务运行在端口 13000。MCP Server 可调用它以执行 `browser_*` 工具。\n\n### 6. SSH 代理（独立服务）\n\n为支持基于 SSH 的远程命令，独立服务运行在端口 12900。\n\n## 多租户模型\n\n```\n用户账户 (邮箱 + 密码)\n │\n ├── Mind 1 (Mind Key 1)\n │ ├── 记忆\n │ ├── 任务\n │ ├── 聊天\n │ └── 脚本\n │\n ├── Mind 2 (Mind Key 2)\n │ └── ... (与 Mind 1 隔离)\n │\n └── Mind 3 (Mind Key 3)\n └── ...\n```\n\n每个 Mind 完全隔离。Mind Key 仅授予访问某一个 Mind 的权限。JWT 授予访问用户账户的权限（用于管理 Mind）。\n\n详见 [多租户](/docs/concepts/multi-tenancy)。\n\n## 请求流\n\n### 记忆存储请求\n\n```\n1. 客户端发送 POST /memory，附带 Authorization: Bearer mk_xxx\n2. Fastify 接收请求\n3. 认证中间件校验 Mind Key，将 mind_id 附加到请求上\n4. Memory 路由处理器：\n a. 校验 JSON body（zod schema）\n b. 插入 memories 表\n c. 更新 FTS5 索引\n d. (异步) 若启用向量嵌入则生成嵌入\n e. 触发 memory.store 事件的 Webhook\n5. 返回 { id, status: \"stored\" }\n```\n\n### 记忆搜索请求\n\n```\n1. 客户端发送 GET /memory/search?q=docker\n2. 认证中间件校验 Mind Key\n3. Memory 路由处理器：\n a. 解析查询（FTS5 语法）\n b. 对 memories 表执行 FTS5 MATCH\n c. 按 mind_id 过滤（租户隔离）\n d. 按相关性排序\n e. 返回结果\n```\n\n## 部署\n\nSynapse 作为 Docker 容器部署。参见 `docker-compose.yml`：\n\n```yaml\nservices:\n synapse:\n image: registry.gitlab.com/schaefer-services/synapse:latest\n ports:\n - \"12800:12800\"\n environment:\n - DATABASE_URL=postgres://...\n - JWT_SECRET=...\n - SYNAPSE_HOST=0.0.0.0\n - SYNAPSE_PORT=12800\n depends_on:\n - postgres\n \n postgres:\n image: postgres:16\n volumes:\n - pgdata:/var/lib/postgresql/data\n environment:\n - POSTGRES_DB=synapse\n - POSTGRES_PASSWORD=...\n```\n\n## 性能特征\n\n| 操作 | 延迟 | 吞吐 |\n|-----------|---------|------------|\n| 记忆存储 | ~5ms | 1000+ req/s |\n| 记忆回放 | ~20ms | 500 req/s |\n| FTS5 搜索 | ~10ms | 800 req/s |\n| 语义搜索 | ~50ms | 200 req/s |\n| 聊天轮询 | ~5ms | 2000 req/s |\n\n## 下一步\n\n- [记忆模型](/docs/concepts/memory-model)\n- [多租户](/docs/concepts/multi-tenancy)\n- [FTS5 搜索](/docs/concepts/fts5-search)\n","content_html":"

Synapse 架构

\n

Synapse 是一个多租户记忆 API，基于 Fastify、带 FTS5 的 PostgreSQL，以及可选的用于语义搜索的向量嵌入服务构建。

\n

高层架构

\n
┌──────────────────────────────────────────────────────────┐\n│                       客户端                             │\n├──────────────┬──────────────┬──────────────┬─────────────┤\n│  LLM Agent   │  Web 浏览器  │  MCP 客户端  │  Webhooks   │\n│  (curl/SDK)  │  (人类)      │ (Claude 等)  │  (外部)     │\n└──────┬───────┴──────┬───────┴──────┬───────┴──────┬──────┘\n       │              │              │              │\n       └──────────────┴──────────────┴──────────────┘\n                              │\n                              ▼\n              ┌───────────────────────────────┐\n              │    Synapse API (Fastify)      │\n              │    port 12800                 │\n              │    - REST 端点                │\n              │    - 认证 (Mind Key / JWT)    │\n              │    - 限速                     │\n              │    - 静态文件服务             │\n              └───────────────┬───────────────┘\n                              │\n              ┌───────────────┼───────────────┐\n              ▼               ▼               ▼\n       ┌─────────────┐ ┌─────────────┐ ┌─────────────┐\n       │ PostgreSQL  │ │ Embeddings  │ │ MCP Server  │\n       │ + FTS5      │ │ Service     │ │ (独立服务)  │\n       │             │ │ (可选)      │ │ port 13100  │\n       │ - memories  │ │             │ │             │\n       │ - tasks     │ │ - 生成      │ │ - 79 个工具 │\n       │ - chat      │ │   向量嵌入  │ │ - stdio/SSE │\n       │ - scripts   │ │             │ │ - WebSocket │\n       └─────────────┘ └─────────────┘ └─────────────┘

核心组件

\n

1. Synapse API（Fastify）

\n

主 HTTP 服务器。负责处理：

\n\n

基于 Fastify 5 构建，注重性能。生产环境运行在端口 12800。

\n

2. 带 FTS5 的 PostgreSQL

\n

主数据存储。使用 PostgreSQL 及 FTS5 扩展进行全文搜索。

\n

关键表：

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
表用途
users用户账户
mindsMind 范围（每个 Mind 有一个 Mind Key）
memories记忆记录，附带 FTS5 虚拟表
tasks任务管理
chat_messages聊天记录
scripts持久化脚本
webhooksWebhook 注册
cron_jobs定时任务
variables键值存储
audit_log审计日志
\n

FTS5 可在所有记忆内容上实现亚毫秒级全文搜索。详见 FTS5 搜索。

\n

3. Embeddings 服务（可选）

\n

为支持语义搜索，Synapse 会为记忆内容生成向量嵌入。这些向量与记忆一起存储，用于相似度搜索。

\n\n

4. MCP Server（独立服务）

\n

Synapse MCP Server 作为独立进程运行（端口 13100）。它：

\n\n

5. Browser 代理（独立服务）

\n

为支持浏览器自动化，独立的基于 Playwright 的服务运行在端口 13000。MCP Server 可调用它以执行 browser_* 工具。

\n

6. SSH 代理（独立服务）

\n

为支持基于 SSH 的远程命令，独立服务运行在端口 12900。

\n

多租户模型

\n
用户账户 (邮箱 + 密码)\n  │\n  ├── Mind 1 (Mind Key 1)\n  │   ├── 记忆\n  │   ├── 任务\n  │   ├── 聊天\n  │   └── 脚本\n  │\n  ├── Mind 2 (Mind Key 2)\n  │   └── ... (与 Mind 1 隔离)\n  │\n  └── Mind 3 (Mind Key 3)\n      └── ...

每个 Mind 完全隔离。Mind Key 仅授予访问某一个 Mind 的权限。JWT 授予访问用户账户的权限（用于管理 Mind）。

\n

详见 多租户。

\n

请求流

\n

记忆存储请求

\n
1. 客户端发送 POST /memory，附带 Authorization: Bearer mk_xxx\n2. Fastify 接收请求\n3. 认证中间件校验 Mind Key，将 mind_id 附加到请求上\n4. Memory 路由处理器：\n   a. 校验 JSON body（zod schema）\n   b. 插入 memories 表\n   c. 更新 FTS5 索引\n   d. (异步) 若启用向量嵌入则生成嵌入\n   e. 触发 memory.store 事件的 Webhook\n5. 返回 { id, status: "stored" }

记忆搜索请求

\n
1. 客户端发送 GET /memory/search?q=docker\n2. 认证中间件校验 Mind Key\n3. Memory 路由处理器：\n   a. 解析查询（FTS5 语法）\n   b. 对 memories 表执行 FTS5 MATCH\n   c. 按 mind_id 过滤（租户隔离）\n   d. 按相关性排序\n   e. 返回结果

部署

\n

Synapse 作为 Docker 容器部署。参见 docker-compose.yml：

\n
services:\n  synapse:\n    image: registry.gitlab.com/schaefer-services/synapse:latest\n    ports:\n      - "12800:12800"\n    environment:\n      - DATABASE_URL=postgres://...\n      - JWT_SECRET=...\n      - SYNAPSE_HOST=0.0.0.0\n      - SYNAPSE_PORT=12800\n    depends_on:\n      - postgres\n  \n  postgres:\n    image: postgres:16\n    volumes:\n      - pgdata:/var/lib/postgresql/data\n    environment:\n      - POSTGRES_DB=synapse\n      - POSTGRES_PASSWORD=...

性能特征

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
操作延迟吞吐
记忆存储~5ms1000+ req/s
记忆回放~20ms500 req/s
FTS5 搜索~10ms800 req/s
语义搜索~50ms200 req/s
聊天轮询~5ms2000 req/s
\n

下一步

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