# 多租户与隔离

Synapse 是多租户的：多个用户，每个用户可有多个 Mind，彼此完全隔离。本页说明隔离模型。

## 租户层级

```
Synapse 实例
  │
  ├── 用户账户 1 (邮箱: alice@example.com)
  │   ├── Mind A (Mind Key mk_aaa...)
  │   │   ├── 记忆 (仅可通过 mk_aaa... 访问)
  │   │   ├── 任务
  │   │   └── 聊天
  │   └── Mind B (Mind Key mk_bbb...)
  │       └── ... (与 Mind A 隔离)
  │
  ├── 用户账户 2 (邮箱: bob@example.com)
  │   └── Mind C (Mind Key mk_ccc...)
  │       └── ... (与 Alice 的 Mind 隔离)
  │
  └── ... (更多用户)
```

## 隔离层级

### 第 1 级：用户隔离

每个用户账户相互隔离。Alice 不能：

- 查看 Bob 的 Mind
- 访问 Bob 的记忆（即使有她的 JWT）
- 列出 Bob 的账户信息

强制方式：所有表上都有 `user_id` 列，JWT 包含 `user_id`，所有查询按 `user_id` 过滤。

### 第 2 级：Mind 隔离

在同一用户下，每个 Mind 相互隔离。Mind A 不能：

- 查看 Mind B 的记忆
- 访问 Mind B 的任务、聊天、脚本

强制方式：所有数据表都有 `mind_id` 列，Mind Key 包含 `mind_id`，所有查询按 `mind_id` 过滤。

> [!CRITICAL]
> Mind Key 隔离是首要的安全边界。泄露的 Mind Key 会授予对该 Mind 数据的完全访问权限 — 但仅限该 Mind。

## 认证令牌

| 令牌 | 范围 | 可访问内容 |
|-------|-------|-------------------|
| Mind Key | 单个 Mind | 仅该 Mind 的数据 |
| JWT | 用户账户 | 账户管理（创建/列出/删除 Mind） |
| Computer Token | 单台计算机 | 该计算机的命令 |

## 跨 Mind 访问

### 同一用户内

用户可通过 JWT 访问自己所有的 Mind（例如 `GET /minds` 列出全部）。但要读写记忆数据，需要具体的 Mind Key。

### 跨用户

用户之间不能互访数据 — 除非通过 Sharing API 显式共享某个 Mind：

```bash
# Alice 将 Mind A 共享给 Bob
curl -X POST https://synapse.schaefer.zone/sharing \
  -H "Authorization: Bearer ALICE_JWT" \
  -d '{"mind_id": "m_aaa", "email": "bob@example.com", "role": "read"}'
```

共享后，Bob 可通过他的 JWT 访问 Mind A（若 `role=read` 则只读）。

## 安全边界

```
┌─────────────────────────────────────────────────┐
│              Synapse 实例                       │
│  ┌─────────────────────────────────────────┐    │
│  │         用户账户边界                     │    │
│  │  ┌──────────────┐  ┌──────────────┐    │    │
│  │  │  Mind 边界   │  │  Mind 边界   │    │    │
│  │  │  (Mind Key)  │  │  (Mind Key)  │    │    │
│  │  │              │  │              │    │    │
│  │  │  记忆        │  │  记忆        │    │    │
│  │  │  任务        │  │  任务        │    │    │
│  │  │  聊天        │  │  聊天        │    │    │
│  │  │  脚本        │  │  脚本        │    │    │
│  │  └──────────────┘  └──────────────┘    │    │
│  └─────────────────────────────────────────┘    │
└─────────────────────────────────────────────────┘
```

## 常见多租户模式

### 模式 1：单用户，单 Mind

个人 LLM Agent 用户最常见。

- 1 个用户账户
- 1 个 Mind
- 1 个 Mind Key
- 所有记忆在同一范围

### 模式 2：单用户，多 Mind

适合有多种上下文的用户（工作、个人、项目）。

- 1 个用户账户
- N 个 Mind（例如 "work"、"personal"、"project-x"）
- N 个 Mind Key
- 每个 LLM 会话使用一个 Mind Key

### 模式 3：团队共享 Mind

适合团队协作某个项目。

- 1 个用户创建 Mind（获得 Mind Key）
- 创建者通过 JWT 共享给团队成员
- 所有团队成员通过 JWT 访问（或共享的 Mind Key）

> [!WARNING]
> 共享 Mind Key 会授予完全读写权限。团队协作时，请优先使用 Sharing API（基于 JWT），而不是直接共享 Mind Key。

### 模式 4：SaaS 提供商

适合将 Synapse 作为记忆层嵌入的应用。

- 每个客户 = 1 个用户账户
- 每个客户项目 = 1 个 Mind
- 应用按客户/项目存储 Mind Key
- 客户之间完全隔离

## 隔离验证

### 测试：Mind Key 不能访问其他 Mind

```bash
# Mind A 的 key 不能读取 Mind B 的记忆
curl -H "Authorization: Bearer mk_aaa..." \
     "https://synapse.schaefer.zone/memory/search?q=test"
# 仅返回 Mind A 的记忆

curl -H "Authorization: Bearer mk_bbb..." \
     "https://synapse.schaefer.zone/memory/search?q=test"
# 仅返回 Mind B 的记忆（不同结果）
```

### 测试：JWT 不能直接读取记忆数据

```bash
# JWT 可以列出 Mind
curl -H "Authorization: Bearer YOUR_JWT" \
     https://synapse.schaefer.zone/minds
# 返回：Mind 列表

# JWT 不能读取记忆（需要 Mind Key）
curl -H "Authorization: Bearer YOUR_JWT" \
     https://synapse.schaefer.zone/memory/recall
# 返回：401 Unauthorized
```

## 最佳实践

> [!TIP]
> - **每个项目/上下文使用一个 Mind** — 隔离是你的朋友
> - **绝不共享 Mind Key** — 改用 Sharing API
> - **泄露时轮换 Mind Key**（删除 Mind、创建新 Mind）
> - **审计共享的 Mind** — 定期检查 `GET /sharing`
> - **人类 UI 用 JWT** — 不要把 Mind Key 暴露给最终用户

## 下一步

- [Authentication](/docs/getting-started/authentication)
- [Mind Key 与 JWT](/docs/getting-started/mind-key-vs-jwt)
- [架构](/docs/concepts/architecture)