---
title: 数据模型
updated: 2026-04-21
status: active
tags: [module, database, schema]
---

# 数据模型

> 从 [[index]] 导航。关联模块: [[saas]] [[memory]]

## 设计思想

**双存储架构: PostgreSQL (SaaS 多租户) + SQLite (本地单用户)**

- PostgreSQL: SaaS 后端，42 表，42 CREATE TABLE，支持多用户/多 Agent/计费/知识库
- SQLite: 本地桌面端，记忆存储 + 会话持久化 + FTS5 全文索引
- 两者通过 SaaS relay + 配置同步实现数据桥接

## 功能清单

| 功能 | 描述 | 存储层 | 状态 |
|------|------|--------|------|
| 用户管理 | 账户 CRUD + 角色权限 | PostgreSQL | ✅ |
| 认证数据 | JWT + 密码 + TOTP | PostgreSQL | ✅ |
| 计费系统 | 订阅/支付/发票/配额 | PostgreSQL | ✅ |
| 知识库 | 分类/条目/向量/结构化 | PostgreSQL | ✅ |
| 模型管理 | Provider/模型/Key 池 | PostgreSQL | ✅ |
| Agent 配置 | 模板/分配/行业 | PostgreSQL | ✅ |
| 本地会话 | 会话/消息持久化 | SQLite | ✅ |
| 本地记忆 | 记忆 CRUD + FTS5 搜索 | SQLite | ✅ |
| 用户画像 | 结构化偏好/兴趣 | SQLite | ✅ |
| 轨迹记录 | 工具调用链 + 压缩摘要 | SQLite | ✅ |

## 代码逻辑

### PostgreSQL (SaaS) — 42 表

**迁移文件**: `crates/zclaw-saas/migrations/` (21 up + 17 down)

#### 认证与账户域 (5 表)

| 表 | 说明 | 关键关系 |
|----|------|---------|
| `accounts` | 用户账户 (邮箱/密码/pwv/角色) | → api_tokens, operation_logs, subscriptions |
| `api_tokens` | API 访问令牌 | FK → accounts |
| `roles` | 角色定义 | — |
| `permission_templates` | 权限模板 | — |
| `refresh_tokens` | JWT 刷新令牌 (单次使用) | FK → accounts |

#### Provider 与模型域 (6 表)

| 表 | 说明 | 关键关系 |
|----|------|---------|
| `providers` | LLM Provider 配置 | → models, provider_keys |
| `models` | 模型定义 (白名单) | FK → providers |
| `provider_keys` | 加密 API Key 池 | FK → providers, accounts |
| `key_usage_window` | Key RPM/TPM 滑动窗口 | — |
| `model_groups` | 模型组 (故障转移) | → model_group_members |
| `model_group_members` | 组成员 | FK → model_groups, providers |

#### 计费域 (5 表)

| 表 | 说明 | 关键关系 |
|----|------|---------|
| `billing_plans` | 计费计划目录 | → subscriptions |
| `billing_subscriptions` | 用户订阅 | FK → accounts, billing_plans |
| `billing_invoices` | 发票 | FK → accounts, subscriptions, plans |
| `billing_payments` | 支付记录 | FK → billing_invoices, accounts |
| `billing_usage_quotas` | 用量配额 | FK → accounts, billing_plans |

#### 知识库域 (7 表)

| 表 | 说明 | 关键关系 |
|----|------|---------|
| `knowledge_categories` | 分类 (自引用 parent_id) | → knowledge_items |
| `knowledge_items` | 知识条目 | FK → categories, accounts |
| `knowledge_chunks` | 向量分块 (pgvector) | FK → knowledge_items |
| `knowledge_versions` | 版本历史 | FK → items, chunks, accounts |
| `knowledge_usage` | 使用统计 | FK → knowledge_items |
| `structured_sources` | 结构化数据源 | FK → accounts |
| `structured_rows` | 结构化行数据 | FK → structured_sources |

#### 其他域 (19 表)

