Python 智能体开发平台数据库设计（多服务 / 可横向扩展版）

1. 设计目标

本设计面向一套基于 Python 的智能体开发平台，要求支持：

多应用、多租户、多环境
多智能体、团队协作、复杂工作流
会话、运行态、上下文、记忆、技能、工具、插件
多服务部署与水平扩展
高并发写入、长链路执行、可观测与审计

数据库设计的目标不是只满足 V0.1，而是保证从早期共库部署到后期多服务独立演进都能平滑过渡。

2. 总体原则

2.1 核心原则

配置数据和运行数据分离
热路径数据和冷路径数据分离
强事务数据优先放 PostgreSQL
短期状态与幂等控制优先放 Redis
语义记忆与知识检索使用 pgvector
文件和产物不落数据库，统一进入对象存储

2.2 分库分域原则

初期可以由一个 PostgreSQL 集群承载多个 schema，后期再按热点服务拆分成独立数据库。建议逻辑分域如下：

auth_db
app_db
session_db
runtime_db
memory_db
tool_db
retrieval_db
trace_db

2.3 横向扩展原则

所有运行态表必须支持按 tenant_id、app_id、run_id 定位
长链路表优先使用追加写，减少热点更新
高并发表尽量避免大事务和跨域 join
跨服务关联尽量靠业务 ID，不依赖数据库外键
表设计默认支持归档和分区

3. ID 与通用字段规范

3.1 主键策略

建议统一使用 UUID 或 ULID 作为主键。

3.2 通用字段

核心业务表建议统一带上以下字段：

id
tenant_id
org_id
created_by
updated_by
created_time
updated_time
deleted_time
version

说明：

tenant_id：多租户隔离关键字段
org_id：组织维度隔离，可选
deleted_time：软删除标记
version：乐观锁或对象版本控制

时间字段规范：

所有时间字段统一使用 _time 后缀
所有时间字段统一使用 datetime 类型
禁止混用 _at、date、timestamp 等命名风格

3.3 枚举字段建议

不要使用数据库原生 enum 绑定太死，建议使用 varchar + check 或应用层常量控制，方便演进。

4. 分域数据库设计

4.1 Auth / Tenant 域

职责：

用户、组织、租户、角色、权限

表：`tenant`

字段	类型	说明
id	uuid	主键
code	varchar(64)	租户编码，唯一
name	varchar(128)	租户名称
status	varchar(32)	`active` / `suspended`
plan_code	varchar(64)	套餐
settings_json	jsonb	租户级配置
created_time	datetime	创建时间
updated_time	datetime	更新时间

索引：

uk_tenant_code(code)
idx_tenant_status(status)

表：`organization`

字段	类型	说明
id	uuid	主键
tenant_id	uuid	租户 ID
parent_id	uuid	上级组织
name	varchar(128)	组织名
status	varchar(32)	状态
created_time	datetime	创建时间
updated_time	datetime	更新时间

索引：

idx_org_tenant(tenant_id)
idx_org_parent(parent_id)

表：`user_account`

字段	类型	说明
id	uuid	主键
tenant_id	uuid	租户 ID
org_id	uuid	组织 ID
username	varchar(64)	用户名
email	varchar(128)	邮箱
phone	varchar(32)	手机号
display_name	varchar(128)	显示名
status	varchar(32)	状态
profile_json	jsonb	扩展资料
created_time	datetime	创建时间
updated_time	datetime	更新时间

索引：

uk_user_tenant_username(tenant_id, username)
uk_user_tenant_email(tenant_id, email)
idx_user_org(org_id)

表：`role`

字段	类型	说明
id	uuid	主键
tenant_id	uuid	租户 ID
code	varchar(64)	角色编码
name	varchar(128)	角色名
role_type	varchar(32)	系统角色 / 自定义角色
created_time	datetime	创建时间
updated_time	datetime	更新时间

表：`permission`

字段	类型	说明
id	uuid	主键
code	varchar(128)	权限编码
name	varchar(128)	权限名称
resource_type	varchar(64)	资源类型
action	varchar(32)	动作

表：`user_role`

字段	类型	说明
id	uuid	主键
tenant_id	uuid	租户 ID
user_id	uuid	用户 ID
role_id	uuid	角色 ID
created_time	datetime	创建时间

唯一索引：

uk_user_role(tenant_id, user_id, role_id)

表：`role_permission`

字段	类型	说明
id	uuid	主键
role_id	uuid	角色 ID
permission_id	uuid	权限 ID
created_time	datetime	创建时间

唯一索引：

uk_role_permission(role_id, permission_id)

4.2 App / Workflow 配置域

职责：

应用定义
工作流定义
版本与环境配置
Agent、Team、Skill 绑定

表：`app_definition`

