[RFC] 036 - LobeChat 服务端数据库 & ORM

[arvinxx]

背景

LobeChat 1.0 要接入数据库方案了，需要确定一下后端数据库方案 & ORM 方案。

• Towards LobeChat 1.0 | 迈向 LobeChat 1.0 #1768

设计思路

数据库

数据库没啥好说的，已经确定用 PostgresSQL 了，这个好处很明显：

• Vercel 自带了 Serverless Postgres，因此 Vercel 部署的用户未来应该可以直接填个 DATABASE_URL 就可以用；
• Docker 版本的用户添加一个 Postgres 数据库 url 或者配置一个 docker-compose 也可以实现类似的效果。市面上也有很多现成的 serverless 的 PG 服务，例如 Neon、Supabase等等；
• Postgres 支持向量数据库，因此理论上用一个数据库就可以解决未来的向量化检索需求；

ORM

针对 ORM 部分，之前比较确定的是采用了 Prisma：prisma.io 。不过最近又研究了下 Drizzle ORM ，说实话也是有点心动的。

Prisma 其实存在几个问题：

• 一个是默认 edge 不友好，没法直接跑在现代化的 edge runtime 上，必须要使用他们的 Accelerate 才能在 edge 上支持起来；
• 数据迁移的部分不友好，它的迁移会直接 drop table，存在导致数据删库的风险（别问我怎么知道的 😰），这个感觉可能是个未来的隐患，比如用户部署的部分一不小心就点挂了；
• 性能会相对差一些。 参考
  

Drizzle ORM 的话比起 prisma 的优势在于：

• 性能更好，压测下的硬件开销更低：
  
• 纯 TS 定义数据模型，不需要走 prisma generate 那一套，直接就是 TS schema；
• 原生支持 Edge Runtime，这意味着未来服务端部分就不会和 prisma Accelerate 这种直接绑死；
• migration 更加友好，针对改字段的场景提供了很友好的引导流程，refs: https://zenstack.dev/blog/drizzle-prisma#migration

但是它存在一个核心的缺陷： AI 不友好：

如果其他模型也不缺少 Dirzzle ORM 的语料，那么直接拿这个用上生产就会比较难。所以最近我可能会试试看其他模型是否能懂 Drizzle 的使用。

client 与 server 的统一

另外最近看到的另外一个比较远的消息，drizzle 支持了 PGLite ：https://github.com/drizzle-team/drizzle-orm/releases/tag/0.30.6 ，PGLite 是 Postgres 的本地 wasm 版本。因此如果采用 drizzle 的话，我们后续有可能可以统一 client 和 server 侧的数据库选型都到 Postgres 上，然后通过 electric 这样的方案实现 client 与 server 的实时同步，这对于长期迭代来看可能是一个比较好的模式，可以统一成一个 ORM 维护。

进展

基础代码改造

Client 与 Server 区分

• ♻️ refactor: move client db to a new folder #2037
• ♻️ refactor: refactor the service with browser db invoke #2038
• ♻️ refactor: refactor the service interface #2062

store 异步化适配

乐观更新 & loading 适配

• 💄 style: improve aync session experience #2075
• ♻️ refactor: refactor for session server mode #2163
• ⚡️ perf: refactor to improve the topic in server mode #2182
• ⚡️ perf: improve chat workspace performance and plugin store ux #2499

数据结构改造

• agent store 与 session store 分离: [RFC] 043 - SessionStore 拆分 AgentStore #2199
• globalStore 和 userStore 分离 ：♻️ refactor: rename globalStore to userStore #2264

关键 PR

• 主 PR ✨ feat: support server db mode with Postgres / Drizzle ORM / tRPC #2556

[arvinxx]

试了下 Opus 似乎可以：

[arvinxx]

DB 接入实现思路

由于之前在 #378 完成了 client 端 DB 的改造，使之非常接近关系型数据库的结构。所以到今天这个节点来实现服务端数据库存储时，收益非常大。经过 #2038 这个 PR 的梳理，目前看下来只需要实现 6 个 services 的 server 端调用逻辑，即可完成服务端数据库方案的基础功能。像 store 那一层可以完全不用改。

不过由于目前 client 和 server 的 db 不是同一套，后续难免需要维护两套实现逻辑。所以在这次实现过程中，需要尽量统一并减少 service 层的接口数量，能复用尽量复用已有的方法。

