> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeus.agentspro.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# Database

> Zeus 数据库架构与 Drizzle ORM

# Database Architecture

## 概述

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

## 架构概览

```mermaid theme={null}
flowchart TD
    subgraph Routes["API Routes<br/>web/src/app/api/[resource]/route.ts"]
        R["HTTP 请求/响应处理、参数校验、权限检查"]
    end

    subgraph Service["Service Layer<br/>web/src/db/service/"]
        S["业务逻辑、事务处理、跨模型协调"]
    end

    subgraph Model["Model Layer<br/>web/src/db/model/"]
        M["单表 CRUD 操作、查询构建"]
    end

    subgraph SchemaLayer["Schema Layer<br/>web/src/db/schema/"]
        SC["表结构定义、关系声明、类型生成"]
    end

    PostgreSQL[(PostgreSQL)]

    Routes --> Service
    Service --> Model
    Model --> SchemaLayer
    SchemaLayer --> PostgreSQL
```

## 层级职责

### 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` 查询，避免循环单条操作。