字段	类型	说明
id	uuid	主键
tenant_id	uuid	租户 ID
code	varchar(64)	应用编码
name	varchar(128)	应用名称
description	text	描述
app_type	varchar(32)	chat / workflow / hybrid
status	varchar(32)	draft / active / archived
owner_user_id	uuid	负责人
settings_json	jsonb	UI、默认模型等配置
created_time	datetime	创建时间
updated_time	datetime	更新时间

索引：

uk_app_tenant_code(tenant_id, code)
idx_app_owner(owner_user_id)
idx_app_status(tenant_id, status)

表：`app_environment`

字段	类型	说明
id	uuid	主键
tenant_id	uuid	租户 ID
app_id	uuid	应用 ID
env_name	varchar(32)	dev / test / prod
model_policy_json	jsonb	环境模型策略
secret_ref_json	jsonb	环境密钥引用
created_time	datetime	创建时间
updated_time	datetime	更新时间

唯一索引：

uk_app_env(app_id, env_name)

表：`app_version`

字段	类型	说明
id	uuid	主键
tenant_id	uuid	租户 ID
app_id	uuid	应用 ID
version_no	integer	版本号
status	varchar(32)	draft / published / rollback
workflow_version_id	uuid	当前工作流版本
published_time	datetime	发布时间
published_by	uuid	发布人
changelog	text	发布说明
created_time	datetime	创建时间

唯一索引：

uk_app_version(app_id, version_no)

表：`workflow_definition`

字段	类型	说明
id	uuid	主键
tenant_id	uuid	租户 ID
app_id	uuid	应用 ID
code	varchar(64)	流程编码
name	varchar(128)	流程名称
workflow_type	varchar(32)	main / subflow / template
latest_version_no	integer	最新版本号
created_time	datetime	创建时间
updated_time	datetime	更新时间

唯一索引：

uk_workflow_code(app_id, code)

表：`workflow_version`

字段	类型	说明
id	uuid	主键
tenant_id	uuid	租户 ID
workflow_id	uuid	流程定义 ID
version_no	integer	版本号
dsl_json	jsonb	内部 DSL
compiled_plan_json	jsonb	编译后的执行计划
schema_version	varchar(32)	DSL 版本
checksum	varchar(128)	内容摘要
status	varchar(32)	draft / validated / published
created_by	uuid	创建人
created_time	datetime	创建时间

索引：

uk_workflow_version(workflow_id, version_no)
idx_workflow_version_status(workflow_id, status)

表：`workflow_import_record`

字段	类型	说明
id	uuid	主键
tenant_id	uuid	租户 ID
app_id	uuid	应用 ID
source_type	varchar(32)	dify / custom_yaml / json
source_uri	varchar(512)	原始来源
raw_content_ref	varchar(512)	原始文件对象存储地址
converted_workflow_version_id	uuid	转换后的流程版本
import_status	varchar(32)	success / failed
error_message	text	错误原因
created_by	uuid	导入人
created_time	datetime	创建时间

表：`agent_definition`

字段	类型	说明
id	uuid	主键
tenant_id	uuid	租户 ID
app_id	uuid	应用 ID
code	varchar(64)	Agent 编码
name	varchar(128)	Agent 名称
role_type	varchar(32)	planner / worker / judge / custom
description	text	描述
created_time	datetime	创建时间
updated_time	datetime	更新时间

唯一索引：

uk_agent_code(app_id, code)

表：`agent_version`

字段	类型	说明
id	uuid	主键
tenant_id	uuid	租户 ID
agent_id	uuid	Agent 定义 ID
version_no	integer	版本号
system_prompt	text	系统提示词
model_policy_json	jsonb	模型策略
tool_policy_json	jsonb	工具策略
output_schema_json	jsonb	输出结构约束
created_by	uuid	创建人
created_time	datetime	创建时间

唯一索引：

uk_agent_version(agent_id, version_no)

表：`team_definition`

字段	类型	说明
id	uuid	主键
tenant_id	uuid	租户 ID
app_id	uuid	应用 ID
code	varchar(64)	Team 编码
name	varchar(128)	Team 名称
team_mode	varchar(32)	leader_worker / debate / pipeline
created_time	datetime	创建时间
updated_time	datetime	更新时间

表：`team_version`

字段	类型	说明
id	uuid	主键
tenant_id	uuid	租户 ID
team_id	uuid	Team 定义 ID
version_no	integer	版本号
config_json	jsonb	团队策略
created_by	uuid	创建人
created_time	datetime	创建时间

表：`team_member_binding`

字段	类型	说明
id	uuid	主键
tenant_id	uuid	租户 ID
team_version_id	uuid	Team 版本 ID
agent_version_id	uuid	Agent 版本 ID
member_role	varchar(32)	planner / reviewer / researcher
sort_order	integer	顺序
config_json	jsonb	角色级配置

