taiji-AI-PAD/Docs/项目文档/数据库设计文档.md

taiji-AI-PAD 数据库设计文档

版本: v1.0
创建时间: 2025年12月23日
最后更新: 2025年12月23日

---

📋 目录

1. 数据库架构概述
2. PostgreSQL 数据库设计
3. Redis 缓存设计
4. NATS 消息队列
5. 数据库使用场景
6. 数据流转和处理
7. 数据库初始化

---

1. 数据库架构概述

1.1 使用的数据库系统

taiji-AI-PAD 系统使用三种数据库/存储系统：

数据库系统	用途	端口	容器名称
PostgreSQL	关系型数据库，存储持久化数据	5432	taiji-postgres
Redis	缓存和会话存储	6379	taiji-redis
NATS	消息队列和事件流	4222	taiji-nats

1.2 数据库架构图

┌─────────────────────────────────────────────────────────┐
│                   应用服务层                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐ │
│  │ MCP Server   │  │ Data Ingestion│  │ LiteLLM      │ │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘ │
└─────────┼──────────────────┼──────────────────┼─────────┘
          │                  │                  │
    ┌─────┴─────┐      ┌─────┴─────┐      ┌─────┴─────┐
    │ PostgreSQL │      │   Redis   │      │   NATS    │
    │  (主数据库) │      │  (缓存)   │      │ (消息队列) │
    └────────────┘      └───────────┘      └───────────┘

---

2. PostgreSQL 数据库设计

2.1 数据库信息

• 数据库名: taiji_db
• 用户名: taiji_user
• 密码: taiji_pass
• 字符集: UTF-8
• 时区: UTC

2.2 数据表设计

2.2.1 users (用户表)

用途: 存储系统用户信息

字段名	类型	说明	约束
id	UUID	用户ID	PRIMARY KEY
username	VARCHAR(50)	用户名	UNIQUE, NOT NULL
email	VARCHAR(255)	邮箱	UNIQUE, NOT NULL
hashed_password	VARCHAR(255)	加密密码	NOT NULL
full_name	VARCHAR(100)	全名
is_active	BOOLEAN	是否激活	DEFAULT TRUE
is_admin	BOOLEAN	是否管理员	DEFAULT FALSE
created_at	TIMESTAMP	创建时间	NOT NULL
updated_at	TIMESTAMP	更新时间	NOT NULL

索引:

• idx_user_username (username)
• idx_user_email (email)

关联关系:

• 一对多: agents (用户拥有的Agent)
• 一对多: sessions (用户的会话)

处理逻辑:

• 密码使用 bcrypt 加密存储
• 创建时自动生成 UUID
• 支持软删除（通过 is_active 字段）

---

2.2.2 agents (Agent表)

用途: 存储AI Agent的定义和配置

字段名	类型	说明	约束
id	UUID	Agent ID	PRIMARY KEY
name	VARCHAR(100)	Agent名称	NOT NULL
description	TEXT	描述
role	VARCHAR(200)	Agent角色定义	NOT NULL
goal	TEXT	Agent目标	NOT NULL
config	JSON	Agent配置信息	DEFAULT {}
tools	JSON	授权使用的工具列表	DEFAULT []
capabilities	JSON	Agent能力列表	DEFAULT []
status	VARCHAR(20)	状态	DEFAULT 'active'
version	VARCHAR(20)	版本号	DEFAULT '1.0.0'
total_executions	INTEGER	总执行次数	DEFAULT 0
success_rate	FLOAT	成功率	DEFAULT 0.0
avg_execution_time	FLOAT	平均执行时间(ms)	DEFAULT 0.0
owner_id	UUID	所有者ID	FOREIGN KEY, NOT NULL
created_at	TIMESTAMP	创建时间	NOT NULL
updated_at	TIMESTAMP	更新时间	NOT NULL

索引:

• idx_agent_name (name)
• idx_agent_owner (owner_id)
• idx_agent_status (status)
• uq_agent_name_owner (name, owner_id) - 唯一约束

关联关系:

• 多对一: users (所有者)
• 一对多: executions (执行记录)

处理逻辑:

• 每个用户在同一名称下只能有一个Agent（唯一约束）
• status 字段: active, inactive, error
• tools 和 capabilities 以 JSON 数组存储
• 自动统计执行次数和成功率

