企业官网建设流程全解析

NocoBase 主数据库（Main Data Source）完全指南：系统表存储、数据源管理、表结构与字段同步机制解析

【免费下载链接】nocobaseNocoBase is an open-source AI + no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase

导读

NocoBase 是一款开源的 AI + 无代码业务系统构建平台，其"主数据库（Main Data Source）"是部署时配置的核心数据库，既承载系统表数据，也支持存储用户业务数据。本文基于当前仓库中的 主数据库官方文档 与 plugin-data-source-main 插件源码 展开，系统讲解主数据库的数据库兼容矩阵、插件安装方式、数据表管理能力、已有表同步、多类型表结构与字段级同步机制，并结合MainDataSource、DatabaseIntrospector等源码揭示底层实现原理，帮助你完整掌握 NocoBase 主数据源的管理与二次开发要点。

主数据库是什么

在 安装部署 NocoBase 时配置的数据库，即为 NocoBase 的主数据库。它承担两类职责：

• 存储 NocoBase 的系统表数据：如collections（数据表元信息）、fields（字段元信息）、collectionCategories（表分类）等，这些元数据驱动着整个平台的建模与界面渲染；
• 支持存储用户业务表数据：用户通过界面创建的业务数据表同样落在主数据库中，与系统表共存。

主数据库默认以固定 keymain注册。在 插件安装逻辑 中可以看到，install()会在dataSources表中firstOrCreate一条key: 'main'、type: 'main'、fixed: true的记录，fixed: true表示该数据源不可被移除，是平台的常驻数据源。

支持的数据库版本与商业版本

提示：KingbaseES 只支持 PostgreSQL 兼容模式，OceanBase 只支持 MySQL 兼容模式。

也就是说，社区版开箱即用支持 MySQL、PostgreSQL、MariaDB 三大主流数据库；KingbaseES（人大金仓）需要专业版及以上授权，OceanBase 需要企业版授权。

插件安装

不同数据库对应不同的接入插件，安装方式如下：

MySQL、PostgreSQL、MariaDB 作为内置能力直接可用；而 KingbaseES、OceanBase 以独立插件形式存在（仓库中可通过plugin-data-source-kingbase、plugin-data-source-oceanbase命名检索确认），依赖商业授权，安装后默认启用。

访问主数据源

在界面上访问主数据库的操作路径为：

1. 点击系统功能中的数据源菜单，进入数据源主页；
2. 在数据源列表中选择Main数据源，点击配置操作，即可进入主数据库管理界面。

主数据源的核心管理入口对应源码中的mainDataSource资源（见 resourcers/main-data-source.ts），它暴露了两个关键动作：

• refresh：当主数据源处于loaded状态时，重新加载全部自定义集合（loadCollections）；
• syncFields：调用mainDataSource.syncFieldsFromDatabase(ctx, collections)将数据库中的字段结构同步进 NocoBase 管理模型。

主数据源管理

主数据库提供完整的数据表管理能力，支持检索、创建、变更、删除数据表，也支持同步数据库中已有数据表的字段；同时支持数据表字段的创建、变更与删除。具体操作项包括：

• 筛选：检索 NocoBase 主数据库管理的数据表；
• 创建数据表：新增业务数据表；
• 编辑：变更业务数据表；
• 删除：删除业务数据表；
• 从数据库同步：同步数据库中已有数据表的结构；
• 配置字段：数据表字段的创建、变更、删除；
• ＋：tab 页的＋用于对数据表进行分类管理，支持分类的创建、变更与删除。

从源码看元数据存储模型

主数据库管理的"数据表"本质上是元数据记录。在 collections 集合定义 中可以看到collections表的字段设计：key（UID 主键）、name（唯一、带t_前缀）、title（可翻译标题）、inherit（是否继承表）、hidden、options（JSON 扩展配置）、description，以及fields（一对多）与category（多对多关联分类）两个关系字段。理解这张元数据表，有助于理解为什么 NocoBase 能做到"界面改表结构、底层自动 DDL"——所有变更都围绕collections/fields元数据驱动，再通过 server.ts 中注册的大量beforeCreate/afterSave/beforeDestroy钩子同步执行数据库迁移（model.migrate()、collection.sync()）与集群消息广播（sendSyncMessage）。