此外，由于之前在 client DB 下并没有 user 层面的鉴权+ 查询逻辑，因此这部分逻辑应该是存在一定的改造量，可能需要和 #2022 一起考虑。

最后，虽说 store 那一层不改也能完成所有主链路，但是由于 sever 调用相比 client 要耗时很多，也存在各种请求出错的情况。因此也需要完善相应的错误处理的逻辑。

tRPC 接入

由于上述方案只需要改造 6个 service 的调用，肯定是尽可能希望类型统一，这样的话采用 tRPC 的方案应该是最为合适的。相当于是在 client 的 db 中使用直接使用 Model 调用 model 层方法，然后在 server 的 service 中通过 tPRC 调用 server model 的方法。

这样一来，两种不同模式的数据调用链路就是：

client 模式: store -> clientService -> ClientDBModel -> indexedDB

server 模式: store -> serverService -> trpcProduce -> ServerDBModel -> PostgresSQL

进展

• service 改造 ♻️ refactor: refactor the service interface #2062
• trpc 框架接入 🧱 chore: introduce trpc as network framework #2227

[arvinxx]

实施过程中发现，store完全不改是个很理想的情况。事实上在之前 client DB 请求响应非常敏捷的情况下，大量中间态都被忽略了。而换成 serverDB 后，网络请求的延迟变得不可忽略。因此需要对应适配服务端操作的逻辑，才能确保体验优良。因此拆解成若干子 PR 实施：

• 💄 style: improve aync session experience #2075
• ♻️ refactor: refactor for session server mode #2163

[arvinxx]

tRPC

高层次介绍 tRPC

tRPC 是一个为全栈 TypeScript 开发者设计的框架，它简化了前后端安全使用端点的过程。tRPC 允许你在客户端和服务器之间实现类型安全的通信，而不需要声明额外的类型，因为它从你的 TypeScript 代码中推断出类型信息。这种方法提供了与 REST 或 GraphQL 相比的一种类型安全的替代方案，特别是在使用 TypeScript 的项目中。

tRPC 的设计理念是基于插件化的，它支持高性能操作并且可以与多种现代 JavaScript 框架（如 Next.js 或 Remix）无缝集成。这使得 tRPC 在构建快速且类型安全的应用程序时显得非常有效。

最小启动用例

要在项目中启动 tRPC，你需要设置一个基本的 tRPC 应用程序，包括服务器和客户端配置。下面是一个最小的启动用例：

1. 安装 tRPC

   npm install @trpc/server @trpc/client react-query zod

2. 设置 tRPC 服务器

   创建一个简单的 tRPC 路由和服务器：

   // src/server/trpc/router/index.ts
   import { initTRPC } from '@trpc/server';
   import { z } from 'zod';
   
   const t = initTRPC.create();
   
   export const appRouter = t.router({
     hello: t.procedure.input(z.string().optional()).query(({ input }) => {
       return `Hello ${input ?? 'world'}`;
     }),
   });
   
   export type AppRouter = typeof appRouter;

   // src/server/index.ts
   import * as trpc from '@trpc/server';
   import { createHTTPServer } from '@trpc/server/adapters/standalone';
   import { appRouter } from './trpc/router';
   
   const server = createHTTPServer({
     router: appRouter,
     createContext: () => null,
   });
   
   server.listen(4000);

3. 设置 tRPC 客户端

   在客户端，配置 tRPC 客户端以连接到服务器：

   // src/client/utils/trpc.ts
   import { createTRPCClient } from '@trpc/client';
   import type { AppRouter } from '../../server/trpc/router';
   
   export const trpc = createTRPCClient<AppRouter>({
     url: 'http://localhost:4000',
   });

   使用 tRPC 客户端在组件中调用服务器端过程：

   // src/client/components/Hello.tsx
   import { trpc } from '../utils/trpc';
   
   function Hello() {
     const { data, isLoading } = trpc.useQuery(['hello', { input: 'TRPC User' }]);
     if (isLoading) return <div>Loading...</div>;
     return <div>{data}</div>;
   }
   
   export default Hello;

这个最小示例展示了如何设置一个简单的 tRPC 应用程序，包括服务器和客户端配置。通过这种方式，你可以在项目中快速地集成 tRPC，并开始构建类型安全的全栈应用程序。

什么是 procedure

在 tRPC 中，procedure 是一个非常核心的概念，它代表了一个可以被远程调用的函数或方法。这些 procedure 可以被定义为接收输入、进行处理，并返回结果的端点。在 tRPC 的架构中，procedure 通常用于定义 API 的具体操作，如获取数据、提交数据等。