---

2.2.3 tools (工具表)

用途: 存储可用的工具定义（API、函数等）

字段名	类型	说明	约束
id	UUID	工具ID	PRIMARY KEY
name	VARCHAR(100)	工具名称	NOT NULL
description	TEXT	描述
category	VARCHAR(50)	分类
schema	JSON	OpenAPI/Pydantic schema	NOT NULL
endpoint	VARCHAR(500)	API端点URL
method	VARCHAR(10)	HTTP方法	DEFAULT 'POST'
auth_type	VARCHAR(20)	认证类型
auth_config	JSON	认证配置	DEFAULT {}
rate_limit	INTEGER	速率限制(次/分钟)	DEFAULT 100
cost_per_call	FLOAT	每次调用成本(EU)	DEFAULT 0.0
timeout	INTEGER	超时时间(秒)	DEFAULT 30
is_active	BOOLEAN	是否激活	DEFAULT TRUE
is_public	BOOLEAN	是否公开	DEFAULT FALSE
total_calls	INTEGER	总调用次数	DEFAULT 0
success_rate	FLOAT	成功率	DEFAULT 0.0
avg_response_time	FLOAT	平均响应时间	DEFAULT 0.0
owner_id	UUID	所有者ID	FOREIGN KEY
created_at	TIMESTAMP	创建时间	NOT NULL
updated_at	TIMESTAMP	更新时间	NOT NULL

索引:

• idx_tool_name (name)
• idx_tool_category (category)
• idx_tool_active (is_active)

关联关系:

• 多对一: users (所有者，可选)

处理逻辑:

• schema 字段存储完整的工具定义（参数、返回值等）
• 支持多种认证类型: api_key, oauth, basic
• 自动统计调用次数和成功率
• is_public 控制工具是否对所有用户可见

---

2.2.4 sessions (会话表)

用途: 存储用户会话和上下文信息

字段名	类型	说明	约束
id	UUID	会话ID	PRIMARY KEY
session_id	VARCHAR(100)	会话标识符	UNIQUE, NOT NULL
context	JSON	会话上下文	DEFAULT {}
session_metadata	JSON	元数据	DEFAULT {}
status	VARCHAR(20)	状态	DEFAULT 'active'
user_id	UUID	用户ID	FOREIGN KEY, NOT NULL
created_at	TIMESTAMP	创建时间	NOT NULL
updated_at	TIMESTAMP	更新时间	NOT NULL

索引:

• idx_session_id (session_id)
• idx_session_user (user_id)
• idx_session_status (status)

关联关系:

• 多对一: users (用户)
• 一对多: executions (执行记录)

处理逻辑:

• context 存储会话的上下文信息（对话历史等）
• status 字段: active, completed, failed
• session_metadata 存储额外的元数据信息

---

2.2.5 executions (执行记录表)

用途: 存储Agent执行记录和资源消耗

字段名	类型	说明	约束
id	UUID	执行ID	PRIMARY KEY
execution_id	VARCHAR(100)	执行标识符	UNIQUE, NOT NULL
method	VARCHAR(50)	MCP方法名	NOT NULL
params	JSON	执行参数	DEFAULT {}
result	JSON	执行结果	DEFAULT {}
error	TEXT	错误信息
started_at	TIMESTAMP	开始时间	NOT NULL
completed_at	TIMESTAMP	完成时间
execution_time	FLOAT	执行时间(毫秒)
status	VARCHAR(20)	状态	NOT NULL
cpu_usage	FLOAT	CPU使用率	DEFAULT 0.0
memory_usage	FLOAT	内存使用(MB)	DEFAULT 0.0
network_io	FLOAT	网络IO(KB)	DEFAULT 0.0
eu_consumed	FLOAT	消耗的执行单元	DEFAULT 0.0
agent_id	UUID	Agent ID	FOREIGN KEY, NOT NULL
session_id	UUID	会话ID	FOREIGN KEY
created_at	TIMESTAMP	创建时间	NOT NULL
updated_at	TIMESTAMP	更新时间	NOT NULL

索引:

• idx_execution_id (execution_id)
• idx_execution_agent (agent_id)
• idx_execution_status (status)
• idx_execution_started (started_at)