从数据库同步已有表

主数据源的一个重要特性是：可以将数据库中已经存在的表同步到 NocoBase 中进行管理。这意味着：

• 保护现有投资：如果数据库中已有大量业务表，无需重新创建，可直接同步使用；
• 灵活集成：可以将通过其他工具（如 SQL 脚本、数据库管理工具等）创建的表纳入 NocoBase 管理；
• 渐进式迁移：支持逐步将现有系统迁移到 NocoBase，而不是一次性重构。

通过「从数据库加载」功能，你可以：

1. 浏览数据库中所有的表；
2. 选择需要同步的表；
3. 自动识别表结构和字段类型；
4. 一键导入到 NocoBase 中进行管理。

底层实现：MainDataSource 与 DatabaseIntrospector

「从数据库加载」在源码层面对应MainDataSource的一组方法（见 main-data-source.ts）：

• readTables()：调用introspector.getTableList()获取数据库全部物理表，与已管理的集合（existsCollections）做差集，返回尚未纳管的表列表；
• tables2Collections()：对每个表调用introspector.getCollection({ tableInfo })，生成对应的CollectionOptions（含推断出的字段定义）；
• loadTables(ctx, tables)：将tables2Collections的结果批量写入collections仓库，并标记from: 'dbsync'，代表这批表来自数据库同步而非界面新建。

类型推断的核心引擎是 DatabaseIntrospector：

• getTableList()/getViewList()分别通过 Sequelize 的showAllTables()与listViews()枚举物理表与视图；
• columnInfoToFieldOptions()将数据库列描述（类型、可空、主键、自增、唯一索引、注释等）转换为 NocoBase 字段选项；
• inferFieldTypeByRawType()依据fieldTypeMap[sequelize.getDialect()]（按方言区分的原始类型映射表）将数据库类型映射为 NocoBase 字段类型；
• 无法识别的类型会被标记为supported: false并归入unsupportedFields，通过日志记录，不影响其余字段的同步；
• getDefaultInterfaceByType()再结合 type-interface-map.ts 为字段类型赋予默认的界面组件配置（如json类型默认使用Input.JSON组件、date默认使用DatePicker）。

此外，DatabaseIntrospector会从表结构自动推导集合配置：识别自增字段/主键/唯一字段作为filterTargetKey，多列主键则生成数组，并将timestamps、autoGenId置为false，保证同步来的表不被 NocoBase 额外篡改结构。

支持多种表结构类型

NocoBase 支持创建和管理多种类型的数据表：

• 普通表：内置了常用的系统字段；
• 继承表：可以创建一个父表，然后从该父表派生出子表，子表会继承父表的结构，同时还可以定义自己的列；
• 树表：树结构表，目前只支持邻接表设计；
• 日历表：用于创建日历相关的事件表；
• 文件表：用于文件存储的管理；
• SQL 表：并不是实际的数据库表，而是将 SQL 查询快速、结构化地展示出来；
• 视图表：连接已有的数据库视图。

这些表类型在仓库中均有对应插件支撑，例如plugin-collection-tree（树表）、plugin-collection-sql（SQL 表）、plugin-calendar（日历表）、plugin-file-manager（文件表）等，可结合 数据源插件目录 进一步查阅。其中继承表在元数据层通过collections表的inherit字段标记，插件中InheritedCollection、inheritanceMap等机制负责父子表字段的继承与联动（如删除父表字段时清理子表 override 字段，见 server.ts）。

支持数据表的分类管理

通过 tab 页的＋操作，可以为数据表创建分类，并支持分类的创建、变更与删除，实现数据表的分组管理。底层对应collectionCategories元数据表，collections通过belongsToMany关系关联分类（through: 'collectionCategory'，见 collections.ts），相关操作均有服务端测试覆盖（见 collection-categories.test.ts）。

提供了丰富的字段类型

