尧图网站建设 
FastGPT 数据库操作规范解析MongoDBMongoose与 PostgreSQL 的 Schema 定义、查询与错误处理实战指南【免费下载链接】FastGPTFastGPT is a knowledge-based platform built on the LLMs, offers a comprehensive suite of out-of-the-box capabilities such as data processing, RAG retrieval, and visual AI workflow orchestration, letting you easily develop and deploy complex question-answering systems without the need for extensive setup or configuration.项目地址: https://gitcode.com/GitHub_Trending/fa/FastGPTFastGPT 是一个基于大语言模型的知识库平台其核心业务数据用户、团队、知识库、应用、对话记录与系统日志存储在 MongoDB 中并通过 Mongoose ODM 访问向量检索场景则交由 PostgreSQLpgvector承担。本文以仓库内 数据库操作规范文档 为骨架结合 MongoDB 公共封装、连接初始化、索引管理器 等源码实现系统讲解 FastGPT 数据库层的 Model 定义、查询操作与错误处理三大规范并给出可直接落地的 PR 审查检查清单。读完本文你将掌握 FastGPT 数据库层的统一写法、索引声明与生命周期管理机制、事务与慢查询治理手段能够据此审查或编写符合项目规范的数据库代码。一、FastGPT 的数据存储架构MongoDB 与 PostgreSQL 分工按照规范文档的定义FastGPT 的数据访问层由两套数据库组成数据库驱动/ODM职责MongoDBMongoose主业务库用户、团队、应用、知识库、对话、日志、各类配置PostgreSQLpgnode-postgres向量检索与全文检索等结构化查询通过pgvector扩展支撑MongoDB 侧的统一封装位于 packages/service/common/mongo/index.ts它导出mongoose、Schema、Types以及两个连接实例connectionMongo业务库与connectionLogMongo日志库默认复用业务库连接可通过MONGODB_LOG_URI单独指定并通过getMongoModel/getMongoLogModel统一注册 Model。值得注意的一点是规范文档中写明的模型目录packages/service/common/mongo/schema/在当前仓库中并不存在实际各领域 Schema 分散在对应模块目录下的schema.ts文件中例如packages/service/support/user/schema.ts用户packages/service/core/dataset/schema.ts知识库packages/service/core/chat/chatSchema.ts对话packages/service/common/system/log/schema.ts系统日志PostgreSQL 侧的连接池封装位于 packages/service/common/vectorDB/pg/controller.ts统一从PG_ADDRESS读取连接串。理解这两套存储的分工是后续所有规范的前提。二、Model 定义规范Schema 声明与敏感字段处理2.1 统一入口getMongoModel类型、中间件与索引同步规范的第一个审查要点是Schema 定义使用 TypeScript 泛型。FastGPT 并未直接使用mongoose.model()而是统一通过 getMongoModel 注册模型export const getMongoModel T(name: string, schema: mongoose.Schema): ModelT { if (connectionMongo.models[name]) return connectionMongo.models[name] as ModelT; addCommonMiddleware(schema); // 注入统一中间件 const model connectionMongo.model(name, schema) as ModelT; syncMongoIndex(model); // 注册后触发索引同步 return model; };该函数做了三件关键的事泛型绑定ModelT使查询结果具备完整的 TypeScript 类型推导配合packages/global下的类型定义如UserModelSchema、DatasetSchemaType编译期即可发现字段拼写错误。注入统一中间件addCommonMiddleware对find、save、create、update、delete、aggregate等操作统一计时超过 500ms 记 warn、超过 2000ms 记 slow query 日志同时在后置钩子中自动把查询结果里的ObjectId转为字符串避免上层到处手动toString()。这意味着任何新 Model 都自动获得慢查询观测能力无需重复编码。触发索引同步syncMongoIndex在非测试、非构建环境下调用MongoIndexManager.syncModelIndexes详见第五节。2.2 Schema 声明规范示例规范文档给出了一个基础示例合并真实仓库的写法后一个合规的 Schema 通常长这样import { getMongoModel, Schema, defineIndex } from fastgpt/service/common/mongo; const UserSchema new Schema({ username: { type: String, required: true, unique: true }, password: { type: String, required: true, select: false }, // 默认不查询 email: { type: String, required: true }, createdAt: { type: Date, default: Date.now } }); // 索引 defineIndex(UserSchema, { key: { username: 1 }, options: { unique: true } }); defineIndex(UserSchema, { key: { email: 1 } }); export const MongoUser getMongoModelUserModelSchema(users, UserSchema);审查时的检查点包括必要的字段添加索引查询频繁的字段如teamId createTime、chatId、username必须显式建索引防止全表扫描所有索引统一通过defineIndex声明而不是散落在迁移脚本中。敏感字段加密存储真实实现可见 用户 Schema 中的密码字段——它通过 Mongoose 的set/get钩子调用hashStrSHA-256 哈希实现位于 packages/global/common/string/tools.ts保证落库即哈希并设置select: false使默认查询不返回该字段对话 Schema 中的deleteTime软删除字段同样使用select: false隐藏。审查时重点确认凡是密钥、密码、令牌等敏感字段是否做到了默认不可见 单向哈希/加密。虚拟字段与实例方法Mongoose 支持UserSchema.virtual(fullName).get(...)派生字段和UserSchema.methods.xxx()实例方法可用于不落库的派生逻辑当前仓库的业务逻辑更多放在独立 service 函数中虚拟字段作为可选优化手段审查时关注其是否会造成隐式查询开销即可。2.3 枚举字段与废弃字段标记从真实 Schema 可以看到 FastGPT 的两个进阶惯例审查时可以一并检查枚举字段使用enum约束如知识库 Schema 中的type字段用enum: Object.keys(DatasetTypeMap)限定合法取值日志 Schema 用enum: Object.values(LogLevelEnum)限定日志级别从数据库层杜绝非法值写入。废弃字段显式标记deprecated的 JSDoc 注释 保留字段定义如 知识库 Schema 中的externalReadUrl、apiServer、feishuServer而不是直接删除字段导致旧数据读取失败——这保证了向后兼容是数据库 Schema 变更审查回归风险检测的关键依据。三、查询操作规范投影、分页与 N1 治理3.1 文档给出的查询基线规范文档对查询操作提出五项要求使用参数化查询防止注入、避免 N1 查询、使用 projection 只查询需要的字段、大结果集使用分页、异步操作有错误处理并给出反例与正例// ❌ 不好的实践 const users await User.find({}).toArray(); // 可能返回大量数据 // ✅ 好的实践 const users await User.find({}) .project({ username: 1, email: 1 }) // 只查询需要的字段 .limit(20) // 限制结果数量 .skip(page * 20) .toArray();在 Mongoose 语境下等价写法是链式.select({ username: 1, email: 1 }).limit(20).skip(page * 20)。审查时关注三点一是是否有未加投影的全文档查询select: false字段会被投影机制天然排除二是分页是否使用limit skip之外更优的方案——对深度分页场景FastGPT 倾向于基于游标cursor或_id/时间戳锚点翻页避免大偏移量下的性能退化可在 全文迁移日志 Schema 中看到cursor字段的使用痕迹三是聚合查询场景aggregate同样被统一中间件覆盖慢查询监控。3.2 避免 N1批量与冗余字段FastGPT 在 Schema 层面直接做了反 N1 设计审查时可以对照冗余计数字段如 对话 Schema 中的hasGoodFeedback、hasBadFeedback、errorCount等布尔/计数冗余字段注释明确写着 redundant fields for performance把高频统计从聚合查询降级为单字段读取。批量写入优先Mongoose 的bulkWrite/insertMany被统一中间件显式纳入监控适合批量 upsert 场景审查时应检查循环内单条写入的写法并建议改为批量操作。3.3 慢查询的可观测性addCommonMiddleware中schema.pre/post钩子会记录collectionName、op、query/pipeline/update等上下文信息并经LogCategories.INFRA.MONGO分类器输出。审查数据库相关代码时应确认新查询路径没有被绕过这套中间件例如直接使用原生 driver 而非getMongoModel注册的 Model否则会失去慢查询告警保护。四、错误处理规范重复键、连接异常与日志上下文4.1 数据库操作必须 try-catch规范要求所有数据库操作包在 try-catch 中并处理三类典型错误重复键错误、连接错误、以及带上下文信息的日志。4.2 重复键错误code 11000的两种处理范式范式一捕获并转化为业务语义。MongoDB 唯一索引冲突会抛出code: 11000的MongoServerErrorFastGPT 在 S3 访问链接下载别名模块 中通过工具函数显式判断!!error typeof error object code in error error.code 11000;审查时关注唯一键冲突是否被正确识别而不是被当作 500 内部错误抛出且错误信息应包含冲突的业务含义如用户名已存在。范式二用部分唯一索引在数据库层兜底并发。全文迁移日志 Schema 给出了一个教科书式的例子通过partialFilterExpression: { status: running }建立部分唯一索引保证同一引擎同时只有一个 running 迁移第二个并发create命中唯一索引后转化为明确的已在运行错误而不是靠应用层锁。这是结合索引设计处理 11000 的高阶实践。4.3 连接错误与自动重连连接初始化实现 展示了完整的连接治理策略移除旧监听器防重复注册对error、connected、disconnected事件分别记录不同级别的日志连接失败后disconnect→delay(1000)→ 递归重连避免一次性失败导致服务不可用设置strictQuery: throw让查询条件中未在 Schema 声明的字段直接抛错在开发期暴露拼写错误关键超时参数齐备connectTimeoutMS/waitQueueTimeoutMS/socketTimeoutMS均为 60sserverSelectionTimeoutMS10smaxPoolSize与maxConnecting由DB_MAX_LINK统一控制heartbeatFrequencyMS5s 做健康检查。审查连接相关改动时检查这些超时与重试参数是否被保留即可。日志侧错误日志必须携带上下文——统一中间件已经把collectionName、query、duration等写进日志载荷手写数据库代码时也应遵循同样的上下文规范相关分类见 日志分类定义。五、纵深索引生命周期管理与 Mongo 事务5.1defineIndex与废弃索引清理规范要求必要的字段添加索引而 FastGPT 把索引声明提升到了生命周期管理的层面。索引声明入口是 schemaIndexes.ts 中的defineIndexdeprecated默认false时直接代理Schema.index()显式传deprecated: true时只登记清理元数据、不写入 Schema否则启动同步会重新创建该索引。索引的实际执行由 MongoIndexManager 完成每个 Model 注册时固定执行安全同步inspectModelIndexes通过model.diffIndexes()计算 Schema 与数据库的差异只记录不删除Schema 外未知索引以保护客户自建索引model.createIndexes({ background: true })后台补建当前索引cleanupModelDeprecatedIndexes清理该 Schema 明确登记且name key 均匹配的废弃索引key 不匹配skip_mismatch、索引不存在skip_missing或出现错误error都安全跳过并记录报告text 索引则兼容_fts/_ftsx形态差异后按字段集合比较。审查数据库相关 PR 时若涉及索引变更应要求新增索引用defineIndex声明并评估对写入性能的影响删除索引必须登记为deprecated: true走安全清理而不是在数据库控制台手工 drop。5.2 事务与会话mongoSessionRun多文档写入需要事务保护时FastGPT 提供了 mongoSessionRun 统一封装内部调用session.withTransaction()并交给 MongoDB driver 处理TransientTransactionError级重试和UnknownTransactionCommitResult针对 ACL 增量写入中的并发冲突抛出MongoTransactionConflictError后最多重试 3 次maxCommitTimeMS设为 60s。审查时注意跨集合的一致性与权限ACL写入都应通过mongoSessionRun包一层事务而不是裸用 session。六、PostgreSQLpg侧的配套规范虽然规范文档的示例集中在 Mongo/Mongoose但 FastGPT 的 PostgreSQL 向量库同样有既定规范体现在 pg 连接池封装 中连接池参数max由DB_MAX_LINK统一控制min为其 50%keepAlive: trueidleTimeoutMillis30 分钟以减少频繁重连超时分层connectionTimeoutMillis30s、query_timeout60s、statement_timeout90s、idle_in_transaction_session_timeout60s保证慢 SQL 不会无限占用连接可观测性application_name: fastgpt-vector-db便于数据库监控识别来源pool 的error/connect/remove事件均有日志失败重连连接失败时清理监听器、结束池、延迟 1s 后递归重连。与 Mongo 侧的规范一致pg 查询必须使用参数化查询$1、$2占位符防止 SQL 注入审查 vectorDB 各引擎 controllerpg、oceanbase、opengauss等时重点检查是否存在字符串拼接 SQL 以及是否复用了统一连接池。七、可复用的数据库 PR 审查检查清单综合规范文档与源码实现可将 FastGPT 数据库操作规范的审查要点收敛为以下清单直接用于 PR 审查对应 PR Review 技能 第四阶段的数据库检查项Model 定义Schema 通过getMongoModelT注册携带类型泛型高频查询字段使用defineIndex声明索引含复合索引与排序方向敏感字段密码/密钥单向哈希或加密并设置select: false枚举字段使用enum约束废弃字段保留并用deprecated标注索引变更遵循生命周期管理新增用defineIndex删除登记deprecated: true查询操作只查询需要的字段projection/select避免全文档返回大结果集分页深度分页优先游标方案无 N1批量操作使用bulkWrite/insertMany高频统计走冗余字段pg 查询使用参数化占位符杜绝 SQL 拼接查询路径未被绕过统一中间件保持慢查询可观测错误处理数据库操作包裹 try-catch重复键错误code 11000被识别并转化为业务语义连接错误有重试与日志参考connectMongo的重连策略错误日志包含集合名、查询条件、耗时等上下文跨集合一致性写入通过mongoSessionRun事务保护这套规范既是代码风格约束也是 FastGPT 数据库层稳定性索引同步、慢查询治理、事务重试、软删除兼容的设计映射。对照 数据库操作规范文档 与实际源码逐项检查即可在审查中快速定位数据库层面的风险点。【免费下载链接】FastGPTFastGPT is a knowledge-based platform built on the LLMs, offers a comprehensive suite of out-of-the-box capabilities such as data processing, RAG retrieval, and visual AI workflow orchestration, letting you easily develop and deploy complex question-answering systems without the need for extensive setup or configuration.项目地址: https://gitcode.com/GitHub_Trending/fa/FastGPT创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 FastGPT 数据库操作规范解析：MongoDB（Mongoose）与 PostgreSQL 的 Schema 定义、查询与错误处理实战指南
FastGPT 数据库操作规范解析MongoDBMongoose与 PostgreSQL 的 Schema 定义、查询与错误处理实战指南【免费下载链接】FastGPTFastGPT is a knowledge-based platform built on the LLMs, offers a comprehensive suite of out-of-the-box capabilities such as data processing, RAG retrieval, and visual AI workflow orchestration, letting you easily develop and deploy complex question-answering systems without the need for extensive setup or configuration.项目地址: https://gitcode.com/GitHub_Trending/fa/FastGPTFastGPT 是一个基于大语言模型的知识库平台其核心业务数据用户、团队、知识库、应用、对话记录与系统日志存储在 MongoDB 中并通过 Mongoose ODM 访问向量检索场景则交由 PostgreSQLpgvector承担。本文以仓库内 数据库操作规范文档 为骨架结合 MongoDB 公共封装、连接初始化、索引管理器 等源码实现系统讲解 FastGPT 数据库层的 Model 定义、查询操作与错误处理三大规范并给出可直接落地的 PR 审查检查清单。读完本文你将掌握 FastGPT 数据库层的统一写法、索引声明与生命周期管理机制、事务与慢查询治理手段能够据此审查或编写符合项目规范的数据库代码。一、FastGPT 的数据存储架构MongoDB 与 PostgreSQL 分工按照规范文档的定义FastGPT 的数据访问层由两套数据库组成数据库驱动/ODM职责MongoDBMongoose主业务库用户、团队、应用、知识库、对话、日志、各类配置PostgreSQLpgnode-postgres向量检索与全文检索等结构化查询通过pgvector扩展支撑MongoDB 侧的统一封装位于 packages/service/common/mongo/index.ts它导出mongoose、Schema、Types以及两个连接实例connectionMongo业务库与connectionLogMongo日志库默认复用业务库连接可通过MONGODB_LOG_URI单独指定并通过getMongoModel/getMongoLogModel统一注册 Model。值得注意的一点是规范文档中写明的模型目录packages/service/common/mongo/schema/在当前仓库中并不存在实际各领域 Schema 分散在对应模块目录下的schema.ts文件中例如packages/service/support/user/schema.ts用户packages/service/core/dataset/schema.ts知识库packages/service/core/chat/chatSchema.ts对话packages/service/common/system/log/schema.ts系统日志PostgreSQL 侧的连接池封装位于 packages/service/common/vectorDB/pg/controller.ts统一从PG_ADDRESS读取连接串。理解这两套存储的分工是后续所有规范的前提。二、Model 定义规范Schema 声明与敏感字段处理2.1 统一入口getMongoModel类型、中间件与索引同步规范的第一个审查要点是Schema 定义使用 TypeScript 泛型。FastGPT 并未直接使用mongoose.model()而是统一通过 getMongoModel 注册模型export const getMongoModel T(name: string, schema: mongoose.Schema): ModelT { if (connectionMongo.models[name]) return connectionMongo.models[name] as ModelT; addCommonMiddleware(schema); // 注入统一中间件 const model connectionMongo.model(name, schema) as ModelT; syncMongoIndex(model); // 注册后触发索引同步 return model; };该函数做了三件关键的事泛型绑定ModelT使查询结果具备完整的 TypeScript 类型推导配合packages/global下的类型定义如UserModelSchema、DatasetSchemaType编译期即可发现字段拼写错误。注入统一中间件addCommonMiddleware对find、save、create、update、delete、aggregate等操作统一计时超过 500ms 记 warn、超过 2000ms 记 slow query 日志同时在后置钩子中自动把查询结果里的ObjectId转为字符串避免上层到处手动toString()。这意味着任何新 Model 都自动获得慢查询观测能力无需重复编码。触发索引同步syncMongoIndex在非测试、非构建环境下调用MongoIndexManager.syncModelIndexes详见第五节。2.2 Schema 声明规范示例规范文档给出了一个基础示例合并真实仓库的写法后一个合规的 Schema 通常长这样import { getMongoModel, Schema, defineIndex } from fastgpt/service/common/mongo; const UserSchema new Schema({ username: { type: String, required: true, unique: true }, password: { type: String, required: true, select: false }, // 默认不查询 email: { type: String, required: true }, createdAt: { type: Date, default: Date.now } }); // 索引 defineIndex(UserSchema, { key: { username: 1 }, options: { unique: true } }); defineIndex(UserSchema, { key: { email: 1 } }); export const MongoUser getMongoModelUserModelSchema(users, UserSchema);审查时的检查点包括必要的字段添加索引查询频繁的字段如teamId createTime、chatId、username必须显式建索引防止全表扫描所有索引统一通过defineIndex声明而不是散落在迁移脚本中。敏感字段加密存储真实实现可见 用户 Schema 中的密码字段——它通过 Mongoose 的set/get钩子调用hashStrSHA-256 哈希实现位于 packages/global/common/string/tools.ts保证落库即哈希并设置select: false使默认查询不返回该字段对话 Schema 中的deleteTime软删除字段同样使用select: false隐藏。审查时重点确认凡是密钥、密码、令牌等敏感字段是否做到了默认不可见 单向哈希/加密。虚拟字段与实例方法Mongoose 支持UserSchema.virtual(fullName).get(...)派生字段和UserSchema.methods.xxx()实例方法可用于不落库的派生逻辑当前仓库的业务逻辑更多放在独立 service 函数中虚拟字段作为可选优化手段审查时关注其是否会造成隐式查询开销即可。2.3 枚举字段与废弃字段标记从真实 Schema 可以看到 FastGPT 的两个进阶惯例审查时可以一并检查枚举字段使用enum约束如知识库 Schema 中的type字段用enum: Object.keys(DatasetTypeMap)限定合法取值日志 Schema 用enum: Object.values(LogLevelEnum)限定日志级别从数据库层杜绝非法值写入。废弃字段显式标记deprecated的 JSDoc 注释 保留字段定义如 知识库 Schema 中的externalReadUrl、apiServer、feishuServer而不是直接删除字段导致旧数据读取失败——这保证了向后兼容是数据库 Schema 变更审查回归风险检测的关键依据。三、查询操作规范投影、分页与 N1 治理3.1 文档给出的查询基线规范文档对查询操作提出五项要求使用参数化查询防止注入、避免 N1 查询、使用 projection 只查询需要的字段、大结果集使用分页、异步操作有错误处理并给出反例与正例// ❌ 不好的实践 const users await User.find({}).toArray(); // 可能返回大量数据 // ✅ 好的实践 const users await User.find({}) .project({ username: 1, email: 1 }) // 只查询需要的字段 .limit(20) // 限制结果数量 .skip(page * 20) .toArray();在 Mongoose 语境下等价写法是链式.select({ username: 1, email: 1 }).limit(20).skip(page * 20)。审查时关注三点一是是否有未加投影的全文档查询select: false字段会被投影机制天然排除二是分页是否使用limit skip之外更优的方案——对深度分页场景FastGPT 倾向于基于游标cursor或_id/时间戳锚点翻页避免大偏移量下的性能退化可在 全文迁移日志 Schema 中看到cursor字段的使用痕迹三是聚合查询场景aggregate同样被统一中间件覆盖慢查询监控。3.2 避免 N1批量与冗余字段FastGPT 在 Schema 层面直接做了反 N1 设计审查时可以对照冗余计数字段如 对话 Schema 中的hasGoodFeedback、hasBadFeedback、errorCount等布尔/计数冗余字段注释明确写着 redundant fields for performance把高频统计从聚合查询降级为单字段读取。批量写入优先Mongoose 的bulkWrite/insertMany被统一中间件显式纳入监控适合批量 upsert 场景审查时应检查循环内单条写入的写法并建议改为批量操作。3.3 慢查询的可观测性addCommonMiddleware中schema.pre/post钩子会记录collectionName、op、query/pipeline/update等上下文信息并经LogCategories.INFRA.MONGO分类器输出。审查数据库相关代码时应确认新查询路径没有被绕过这套中间件例如直接使用原生 driver 而非getMongoModel注册的 Model否则会失去慢查询告警保护。四、错误处理规范重复键、连接异常与日志上下文4.1 数据库操作必须 try-catch规范要求所有数据库操作包在 try-catch 中并处理三类典型错误重复键错误、连接错误、以及带上下文信息的日志。4.2 重复键错误code 11000的两种处理范式范式一捕获并转化为业务语义。MongoDB 唯一索引冲突会抛出code: 11000的MongoServerErrorFastGPT 在 S3 访问链接下载别名模块 中通过工具函数显式判断!!error typeof error object code in error error.code 11000;审查时关注唯一键冲突是否被正确识别而不是被当作 500 内部错误抛出且错误信息应包含冲突的业务含义如用户名已存在。范式二用部分唯一索引在数据库层兜底并发。全文迁移日志 Schema 给出了一个教科书式的例子通过partialFilterExpression: { status: running }建立部分唯一索引保证同一引擎同时只有一个 running 迁移第二个并发create命中唯一索引后转化为明确的已在运行错误而不是靠应用层锁。这是结合索引设计处理 11000 的高阶实践。4.3 连接错误与自动重连连接初始化实现 展示了完整的连接治理策略移除旧监听器防重复注册对error、connected、disconnected事件分别记录不同级别的日志连接失败后disconnect→delay(1000)→ 递归重连避免一次性失败导致服务不可用设置strictQuery: throw让查询条件中未在 Schema 声明的字段直接抛错在开发期暴露拼写错误关键超时参数齐备connectTimeoutMS/waitQueueTimeoutMS/socketTimeoutMS均为 60sserverSelectionTimeoutMS10smaxPoolSize与maxConnecting由DB_MAX_LINK统一控制heartbeatFrequencyMS5s 做健康检查。审查连接相关改动时检查这些超时与重试参数是否被保留即可。日志侧错误日志必须携带上下文——统一中间件已经把collectionName、query、duration等写进日志载荷手写数据库代码时也应遵循同样的上下文规范相关分类见 日志分类定义。五、纵深索引生命周期管理与 Mongo 事务5.1defineIndex与废弃索引清理规范要求必要的字段添加索引而 FastGPT 把索引声明提升到了生命周期管理的层面。索引声明入口是 schemaIndexes.ts 中的defineIndexdeprecated默认false时直接代理Schema.index()显式传deprecated: true时只登记清理元数据、不写入 Schema否则启动同步会重新创建该索引。索引的实际执行由 MongoIndexManager 完成每个 Model 注册时固定执行安全同步inspectModelIndexes通过model.diffIndexes()计算 Schema 与数据库的差异只记录不删除Schema 外未知索引以保护客户自建索引model.createIndexes({ background: true })后台补建当前索引cleanupModelDeprecatedIndexes清理该 Schema 明确登记且name key 均匹配的废弃索引key 不匹配skip_mismatch、索引不存在skip_missing或出现错误error都安全跳过并记录报告text 索引则兼容_fts/_ftsx形态差异后按字段集合比较。审查数据库相关 PR 时若涉及索引变更应要求新增索引用defineIndex声明并评估对写入性能的影响删除索引必须登记为deprecated: true走安全清理而不是在数据库控制台手工 drop。5.2 事务与会话mongoSessionRun多文档写入需要事务保护时FastGPT 提供了 mongoSessionRun 统一封装内部调用session.withTransaction()并交给 MongoDB driver 处理TransientTransactionError级重试和UnknownTransactionCommitResult针对 ACL 增量写入中的并发冲突抛出MongoTransactionConflictError后最多重试 3 次maxCommitTimeMS设为 60s。审查时注意跨集合的一致性与权限ACL写入都应通过mongoSessionRun包一层事务而不是裸用 session。六、PostgreSQLpg侧的配套规范虽然规范文档的示例集中在 Mongo/Mongoose但 FastGPT 的 PostgreSQL 向量库同样有既定规范体现在 pg 连接池封装 中连接池参数max由DB_MAX_LINK统一控制min为其 50%keepAlive: trueidleTimeoutMillis30 分钟以减少频繁重连超时分层connectionTimeoutMillis30s、query_timeout60s、statement_timeout90s、idle_in_transaction_session_timeout60s保证慢 SQL 不会无限占用连接可观测性application_name: fastgpt-vector-db便于数据库监控识别来源pool 的error/connect/remove事件均有日志失败重连连接失败时清理监听器、结束池、延迟 1s 后递归重连。与 Mongo 侧的规范一致pg 查询必须使用参数化查询$1、$2占位符防止 SQL 注入审查 vectorDB 各引擎 controllerpg、oceanbase、opengauss等时重点检查是否存在字符串拼接 SQL 以及是否复用了统一连接池。七、可复用的数据库 PR 审查检查清单综合规范文档与源码实现可将 FastGPT 数据库操作规范的审查要点收敛为以下清单直接用于 PR 审查对应 PR Review 技能 第四阶段的数据库检查项Model 定义Schema 通过getMongoModelT注册携带类型泛型高频查询字段使用defineIndex声明索引含复合索引与排序方向敏感字段密码/密钥单向哈希或加密并设置select: false枚举字段使用enum约束废弃字段保留并用deprecated标注索引变更遵循生命周期管理新增用defineIndex删除登记deprecated: true查询操作只查询需要的字段projection/select避免全文档返回大结果集分页深度分页优先游标方案无 N1批量操作使用bulkWrite/insertMany高频统计走冗余字段pg 查询使用参数化占位符杜绝 SQL 拼接查询路径未被绕过统一中间件保持慢查询可观测错误处理数据库操作包裹 try-catch重复键错误code 11000被识别并转化为业务语义连接错误有重试与日志参考connectMongo的重连策略错误日志包含集合名、查询条件、耗时等上下文跨集合一致性写入通过mongoSessionRun事务保护这套规范既是代码风格约束也是 FastGPT 数据库层稳定性索引同步、慢查询治理、事务重试、软删除兼容的设计映射。对照 数据库操作规范文档 与实际源码逐项检查即可在审查中快速定位数据库层面的风险点。【免费下载链接】FastGPTFastGPT is a knowledge-based platform built on the LLMs, offers a comprehensive suite of out-of-the-box capabilities such as data processing, RAG retrieval, and visual AI workflow orchestration, letting you easily develop and deploy complex question-answering systems without the need for extensive setup or configuration.项目地址: https://gitcode.com/GitHub_Trending/fa/FastGPT创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考