特点

1. 类型安全：tRPC 的 procedure 允许你定义输入和输出的类型，确保了类型的一致性和安全性。这意味着在编译时就可以捕获可能的错误，提高了代码的稳定性和维护性。
2. 灵活性：你可以定义各种类型的 procedure，包括查询（query）、变更（mutation）、订阅（subscription）等，覆盖了大多数后端服务的需求。
3. 组合性：可以将多个 procedure 组合在一起，形成一个路由（router），这样可以更好地组织和管理 API。

使用方法

在 tRPC 中，创建一个 procedure 通常涉及几个步骤：

1. 定义 procedure：你需要指定 procedure 的输入和输出类型。可以使用像 zod 这样的库来定义这些类型，以增强类型校验和错误处理。
2. 实现逻辑：在 procedure 的实现中，你可以编写实际的业务逻辑，比如数据库操作、调用其他服务等。
3. 注册到路由：将定义好的 procedure 注册到一个 tRPC 路由，这样客户端就可以通过这个路由调用对应的 procedure。

示例代码

以下是一个简单的 procedure 示例，展示了如何在 tRPC 中创建和使用 procedure：

// 引入 tRPC 和 zod 库
import { initTRPC } from '@trpc/server';
import { z } from 'zod';

// 初始化 tRPC
const t = initTRPC.create();

// 定义一个 tRPC 路由
export const appRouter = t.router({
  // 定义一个名为 'hello' 的 procedure
  hello: t.procedure
    .input(z.string().optional())  // 输入类型定义
    .query(({ input }) => {        // 实现逻辑
      return `Hello ${input ?? 'world'}`;
    }),
});

// 导出路由类型
export type AppRouter = typeof appRouter;

在这个例子中，我们定义了一个名为 hello 的 procedure，它接受一个可选的字符串输入，并返回一个问候语。这个 procedure 被注册到了一个 tRPC 路由中，客户端可以通过这个路由调用 hello procedure。

总之，tRPC 中的 procedure 是实现服务器功能的基本单元，通过它可以构建出强大且类型安全的 API 接口。

[arvinxx]

trpc 的最佳实践

RPC 提供了一种高效、类型安全的方式来构建全栈应用程序，其最佳实践主要围绕如何充分利用其类型安全性、减少冗余代码、提高系统的可维护性和可扩展性。以下是一些使用 tRPC 的最佳实践：

1. 保持类型安全

由于 tRPC 的主要优势之一是类型安全，因此在开发过程中应始终保持输入、输出以及传输数据的类型定义清晰和准确。使用如 zod 这样的库来定义和验证数据模型可以进一步增强类型安全。

2. 合理组织路由和过程

将相关的 procedure 组织到同一个路由下，这有助于保持代码的清晰和模块化。例如，可以按照资源或功能模块来组织路由和过程，使得代码更易于管理和扩展。

3. 使用中间件进行权限验证和错误处理

tRPC 允许在路由和过程中使用中间件，这是处理身份验证、权限控制和错误处理的理想场所。通过中间件，可以在处理请求之前统一进行用户身份验证和权限检查，以及优雅地处理错误。

4. 优化客户端查询

利用 tRPC 客户端库和集成的数据查询库（如 React Query）优化数据加载和缓存策略。这可以减少网络请求，提升用户体验和应用性能。

5. 版本控制和向后兼容性

随着应用的发展，API 可能需要变更。在设计 API 时，应考虑到版本控制和向后兼容性，确保客户端在升级过程中能平滑过渡。

6. 利用类型推断

尽量利用 tRPC 提供的类型推断功能，减少手动定义类型的需要。这不仅可以减少代码量，还可以减少因手动类型定义错误导致的问题。

7. 单元测试和集成测试

编写单元测试和集成测试来验证 procedure 的功能和路由的行为。这有助于在开发过程中快速发现和修复错误，并确保应用的稳定性和可靠性。

8. 性能监控和优化

监控 tRPC 应用的性能，特别是响应时间和资源消耗。根据监控结果优化代码，例如通过减少不必要的数据处理、缓存常用数据等方法来提高性能。

9. 文档和示例

虽然 tRPC 是自描述的，但为开发人员提供额外的文档和使用示例仍然很重要。这有助于新团队成员更快地理解和使用 API。

