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

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

---

## 📋 目录

1. [数据库架构概述](#数据库架构概述)
2. [PostgreSQL 数据库设计](#postgresql-数据库设计)
3. [Redis 缓存设计](#redis-缓存设计)
4. [NATS 消息队列](#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 开发团队