​

Database Architecture

​

概述

Zeus 采用分层的数据库架构，将数据库操作从业务逻辑中分离，实现清晰的职责划分。

​

架构概览

​

层级职责

​

1. Schema 层

定义表结构和关系，使用 Drizzle ORM 的声明式语法定义数据库表、字段类型、约束和外键关系。

​

2. Model 层

封装单表 CRUD 操作，提供 findById、findByUserId、create、update、delete 等标准方法，每个 Model 对应一张数据库表。

​

3. Service 层

处理业务逻辑，包括跨模型的事务处理和协调操作。例如创建会话时同时添加第一条消息、删除会话时级联删除所有消息等。

​

4. API Route 层

处理 HTTP 请求，负责权限检查、参数校验、调用 Service 层和返回响应。API Route 不直接操作数据库。

---

​

Drizzle ORM

​

概述

Zeus 使用 Drizzle ORM 与 PostgreSQL 进行类型安全的数据库操作。

​

数据库表

系统包含以下数据库表（定义在 db/schema/ 中）： 认证与用户：

• user - 用户信息（id, name, email, emailVerified, image 等）
• session - 用户会话（关联 user，包含 token 和过期时间）
• account - OAuth 账户（关联 user，存储第三方登录信息）
• user_settings - 用户偏好设置
• invitation_code - 注册邀请码

聊天与会话：

• chat_session - 聊天会话（关联 user 和 project）
• message - 消息记录（关联 chat_session，包含角色、内容和工具调用信息）
• checkpoint - Agent 状态检查点，用于会话恢复

项目：

• project - 项目管理（关联 user）
• settings - 项目级设置

知识库：

• knowledge_base - 知识库元数据（关联 user）
• embedding - 向量搜索的嵌入模型配置

工具与技能：

• tools - MCP 服务器和工具配置（关联 user，包含 tools 和 prompts）
• tool_allowlist - 用户级自动运行工具白名单
• skills - 技能配置与元数据

AI 与 Agent：

• llm - 用户级 LLM 模型配置
• memory - 长期记忆条目（关联 user）
• sandbox - 沙盒环境配置
• plan - Agent 计划记录

自动化与积分：

• scheduled_task - 定时任务定义
• credits - 用户积分余额与交易记录

案例展示：

• showcase - 已发布的案例展示条目

​

类型安全

Drizzle 通过 InferSelectModel 和 InferInsertModel 自动从 Schema 定义生成 TypeScript 类型，确保查询和插入操作的类型安全。

​

最佳实践

​

1. 使用连接池

配置数据库连接池（推荐 max: 20），设置合理的超时参数以优化性能。

​

2. 添加索引

在频繁查询的字段上添加索引，例如 userId、projectId 等外键字段。

​

3. 使用事务

对于需要原子性的多步操作，使用 db.transaction() 确保数据一致性。

​

4. 批量操作

优先使用批量插入和 IN 查询，避免循环单条操作。