mirror of
https://github.com/lobehub/lobe-chat.git
synced 2025-12-20 01:12:52 +08:00
ed2ce8d32f
* 📝 docs: add some cursor rules & optimize codebase indexing * 📝 docs: some code reviews issue by greptile
95 lines
5.5 KiB
Plaintext
95 lines
5.5 KiB
Plaintext
---
|
||
description:
|
||
globs: src/services/**/*,src/database/**/*,src/server/**/*
|
||
alwaysApply: false
|
||
---
|
||
# LobeChat 后端技术架构指南
|
||
|
||
本指南旨在阐述 LobeChat 项目的后端分层架构，重点介绍各核心目录的职责以及它们之间的协作方式。
|
||
|
||
## 目录结构映射
|
||
|
||
```
|
||
src/
|
||
├── server/
|
||
│ ├── routers/ # tRPC API 路由定义
|
||
│ └── services/ # 业务逻辑服务层
|
||
│ └── */impls/ # 平台特定实现
|
||
├── database/
|
||
│ ├── models/ # 数据模型 (单表 CRUD)
|
||
│ ├── repositories/ # 仓库层 (复杂查询/聚合)
|
||
│ └── schemas/ # Drizzle ORM 表定义
|
||
└── services/ # 客户端服务 (调用 tRPC 或直接访问 Model)
|
||
```
|
||
|
||
## 核心架构分层
|
||
|
||
LobeChat 的后端设计注重模块化、可测试性和灵活性，以适应不同的运行环境（如浏览器端 PGLite、服务端远程 PostgreSQL 以及 Electron 桌面应用）。
|
||
|
||
其主要分层如下：
|
||
|
||
1. **客户端服务层 (`src/services`)**:
|
||
* 位于 [src/services/](mdc:src/services)。
|
||
* 这是客户端业务逻辑的核心层，负责封装各种业务操作和数据处理逻辑。
|
||
* **环境适配**: 根据不同的运行环境，服务层会选择合适的数据访问方式：
|
||
* **本地数据库模式**: 直接调用 `Model` 层进行数据操作，适用于浏览器 PGLite 和本地 Electron 应用。
|
||
* **远程数据库模式**: 通过 `tRPC` 客户端调用服务端 API，适用于需要云同步的场景。
|
||
* **类型转换**: 对于简单的数据类型转换，直接在此层进行类型断言，如 `this.pluginModel.query() as Promise<LobeTool[]>`（参见 [src/services/plugin/client.ts](mdc:src/services/plugin/client.ts)）。
|
||
* 每个服务模块通常包含 `client.ts`（本地模式）、`server.ts`（远程模式）和 `type.ts`（接口定义）文件。
|
||
|
||
2. **API 接口层 (`TRPC`)**:
|
||
* 位于 [src/server/routers/](mdc:src/server/routers)。
|
||
* 使用 `tRPC` 构建类型安全的 API。Router 根据运行时环境（如 Edge Functions, Node.js Lambda）进行组织。
|
||
* 负责接收客户端请求，并将其路由到相应的 `Service` 层进行处理。
|
||
|
||
3. **服务端服务层 (`server/services`)**:
|
||
* 位于 [src/server/services/](mdc:src/server/services)。
|
||
* 核心职责是封装独立的、可复用的业务逻辑单元。这些服务应易于测试。
|
||
* **平台差异抽象**: 一个关键特性是通过其内部的 `impls` 子目录（例如 [src/server/services/file/impls/](mdc:src/server/services/file/impls) 包含 `s3.ts` 和 `local.ts`）来抹平不同运行环境带来的差异（例如云端使用 S3 存储，桌面版使用本地文件系统）。这使得上层（如 `tRPC` routers）无需关心底层具体实现。
|
||
* 目标是使 `tRPC` router 层的逻辑尽可能纯粹，专注于请求处理和业务流程编排。
|
||
* 服务会调用 `Repository` 层或直接调用 `Model` 层进行数据持久化和检索，也可能调用其他服务。
|
||
|
||
4. **仓库层 (`Repositories`)**:
|
||
* 位于 [src/database/repositories/](mdc:src/database/repositories)。
|
||
* 主要处理**复杂的跨表查询和数据聚合**逻辑，特别是当需要从**多个 `Model`** 获取数据并进行组合时。
|
||
* 与 `Model` 层不同，`Repository` 层专注于复杂的业务查询场景，而不涉及简单的领域模型转换。
|
||
* 当业务逻辑涉及多表关联、复杂的数据统计或需要事务处理时，会使用 `Repository` 层。
|
||
* 如果数据操作简单（仅涉及单个 `Model`），则通常直接在 `src/services` 层调用 `Model` 并进行简单的类型断言。
|
||
|
||
5. **模型层 (`Models`)**:
|
||
* 位于 [src/database/models/](mdc:src/database/models) (例如 [src/database/models/plugin.ts](mdc:src/database/models/plugin.ts) 和 [src/database/models/document.ts](mdc:src/database/models/document.ts))。
|
||
* 提供对数据库中各个表（由 [src/database/schemas/](mdc:src/database/schemas) 中的 Drizzle ORM schema 定义）的基本 CRUD (创建、读取、更新、删除) 操作和简单的查询能力。
|
||
* `Model` 类专注于单个数据表的直接操作，**不涉及复杂的领域模型转换**，这些转换通常在上层的 `src/services` 中通过类型断言完成。
|
||
|
||
6. **数据库 (`Database`)**:
|
||
* **客户端模式 (浏览器/PWA)**: 使用 PGLite (基于 WASM 的 PostgreSQL)，数据存储在用户浏览器本地。
|
||
* **服务端模式 (云部署)**: 使用远程 PostgreSQL 数据库。
|
||
* **Electron 桌面应用**:
|
||
* Electron 客户端会启动一个本地 Node.js 服务。
|
||
* 本地服务通过 `tRPC` 与 Electron 的渲染进程通信。
|
||
* 数据库选择依赖于是否开启**云同步**功能：
|
||
* **云同步开启**: 连接到远程 PostgreSQL 数据库。
|
||
* **云同步关闭**: 使用 PGLite (通过 Node.js 的 WASM 实现) 在本地存储数据。
|
||
|
||
## 数据流向说明
|
||
|
||
### 浏览器/PWA 模式
|
||
```
|
||
UI (React) → Zustand State → Model Layer → PGLite (本地数据库)
|
||
```
|
||
|
||
### 服务端模式
|
||
```
|
||
UI (React) → Zustand State → tRPC Client → tRPC Routers → Services → Repositories/Models → Remote PostgreSQL
|
||
```
|
||
|
||
### Electron 桌面应用模式
|
||
```
|
||
UI (Electron Renderer) → Zustand State → tRPC Client → 本地 Node.js 服务 → tRPC Routers → Services → Repositories/Models → PGLite/Remote PostgreSQL (取决于云同步设置)
|
||
```
|
||
|
||
|
||
|
||
|
||
|