| 域 | 表 | 说明 |
|----|----|------|
| API & Relay | `account_api_keys`, `usage_records`, `relay_tasks` | API Key/用量/异步任务 |
| 配置 | `config_items`, `config_sync_log` | KV 配置/同步日志 |
| Prompt | `prompt_templates`, `prompt_versions`, `prompt_sync_status` | 模板/版本/同步 |
| Agent | `agent_templates` | Agent 模板配置 |
| 设备 | `devices` | 设备管理 |
| 遥测 | `operation_logs`, `telemetry_reports`, `saas_schema_version` | 操作日志/统计/版本 |
| 调度 | `scheduled_tasks` | 定时任务 |
| 限流 | `rate_limit_events` | 限流事件日志 |
| Webhook | `webhook_subscriptions`, `webhook_deliveries` | Webhook 订阅/投递 |
| 行业 | `industries`, `account_industries` | 行业配置/账户关联 |

### SQLite 本地存储

**zclaw-memory** (`crates/zclaw-memory/src/schema.rs`):

| 表 | 说明 | 版本 |
|----|------|------|
| `agents` | Agent 定义 | v1 |
| `sessions` | 聊天会话 | v1, FK → agents |
| `messages` | 会话消息 | v1, FK → sessions |
| `kv_store` | Agent KV 存储 | v1, FK → agents |
| `facts` | 提取的事实 | v2, FK → agents |
| `user_profiles` | 用户画像 | v2 |
| `trajectory_events` | 工具调用链事件 | v3 |
| `compressed_trajectories` | 压缩轨迹摘要 | v3 |
| `hand_runs` | Hand 执行追踪 | v1 |
| `schema_version` | 迁移版本 | v1 |

**zclaw-growth** (`crates/zclaw-growth/src/storage/sqlite.rs`):

| 表 | 说明 |
|----|------|
| `memories` | 记忆条目 (uri, memory_type, content, keywords, importance, access_count) |
| `metadata` | KV 元数据 |

**FTS5 虚拟表**:

| 虚拟表 | 定义 | 分词器 |
|--------|------|--------|
| `memories_fts` | `fts5(uri, content, keywords)` | `trigram` (CJK 支持) |

> FTS5 使用 `trigram` 分词器（从 `unicode61` 迁移）支持中文/日文/韩文。CJK 查询零结果时 fallback 到 LIKE 搜索。

## 数据流

```
桌面端聊天
  → SQLite: sessions + messages (本地持久化)
  → SaaS Relay: relay_tasks (异步任务追踪)
  → PostgreSQL: usage_records (用量记录)

记忆管道
  → SQLite: memories + memories_fts (FTS5 全文索引)
  → SQLite: facts + user_profiles (结构化提取)
  → PostgreSQL: knowledge_chunks (pgvector 向量, embedding deferred)

计费闭环
  → PostgreSQL: billing_usage_quotas (实时递增)
  → PostgreSQL: billing_subscriptions → invoices → payments
  → Worker: aggregate_usage (聚合器调度)
```

## 测试链路

| 功能 | 测试文件 | 覆盖状态 |
|------|---------|---------|
| 全模块 | `crates/zclaw-saas/tests/` (17 文件) | ✅ |
| SQL 迁移 | `crates/zclaw-saas/migrations/` (21 up) | ✅ 启动时自动执行 |
| 本地存储 | `crates/zclaw-memory/src/store.rs` (20 tests) | ✅ |
| 用户画像 | `crates/zclaw-memory/src/user_profile_store.rs` (20 tests) | ✅ |
| 轨迹存储 | `crates/zclaw-memory/src/trajectory_store.rs` (9 tests) | ✅ |
| 记忆存储 | `crates/zclaw-growth/src/storage/sqlite.rs` (6 tests) | ✅ |

## 关联模块

- [[saas]] — PostgreSQL 由 SaaS 后端管理
- [[memory]] — SQLite 本地记忆存储 + FTS5
- [[routing]] — relay_tasks 异步任务追踪

## 关键文件

| 文件 | 职责 |
|------|------|
| `crates/zclaw-saas/migrations/` | 21 up SQL 迁移 (42 CREATE TABLE) |
| `crates/zclaw-saas/src/models/` | 数据模型 struct 定义 |
| `crates/zclaw-memory/src/schema.rs` | SQLite schema 定义 |
| `crates/zclaw-growth/src/storage/sqlite.rs` | FTS5 + TF-IDF 存储 |
| `docker-compose.yml` | PostgreSQL 容器配置 |

## 已知问题

- ⚠️ **pgvector embedding 生成未实现** — 索引就绪，`generate_embedding.rs` Worker 逻辑 deferred
- ⚠️ **FTS5 CJK 零结果** — trigram 分词器已启用，极短查询可能仍 fallback 到 LIKE