索引：

idx_team_member_team(team_version_id)

表：`skill_definition`

字段	类型	说明
id	uuid	主键
tenant_id	uuid	租户 ID
code	varchar(64)	技能编码
name	varchar(128)	技能名称
skill_type	varchar(32)	prompt / workflow / decision / retrieval
owner_scope	varchar(32)	system / tenant / app
created_time	datetime	创建时间
updated_time	datetime	更新时间

表：`skill_version`

字段	类型	说明
id	uuid	主键
tenant_id	uuid	租户 ID
skill_id	uuid	技能定义 ID
version_no	integer	版本号
content_json	jsonb	技能定义内容
created_by	uuid	创建人
created_time	datetime	创建时间

表：`app_binding`

统一保存应用对 Agent / Team / Skill / Tool / Plugin 的绑定关系。

字段	类型	说明
id	uuid	主键
tenant_id	uuid	租户 ID
app_id	uuid	应用 ID
bind_type	varchar(32)	agent / team / skill / tool / plugin
target_id	uuid	绑定对象 ID
target_version_id	uuid	绑定版本 ID
binding_scope	varchar(32)	app / env / workflow / node
config_json	jsonb	绑定配置
created_time	datetime	创建时间

索引：

idx_app_binding_app(app_id, bind_type)

4.3 Session 域

职责：

用户会话
对话消息
请求入口
应答记录

表：`session`

字段	类型	说明
id	uuid	主键
tenant_id	uuid	租户 ID
app_id	uuid	应用 ID
user_id	uuid	用户 ID
channel_type	varchar(32)	web / api / webhook / sdk
session_status	varchar(32)	active / closed
title	varchar(256)	会话标题
started_time	datetime	开始时间
last_active_time	datetime	最后活跃时间
closed_time	datetime	结束时间

索引：

idx_session_user(user_id, last_active_time desc)
idx_session_app(app_id, last_active_time desc)

表：`conversation_turn`

字段	类型	说明
id	uuid	主键
tenant_id	uuid	租户 ID
session_id	uuid	会话 ID
turn_no	integer	轮次
input_message_id	uuid	用户消息 ID
output_message_id	uuid	最终回答消息 ID
run_id	uuid	对应运行 ID
created_time	datetime	创建时间

唯一索引：

uk_turn_session_no(session_id, turn_no)

表：`message`

字段	类型	说明
id	uuid	主键
tenant_id	uuid	租户 ID
session_id	uuid	会话 ID
turn_id	uuid	对话轮次 ID
role	varchar(32)	user / assistant / system / tool
content_type	varchar(32)	text / json / file / stream
content_text	text	文本内容
content_json	jsonb	结构化消息
token_count	integer	token 数
created_time	datetime	创建时间

索引：

idx_message_session(session_id, created_time)
idx_message_turn(turn_id)

表：`run_request`

字段	类型	说明
id	uuid	主键
tenant_id	uuid	租户 ID
session_id	uuid	会话 ID
app_version_id	uuid	应用版本 ID
workflow_version_id	uuid	流程版本 ID
trigger_type	varchar(32)	chat / api / schedule / webhook
request_payload_json	jsonb	原始请求
request_status	varchar(32)	accepted / rejected / started
created_time	datetime	创建时间

索引：

idx_run_request_session(session_id, created_time desc)

4.4 Runtime 域

职责：

流程运行
节点执行
状态迁移
快照与恢复
异步事件

这是平台最高频的核心域之一。

表：`workflow_run`

字段	类型	说明
id	uuid	主键
tenant_id	uuid	租户 ID
app_id	uuid	应用 ID
app_version_id	uuid	应用版本 ID
workflow_id	uuid	流程定义 ID
workflow_version_id	uuid	流程版本 ID
session_id	uuid	会话 ID，可空
parent_run_id	uuid	父运行 ID，子流程时使用
root_run_id	uuid	根运行 ID
run_type	varchar(32)	main / subflow / scheduled / batch
status	varchar(32)	pending / running / completed / failed / cancelled / paused
trigger_type	varchar(32)	user / api / event / timer
priority	integer	优先级
current_node_count	integer	已执行节点数
started_time	datetime	开始时间
finished_time	datetime	结束时间
error_code	varchar(64)	错误码
error_message	text	错误信息
created_time	datetime	创建时间

索引：

idx_run_root(root_run_id)
idx_run_session(session_id, created_time desc)
idx_run_status(status, created_time desc)
idx_run_app(app_id, created_time desc)

表：`node_run`