主数据库支持丰富的字段类型，覆盖文本、数值、日期时间、关系、JSON、文件、计算、加密等场景。字段的"类型"与"界面组件（interface）"解耦：数据库底层存储类型不变，界面表现可自由切换。

灵活的字段类型转换

NocoBase 支持在同种数据库类型基础上进行灵活的字段类型转换。

示例：String 类型字段的转换选项

当数据库中的字段是 String 类型时，可以在 NocoBase 中转换为以下任意形式：

• 基础类型：单行文本、多行文本、手机号码、电子邮箱、URL、密码、颜色、图标；
• 选择类型：下拉菜单（单选）、单选框；
• 富媒体类型：Markdown、Markdown (Vditor)、富文本、附件（URL）；
• 日期时间类型：日期时间（含时区）、日期时间（不含时区）；
• 高级类型：自动编码、数据表选择器、加密。

这种灵活的转换机制意味着：

• 无需修改数据库结构：字段的底层存储类型保持不变，只是在 NocoBase 中的表现形式发生改变；
• 适应业务变化：随着业务需求的变化，可以快速调整字段的展示和交互方式；
• 数据安全：转换过程不会影响已有数据的完整性。

从实现看，同步/查询字段时，服务端会通过possibleTypes（由fieldTypeMap按方言映射得到的可选类型列表）约束转换范围，只有底层原始类型兼容的转换才被允许（见 server.ts 中extractTypeFromDefinition+fieldTypes[mappedType]的逻辑）。

字段级别的灵活同步

NocoBase 不仅可以同步整个表，还支持字段级别的精细化同步管理：

字段同步的特点：

1. 实时同步：当数据库表结构发生变化时，可以随时同步新增的字段；
2. 选择性同步：可以选择性地同步需要的字段，而不是全部字段；
3. 类型自动识别：自动识别数据库字段类型并映射到 NocoBase 的字段类型；
4. 保持数据完整性：同步过程不会影响已有数据。

使用场景：

• 数据库结构演进：当业务需求变化，需要在数据库中添加新字段时，可以快速同步到 NocoBase；
• 团队协作：当其他团队成员或 DBA 在数据库中添加了字段，可以及时同步；
• 混合管理模式：部分字段通过 NocoBase 管理，部分字段通过传统方式管理，灵活组合。

字段级同步的源码实现

字段级同步对应MainDataSource.syncFieldsFromDatabase(ctx, collectionNames?)（见 main-data-source.ts）：

1. 根据传入的集合名（可选）过滤出已加载的集合及其字段（含物理列名columnName）；
2. 通过 introspection 重新获取这些表的当前字段结构；
3. mergeWithLoadedCollections合并新旧结构，找出已被删除的字段；
4. 在数据库事务中：先fields仓库销毁已删除字段，再collections仓库update更新字段列表（updateAssociationValues: ['fields']）；
5. 同步过程中对schema === 'public'的默认 schema 做归一化处理，避免跨 schema 差异。

对应地，mainDataSource资源的syncFields动作会在主数据源loaded状态下触发该流程；而插件在集群场景下还会通过sendSyncMessage广播syncCollection/removeField/removeCollection消息，保证多节点结构一致（见 server.ts）。

小结

主数据库是 NocoBase 的根基：社区版即可使用 MySQL、PostgreSQL、MariaDB，专业版/企业版可扩展 KingbaseES 与 OceanBase；它既管理平台系统元数据，也能托管业务数据表。借助「从数据库加载」与字段级同步，主数据库能够无缝承接存量数据库资产，实现渐进式迁移；借助普通表、继承表、树表、日历表、文件表、SQL 表、视图表等丰富的表结构类型，以及同类型内灵活的字段转换，可以低成本响应业务变化。

如果想继续深入，推荐阅读：

• 数据表字段 / 概述：字段类型与配置的完整说明；
• plugin-data-source-main 服务端源码：钩子、模型、资源与迁移的完整实现；
• 数据源管理文档：理解多数据源架构下主数据源与外部数据源的关系；
• MainDataSource 实现 与 DatabaseIntrospector 实现：表结构与字段推断的底层原理。

【免费下载链接】nocobaseNocoBase is an open-source AI + no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase