zclaw_openfang/wiki/data-model.md

title, updated, status, tags

title	updated	status	tags
数据模型	2026-04-21	active	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