关联关系:

• 多对一: agents (所属Agent)
• 多对一: sessions (所属会话，可选)
• 一对多: billing (计费记录)

处理逻辑:

• 记录每次Agent执行的详细信息
• 跟踪资源消耗（CPU、内存、网络、存储）
• status 字段: running, completed, failed
• eu_consumed 用于计费系统

---

2.2.6 api_keys (API密钥表)

用途: 存储用户API密钥

字段名	类型	说明	约束
id	UUID	密钥ID	PRIMARY KEY
name	VARCHAR(100)	密钥名称	NOT NULL
key_hash	VARCHAR(255)	哈希后的密钥	NOT NULL
prefix	VARCHAR(20)	密钥前缀	NOT NULL
scopes	JSON	权限范围	DEFAULT []
rate_limit	INTEGER	速率限制	DEFAULT 1000
is_active	BOOLEAN	是否激活	DEFAULT TRUE
expires_at	TIMESTAMP	过期时间
last_used_at	TIMESTAMP	最后使用时间
total_requests	INTEGER	总请求数	DEFAULT 0
user_id	UUID	用户ID	FOREIGN KEY, NOT NULL
created_at	TIMESTAMP	创建时间	NOT NULL
updated_at	TIMESTAMP	更新时间	NOT NULL

索引:

• idx_api_key_hash (key_hash)
• idx_api_key_prefix (prefix)
• idx_api_key_user (user_id)

关联关系:

• 多对一: users (所有者)

处理逻辑:

• 密钥以哈希形式存储，不存储明文
• prefix 用于快速识别密钥类型
• scopes 定义密钥的权限范围
• 支持过期时间和使用统计

---

2.2.7 billing (计费记录表)

用途: 存储执行单元的计费记录

字段名	类型	说明	约束
id	UUID	计费ID	PRIMARY KEY
eu_consumed	FLOAT	消耗的执行单元	NOT NULL
cost	FLOAT	成本	NOT NULL
currency	VARCHAR(3)	货币	DEFAULT 'USD'
cpu_time	FLOAT	CPU时间(秒)	DEFAULT 0.0
memory_max	FLOAT	峰值内存(MB)	DEFAULT 0.0
network_io	FLOAT	网络IO(KB)	DEFAULT 0.0
storage_io	FLOAT	存储IO(KB)	DEFAULT 0.0
execution_id	UUID	执行ID	FOREIGN KEY, NOT NULL
user_id	UUID	用户ID	FOREIGN KEY, NOT NULL
created_at	TIMESTAMP	创建时间	NOT NULL
updated_at	TIMESTAMP	更新时间	NOT NULL

索引:

• idx_billing_execution (execution_id)
• idx_billing_user (user_id)
• idx_billing_created (created_at)

关联关系:

• 多对一: executions (执行记录)
• 多对一: users (用户)

处理逻辑:

• 每条执行记录对应一条计费记录
• eu_consumed 基于资源消耗计算
• 支持多货币计费

---

2.2.8 audit_logs (审计日志表)

用途: 存储系统操作审计日志

字段名	类型	说明	约束
id	UUID	日志ID	PRIMARY KEY
action	VARCHAR(50)	操作类型	NOT NULL
resource_type	VARCHAR(50)	资源类型	NOT NULL
resource_id	VARCHAR(100)	资源ID
details	JSON	操作详情	DEFAULT {}
ip_address	VARCHAR(45)	IP地址
user_agent	TEXT	用户代理
success	BOOLEAN	是否成功	NOT NULL
error_message	TEXT	错误信息
user_id	UUID	用户ID	FOREIGN KEY
created_at	TIMESTAMP	创建时间	NOT NULL
updated_at	TIMESTAMP	更新时间	NOT NULL

索引:

• idx_audit_action (action)
• idx_audit_resource (resource_type, resource_id)
• idx_audit_user (user_id)
• idx_audit_created (created_at)

关联关系:

• 多对一: users (操作用户，可选)

处理逻辑:

• 记录所有关键操作（创建、更新、删除等）
• details 字段存储操作的详细信息
• 支持成功和失败两种状态记录

---

2.3 LiteLLM 相关表