字段	类型	说明
id	uuid	主键
tenant_id	uuid	租户 ID
run_id	uuid	运行 ID
parent_node_run_id	uuid	父节点运行 ID
node_id	varchar(128)	DSL 节点 ID
node_type	varchar(32)	llm / tool / code / team 等
attempt_no	integer	第几次尝试
status	varchar(32)	pending / queued / running / completed / failed / skipped
worker_key	varchar(128)	执行 worker 标识
lease_expire_time	datetime	执行 lease 到期时间
queued_time	datetime	入队时间
started_time	datetime	开始时间
finished_time	datetime	结束时间
error_code	varchar(64)	错误码
error_message	text	错误信息
created_time	datetime	创建时间

唯一索引建议：

uk_node_run_attempt(run_id, node_id, attempt_no)

普通索引：

idx_node_run_status(status, queued_time)
idx_node_run_run(run_id, started_time)
idx_node_run_worker(worker_key, status)

表：`node_io_snapshot`

用于存储节点输入输出快照，便于回放和问题定位。

字段	类型	说明
id	uuid	主键
tenant_id	uuid	租户 ID
node_run_id	uuid	节点运行 ID
snapshot_type	varchar(32)	input / output / intermediate
payload_json	jsonb	快照内容
payload_ref	varchar(512)	大对象外置引用
created_time	datetime	创建时间

索引：

idx_node_snapshot_node(node_run_id, snapshot_type)

表：`run_state_snapshot`

字段	类型	说明
id	uuid	主键
tenant_id	uuid	租户 ID
run_id	uuid	运行 ID
snapshot_no	integer	快照号
state_json	jsonb	当前运行态
context_hash	varchar(128)	状态摘要
created_time	datetime	创建时间

唯一索引：

uk_run_snapshot(run_id, snapshot_no)

表：`run_event`

字段	类型	说明
id	bigint	主键
tenant_id	uuid	租户 ID
run_id	uuid	运行 ID
node_run_id	uuid	节点运行 ID，可空
event_type	varchar(64)	事件类型
event_time	datetime	事件时间
payload_json	jsonb	事件内容

索引：

idx_run_event_run(run_id, id)
idx_run_event_type(event_type, event_time desc)

建议：

run_event 可按月分区

表：`run_queue_task`

适合在没有独立 MQ 可视化追踪时保留调度状态。

字段	类型	说明
id	uuid	主键
tenant_id	uuid	租户 ID
run_id	uuid	运行 ID
node_run_id	uuid	节点运行 ID
task_type	varchar(32)	schedule / retry / timeout / resume
execute_after_time	datetime	可执行时间
task_status	varchar(32)	pending / taken / done / dead_letter
retry_count	integer	重试次数
payload_json	jsonb	任务内容
created_time	datetime	创建时间
updated_time	datetime	更新时间

索引：

idx_queue_ready(task_status, execute_after_time)

4.5 Memory / Context 域

职责：

会话上下文
任务上下文
长期记忆
领域隔离记忆
召回记录

表：`context_namespace`

表示不同作用域下的上下文命名空间。

字段	类型	说明
id	uuid	主键
tenant_id	uuid	租户 ID
app_id	uuid	应用 ID
namespace_type	varchar(32)	session / run / user / domain / team
namespace_key	varchar(256)	如 `session:{id}` 或 `domain:policy`
owner_ref	varchar(256)	归属对象
created_time	datetime	创建时间

唯一索引：

uk_context_namespace(tenant_id, namespace_type, namespace_key)

表：`context_kv`

字段	类型	说明
id	uuid	主键
tenant_id	uuid	租户 ID
namespace_id	uuid	命名空间 ID
key	varchar(128)	键
value_type	varchar(32)	string / number / bool / json
value_json	jsonb	值
revision	integer	修订号
updated_time	datetime	更新时间
updated_by_run_id	uuid	最后修改运行

唯一索引：

uk_context_kv(namespace_id, key)

表：`context_change_log`

字段	类型	说明
id	bigint	主键
tenant_id	uuid	租户 ID
namespace_id	uuid	命名空间 ID
key	varchar(128)	键
before_json	jsonb	修改前
after_json	jsonb	修改后
change_source	varchar(32)	node / tool / system
run_id	uuid	来源运行
node_run_id	uuid	来源节点
created_time	datetime	创建时间

索引：

idx_context_change_namespace(namespace_id, id desc)

表：`memory_record`

统一长期记忆记录。

字段	类型	说明
id	uuid	主键
tenant_id	uuid	租户 ID
app_id	uuid	应用 ID
user_id	uuid	用户 ID，可空
session_id	uuid	会话 ID，可空
run_id	uuid	运行 ID，可空
namespace	varchar(128)	`user` / `app` / `domain:order`
memory_type	varchar(32)	fact / preference / summary / episode
importance_score	numeric(5,2)	重要性
freshness_score	numeric(5,2)	新鲜度
content_text	text	内容
content_json	jsonb	结构化内容
source_type	varchar(32)	conversation / tool / import / rule
status	varchar(32)	active / archived / deleted
created_time	datetime	创建时间
updated_time	datetime	更新时间