通过遵循这些最佳实践，可以最大化地发挥 tRPC 在全栈 TypeScript 应用开发中的优势，构建出既强大又易于维护的系统。

[arvinxx]

路由组织最佳实践

在使用 tRPC 构建应用时，合理组织路由是关键因素之一，这不仅影响代码的可维护性，还影响开发效率和应用性能。以下是一些关于如何在 tRPC 中组织路由的最佳实践：

1. 按功能模块划分

将 API 划分为不同的模块或领域，每个模块对应一组功能相关的操作。例如，如果你的应用包含用户管理、产品管理和订单处理等功能，可以为每个功能创建一个单独的路由文件。

// 用户管理路由
const userRouter = t.router({
  getUser: t.procedure.query(...),
  createUser: t.procedure.mutation(...),
  deleteUser: t.procedure.mutation(...)
});

// 产品管理路由
const productRouter = t.router({
  getProduct: t.procedure.query(...),
  addProduct: t.procedure.mutation(...),
  updateProduct: t.procedure.mutation(...)
});

// 订单处理路由
const orderRouter = t.router({
  getOrder: t.procedure.query(...),
  placeOrder: t.procedure.mutation(...)
});

2. 使用路由嵌套

利用 tRPC 支持的路由嵌套功能来进一步组织和模块化代码。这允许你在一个主路由下嵌套多个子路由，使结构更加清晰。

const appRouter = t.router({
  users: userRouter,
  products: productRouter,
  orders: orderRouter
});

3. 遵循 RESTful 风格（可选）

尽管 tRPC 不是基于 REST，但遵循 RESTful 风格的命名和结构可以使 API 更加直观易懂。例如，使用动词（get, create, update, delete）来描述操作，使用名词（user, product, order）来表示资源。

4. 中间件的合理使用

在合适的层级使用中间件来处理跨路由的共通逻辑，如身份验证、日志记录、错误处理等。这样可以避免代码重复，同时确保所有相关请求都能通过必要的处理步骤。

const securedRouter = t.router({
  // Authorization middleware
}).merge('users.', userRouter)
  .merge('products.', productRouter)
  .merge('orders.', orderRouter);

5. 类型安全与代码复用

尽量复用类型定义和辅助函数，以减少重复代码并保持类型的一致性。例如，对于常见的请求和响应模型，可以定义共通的类型或使用工具类来生成响应。

6. 文档和注释

在路由和过程中添加必要的注释和文档，说明每个 API 的功能、输入输出和使用场景。这不仅有助于团队成员理解和维护代码，也方便自动生成 API 文档。

通过遵循这些最佳实践，你可以构建出结构清晰、易于维护且高效的 tRPC 应用程序。同时，这些实践还有助于提高团队的协作效率和代码的可扩展性。

[arvinxx]

Context

context 是一个关键的概念，用于在 tRPC （TypeScript RPC 框架）中管理和传递请求相关的信息。这里的 context 主要用于以下几个方面：

1. 请求级别的数据传递：context 可以包含任何与当前请求相关的数据，比如用户身份信息、会话信息等。这些信息可以在整个请求生命周期中被访问和修改。

2. 安全和认证：通过 context，可以在请求处理流程中加入用户认证和权限验证的逻辑。例如，可以在 context 中检查用户的登录状态或权限等级，并据此允许或拒绝对特定资源的访问。

3. 错误处理和日志记录：context 也可用于处理错误和进行日志记录。在处理请求时，可以在 context 中收集错误信息和重要的调试信息，然后在适当的时机进行处理或记录。

4. 依赖注入：在 tRPC 应用中，context 可用于依赖注入，即将一些必要的服务或者工具通过 context 传递给处理函数，使得这些函数可以在没有直接依赖关系的情况下使用这些服务或工具。

在代码中，context 是通过 createContext 和 createContextInner 函数来实现的。这些函数负责构建并返回一个 context 对象，该对象随后会被传递给 tRPC 的路由处理器。在 fetchRequestHandler 函数中，createContext 被指定为创建 context 的函数，这样每个请求都会有一个新的 context 实例，确保请求之间的数据隔离。

总之，context 在 tRPC 中充当了一个中心数据仓库的角色，用于在请求处理过程中安全地存储和传递数据。这样的设计使得 tRPC 应用可以更灵活和安全地处理各种请求。

[arvinxx]

这一层记录一些实践经验与笔记

[arvinxx]