PostgreSQL 中还包含 LiteLLM Gateway 使用的表：

• LiteLLM_Config: LiteLLM 配置信息
• LiteLLM_UserTable: LiteLLM 用户表
• LiteLLM_VerificationToken: LiteLLM 验证令牌表

这些表由 LiteLLM 自动管理，用于模型网关的用户管理和配置。

---

3. Redis 缓存设计

3.1 Redis 用途

Redis 在系统中主要用于：

1. Token 缓存: 存储 JWT Token 和 Refresh Token
2. 会话缓存: 缓存用户会话信息
3. 工具定义缓存: 缓存工具定义，减少数据库查询
4. API 响应缓存: 缓存 API 调用结果
5. 速率限制: 实现 API 速率限制
6. 实时数据: 存储实时统计数据

3.2 Redis Key 设计规范

# Token 相关
token:access:{user_id}:{token_hash}     # Access Token
token:refresh:{user_id}:{token_hash}    # Refresh Token
token:blacklist:{token_hash}             # Token 黑名单

# 会话相关
session:{session_id}                     # 会话信息
session:user:{user_id}                   # 用户会话列表

# 工具相关
tool:def:{tool_id}                       # 工具定义
tool:cache:{tool_name}                   # 工具缓存

# API 缓存
api:cache:{endpoint}:{params_hash}       # API 响应缓存

# 速率限制
rate:limit:{user_id}:{endpoint}         # 速率限制计数

# 统计数据
stats:agent:{agent_id}:executions        # Agent 执行统计
stats:user:{user_id}:usage              # 用户使用统计

3.3 Redis 配置

• 数据库: 默认使用 db 0
• 持久化: 根据配置启用 RDB 或 AOF
• 过期策略: 使用 TTL 自动过期
• 连接池: 最大连接数 20

3.4 缓存策略

1. Token 缓存:

   • Access Token: TTL = 60 分钟
   • Refresh Token: TTL = 7 天

2. 工具定义缓存:

   • TTL = 1 小时
   • 工具更新时自动失效

3. API 响应缓存:

   • TTL = 5 分钟
   • 根据 endpoint 和参数生成 key

---

4. NATS 消息队列

4.1 NATS 用途

NATS 在系统中用于：

1. 事件发布/订阅: Agent 执行事件、系统事件
2. 异步任务处理: 长时间运行的任务
3. 服务间通信: 微服务之间的消息传递
4. 实时通知: WebSocket 消息推送

4.2 NATS 主题设计

# Agent 相关事件
agent.execution.start.{agent_id}         # Agent 执行开始
agent.execution.complete.{agent_id}      # Agent 执行完成
agent.execution.error.{agent_id}         # Agent 执行错误

# 计费相关事件
billing.record.{user_id}                 # 计费记录
billing.quota.exceeded.{user_id}         # 配额超限

# 系统事件
system.health.check                      # 健康检查
system.config.update                     # 配置更新
system.alert.{level}                     # 系统告警

# 工具相关事件
tool.call.{tool_id}                      # 工具调用
tool.update.{tool_id}                    # 工具更新

4.3 NATS 配置

• 端口: 4222 (客户端连接)
• JetStream: 启用，用于持久化消息
• 监控端口: 8222
• 路由端口: 6222

---

5. 数据库使用场景

5.1 MCP Server 使用场景

PostgreSQL:

• 存储用户、Agent、工具、会话、执行记录等核心数据
• 支持复杂查询和关联查询
• 保证数据一致性和完整性

Redis:

• 缓存 Agent 配置和工具定义
• 存储 WebSocket 会话信息
• 实现速率限制

NATS:

• 发布 Agent 执行事件
• 处理异步任务
• 实时通知 WebSocket 客户端

5.2 Data Ingestion 使用场景

PostgreSQL:

• 存储 API 文档和工具定义（可选）

Redis:

• 缓存 API 文档处理结果
• 缓存工具定义
• 存储处理队列

NATS:

• 发布新工具注册事件
• 通知工具更新

5.3 LiteLLM Gateway 使用场景

PostgreSQL:

• 存储 LiteLLM 配置
• 存储用户和密钥信息

Redis:

• 缓存模型响应
• 实现速率限制

---

6. 数据流转和处理

6.1 Agent 注册流程

1. 用户请求创建 Agent
   ↓
2. MCP Server 验证请求
   ↓
3. 写入 PostgreSQL (agents 表)
   ↓
4. 缓存到 Redis (tool:def:{agent_id})
   ↓
5. 发布事件到 NATS (agent.created)
   ↓
6. 返回 Agent Card

6.2 Agent 执行流程

1. 用户请求执行 Agent
   ↓
2. 创建执行记录 (PostgreSQL: executions)
   ↓
3. 发布开始事件 (NATS: agent.execution.start)
   ↓
4. 执行 Agent 逻辑
   ↓
5. 更新执行记录 (PostgreSQL: executions)
   ↓
6. 创建计费记录 (PostgreSQL: billing)
   ↓
7. 发布完成事件 (NATS: agent.execution.complete)
   ↓
8. 更新统计信息 (Redis: stats:agent:{agent_id})
   ↓
9. 返回执行结果

6.3 工具调用流程

1. Agent 请求调用工具
   ↓
2. 检查 Redis 缓存 (tool:def:{tool_id})
   ↓
3. 如果未命中，从 PostgreSQL 查询 (tools 表)
   ↓
4. 缓存到 Redis
   ↓
5. 执行工具调用
   ↓
6. 更新工具统计 (PostgreSQL: tools)
   ↓
7. 发布事件 (NATS: tool.call.{tool_id})
   ↓
8. 返回结果

---

7. 数据库初始化

7.1 初始化流程

1. 创建数据库表:

   • 使用 SQLAlchemy 的 Base.metadata.create_all() 创建所有表
   • 自动创建索引和约束

2. 创建初始数据:

   • 创建默认管理员用户 (username: admin, password: admin123)
   • 创建默认工具 (web_search, text_completion, weather_api)

3. 初始化检查:

   • 检查用户表是否为空
   • 检查工具表是否为空
   • 只在首次初始化时创建初始数据

7.2 初始化代码位置

• 文件: services/mcp-server/database.py
• 函数: init_db() 和 create_initial_data()
• 调用时机: MCP Server 启动时自动调用

7.3 数据库迁移

当前使用 SQLAlchemy 的自动建表功能。未来可以使用 Alembic 进行数据库迁移管理。

---

8. 数据库维护

8.1 备份策略

• PostgreSQL: 定期备份（建议每日）
• Redis: 根据持久化配置自动备份
• NATS: JetStream 数据自动持久化

8.2 性能优化

1. 索引优化: 所有外键和常用查询字段已建立索引
2. 连接池: PostgreSQL 连接池大小 20
3. 查询优化: 使用异步查询，避免阻塞
4. 缓存策略: 热点数据缓存到 Redis

8.3 监控指标

• PostgreSQL: 连接数、查询性能、表大小
• Redis: 内存使用、命中率、连接数
• NATS: 消息吞吐量、连接数、JetStream 状态

---

9. 数据安全

9.1 数据加密

• 密码: 使用 bcrypt 加密存储
• API Key: 使用哈希存储，不存储明文
• 敏感配置: 存储在环境变量中

9.2 访问控制

• 数据库访问: 使用专用用户和密码
• 网络隔离: 数据库仅在 Docker 网络内可访问
• 权限控制: 应用层实现细粒度权限控制

9.3 审计日志

• 所有关键操作记录到 audit_logs 表
• 记录操作时间、用户、IP、结果等信息
• 支持查询和分析

---

10. 总结

10.1 数据库选择理由

• PostgreSQL:

  • 强大的关系型数据库功能
  • 支持 JSON 字段，灵活存储配置
  • 良好的性能和可靠性

• Redis:

  • 高性能缓存
  • 支持复杂数据结构
  • 适合实时数据存储

• NATS:

  • 轻量级消息队列
  • 支持发布/订阅模式
  • 低延迟，高吞吐量

10.2 数据一致性

• 强一致性: PostgreSQL 保证数据一致性
• 最终一致性: Redis 缓存可能短暂不一致，通过 TTL 和失效机制保证最终一致
• 事件驱动: NATS 事件保证系统间数据同步

---

文档版本: v1.0
最后更新: 2025年12月23日
维护者: taiji-AI-PAD 开发团队