索引：

idx_memory_namespace(namespace, created_time desc)
idx_memory_user(user_id, created_time desc)
idx_memory_app(app_id, created_time desc)
idx_memory_type(memory_type, status)

表：`memory_embedding`

字段	类型	说明
id	uuid	主键
tenant_id	uuid	租户 ID
memory_id	uuid	记忆记录 ID
embedding_model	varchar(64)	Embedding 模型
embedding	vector	向量
token_count	integer	token 数
created_time	datetime	创建时间

索引：

向量索引：ivfflat 或 hnsw(embedding)
idx_memory_embedding_memory(memory_id)

表：`memory_recall_log`

字段	类型	说明
id	bigint	主键
tenant_id	uuid	租户 ID
run_id	uuid	运行 ID
node_run_id	uuid	节点运行 ID
query_text	text	召回查询
namespace	varchar(128)	召回命名空间
top_k	integer	返回条数
result_ids_json	jsonb	命中记录 ID 列表
created_time	datetime	创建时间

索引：

idx_memory_recall_run(run_id, created_time desc)

4.6 Tool / Plugin 域

职责：

工具、插件、凭据、调用记录

表：`plugin_definition`

字段	类型	说明
id	uuid	主键
tenant_id	uuid	租户 ID，可空表示系统插件
code	varchar(64)	插件编码
name	varchar(128)	插件名称
provider	varchar(128)	提供方
source_type	varchar(32)	marketplace / local / git
manifest_json	jsonb	插件清单
created_time	datetime	创建时间
updated_time	datetime	更新时间

表：`plugin_version`

字段	类型	说明
id	uuid	主键
plugin_id	uuid	插件 ID
version	varchar(64)	版本号
package_ref	varchar(512)	包引用
checksum	varchar(128)	校验值
status	varchar(32)	active / disabled
created_time	datetime	创建时间

唯一索引：

uk_plugin_version(plugin_id, version)

表：`tool_definition`

字段	类型	说明
id	uuid	主键
tenant_id	uuid	租户 ID，可空表示系统工具
plugin_id	uuid	所属插件
code	varchar(64)	工具编码
name	varchar(128)	工具名称
tool_type	varchar(32)	function / http / mcp / db
description	text	描述
created_time	datetime	创建时间
updated_time	datetime	更新时间

唯一索引：

uk_tool_code(tenant_id, code)

表：`tool_version`

字段	类型	说明
id	uuid	主键
tool_id	uuid	工具定义 ID
version_no	integer	版本号
input_schema_json	jsonb	输入 schema
output_schema_json	jsonb	输出 schema
invoke_config_json	jsonb	调用配置
timeout_ms	integer	超时
retry_policy_json	jsonb	重试策略
created_time	datetime	创建时间

唯一索引：

uk_tool_version(tool_id, version_no)

表：`tool_credential`

不要直接存明文密钥，建议只存密文或外部 Secret 引用。

字段	类型	说明
id	uuid	主键
tenant_id	uuid	租户 ID
credential_name	varchar(128)	名称
secret_type	varchar(32)	api_key / oauth / service_account
secret_ref	varchar(512)	Secret Manager 引用
encrypted_payload	bytea	可选密文
created_time	datetime	创建时间
updated_time	datetime	更新时间

表：`tool_binding`

字段	类型	说明
id	uuid	主键
tenant_id	uuid	租户 ID
app_id	uuid	应用 ID
tool_version_id	uuid	工具版本 ID
credential_id	uuid	凭据 ID
binding_scope	varchar(32)	app / env / workflow / node
enabled	boolean	是否启用
config_json	jsonb	绑定配置
created_time	datetime	创建时间

索引：

idx_tool_binding_app(app_id, binding_scope)

表：`tool_invocation_log`

字段	类型	说明
id	uuid	主键
tenant_id	uuid	租户 ID
run_id	uuid	运行 ID
node_run_id	uuid	节点运行 ID
tool_id	uuid	工具 ID
tool_version_id	uuid	工具版本 ID
request_json	jsonb	请求参数
response_json	jsonb	响应结果
response_ref	varchar(512)	大对象引用
status	varchar(32)	success / failed / timeout
latency_ms	integer	调用耗时
error_message	text	错误信息
invoked_time	datetime	调用时间

索引：

idx_tool_invocation_run(run_id, invoked_time desc)
idx_tool_invocation_tool(tool_id, invoked_time desc)
idx_tool_invocation_status(status, invoked_time desc)

4.7 Retrieval / Knowledge 域

职责：

知识库
文档与分片
向量索引
检索审计

表：`knowledge_base`