遇到一个问题：怎么做好 ServerModel 的 测试 CI ？直连真实测试数据库的方案在跑单个用例的时候没问题，但是并发跑的时候似乎会有问题。

[linth2005]

可以说说具体是什么问题？

[arvinxx]

可以说说具体是什么问题？

比如多个测试文件同时连一个db，那么执行ci的时候就会出现并发插入同id 的数据造成冲突，或者一个测试在结束时清理了数据，把另一个测试文件的数据清理掉的情况

[linth2005]

这里的测试文件指的是什么？id是数据库自增的吗？如果是数据库的自增那我理解不会有这个问题吧。至于清理的话，就是自己做数据隔离的范畴了

[arvinxx]

这里的测试文件指的是什么

单元测试文件。

id是数据库自增的吗？如果是数据库的自增那我理解不会有这个问题吧。

不是，id 是我指定的。

[arvinxx]

DB PR 剩余相关改造：

User Store

• user store 改造 🐛 fix: refactor user store and fix custom model list form #2620
  • 去掉 serverConfig
  • model list 实现优化
  • StoreInitialization 改造（收敛重构所有初始化逻辑到一个地方）

Agent Store

• agent store 优化升级 ♻️ refactor: refactor agent store data #2690
  • inbox agent / default agent

数据结构迁移

• agent setting 数据迁移：🗃️ refactor: refactor the agent config to chat config #2646
• language model 重构，数据迁移（ endpoint -> baseURL ）： ♻️ refactor: refactor keyVaults and rename endpoint to baseURL #2673

Topic 数据优化

• Topic list 优化 ⚡️ perf: improve topic loading ux and performance #2609
• active Topic 优化

File 上传乐观更新

• File 上传逻辑的乐观更新: 💄 style: add optimistic loading for image uploading #2700

数据导入重构

• 将导入逻辑全部异步事务化，通过请求完成。

[arvinxx]

DB Schema 在版本升级过程中无感 migration

类似于前端 db ，我们需要一个服务端db无感升级的方案，这样可以确保在版本自动发布过程中，用户的 db schema 会自动升级到最新版

实现思路：

Drizzle ORM 提供了程序化迁移的方法，使用该方法，在每次 vercel build 之后，执行一次迁移。如果能正常通过，说明迁移成功，否则 db 的升级失败。

import * as dotenv from 'dotenv';
import * as migrator from 'drizzle-orm/neon-serverless/migrator';
import { join } from 'node:path';

import { serverDB } from '../../src/database/server/core/db';

// Read the `.env` file if it exists, or a file specified by the
// dotenv_config_path parameter that's passed to Node.js
dotenv.config();

const runMigrations = async () => {
  await migrator.migrate(serverDB, {
    migrationsFolder: join(__dirname, '../../src/database/server/migrations'),
  });
  console.log('✅ database migration pass.');
  // eslint-disable-next-line unicorn/no-process-exit
  process.exit(0);
};

let connectionString = process.env.DATABASE_URL;

// only migrate database if the connection string is available
if (connectionString) {
  // eslint-disable-next-line unicorn/prefer-top-level-await
  runMigrations().catch((err) => {
    console.error('❌ Database migrate failed:', err);
    // eslint-disable-next-line unicorn/no-process-exit
    process.exit(1);
  });
}

目前已经在线上实际测试，运行良好。

[arvinxx]

Github Action 集成数据库测试

database/model 目录下的实现都需要连接真实数据库进行测试，前面有提到，遇到了 vitest 并发导致数据库共用导致的错误。最终解决方案包含两部分。

1. vitest 本身支持采用顺序执行的方案，设定 singleThread = true 即可；

export default defineConfig({
  // ...
   poolOptions: {
      threads: { singleThread: true },
    },
})

2. 为了不拖慢其他测试的速度，并考虑到 server 和其他部分的 setup、执行环境都不太一样，因此将 server 部分单独提出来一个测试配置（ vitest.server.config.ts ）和测试脚本 test-server ，在 ci 中作为独立 step 执行；

3. Github Action 中配置 test.yml 集成 Postgres 服务：

jobs:
  test:
    runs-on: ubuntu-latest

    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_PASSWORD: postgres
        options: >-
          --health-cmd pg_isready --health-interval 10s --health-timeout 5s  --health-retries 5
        ports:
          - 5432:5432

4. 由于拆成了两个运行测试，但我希望覆盖率还是合并为一个，因此需要配置 codecov 做覆盖率合并。