字段	类型	说明
id	uuid	主键
tenant_id	uuid	租户 ID
app_id	uuid	应用 ID
code	varchar(64)	知识库编码
name	varchar(128)	名称
retrieval_strategy	varchar(32)	vector / hybrid / keyword
status	varchar(32)	active / disabled
created_time	datetime	创建时间
updated_time	datetime	更新时间

表：`document`

字段	类型	说明
id	uuid	主键
tenant_id	uuid	租户 ID
kb_id	uuid	知识库 ID
source_type	varchar(32)	file / url / api / manual
source_uri	varchar(512)	来源
title	varchar(256)	标题
mime_type	varchar(128)	文件类型
object_ref	varchar(512)	文件存储引用
parse_status	varchar(32)	pending / parsed / failed
metadata_json	jsonb	元数据
created_time	datetime	创建时间
updated_time	datetime	更新时间

索引：

idx_document_kb(kb_id, created_time desc)

表：`document_chunk`

字段	类型	说明
id	uuid	主键
tenant_id	uuid	租户 ID
document_id	uuid	文档 ID
chunk_no	integer	分片序号
content_text	text	分片内容
metadata_json	jsonb	分片元数据
created_time	datetime	创建时间

唯一索引：

uk_document_chunk(document_id, chunk_no)

表：`chunk_embedding`

字段	类型	说明
id	uuid	主键
tenant_id	uuid	租户 ID
chunk_id	uuid	分片 ID
embedding_model	varchar(64)	Embedding 模型
embedding	vector	向量
created_time	datetime	创建时间

索引：

向量索引：ivfflat 或 hnsw(embedding)
idx_chunk_embedding_chunk(chunk_id)

表：`retrieval_log`

字段	类型	说明
id	bigint	主键
tenant_id	uuid	租户 ID
run_id	uuid	运行 ID
node_run_id	uuid	节点运行 ID
kb_id	uuid	知识库 ID
query_text	text	查询语句
strategy	varchar(32)	vector / hybrid
top_k	integer	命中数
result_json	jsonb	命中详情
latency_ms	integer	耗时
created_time	datetime	创建时间

索引：

idx_retrieval_run(run_id, created_time desc)
idx_retrieval_kb(kb_id, created_time desc)

4.8 Model / LLM 域

如果 model-gateway 需要单独统计模型调用和成本，建议独立表。

表：`model_provider`

字段	类型	说明
id	uuid	主键
code	varchar(64)	openai / azure_openai / anthropic
name	varchar(128)	名称
provider_type	varchar(32)	hosted / self_hosted
config_json	jsonb	默认配置
created_time	datetime	创建时间

表：`model_definition`

字段	类型	说明
id	uuid	主键
provider_id	uuid	Provider ID
model_code	varchar(128)	模型编码
model_kind	varchar(32)	chat / embedding / rerank
capability_json	jsonb	能力描述
pricing_json	jsonb	价格配置
status	varchar(32)	active / deprecated
created_time	datetime	创建时间

唯一索引：

uk_model_provider_code(provider_id, model_code)

表：`model_invocation_log`

字段	类型	说明
id	uuid	主键
tenant_id	uuid	租户 ID
run_id	uuid	运行 ID
node_run_id	uuid	节点运行 ID
provider_id	uuid	Provider ID
model_id	uuid	模型 ID
request_json	jsonb	请求摘要
response_json	jsonb	响应摘要
prompt_tokens	integer	输入 token
completion_tokens	integer	输出 token
total_tokens	integer	总 token
estimated_cost	numeric(18,6)	预估成本
latency_ms	integer	耗时
status	varchar(32)	success / failed / timeout
invoked_time	datetime	调用时间

索引：

idx_model_invocation_run(run_id, invoked_time desc)
idx_model_invocation_model(model_id, invoked_time desc)

4.9 Trace / Eval 域

职责：

链路追踪
回放
评测与基线

表：`trace_span`

字段	类型	说明
id	uuid	主键
tenant_id	uuid	租户 ID
trace_id	uuid	Trace ID
parent_span_id	uuid	父 Span
span_type	varchar(32)	run / node / tool / model / memory
ref_id	varchar(128)	关联业务 ID
name	varchar(128)	Span 名称
status	varchar(32)	ok / error
started_time	datetime	开始时间
finished_time	datetime	结束时间
attributes_json	jsonb	属性

索引：

idx_trace_trace(trace_id, started_time)
idx_trace_ref(span_type, ref_id)

表：`trace_event`

字段	类型	说明
id	bigint	主键
tenant_id	uuid	租户 ID
trace_id	uuid	Trace ID
span_id	uuid	Span ID
event_name	varchar(128)	事件名
payload_json	jsonb	事件内容
event_time	datetime	事件时间

索引：

idx_trace_event_trace(trace_id, id)

表：`eval_suite`

字段	类型	说明
id	uuid	主键
tenant_id	uuid	租户 ID
app_id	uuid	应用 ID
name	varchar(128)	评测集名称
description	text	描述
created_by	uuid	创建人
created_time	datetime	创建时间

表：`eval_case`

字段	类型	说明
id	uuid	主键
suite_id	uuid	评测集 ID
input_json	jsonb	输入
expected_json	jsonb	预期输出
tags_json	jsonb	标签
created_time	datetime	创建时间

表：`eval_run`

字段	类型	说明
id	uuid	主键
tenant_id	uuid	租户 ID
suite_id	uuid	评测集 ID
app_version_id	uuid	评测应用版本
status	varchar(32)	pending / running / completed
started_time	datetime	开始时间
finished_time	datetime	结束时间
created_time	datetime	创建时间

表：`eval_result`

字段	类型	说明
id	uuid	主键
eval_run_id	uuid	评测运行 ID
eval_case_id	uuid	评测用例 ID
run_id	uuid	实际运行 ID
score	numeric(5,2)	得分
verdict	varchar(32)	pass / fail
detail_json	jsonb	评测详情
created_time	datetime	创建时间

索引：

idx_eval_result_run(eval_run_id)

5. 关键关系说明

核心关系可以理解为：

一个 tenant 下有多个 app_definition
一个 app_definition 下有多个 app_version
一个 app_definition 下有多个 workflow_definition
一个 workflow_definition 下有多个 workflow_version
一个 app 可以绑定多个 agent、team、skill、tool
一个 session 会产生多轮 conversation_turn
一次输入通常对应一个 run_request 和一个 workflow_run
一个 workflow_run 下会有多个 node_run
一个 node_run 会产生快照、工具调用、模型调用、trace 和 memory recall
memory_record 与 context_namespace 共同组成“长期记忆 + 运行状态”的双层体系

6. 索引与分区建议

6.1 必须优先建索引的表

workflow_run
node_run
run_event
message
memory_record
tool_invocation_log
model_invocation_log
retrieval_log
trace_event

6.2 建议分区的表

当数据量上来后，以下表建议按时间分区：

run_event
tool_invocation_log
model_invocation_log
retrieval_log
trace_event
context_change_log

优先方案：

PostgreSQL 按月 range partition

6.3 JSONB 使用建议

适合放 jsonb 的字段：

DSL 内容
节点快照
模型能力描述
工具输入输出 schema
配置策略

不要把核心检索条件全部塞进 jsonb，例如状态、版本、归属、时间等必须单独成列。

7. Redis 设计建议

Redis 不替代主数据库，主要承载以下内容：

session:{id}:recent_messages
run:{id}:state_cache
run:{id}:node_lock:{node_id}
idempotency:{key}
queue:ready
model_rate_limit:{provider}:{model}

建议：

所有 Redis Key 带租户前缀
运行态缓存必须可从数据库重建
分布式锁必须带 TTL

8. 对象存储设计建议

对象存储主要保存：

原始导入 YAML/JSON
大体积节点快照
工具大响应结果
文件上传
回放原始材料
检索文档原文

建议存储路径规范：

tenant/{tenant_id}/app/{app_id}/imports/...
tenant/{tenant_id}/run/{run_id}/snapshots/...
tenant/{tenant_id}/trace/{trace_id}/...
tenant/{tenant_id}/kb/{kb_id}/documents/...

9. 分阶段建表建议

V0.1 必需表

tenant
user_account
app_definition
app_version
workflow_definition
workflow_version
session
message
run_request
workflow_run
node_run
node_io_snapshot
tool_definition
tool_version
tool_binding
tool_invocation_log
model_provider
model_definition
model_invocation_log

目标：

跑通“应用配置 + 工作流执行 + 工具调用 + 基础日志”

V0.2 新增表

agent_definition
agent_version
skill_definition
skill_version
app_binding
context_namespace
context_kv
memory_record
memory_embedding
memory_recall_log

目标：

跑通“Agent + 技能 + 记忆”

V0.3 新增表

team_definition
team_version
team_member_binding
run_state_snapshot
run_queue_task
context_change_log
knowledge_base
document
document_chunk
chunk_embedding
retrieval_log

目标：

跑通“多智能体 + 子流程 + 检索 + 恢复”

V0.4 新增表

organization
role
permission
user_role
role_permission
plugin_definition
plugin_version
trace_span
trace_event
eval_suite
eval_case
eval_run
eval_result

目标：

跑通“治理、可观测、评测、插件化”

10. 跨服务数据边界建议

为避免后续服务拆分时数据库耦合过深，建议遵循以下约束：

auth-service 只直接管理 auth_db
workflow-service 只直接写 app_db
runtime-service 只直接写 runtime_db
memory-service 只直接写 memory_db
tool-service 只直接写 tool_db
retrieval-service 只直接写 retrieval_db
trace-service 只直接写 trace_db

其他服务如果需要这些数据：

通过 API 读
或通过事件异步复制只读视图

不要在应用层做跨库强事务。

11. 迁移与演进建议

11.1 迁移工具

Alembic 统一管理迁移
每个服务单独 migration 目录
共用库只提供模型定义，不直接统一迁移所有库

11.2 演进策略

先 schema 兼容，再代码切换
大字段新增优先 nullable
热表结构变更优先分阶段 rollout
分区表和归档表尽量提前规划

11.3 审计策略

以下操作建议强制审计：

应用发布
工作流导入
工具绑定变更
记忆写入策略变更
权限变更
人工审批结果

12. 推荐下一步

如果进入工程实施，最顺的下一步是：

先把 V0.1 的 SQLAlchemy 模型定义出来
建 Monorepo 下的多服务目录和共享 libs
先跑通 app_db + session_db + runtime_db + tool_db
后续再补 memory_db 和 trace_db

13. 结论

这套数据库设计的核心思想是：

用 PostgreSQL 承载配置、运行、治理主数据
用 Redis 承载高频短期状态和幂等控制
用 pgvector 承载语义记忆与知识检索
用对象存储承载大对象和原始产物
用分域设计保证未来多服务拆分和水平扩展不需要推翻重来

如果你下一步继续让我执行，我建议直接进入：

V0.1 SQLAlchemy 模型骨架
Alembic 初始建表脚本

agent-platform-database-design.md 37 KB 文件历史 原始文件

Python 智能体开发平台数据库设计（多服务 / 可横向扩展版）

1. 设计目标

2. 总体原则

2.1 核心原则

2.2 分库分域原则

2.3 横向扩展原则

3. ID 与通用字段规范

3.1 主键策略

3.2 通用字段

3.3 枚举字段建议

4. 分域数据库设计

4.1 Auth / Tenant 域

表：tenant

表：organization

表：user_account

表：role

表：permission

表：user_role

表：role_permission

4.2 App / Workflow 配置域

表：app_definition

表：app_environment

表：app_version

表：workflow_definition

表：workflow_version

表：workflow_import_record

表：agent_definition

表：agent_version

表：team_definition

表：team_version

表：team_member_binding

表：skill_definition

表：skill_version

表：app_binding

4.3 Session 域

表：session

表：conversation_turn

表：message

表：run_request

4.4 Runtime 域

表：workflow_run

表：node_run

表：node_io_snapshot

表：run_state_snapshot

表：run_event

表：run_queue_task

4.5 Memory / Context 域

表：context_namespace

表：context_kv

表：context_change_log

表：memory_record

表：memory_embedding

表：memory_recall_log

4.6 Tool / Plugin 域

表：plugin_definition

表：plugin_version

表：tool_definition

表：tool_version

表：tool_credential

表：tool_binding

表：tool_invocation_log

4.7 Retrieval / Knowledge 域

表：knowledge_base

表：document

表：document_chunk

表：chunk_embedding

表：retrieval_log

4.8 Model / LLM 域

表：model_provider

表：model_definition

表：model_invocation_log

4.9 Trace / Eval 域

表：trace_span

表：trace_event

表：eval_suite

表：eval_case

表：eval_run

表：eval_result

5. 关键关系说明

agent-platform-database-design.md 37 KB

文件历史原始文件

表：`tenant`

表：`organization`

表：`user_account`

表：`role`

表：`permission`

表：`user_role`

表：`role_permission`

表：`app_definition`

表：`app_environment`

表：`app_version`

表：`workflow_definition`

表：`workflow_version`

表：`workflow_import_record`

表：`agent_definition`

表：`agent_version`

表：`team_definition`

表：`team_version`

表：`team_member_binding`

表：`skill_definition`

表：`skill_version`

表：`app_binding`

表：`session`

表：`conversation_turn`

表：`message`

表：`run_request`

表：`workflow_run`

表：`node_run`

表：`node_io_snapshot`

表：`run_state_snapshot`

表：`run_event`

表：`run_queue_task`

表：`context_namespace`

表：`context_kv`

表：`context_change_log`

表：`memory_record`

表：`memory_embedding`

表：`memory_recall_log`

表：`plugin_definition`

表：`plugin_version`

表：`tool_definition`

表：`tool_version`

表：`tool_credential`

表：`tool_binding`

表：`tool_invocation_log`

表：`knowledge_base`

表：`document`

表：`document_chunk`

表：`chunk_embedding`

表：`retrieval_log`

表：`model_provider`

表：`model_definition`

表：`model_invocation_log`

表：`trace_span`

表：`trace_event`

表：`eval_suite`

表：`eval_case`

表：`eval_run`

表：`eval_result`